mcp-codex-worker 0.1.0 → 0.1.2

package/src/mcp/tool-definitions.ts

@@ -1,7 +1,5 @@
 import { z } from 'zod';
 
-const jsonSchema = { type: 'object' as const };
-
 const threadStartSchema = z.object({
   model: z.string().optional(),
   cwd: z.string().optional(),
@@ -46,10 +44,6 @@ const requestListSchema = z.object({
   include_resolved: z.boolean().optional(),
 });
 
-const requestReadSchema = z.object({
-  request_id: z.union([z.string(), z.number()]),
-});
-
 const requestRespondSchema = z.object({
   request_id: z.union([z.string(), z.number()]),
   payload: z.record(z.string(), z.unknown()).optional(),
@@ -91,20 +85,32 @@ function objectSchema(
   };
 }
 
-export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
+export interface CreateToolDefinitionsInput {
+  modelIds: string[];
+  threadBanner: string;
+  requestBanner: string;
+}
+
+export function createToolDefinitions(input: CreateToolDefinitionsInput): ToolDefinition[] {
+  const { modelIds, threadBanner, requestBanner } = input;
   return [
     {
-      name: 'thread-start',
+      name: 'codex-thread-start',
       description: [
-        'Create a new Codex conversation thread.',
-        'Each thread is an independent agent workspace. Launch multiple threads in parallel to work on different tasks concurrently.',
-        'Returns thread_id for use with turn-start.',
-      ].join(' '),
+        'Launch a new Codex agent as a background thread.',
+        '',
+        'PARALLEL EXECUTION: Launch multiple threads simultaneously — each thread is an independent agent workspace with its own context and conversation history.',
+        'This is the primary way to dispatch coding and testing work to Codex.',
+        '',
+        'After creating a thread, use codex-turn-start to send the task prompt.',
+        'Use codex-wait to block until the agent finishes or asks for permission.',
+        'Check codex-request-list after starting turns — agents often need approval for commands or file changes.',
+      ].join('\n'),
       inputSchema: objectSchema({
         model: {
           type: 'string',
           ...(modelIds.length > 0 ? { enum: modelIds } : {}),
-          description: 'Model to use for this thread. If omitted, Codex uses the account default.',
+          description: 'Model to use. Defaults to gpt-5.4. Available models are listed in the enum.',
         },
         cwd: {
           type: 'string',
@@ -112,14 +118,14 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
         },
         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 before user messages. Use for constraints, coding style, acceptance criteria, or scope boundaries. Be specific — include file paths, function names, and expected behavior.',
         },
       }),
       validate: (value) => threadStartSchema.parse(value),
     },
     {
-      name: 'thread-resume',
-      description: 'Resume an existing Codex thread that was previously started. Reloads context and reconnects the agent to the conversation.',
+      name: 'codex-thread-resume',
+      description: 'Resume a previously started Codex thread. Reloads context and reconnects the agent. Use to continue work on an existing thread after a pause, or to send follow-up instructions to a completed thread.',
       inputSchema: objectSchema({
         thread_id: { type: 'string', minLength: 1, description: 'ID of the thread to resume.' },
         model: {
@@ -133,17 +139,20 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
       validate: (value) => threadResumeSchema.parse(value),
     },
     {
-      name: 'thread-read',
-      description: 'Read a thread and its conversation history. Use include_turns=true to get full turn details.',
+      name: 'codex-thread-read',
+      description: [
+        'Read thread status and conversation history. Use to check what an agent has done, inspect its output, or verify task completion. Set include_turns=true for full turn details including tool calls and file changes.',
+        threadBanner,
+      ].filter(Boolean).join('\n\n'),
       inputSchema: objectSchema({
         thread_id: { type: 'string', minLength: 1, description: 'Thread to read.' },
-        include_turns: { type: 'boolean', description: 'Include full turn history. Defaults to true.' },
+        include_turns: { type: 'boolean', description: 'Include full turn history with tool calls and outputs. Defaults to true.' },
       }, ['thread_id']),
       validate: (value) => threadReadSchema.parse(value),
     },
     {
-      name: 'thread-list',
-      description: 'List recent Codex threads. Use to discover existing conversations before starting new ones.',
+      name: 'codex-thread-list',
+      description: 'List recent Codex threads across all sessions. Use to discover existing threads before starting new ones, or to find a thread ID you need to resume.',
       inputSchema: objectSchema({
         limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Max threads to return. Default 50.' },
         cursor: { type: 'string', description: 'Pagination cursor from a previous response.' },
@@ -151,15 +160,23 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
       validate: (value) => threadListSchema.parse(value),
     },
     {
-      name: 'turn-start',
+      name: 'codex-turn-start',
       description: [
-        'Send a user message to an active thread, starting a new agent turn.',
-        'The agent will execute autonomously — use wait or turn-steer to monitor or redirect.',
-        'For parallel work, start turns on multiple threads simultaneously.',
-      ].join(' '),
+        [
+          'Send a task to an active Codex thread, starting an autonomous agent turn.',
+          '',
+          'The agent executes independently — it reads files, writes code, runs commands, and commits changes.',
+          'Use codex-wait to block until the turn completes or a pending request appears.',
+          'Use codex-turn-steer to redirect the agent mid-execution if it goes off track.',
+          '',
+          'IMPORTANT: After starting a turn, check codex-request-list — the agent frequently needs approval for shell commands or file changes before it can proceed.',
+          'For parallel work, start turns on multiple threads simultaneously.',
+        ].join('\n'),
+        threadBanner,
+      ].filter(Boolean).join('\n\n'),
       inputSchema: objectSchema({
-        thread_id: { type: 'string', minLength: 1, description: 'Thread to send the message to.' },
-        user_input: { type: 'string', minLength: 1, description: 'The user message or task instruction.' },
+        thread_id: { type: 'string', minLength: 1, description: 'Thread to send the task to.' },
+        user_input: { type: 'string', minLength: 1, description: 'The task instruction. Be specific: include file paths, function names, acceptance criteria, and constraints.' },
         model: {
           type: 'string',
           ...(modelIds.length > 0 ? { enum: modelIds } : {}),
@@ -169,8 +186,11 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
       validate: (value) => turnStartSchema.parse(value),
     },
     {
-      name: 'turn-steer',
-      description: 'Redirect an in-progress turn with new instructions. The agent adjusts its approach without losing prior context.',
+      name: 'codex-turn-steer',
+      description: [
+        'Redirect an in-progress turn with new instructions. The agent adjusts course without losing prior context. Use when you see the agent heading in the wrong direction via codex-thread-read or codex-request-list.',
+        threadBanner,
+      ].filter(Boolean).join('\n\n'),
       inputSchema: objectSchema({
         thread_id: { type: 'string', minLength: 1, description: 'Thread containing the active turn.' },
         expected_turn_id: { type: 'string', minLength: 1, description: 'Turn ID to steer. Must be the currently active turn.' },
@@ -179,8 +199,8 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
       validate: (value) => turnSteerSchema.parse(value),
     },
     {
-      name: 'turn-interrupt',
-      description: 'Stop an active turn immediately. Use when the agent is heading in the wrong direction or a task should be cancelled.',
+      name: 'codex-turn-interrupt',
+      description: 'Stop an active turn immediately. Use when the agent is heading in the wrong direction and steering is not enough, or when you need to cancel work in progress.',
       inputSchema: objectSchema({
         thread_id: { type: 'string', minLength: 1, description: 'Thread containing the turn.' },
         turn_id: { type: 'string', minLength: 1, description: 'Turn ID to interrupt.' },
@@ -188,58 +208,38 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
       validate: (value) => turnInterruptSchema.parse(value),
     },
     {
-      name: 'model-list',
-      description: 'List all available models for the authenticated Codex account.',
-      inputSchema: jsonSchema,
-      validate: (value) => value ?? {},
-    },
-    {
-      name: 'account-read',
-      description: 'Read the authenticated Codex account details — username, plan, and capabilities.',
-      inputSchema: jsonSchema,
-      validate: (value) => value ?? {},
-    },
-    {
-      name: 'account-rate-limits-read',
-      description: 'Read current rate limit status for the Codex account. Check before launching many parallel threads.',
-      inputSchema: jsonSchema,
-      validate: (value) => value ?? {},
-    },
-    {
-      name: 'skills-list',
-      description: 'List registered Codex skills available in this session.',
-      inputSchema: jsonSchema,
-      validate: (value) => value ?? {},
-    },
-    {
-      name: 'app-list',
-      description: 'List Codex apps available in this session.',
-      inputSchema: jsonSchema,
-      validate: (value) => value ?? {},
-    },
-    {
-      name: 'request-list',
-      description: 'List pending Codex server requests awaiting approval (command execution, file changes, permissions). Check this after starting turns — agents often need permission to proceed.',
+      name: 'codex-request-list',
+      description: [
+        [
+          'List pending approval requests from Codex agents (command execution, file changes, permissions).',
+          '',
+          'CRITICAL: Check this after every codex-turn-start — agents frequently pause and wait for approval before executing shell commands or writing files.',
+          'If an agent appears stuck, it is almost certainly waiting for a request to be approved.',
+          'Use codex-request-respond to approve or decline each request.',
+        ].join('\n'),
+        requestBanner,
+      ].filter(Boolean).join('\n\n'),
       inputSchema: objectSchema({
         include_resolved: { type: 'boolean', description: 'Include already-resolved requests. Default false.' },
       }),
       validate: (value) => requestListSchema.parse(value),
     },
     {
-      name: 'request-read',
-      description: 'Read details of a specific pending server request. Use to understand what the agent is asking before responding.',
-      inputSchema: objectSchema({
-        request_id: { type: ['string', 'number'], description: 'ID of the pending request.' },
-      }, ['request_id']),
-      validate: (value) => requestReadSchema.parse(value),
-    },
-    {
-      name: 'request-respond',
+      name: 'codex-request-respond',
       description: [
-        'Respond to a pending Codex server request (approve commands, grant permissions, answer questions).',
-        'The response shape depends on the request method. For command/file approvals use decision="accept".',
-        'For permission grants use scope and permissions. The tool auto-builds the right payload shape for common methods.',
-      ].join(' '),
+        [
+          'Approve or decline a pending Codex agent request (command execution, file changes, permissions, user input).',
+          '',
+          'Common patterns:',
+          '- Approve command/file change: decision="accept"',
+          '- Decline: decision="decline"',
+          '- Grant permissions: scope="session", permissions={...}',
+          '- Answer agent question: answers={ "key": { "answers": ["value"] } }',
+          '',
+          'The tool auto-builds the correct payload shape based on the request method.',
+        ].join('\n'),
+        requestBanner,
+      ].filter(Boolean).join('\n\n'),
       inputSchema: objectSchema({
         request_id: { type: ['string', 'number'], description: 'ID of the request to respond to.' },
         payload: { type: 'object', description: 'Raw response payload. Overrides all other fields if provided.' },
@@ -254,10 +254,16 @@ export function createToolDefinitions(modelIds: string[]): ToolDefinition[] {
       validate: (value) => requestRespondSchema.parse(value),
     },
     {
-      name: 'wait',
-      description: 'Block until a Codex operation completes or a pending request appears. Use after turn-start to wait for the agent to finish or ask for approval. Provide either operation_id or thread_id.',
+      name: 'codex-wait',
+      description: [
+        'Block until a Codex turn completes or a pending approval request appears.',
+        '',
+        'Use after codex-turn-start to wait for the agent to finish or ask for permission.',
+        'Provide operation_id (from turn-start response) for precise tracking, or thread_id to poll thread status.',
+        'When it returns with a pending request, use codex-request-list + codex-request-respond to unblock the agent.',
+      ].join('\n'),
       inputSchema: objectSchema({
-        operation_id: { type: 'string', description: 'Operation ID to wait on (from a turn-start response).' },
+        operation_id: { type: 'string', description: 'Operation ID to wait on (from a codex-turn-start response).' },
         thread_id: { type: 'string', description: 'Thread ID to wait on — polls until thread status is no longer active.' },
         timeout_ms: { type: 'integer', minimum: 1, maximum: 300000, description: 'Max wait time in ms. Default 120,000 (2 minutes).' },
         poll_interval_ms: { type: 'integer', minimum: 1, maximum: 5000, description: 'Poll interval in ms. Default 250.' },
@@ -275,6 +281,5 @@ export type TurnStartInput = z.infer<typeof turnStartSchema>;
 export type TurnSteerInput = z.infer<typeof turnSteerSchema>;
 export type TurnInterruptInput = z.infer<typeof turnInterruptSchema>;
 export type RequestListInput = z.infer<typeof requestListSchema>;
-export type RequestReadInput = z.infer<typeof requestReadSchema>;
 export type RequestRespondInput = z.infer<typeof requestRespondSchema>;
 export type WaitInput = z.infer<typeof waitSchema>;

package/src/services/app-server-client.ts

@@ -352,6 +352,12 @@ export class AppServerClient extends EventEmitter {
     }));
   }
 
+  listOperationsForThread(threadId: string): RuntimeOperation[] {
+    return [...this.operations.values()]
+      .filter((op) => op.threadId === threadId)
+      .map((op) => ({ ...op, pendingRequestIds: [...op.pendingRequestIds] }));
+  }
+
   listServerRequests(includeResolved = false): PendingServerRequest[] {
     return [...this.serverRequests.values()]
       .filter((request) => includeResolved || request.status === 'pending')

package/src/services/codex-runtime.ts

@@ -8,7 +8,7 @@ import {
   CODEX_APP_SERVER_COMMAND_ENV,
   REQUEST_TIMEOUT_MS,
 } from '../config/defaults.js';
-import type { PendingServerRequest } from '../types/codex.js';
+import type { PendingServerRequest, RuntimeOperation } from '../types/codex.js';
 import { AppServerClient, type BridgedOperationResult } from './app-server-client.js';
 import { appendFleetDeveloperInstructions } from './fleet-mode.js';
 import {
@@ -294,6 +294,7 @@ export class CodexRuntime {
         cwd: input.cwd ?? process.cwd(),
         approvalPolicy: 'on-request',
         sandbox: 'workspace-write',
+        reasoningEffort: 'high',
         developerInstructions: appendFleetDeveloperInstructions(input.developerInstructions),
         experimentalRawEvents: false,
         persistExtendedHistory: false,
@@ -319,6 +320,7 @@ export class CodexRuntime {
         cwd: input.cwd ?? process.cwd(),
         approvalPolicy: 'on-request',
         sandbox: 'workspace-write',
+        reasoningEffort: 'high',
         developerInstructions: appendFleetDeveloperInstructions(input.developerInstructions),
         persistExtendedHistory: false,
       };
@@ -364,6 +366,22 @@ export class CodexRuntime {
     };
   }
 
+  getOperationsForThread(threadId: string): RuntimeOperation[] {
+    try {
+      return this.getCurrentClient().listOperationsForThread(threadId);
+    } catch {
+      return [];
+    }
+  }
+
+  getAllOperations(): RuntimeOperation[] {
+    try {
+      return this.getCurrentClient().listOperations();
+    } catch {
+      return [];
+    }
+  }
+
   async getThreadEvents(threadId: string): Promise<unknown[]> {
     return this.getCurrentClient().getThreadEvents(threadId);
   }

package/src/services/model-catalog.ts

@@ -52,7 +52,7 @@ export function resolveModel(
   catalog: ModelCatalog,
   requestedModel?: string | undefined,
 ): ModelResolution {
-  const requested = requestedModel ?? catalog.defaultModelId;
+  const requested = requestedModel ?? catalog.defaultModelId ?? 'gpt-5.4';
   if (!requested) {
     throw new Error('No models available from model/list.');
   }