Plato CLI and MCP Surface

@bensigo/plato-cli owns Plato's caller-facing orchestration surface.

This package speaks @bensigo/plato-orchestration contracts only. Command handlers and MCP tool handlers must not import @bensigo/plato-codex-runner; Codex is one runtime adapter behind the orchestration boundary, not the product API.

Install

Install the CLI from npm:

npm install -g @bensigo/plato-cli

The global install runs a non-fatal setup check. Plato includes the official Codex CLI package for auth and task execution; install Codex globally only if you also want the standalone codex command:

npm install -g @openai/codex

Then log in with Codex/ChatGPT so Plato can use your subscription, and configure the default model for real Codex-backed tasks:

plato config auth-chatgpt
plato config set-model gpt-5.4
plato config status

Run a quick local health check:

plato smoke

Start a real task in the current repository:

plato task start --workspace-path "$PWD" --prompt "Inspect this repo and summarize the package layout."

Runtime Bootstrap

src/index.ts owns the neutral handler surface and accepts an injected orchestration client. src/bootstrap.ts is the composition layer that opens the current Codex runtime, wraps it in CodexRunnerAgentRuntime, registers it with TaskOrchestrationService, and passes that neutral client into the CLI or MCP surface.

Use runPlatoCliWithRuntime() when the CLI should open the default local Codex-backed runtime for one command. Use createPlatoMcpServerWithRuntime() when MCP hosting code needs a server plus a close() hook for the opened runtime resources.

The package exposes two thin executables:

• plato for operator CLI commands, including plato mcp
• plato-mcp for agent configs that prefer a dedicated MCP command

It also exposes a deterministic health check:

pnpm --filter @bensigo/plato-cli smoke

The smoke command exercises task lifecycle, delegated decomposition, validation, worker graph execution, graph results, graph review, and interrupt/resume control flow through the real CLI handlers using an in-memory fake runtime. For the real Codex-backed manual smoke path, see docs/local-task-smoke.md.

The read-only worker tool harness catalog is available without opening a runtime:

plato tool catalog

The delegate planner entrypoint turns a top-level task into a reviewable decomposition plan and validates it without starting tasks or opening the runtime-backed client:

plato delegate plan --task-id m28 --workspace-path /repo --prompt "Break this into reviewable milestones"

The response shape is { "plan": ..., "validation": ... }, using the deterministic planner from @bensigo/plato-orchestration.

To run the default delegated execution flow in one step, use:

plato delegate start --task-id m29 --workspace-path /repo --prompt "Execute this through workers"

This creates the plan, validates it, and starts the worker graph only when the plan passes validation. The response shape is { "plan": ..., "validation": ..., "graph": ... }; invalid plans omit graph.

After review, start execution through the validated plan gate:

plato graph start-plan --plan-json "$PLAN_JSON"

Invalid plans return validation issues and do not start a graph.

Worker result inspection stays on the same neutral orchestration surface. Use the CLI to inspect the per-worker result records and final parent synthesis for a graph:

plato graph results --task-id m30

MCP clients can read the same snapshot through plato.get_task_graph_results or plato://graphs/{taskId}/results. The response shape is { "parentTaskId": ..., "results": [...], "synthesis": ... }.

To convert a reviewed plan into graph input for execution, use:

plato graph validate --plan-json '<plan-json>'

The validation command returns { "validation": ..., "graphInput": ... } only when the decomposition plan is valid. Invalid plans return validation issues and omit graphInput; plato graph start remains the lower-level command for already-prepared graph inputs.

Both MCP entrypoints use stdio transport. Do not write normal logs to stdout in this process; stdout is reserved for MCP JSON-RPC messages.

The boundary rule is intentional: handler tests should use fake OrchestrationClient implementations, and only bootstrap or executable entrypoints should import concrete runtime adapters.

Example local agent configuration:

{
  "mcpServers": {
    "plato": {
      "command": "plato",
      "args": ["mcp"]
    }
  }
}

Tool Catalog

• plato.delegate_task_plan
• plato.delegate_task
• plato.start_task
• plato.plan_task_graph
• plato.validate_task_graph_plan
• plato.create_task_graph_from_plan
• plato.create_task_graph
• plato.get_task
• plato.list_tasks
• plato.get_task_graph
• plato.get_task_graph_results
• plato.list_task_events
• plato.interrupt_task
• plato.resume_task
• plato.approve_task_action
• plato.reject_task_action
• plato.list_tools
• plato.list_orchestration_tools

Resource Catalog

• plato://tasks
• plato://tasks/{taskId}
• plato://tasks/{taskId}/events
• plato://graphs/{taskId}
• plato://graphs/{taskId}/results
• plato://approvals

Development Notes

• Run tests with pnpm --filter @bensigo/plato-cli test.
• Run type-checking with pnpm --filter @bensigo/plato-cli typecheck.