mcp-codex-worker 0.1.21 → 0.1.22

package/src/mcp/tool-definitions.ts

@@ -1,14 +1,18 @@
 import { z } from 'zod';
 
+import { REASONING_OPTIONS } from '../services/reasoning-options.js';
+
 // ---------------------------------------------------------------------------
 // Unified task tool schemas (provider-agnostic)
 // ---------------------------------------------------------------------------
 
+const reasoningEnum = z.enum(REASONING_OPTIONS);
+
 const spawnTaskSchema = z.object({
   prompt: z.string().min(1),
   task_type: z.enum(['coder', 'planner', 'tester', 'researcher', 'general']).default('coder'),
   provider: z.enum(['codex', 'copilot', 'claude-cli']).optional(),
-  model: z.string().optional(),
+  reasoning: reasoningEnum.optional(),
   cwd: z.string().optional(),
   timeout_ms: z.number().int().min(1000).max(3_600_000).optional(),
   keep_alive: z.number().optional(),
@@ -60,7 +64,7 @@ const respondTaskSchema = z.discriminatedUnion('type', [
 const messageTaskSchema = z.object({
   task_id: z.string().min(1),
   message: z.string().min(1),
-  model: z.string().optional(),
+  reasoning: reasoningEnum.optional(),
 });
 
 const cancelTaskSchema = z.object({
@@ -89,69 +93,94 @@ function objectSchema(
   };
 }
 
+const REASONING_DESCRIPTION = [
+  'Model + reasoning effort for this task. The value is a single literal — the server splits it into a model id and a reasoning-effort level and passes them to Codex separately.',
+  '',
+  'Picking the level:',
+  '- `gpt-5.4(medium)` — default workhorse. Use for most coding, refactors, and focused debugging.',
+  '- `gpt-5.4(high)` — harder tasks: multi-file reasoning, subtle bugs, non-trivial design decisions.',
+  '- `gpt-5.4(xhigh)` — reserved for exceptional deep research, novel architecture work, or problems where you have already tried `high` and it was not enough.',
+  '- `gpt-5.4(low)` — rare; only for trivial mechanical edits where latency matters more than quality.',
+  '',
+  'Omit to use the server default from config.',
+].join('\n');
+
 export function createToolDefinitions(): ToolDefinition[] {
   return [
     {
       name: 'spawn-task',
       description: [
-        'Create and start a provider-agnostic task.',
+        'Create and start a provider-agnostic task, returning a task_id you can track.',
+        '',
+        'Dispatches the prompt to the provider registered for the given `task_type` (Codex, Copilot, Claude CLI) and returns immediately with a task_id. Use `wait-task` to block until the task reaches a terminal state or needs input, `respond-task` to unblock it, and `message-task` to send follow-ups on the same session.',
         '',
-        'Dispatches work to the configured provider (Codex, Copilot, Claude CLI) based on task_type routing.',
-        'Returns immediately with a task_id for tracking. Use wait-task to block until completion or input_required.',
+        'PARALLEL EXECUTION: Spawn multiple tasks in the same message to fan out work — each task runs in its own isolated agent workspace and reports back independently. Prefer parallel spawns over sequential ones whenever the subtasks do not depend on each other.',
         '',
-        'PARALLEL EXECUTION: Spawn multiple tasks simultaneously — each runs in an independent agent workspace.',
-        'After spawning, check wait-task — the agent may need approval or user input before it can proceed.',
+        'AFTER SPAWNING: Always follow up with `wait-task`. The agent may pause almost immediately to request a command/file approval or structured user input; the bridge window surfaces that pending question so you can answer it without polling forever.',
+        '',
+        'WRITING A GOOD PROMPT: Name the exact files, functions, or symbols involved, state the expected behavior or acceptance criteria, and mention anything the agent must NOT touch. Vague prompts produce vague work.',
       ].join('\n'),
       inputSchema: objectSchema({
-        prompt: { type: 'string', minLength: 1, description: 'What the task should do. Be specific — include file paths, function names, and expected behavior.' },
+        prompt: {
+          type: 'string',
+          minLength: 1,
+          description: 'What the task should do. Be specific: include file paths, function or symbol names, the expected outcome, and any constraints. The agent only sees this prompt — treat it as the full brief.',
+        },
         task_type: {
           type: 'string',
           enum: ['coder', 'planner', 'tester', 'researcher', 'general'],
           default: 'coder',
-          description: 'Type of task. Determines provider routing. Default: coder.',
+          description: 'Routing hint that picks a provider and default prompt shape. `coder` for writing/editing code, `planner` for decomposing work, `tester` for writing or running tests, `researcher` for investigation, `general` for anything else. Defaults to `coder`.',
         },
         provider: {
           type: 'string',
           enum: ['codex', 'copilot', 'claude-cli'],
-          description: 'Override automatic provider selection. Optional — defaults to the provider registered for the task_type.',
+          description: 'Force a specific backend instead of the one registered for the `task_type`. Leave unset in almost all cases — only override when you need a particular provider for capability reasons.',
+        },
+        reasoning: {
+          type: 'string',
+          enum: [...REASONING_OPTIONS],
+          description: REASONING_DESCRIPTION,
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute working directory the task runs in. Defaults to the server process cwd; set this when the work is scoped to a specific repo or subfolder.',
         },
-        model: { type: 'string', description: 'Model to use. Omit to use the provider default.' },
-        cwd: { type: 'string', description: 'Working directory for the task. Defaults to server process cwd.' },
         timeout_ms: {
           type: 'integer',
           minimum: 1000,
           maximum: 3600000,
-          description: 'Max execution time in ms. Default varies by provider.',
+          description: 'Hard time limit for the task in milliseconds. The task is marked `timed_out` if it exceeds this. Defaults to the provider default when omitted.',
         },
         keep_alive: {
           type: 'number',
-          description: 'SEP-1686 result retention period in ms. How long the server keeps the result available after completion.',
+          description: 'SEP-1686 retention window (ms). How long the server keeps the completed task result available for follow-up queries after the task finishes.',
         },
         labels: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Arbitrary labels for filtering and grouping tasks.',
+          description: 'Free-form tags for filtering and grouping in the task scoreboard. Purely organizational — they do not affect execution.',
         },
         depends_on: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Task IDs that must complete before this task starts.',
+          description: 'Task IDs that must reach a terminal state before this task is allowed to start. Use this to chain dependent work.',
         },
         developer_instructions: {
           type: 'string',
-          description: 'System-level instructions injected before user messages. Use for constraints, coding style, or scope boundaries.',
+          description: 'System-level instructions injected ahead of the user prompt. Use this for hard constraints (coding style, allowed directories, forbidden actions) rather than folding them into the prompt.',
         },
         context_files: {
           type: 'array',
           items: {
             type: 'object',
             properties: {
-              path: { type: 'string', description: 'File path to include as context.' },
-              description: { type: 'string', description: 'Optional description of why this file is relevant.' },
+              path: { type: 'string', description: 'Absolute path of a file to include as context for the task.' },
+              description: { type: 'string', description: 'Optional note explaining why this file is relevant so the agent knows what to look at.' },
             },
             required: ['path'],
           },
-          description: 'Files to include as context for the task.',
+          description: 'Files to prepend as additional context. Use sparingly — context is not free; prefer pointing at files from the prompt when the agent can open them itself.',
         },
       }, ['prompt']),
       validate: (value) => spawnTaskSchema.parse(value),
@@ -159,27 +188,27 @@ export function createToolDefinitions(): ToolDefinition[] {
     {
       name: 'wait-task',
       description: [
-        'Block until a task reaches a terminal state or requires input.',
+        'Block until a task settles or asks for input. This is how you synchronously track progress after `spawn-task` or `message-task`.',
+        '',
+        'Returns as soon as the task reaches a terminal state (`completed`, `failed`, `cancelled`, `timed_out`) or enters `waiting_answer` because the agent needs an approval or structured input. If `timeout_ms` elapses first, it returns the current status and you decide whether to wait again.',
         '',
-        'Polls the task store internally at poll_interval_ms. Returns when the task completes, fails, is cancelled, or enters input_required.',
-        'If timeout_ms elapses, returns the current status — the caller decides whether to wait again.',
-        'Use after spawn-task to synchronously track task progress.',
+        'PATTERN: loop `wait-task` → if `waiting_answer`, call `respond-task` with the matching question payload → loop back to `wait-task`. Do not busy-poll with short timeouts; give each call enough time to catch meaningful progress.',
       ].join('\n'),
       inputSchema: objectSchema({
-        task_id: { type: 'string', minLength: 1, description: 'ID of the task to wait on.' },
+        task_id: { type: 'string', minLength: 1, description: 'ID of the task to wait on, as returned by `spawn-task`.' },
         timeout_ms: {
           type: 'integer',
           minimum: 1,
           maximum: 300000,
           default: 30000,
-          description: 'Max wait time in ms. Default 30,000 (30 seconds).',
+          description: 'Maximum time to block in milliseconds. Returns early on terminal state or `waiting_answer`. Defaults to 30,000 (30 seconds).',
         },
         poll_interval_ms: {
           type: 'integer',
           minimum: 250,
           maximum: 30000,
           default: 1000,
-          description: 'Internal poll interval in ms. Default 1,000.',
+          description: 'Internal poll interval in milliseconds. Keep the default (1,000) unless you have a specific reason to tune it.',
         },
       }, ['task_id']),
       validate: (value) => waitTaskSchema.parse(value),
@@ -187,49 +216,49 @@ export function createToolDefinitions(): ToolDefinition[] {
     {
       name: 'respond-task',
       description: [
-        'Respond to a paused task that requires input.',
+        'Unblock a task that is in `waiting_answer` because the agent requested input or an approval.',
         '',
-        'The response shape is discriminated by the `type` field, matching the PendingQuestion type from wait-task:',
-        '- user_input: provide answers as Record<string, string>',
-        '- command_approval: accept or reject the command',
-        '- file_approval: accept or reject file changes',
-        '- elicitation: accept or decline, with optional content',
-        '- dynamic_tool: provide result or error string',
+        'The payload shape is discriminated by `type` and must match the pending question surfaced by `wait-task`:',
+        '- `user_input` — reply with `answers` as a map of question id → string.',
+        '- `command_approval` — `decision: "accept" | "reject"` for a proposed shell command.',
+        '- `file_approval` — `decision: "accept" | "reject"` for a proposed file edit.',
+        '- `elicitation` — `action: "accept" | "decline"`, plus optional structured `content` for MCP elicitation prompts.',
+        '- `dynamic_tool` — return a tool call result via `result`, or an `error` string on failure.',
         '',
-        'After responding, the task resumes execution. Use wait-task again to track further progress.',
+        'After responding the task resumes automatically. Follow up with `wait-task` to track the next step.',
       ].join('\n'),
       inputSchema: objectSchema({
-        task_id: { type: 'string', minLength: 1, description: 'ID of the paused task.' },
+        task_id: { type: 'string', minLength: 1, description: 'ID of the paused task. Must currently be in `waiting_answer`.' },
         type: {
           type: 'string',
           enum: ['user_input', 'command_approval', 'file_approval', 'elicitation', 'dynamic_tool'],
-          description: 'Type of response, must match the pending question type.',
+          description: 'Which pending-question variant you are answering. Must match the `type` of the question returned by `wait-task` exactly.',
         },
         answers: {
           type: 'object',
-          description: 'For user_input: map of question keys to answer strings.',
+          description: 'For `user_input`: map of each question id (as returned in the pending question) to the user-facing answer string.',
         },
         decision: {
           type: 'string',
           enum: ['accept', 'reject'],
-          description: 'For command_approval or file_approval: accept or reject.',
+          description: 'For `command_approval` or `file_approval`: whether the agent may run the proposed command / apply the proposed edit.',
         },
         action: {
           type: 'string',
           enum: ['accept', 'decline'],
-          description: 'For elicitation: accept or decline.',
+          description: 'For `elicitation`: accept the MCP server\'s elicitation request or decline it.',
         },
         content: {
           type: 'object',
-          description: 'For elicitation: optional structured content payload.',
+          description: 'For `elicitation`: optional structured payload that satisfies the requested schema when accepting.',
         },
         result: {
           type: 'string',
-          description: 'For dynamic_tool: the tool result string.',
+          description: 'For `dynamic_tool`: the tool call result string returned to the agent.',
         },
         error: {
           type: 'string',
-          description: 'For dynamic_tool: error string if the tool call failed.',
+          description: 'For `dynamic_tool`: error string if the tool call failed. Sets `success=false` on the response.',
         },
       }, ['task_id', 'type']),
       validate: (value) => respondTaskSchema.parse(value),
@@ -237,15 +266,20 @@ export function createToolDefinitions(): ToolDefinition[] {
     {
       name: 'message-task',
       description: [
-        'Send a follow-up message to an existing task.',
+        'Send a follow-up message to an existing task on its original session.',
         '',
-        'If the task is still running, adds a new turn. If idle, resumes the thread first.',
-        'Use to provide additional instructions, ask the agent to refine its work, or continue a completed task.',
+        'Use this to add instructions to a still-running task, ask a completed task to refine or extend its work, or steer the agent after reviewing partial results. If the task is idle, the session is resumed first; if it is actively running, the message is queued as the next turn.',
+        '',
+        'After calling, follow up with `wait-task` exactly like after `spawn-task`.',
       ].join('\n'),
       inputSchema: objectSchema({
-        task_id: { type: 'string', minLength: 1, description: 'ID of the task to message.' },
-        message: { type: 'string', minLength: 1, description: 'Follow-up instruction or question for the agent.' },
-        model: { type: 'string', description: 'Override model for this follow-up turn.' },
+        task_id: { type: 'string', minLength: 1, description: 'ID of the task whose session should receive the follow-up.' },
+        message: { type: 'string', minLength: 1, description: 'The follow-up instruction or question. Be as specific as the original prompt — reference files and expected behavior.' },
+        reasoning: {
+          type: 'string',
+          enum: [...REASONING_OPTIONS],
+          description: `${REASONING_DESCRIPTION}\n\nOverrides the reasoning used for this follow-up turn only.`,
+        },
       }, ['task_id', 'message']),
       validate: (value) => messageTaskSchema.parse(value),
     },
@@ -254,17 +288,15 @@ export function createToolDefinitions(): ToolDefinition[] {
       description: [
         'Cancel one or more running tasks.',
         '',
-        'Accepts a single task_id string or an array of task_id strings for batch cancellation.',
-        'For running tasks, signals the provider to abort execution.',
-        'Tasks already in a terminal state are counted as already_terminal in the response.',
+        'Accepts a single task_id or an array. For each running task, asks the provider to abort execution and marks the task `cancelled`. Tasks already in a terminal state are returned under `already_terminal`; unknown ids are returned under `not_found`. Safe to call on a batch — each id is handled independently.',
       ].join('\n'),
       inputSchema: objectSchema({
         task_id: {
           oneOf: [
             { type: 'string', minLength: 1, description: 'Single task ID to cancel.' },
-            { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, description: 'Array of task IDs to cancel.' },
+            { type: 'array', items: { type: 'string', minLength: 1 }, minItems: 1, description: 'Array of task IDs to cancel in one call.' },
           ],
-          description: 'Task ID or array of task IDs to cancel.',
+          description: 'Task ID or array of task IDs to cancel. Accepts both a single string and an array for convenience.',
         },
       }, ['task_id']),
       validate: (value) => cancelTaskSchema.parse(value),

package/src/services/codex-runtime.ts

@@ -22,6 +22,7 @@ import {
   ProfileManager,
   type CodexProfile,
 } from './profile-manager.js';
+import type { ReasoningEffortLevel } from './reasoning-options.js';
 
 interface RuntimeRequestOptions {
   timeoutMs?: number | undefined;
@@ -299,6 +300,7 @@ export class CodexRuntime {
 
   buildThreadStartParams(input: {
     model?: string | undefined;
+    effort?: ReasoningEffortLevel | undefined;
     cwd?: string | undefined;
     developerInstructions?: string | undefined;
   }): Promise<{ params: Record<string, unknown>; remappedFrom?: string | undefined; }> {
@@ -308,7 +310,7 @@ export class CodexRuntime {
         cwd: input.cwd ?? process.cwd(),
         approvalPolicy: 'on-request',
         sandbox: 'workspace-write',
-        reasoningEffort: 'high',
+        ...(input.effort ? { reasoningEffort: input.effort } : {}),
         developerInstructions: appendFleetDeveloperInstructions(input.developerInstructions),
         experimentalRawEvents: false,
         persistExtendedHistory: false,
@@ -323,6 +325,7 @@ export class CodexRuntime {
   buildThreadResumeParams(input: {
     threadId: string;
     model?: string | undefined;
+    effort?: ReasoningEffortLevel | undefined;
     cwd?: string | undefined;
     developerInstructions?: string | undefined;
   }): Promise<{ params: Record<string, unknown>; remappedFrom?: string | undefined; }> {
@@ -333,7 +336,7 @@ export class CodexRuntime {
         cwd: input.cwd ?? process.cwd(),
         approvalPolicy: 'on-request',
         sandbox: 'workspace-write',
-        reasoningEffort: 'high',
+        ...(input.effort ? { reasoningEffort: input.effort } : {}),
         developerInstructions: appendFleetDeveloperInstructions(input.developerInstructions),
         persistExtendedHistory: false,
       };
@@ -348,11 +351,13 @@ export class CodexRuntime {
     threadId: string;
     userInput: string;
     model?: string | undefined;
+    effort?: ReasoningEffortLevel | undefined;
   }): Promise<{ params: Record<string, unknown>; remappedFrom?: string | undefined; }> {
     return this.resolveModelIfRequested(input.model).then((resolved) => ({
       params: {
         threadId: input.threadId,
         ...(resolved ? { model: resolved.resolvedModel } : {}),
+        ...(input.effort ? { effort: input.effort } : {}),
         input: [{
           type: 'text',
           text: input.userInput,
@@ -407,12 +412,16 @@ export class CodexRuntime {
     return [...this.knownThreadIds].sort();
   }
 
-  async ensureThreadLoaded(threadId: string, model?: string | undefined): Promise<void> {
+  async ensureThreadLoaded(
+    threadId: string,
+    model?: string | undefined,
+    effort?: ReasoningEffortLevel | undefined,
+  ): Promise<void> {
     if (!this.knownThreadIds.has(threadId) || this.loadedThreadIds.has(threadId)) {
       return;
     }
 
-    const built = await this.buildThreadResumeParams({ threadId, model });
+    const built = await this.buildThreadResumeParams({ threadId, model, effort });
     await this.request('thread/resume', built.params);
   }
 

package/src/services/reasoning-options.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Reasoning option parsing
+//
+// The MCP `reasoning` parameter is a hardcoded allow-list of `gpt-5.4` model
+// variants paired with a Codex reasoning-effort level. Everything flowing
+// through the tools is one of the exact strings in REASONING_OPTIONS — we
+// split it into `{ model, effort }` at the boundary so the adapter chain can
+// pass the two fields independently to Codex (`reasoningEffort` on
+// thread/start, `effort` on turn/start).
+// ---------------------------------------------------------------------------
+
+export type ReasoningEffortLevel = 'low' | 'medium' | 'high' | 'xhigh';
+
+/** The only model we expose. Hardcoded — do not add variants without intent. */
+export const ALLOWED_MODEL = 'gpt-5.4';
+
+/**
+ * The full set of accepted `reasoning` values. Order matters for display:
+ * medium/high first (the common cases), xhigh next (exceptional research),
+ * low last (rare, kept for completeness).
+ */
+export const REASONING_OPTIONS = [
+  'gpt-5.4(medium)',
+  'gpt-5.4(high)',
+  'gpt-5.4(xhigh)',
+  'gpt-5.4(low)',
+] as const;
+
+export type ReasoningOption = (typeof REASONING_OPTIONS)[number];
+
+const REASONING_PATTERN = /^(gpt-5\.4)\((low|medium|high|xhigh)\)$/;
+
+export interface ParsedReasoning {
+  model: string;
+  effort: ReasoningEffortLevel;
+}
+
+export function isReasoningOption(value: unknown): value is ReasoningOption {
+  return typeof value === 'string' && (REASONING_OPTIONS as readonly string[]).includes(value);
+}
+
+/**
+ * Parse a `reasoning` value such as `gpt-5.4(high)` into its model id and
+ * reasoning-effort level. Throws on any value not in {@link REASONING_OPTIONS}.
+ */
+export function parseReasoning(value: string): ParsedReasoning {
+  const match = REASONING_PATTERN.exec(value);
+  if (!match) {
+    throw new Error(
+      `Invalid reasoning option "${value}". Allowed: ${REASONING_OPTIONS.join(', ')}`,
+    );
+  }
+  return {
+    model: match[1]!,
+    effort: match[2] as ReasoningEffortLevel,
+  };
+}

package/src/task/task-manager.ts

@@ -41,6 +41,7 @@ export interface CreateTaskInput {
   provider: Provider;
   taskType: TaskTypeName;
   model?: string;
+  effort?: 'low' | 'medium' | 'high' | 'xhigh';
   timeoutMs?: number;
   dependsOn?: string[];
   labels?: string[];
@@ -115,6 +116,7 @@ export class TaskManager {
 
     // Only set optional properties when defined (exactOptionalPropertyTypes)
     if (input.model !== undefined) task.model = input.model;
+    if (input.effort !== undefined) task.effort = input.effort;
     if (input.timeoutMs !== undefined) task.timeoutMs = input.timeoutMs;
     if (input.dependsOn !== undefined) task.dependsOn = input.dependsOn;
 

package/src/task/task-state.ts

@@ -86,6 +86,7 @@ export interface TaskState {
   prompt: string;
   cwd: string;
   model?: string;
+  effort?: 'low' | 'medium' | 'high' | 'xhigh';
   sessionId?: string;
   operationId?: string;