mcp-codex-worker 0.1.18 → 0.1.21

package/README.md

@@ -1,22 +1,22 @@
 # mcp-codex-worker
 
-a stdio MCP server that bridges MCP clients to the Codex app-server runtime. gives you thread management, turn control, request approval, and model selection through a clean MCP tool surface.
+A stdio MCP server that bridges MCP clients to the Codex app-server runtime. Provides **5 task tools** for provider-agnostic task orchestration — spawn, wait, respond, message, cancel. Does not call OpenAI APIs directly — all work is delegated to `codex app-server`.
 
-does not call OpenAI APIs directly — all work is delegated to the `codex app-server`.
+## Install
 
-## install
+### MCP server
 
 ```bash
 npx -y mcp-codex-worker
 ```
 
-or add to Claude Code globally:
+Add to Claude Code globally:
 
 ```bash
 claude mcp add codex-worker --scope user -- npx -y mcp-codex-worker
 ```
 
-or add to any MCP client config:
+Add to any MCP client config (Claude Desktop, VS Code, Cursor, etc.):
 
 ```json
 {
@@ -29,107 +29,174 @@ or add to any MCP client config:
 }
 ```
 
-## requirements
+### Companion skill (optional)
 
-- node 22+
+The `run-codex-subagents` skill teaches AI agents how to orchestrate tasks through this server — wave execution, approval handling, parallel dispatch, and more.
+
+```bash
+npx -y skills add -y -g yigitkonur/skills-by-yigitkonur/skills/run-codex-subagents
+```
+
+Or install the full skills pack:
+
+```bash
+npx -y skills add -y -g yigitkonur/skills-by-yigitkonur
+```
+
+The skill is also bundled at `skills/run-codex-subagents/` in this repo for reference.
+
+## Requirements
+
+- Node 22+
 - `codex` CLI installed and authenticated
 
-## tools
+## Unified task tools
 
-### thread management
+The primary interface. Provider-agnostic — tasks route to Codex today, Copilot and Claude CLI in Phase 2.
 
-| tool | description |
+| Tool | Purpose |
 |---|---|
-| `thread-start` | create a new conversation thread — each thread is an independent agent workspace |
-| `thread-resume` | resume an existing thread, optionally switching model or cwd |
-| `thread-read` | read thread state and conversation history |
-| `thread-list` | list recent threads for discovery |
+| `spawn-task` | Create and start a coding task. Returns immediately with a task_id. |
+| `wait-task` | Block until a task completes, fails, or needs input. |
+| `respond-task` | Answer an agent's question or approve a pending action. |
+| `message-task` | Send a follow-up message to an active task. |
+| `cancel-task` | Cancel one or more tasks (single or batch). |
 
-### turn control
+### Typical workflow
 
-| tool | description |
-|---|---|
-| `turn-start` | send a message to a thread, starting an autonomous agent turn |
-| `turn-steer` | redirect an in-progress turn with new instructions |
-| `turn-interrupt` | stop an active turn immediately |
+```
+spawn-task(prompt, cwd)           → task_id, status
+wait-task(task_id)                → completed | input_required | failed
+respond-task(task_id, type, ...)  → task resumes (if paused)
+wait-task(task_id)                → completed
+```
 
-### request approval
+### spawn-task
 
-| tool | description |
-|---|---|
-| `request-list` | list pending server requests (command approvals, permissions, etc.) |
-| `request-read` | read details of a specific pending request |
-| `request-respond` | approve/decline/answer a pending request |
+Create and start a task. The agent begins working immediately.
 
-### introspection
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `prompt` | string | yes | What the task should do. Be specific — include file paths, function names. |
+| `cwd` | string | no | Working directory. Agent sees files here. |
+| `task_type` | enum | no | `coder` (default), `planner`, `tester`, `researcher`, `general` |
+| `model` | string | no | Override provider default model. |
+| `timeout_ms` | integer | no | Max execution time (1,000–3,600,000 ms). |
+| `developer_instructions` | string | no | System-level constraints injected before the prompt. |
+| `labels` | string[] | no | Arbitrary labels for filtering. |
+| `depends_on` | string[] | no | Task IDs that must complete first. |
+| `context_files` | array | no | Files to include: `[{ path, description? }]` |
 
-| tool | description |
-|---|---|
-| `model-list` | list available models |
-| `account-read` | read account details |
-| `account-rate-limits-read` | check rate limit status |
-| `skills-list` | list registered skills |
-| `app-list` | list available apps |
-| `wait` | block until an operation completes or a request appears |
+Returns: `{ task_id, status, poll_frequency, provider_session_id, resources }`
 
-## parallel execution
+### wait-task
 
-launch multiple threads simultaneously for parallel work:
+Block until a task reaches a terminal state or `input_required`.
 
-```
-thread-start → thread_id_1
-thread-start → thread_id_2
-thread-start → thread_id_3
+| Parameter | Type | Required | Default |
+|---|---|---|---|
+| `task_id` | string | yes | — |
+| `timeout_ms` | integer | no | 30,000 |
+| `poll_interval_ms` | integer | no | 1,000 |
 
-turn-start(thread_id_1, "implement auth module...")
-turn-start(thread_id_2, "implement payment module...")
-turn-start(thread_id_3, "write e2e tests...")
-```
+Returns: `{ task_id, status, provider_session_id, pending_question?, output? }`
 
-each thread is fully isolated — they can work on different tasks concurrently without interfering.
+### respond-task
 
-## resources
+Respond to a paused task. The `type` field must match the `pending_question.type` from wait-task.
 
-| uri | description |
-|---|---|
-| `codex://threads` | latest threads from thread/list |
-| `codex://thread/{id}` | full thread with turns |
-| `codex://thread/{id}/events` | observed notifications for a thread |
-| `codex://models` | available models |
-| `codex://account` | account details and rate limits |
-| `codex://requests` | pending server requests |
+| Type | When | Key fields |
+|---|---|---|
+| `user_input` | Agent has questions | `answers: { "key": "value" }` |
+| `command_approval` | Agent wants to run a command | `decision: "accept" \| "reject"` |
+| `file_approval` | Agent wants to modify files | `decision: "accept" \| "reject"` |
+| `elicitation` | MCP server needs confirmation | `action: "accept" \| "decline"` |
+| `dynamic_tool` | Agent invoked an external tool | `result: "..."` or `error: "..."` |
+
+### message-task
 
-## environment variables
+Send a follow-up to an active task. Only works on non-terminal tasks.
 
-| variable | description | default |
+| Parameter | Type | Required |
 |---|---|---|
-| `CODEX_APP_SERVER_COMMAND` | codex binary path | `codex` |
-| `CODEX_APP_SERVER_ARGS` | app-server arguments | `app-server --listen stdio://` |
-| `CODEX_HOME_DIRS` | colon-separated profile roots for failover | `~/.codex` |
-| `CODEX_ENABLE_FLEET` | enable fleet mode (appends sub-agent instructions) | off |
+| `task_id` | string | yes |
+| `message` | string | yes |
+| `model` | string | no |
 
-## typical workflow
+### cancel-task
+
+Cancel one or many tasks.
+
+| Parameter | Type | Required |
+|---|---|---|
+| `task_id` | string or string[] | yes |
+
+Returns: `{ cancelled: [...], already_terminal: [...], not_found: [...] }`
+
+## Task resources
+
+| URI | Description |
+|---|---|
+| `task:///all` | Scoreboard — all tasks with status badges and elapsed time |
+| `task:///{id}` | Detail — metadata, provider session, timestamps, error |
+| `task:///{id}/log` | Summary log — last 20 output lines |
+| `task:///{id}/log.verbose` | Verbose log — full output history |
+
+### Wire states (SEP-1686)
+
+All statuses returned by tools use these 7 values:
+
+| State | Meaning |
+|---|---|
+| `submitted` | Queued, not started |
+| `working` | Agent is executing |
+| `input_required` | Paused, needs response |
+| `completed` | Done |
+| `failed` | Error |
+| `cancelled` | Interrupted |
+| `unknown` | Crash recovery fallback |
+
+## Parallel execution
+
+Spawn multiple tasks simultaneously. Each runs in an independent agent workspace.
 
 ```
-1. thread-start                    → get thread_id
-2. turn-start(thread_id, prompt)   → agent starts working
-3. wait(thread_id=...)             → wait for completion or request
-4. request-list                    → check if agent needs approval
-5. request-respond(request_id)     → approve and resume
-6. thread-read(thread_id)          → read final results
+spawn-task(prompt: "implement auth module", cwd: "/project")   → task_a
+spawn-task(prompt: "implement billing module", cwd: "/project") → task_b
+spawn-task(prompt: "write e2e tests", cwd: "/project")          → task_c
+
+# Monitor via scoreboard
+read resource: task:///all
+→ tasks -- 3 total (1 done, 2 busy)
+
+# Wait for each
+wait-task(task_a) → completed
+wait-task(task_b) → completed
+wait-task(task_c) → completed
 ```
 
-## local development
+## Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `CODEX_APP_SERVER_COMMAND` | Codex binary path | `codex` |
+| `CODEX_APP_SERVER_ARGS` | App-server arguments | `app-server --listen stdio://` |
+| `CODEX_HOME_DIRS` | Colon-separated profile roots for failover | `~/.codex` |
+| `CODEX_ENABLE_FLEET` | Enable fleet mode (sub-agent instructions) | off |
+
+## Local development
 
 ```bash
 npm install
 npm run build
-npm run test:unit
-npm run smoke          # requires codex CLI
+npm run test:unit    # 158 tests
+npm run smoke        # requires codex CLI
 ```
 
-## troubleshooting
+### Contract tests (mcpc)
+
+```bash
+./test/mcpc/gherkin-tests.sh   # 45 scenarios, 84 assertions
+```
 
-- make sure `codex` CLI is installed and authenticated
-- check `CODEX_APP_SERVER_COMMAND` if using a non-standard install path
-- use `account-rate-limits-read` before launching many parallel threads
+Requires [mcpc](https://github.com/nicobailey/mcpc) v0.1.11+.

package/dist/src/app.d.ts

@@ -20,19 +20,9 @@ export declare class CodexWorkerApp {
         text: string;
     }>;
     callTool(name: string, args: unknown): Promise<string>;
-    private handleThreadStart;
-    private handleThreadResume;
-    private handleThreadRead;
-    private handleThreadList;
-    private handleTurnStart;
-    private handleTurnSteer;
-    private handleTurnInterrupt;
-    private handleRequestRespond;
-    private handleWait;
     private handleSpawnTask;
     private handleWaitTask;
     private handleRespondTask;
     private handleMessageTask;
     private handleCancelTask;
-    private buildServerRequestPayload;
 }