mcp-codex-worker 0.1.0 → 0.1.2

package/src/app.ts

@@ -11,6 +11,12 @@ import {
   type TurnSteerInput,
   type WaitInput,
 } from './mcp/tool-definitions.js';
+import { buildRequestBanner, buildThreadBanner } from './mcp/tool-banners.js';
+import {
+  renderRequestListMarkdown,
+  renderThreadListMarkdown,
+  renderThreadMarkdown,
+} from './mcp/task-markdown.js';
 import { OPERATION_POLL_INTERVAL_MS, REQUEST_TIMEOUT_MS } from './config/defaults.js';
 import { CodexRuntime } from './services/codex-runtime.js';
 
@@ -33,9 +39,13 @@ export class CodexWorkerApp {
   async listTools(): Promise<ToolDefinition[]> {
     try {
       const modelIds = await this.runtime.listVisibleModelIds();
-      return createToolDefinitions(modelIds);
+      return createToolDefinitions({
+        modelIds,
+        threadBanner: buildThreadBanner(this.runtime),
+        requestBanner: buildRequestBanner(this.runtime),
+      });
     } catch {
-      return createToolDefinitions([]);
+      return createToolDefinitions({ modelIds: [], threadBanner: '', requestBanner: '' });
     }
   }
 
@@ -44,8 +54,8 @@ export class CodexWorkerApp {
       {
         uri: 'codex://threads',
         name: 'Codex Threads',
-        description: 'Latest threads from `thread/list`',
-        mimeType: 'application/json',
+        description: 'All tracked threads with status',
+        mimeType: 'text/markdown',
       },
       {
         uri: 'codex://models',
@@ -72,8 +82,8 @@ export class CodexWorkerApp {
         {
           uri: `codex://thread/${threadId}`,
           name: `Thread ${threadId}`,
-          description: 'Thread from `thread/read`',
-          mimeType: 'application/json',
+          description: 'Thread status and guidance',
+          mimeType: 'text/markdown',
         },
         {
           uri: `codex://thread/${threadId}/events`,
@@ -98,18 +108,18 @@ export class CodexWorkerApp {
         }
       }
       return {
-        mimeType: 'application/json',
-        text: JSON.stringify(response, null, 2),
+        mimeType: 'text/markdown',
+        text: renderThreadListMarkdown(
+          response.data ?? [],
+          this.runtime.getPendingServerRequests(false),
+        ),
       };
     }
 
     if (uri === 'codex://models') {
-      const response = {
-        data: await this.runtime.listModels(false),
-      };
       return {
         mimeType: 'application/json',
-        text: JSON.stringify(response, null, 2),
+        text: JSON.stringify({ data: await this.runtime.listModels(false) }, null, 2),
       };
     }
 
@@ -153,8 +163,12 @@ export class CodexWorkerApp {
         includeTurns: true,
       });
       return {
-        mimeType: 'application/json',
-        text: JSON.stringify(response, null, 2),
+        mimeType: 'text/markdown',
+        text: renderThreadMarkdown(
+          response,
+          this.runtime.getOperationsForThread(threadId),
+          this.runtime.getPendingServerRequests(false),
+        ),
       };
     }
 
@@ -172,47 +186,29 @@ export class CodexWorkerApp {
     }
     const validated = tool.validate(args ?? {});
     switch (name) {
-      case 'thread-start':
+      case 'codex-thread-start':
         return this.handleThreadStart(validated as ThreadStartInput);
-      case 'thread-resume':
+      case 'codex-thread-resume':
         return this.handleThreadResume(validated as ThreadResumeInput);
-      case 'thread-read':
+      case 'codex-thread-read':
         return this.handleThreadRead(validated as ThreadReadInput);
-      case 'thread-list':
+      case 'codex-thread-list':
         return this.handleThreadList(validated as ThreadListInput);
-      case 'turn-start':
+      case 'codex-turn-start':
         return this.handleTurnStart(validated as TurnStartInput);
-      case 'turn-steer':
+      case 'codex-turn-steer':
         return this.handleTurnSteer(validated as TurnSteerInput);
-      case 'turn-interrupt':
+      case 'codex-turn-interrupt':
         return this.handleTurnInterrupt(validated as TurnInterruptInput);
-      case 'model-list':
-        return JSON.stringify({
-          data: await this.runtime.listModels(false),
-        }, null, 2);
-      case 'account-read':
-        return JSON.stringify(await this.runtime.request('account/read', {}), null, 2);
-      case 'account-rate-limits-read':
-        return JSON.stringify(await this.runtime.request('account/rateLimits/read', {}), null, 2);
-      case 'skills-list':
-        return JSON.stringify(await this.runtime.request('skills/list', {}), null, 2);
-      case 'app-list':
-        return JSON.stringify(await this.runtime.request('app/list', {}), null, 2);
-      case 'request-list':
-        return JSON.stringify({
-          requests: this.runtime.getPendingServerRequests(
+      case 'codex-request-list':
+        return renderRequestListMarkdown(
+          this.runtime.getPendingServerRequests(
             Boolean((validated as { include_resolved?: boolean }).include_resolved),
           ),
-        }, null, 2);
-      case 'request-read':
-        return JSON.stringify({
-          request: this.runtime.getPendingServerRequest(
-            (validated as { request_id: string | number }).request_id,
-          ) ?? null,
-        }, null, 2);
-      case 'request-respond':
+        );
+      case 'codex-request-respond':
         return this.handleRequestRespond(validated as RequestRespondInput);
-      case 'wait':
+      case 'codex-wait':
         return this.handleWait(validated as WaitInput);
       default:
         throw new Error(`Unhandled tool: ${name}`);
@@ -230,11 +226,18 @@ export class CodexWorkerApp {
     if (threadId) {
       this.runtime.rememberThreadId(threadId);
     }
-    return JSON.stringify({
-      method: 'thread/start',
-      remapped_from: built.remappedFrom,
-      result: response,
-    }, null, 2);
+
+    const remapNote = built.remappedFrom ? ` (remapped from ${built.remappedFrom})` : '';
+    return [
+      `**Thread started**`,
+      `thread_id: \`${threadId ?? 'unknown'}\``,
+      `model: \`${built.params.model as string}\`${remapNote}`,
+      '',
+      '**What to do next:**',
+      `- Use \`codex-turn-start\` with \`thread_id: "${threadId}"\` to send the agent its task.`,
+      '- After starting a turn, use `codex-wait` with `operation_id` to block until it finishes or asks for approval.',
+      '- Check `codex-request-list` after starting turns -- agents often need approval for commands or file changes.',
+    ].join('\n');
   }
 
   private async handleThreadResume(input: ThreadResumeInput): Promise<string> {
@@ -244,13 +247,17 @@ export class CodexWorkerApp {
       cwd: input.cwd,
       developerInstructions: input.developer_instructions,
     });
-    const response = await this.runtime.request('thread/resume', built.params);
+    await this.runtime.request('thread/resume', built.params);
     this.runtime.rememberThreadId(input.thread_id);
-    return JSON.stringify({
-      method: 'thread/resume',
-      remapped_from: built.remappedFrom,
-      result: response,
-    }, null, 2);
+
+    return [
+      `**Thread resumed**`,
+      `thread_id: \`${input.thread_id}\``,
+      '',
+      '**What to do next:**',
+      '- Use `codex-turn-start` to send a new task to this thread.',
+      '- The thread\'s previous context is loaded -- the agent remembers prior conversation.',
+    ].join('\n');
   }
 
   private async handleThreadRead(input: ThreadReadInput): Promise<string> {
@@ -259,7 +266,11 @@ export class CodexWorkerApp {
       includeTurns: input.include_turns ?? true,
     });
     this.runtime.rememberThreadId(input.thread_id);
-    return JSON.stringify(response, null, 2);
+    return renderThreadMarkdown(
+      response,
+      this.runtime.getOperationsForThread(input.thread_id),
+      this.runtime.getPendingServerRequests(false),
+    );
   }
 
   private async handleThreadList(input: ThreadListInput): Promise<string> {
@@ -274,7 +285,10 @@ export class CodexWorkerApp {
         this.runtime.rememberThreadId(row.id);
       }
     }
-    return JSON.stringify(response, null, 2);
+    return renderThreadListMarkdown(
+      response.data ?? [],
+      this.runtime.getPendingServerRequests(false),
+    );
   }
 
   private async handleTurnStart(input: TurnStartInput): Promise<string> {
@@ -287,11 +301,48 @@ export class CodexWorkerApp {
     const bridged = await this.runtime.requestWithBridge('turn/start', built.params, {
       threadId: input.thread_id,
     });
-    return JSON.stringify({
-      method: 'turn/start',
-      remapped_from: built.remappedFrom,
-      ...bridged,
-    }, null, 2);
+
+    const remapNote = built.remappedFrom ? ` (remapped from ${built.remappedFrom})` : '';
+    const header = [
+      `thread_id: \`${input.thread_id}\``,
+      `operation_id: \`${bridged.operationId}\`${remapNote}`,
+    ];
+
+    if (bridged.status === 'pending_request') {
+      const reqCount = bridged.pendingRequestIds?.length ?? 0;
+      return [
+        `**Turn started -- approval needed**`,
+        ...header,
+        `pending_requests: ${reqCount}`,
+        '',
+        '**ACTION REQUIRED:**',
+        'The agent needs approval before it can proceed. Use `codex-request-list` to see what it needs, then `codex-request-respond` to approve or decline.',
+        '',
+        '**After approving:**',
+        `Use \`codex-wait\` with \`operation_id: "${bridged.operationId}"\` to block until the turn completes.`,
+      ].join('\n');
+    }
+
+    if (bridged.status === 'completed') {
+      return [
+        `**Turn completed**`,
+        ...header,
+        '',
+        '**What to do next:**',
+        `- Use \`codex-thread-read\` with \`thread_id: "${input.thread_id}"\` to inspect the agent's output and file changes.`,
+        '- Use `codex-turn-start` to send follow-up instructions.',
+      ].join('\n');
+    }
+
+    return [
+      `**Turn started -- agent working**`,
+      ...header,
+      '',
+      '**What to do next:**',
+      `- Use \`codex-wait\` with \`operation_id: "${bridged.operationId}"\` to block until the agent finishes or asks for approval.`,
+      '- Check `codex-request-list` for any pending approvals.',
+      '- For parallel work, start turns on other threads now.',
+    ].join('\n');
   }
 
   private async handleTurnSteer(input: TurnSteerInput): Promise<string> {
@@ -303,18 +354,30 @@ export class CodexWorkerApp {
     const bridged = await this.runtime.requestWithBridge('turn/steer', params, {
       threadId: input.thread_id,
     });
-    return JSON.stringify({
-      method: 'turn/steer',
-      ...bridged,
-    }, null, 2);
+
+    return [
+      `**Turn steered**`,
+      `thread_id: \`${input.thread_id}\``,
+      `operation_id: \`${bridged.operationId}\``,
+      '',
+      'The agent is adjusting course with your new instructions.',
+      `Use \`codex-wait\` with \`operation_id: "${bridged.operationId}"\` to block until it finishes.`,
+    ].join('\n');
   }
 
   private async handleTurnInterrupt(input: TurnInterruptInput): Promise<string> {
-    const response = await this.runtime.request('turn/interrupt', {
+    await this.runtime.request('turn/interrupt', {
       threadId: input.thread_id,
       turnId: input.turn_id,
     });
-    return JSON.stringify(response, null, 2);
+
+    return [
+      `**Turn interrupted**`,
+      `thread_id: \`${input.thread_id}\``,
+      `turn_id: \`${input.turn_id}\``,
+      '',
+      'The turn has been stopped. Use `codex-turn-start` to begin a new turn with corrected instructions.',
+    ].join('\n');
   }
 
   private async handleRequestRespond(input: RequestRespondInput): Promise<string> {
@@ -325,12 +388,16 @@ export class CodexWorkerApp {
 
     const payload = this.buildServerRequestPayload(pending.method, input);
     await this.runtime.respondToServerRequest(input.request_id, payload);
-    return JSON.stringify({
-      request_id: input.request_id,
-      method: pending.method,
-      payload,
-      status: 'responded',
-    }, null, 2);
+
+    return [
+      `**Request responded**`,
+      `request_id: \`${String(input.request_id)}\``,
+      `method: \`${pending.method}\``,
+      '',
+      '**What to do next:**',
+      '- The agent will continue working. Use `codex-wait` to block until it finishes or needs another approval.',
+      '- Check `codex-request-list` for any remaining pending requests.',
+    ].join('\n');
   }
 
   private async handleWait(input: WaitInput): Promise<string> {
@@ -339,7 +406,41 @@ export class CodexWorkerApp {
 
     if (input.operation_id) {
       const operation = await this.runtime.waitForOperation(input.operation_id, timeoutMs, pollIntervalMs);
-      return JSON.stringify(operation, null, 2);
+      const threadId = operation.threadId ?? 'unknown';
+
+      if (operation.status === 'failed') {
+        return [
+          `**Operation failed**`,
+          `operation_id: \`${operation.operationId}\``,
+          `error: ${operation.error ?? 'unknown error'}`,
+          '',
+          '**What to do next:**',
+          `- Use \`codex-thread-read\` with \`thread_id: "${threadId}"\` to inspect what happened.`,
+          '- Fix the issue and use `codex-turn-start` to retry.',
+        ].join('\n');
+      }
+
+      if (operation.pendingRequestIds.length > 0) {
+        return [
+          `**Operation paused -- approval needed**`,
+          `operation_id: \`${operation.operationId}\``,
+          `pending_requests: ${operation.pendingRequestIds.length}`,
+          '',
+          '**ACTION REQUIRED:**',
+          'Use `codex-request-list` to see what the agent needs, then `codex-request-respond` to approve.',
+          `After approving, call \`codex-wait\` again with \`operation_id: "${operation.operationId}"\`.`,
+        ].join('\n');
+      }
+
+      return [
+        `**Operation completed**`,
+        `operation_id: \`${operation.operationId}\``,
+        `thread_id: \`${threadId}\``,
+        '',
+        '**What to do next:**',
+        `- Use \`codex-thread-read\` with \`thread_id: "${threadId}"\` to inspect the agent's output.`,
+        '- Use `codex-turn-start` to send follow-up instructions.',
+      ].join('\n');
     }
 
     if (input.thread_id) {
@@ -355,21 +456,22 @@ export class CodexWorkerApp {
         };
         const statusType = response.thread?.status?.type;
         if (statusType !== 'active') {
-          return JSON.stringify({
-            thread_id: input.thread_id,
-            status: statusType ?? 'unknown',
-            thread: response.thread ?? null,
-          }, null, 2);
+          return [
+            `**Thread idle**`,
+            `thread_id: \`${input.thread_id}\``,
+            `status: \`${statusType ?? 'unknown'}\``,
+            '',
+            '**What to do next:**',
+            `- Use \`codex-thread-read\` with \`thread_id: "${input.thread_id}"\` to review the agent's work.`,
+            '- Use `codex-turn-start` to send another task.',
+          ].join('\n');
         }
         await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
       }
       throw new Error(`Timed out waiting for thread ${input.thread_id}`);
     }
 
-    return JSON.stringify({
-      requests: this.runtime.getPendingServerRequests(false),
-      operations: [],
-    }, null, 2);
+    return renderRequestListMarkdown(this.runtime.getPendingServerRequests(false));
   }
 
   private buildServerRequestPayload(method: string, input: RequestRespondInput): unknown {

package/src/mcp/task-markdown.ts

@@ -0,0 +1,136 @@
+import type { PendingServerRequest, RuntimeOperation } from '../types/codex.js';
+
+interface ThreadData {
+  id: string | undefined;
+  status: { type?: string } | undefined;
+  model: string | undefined;
+  createdAt: string | undefined;
+}
+
+function extractThread(raw: unknown): ThreadData {
+  const obj = (raw ?? {}) as Record<string, unknown>;
+  const thread = (obj.thread ?? obj) as Record<string, unknown>;
+  return {
+    id: typeof thread.id === 'string' ? thread.id : undefined,
+    status: thread.status as ThreadData['status'],
+    model: typeof thread.model === 'string' ? thread.model : undefined,
+    createdAt: typeof thread.createdAt === 'string' ? thread.createdAt : undefined,
+  };
+}
+
+function requestsForThread(requests: PendingServerRequest[], threadId: string | undefined): PendingServerRequest[] {
+  if (!threadId) return requests;
+  return requests.filter((r) => {
+    const params = r.params as Record<string, unknown> | undefined;
+    return params?.threadId === threadId;
+  });
+}
+
+export function renderThreadMarkdown(
+  raw: unknown,
+  operations: RuntimeOperation[],
+  pendingRequests: PendingServerRequest[],
+): string {
+  const thread = extractThread(raw);
+  const threadId = thread.id ?? 'unknown';
+  const statusType = thread.status?.type ?? 'unknown';
+  const threadRequests = requestsForThread(pendingRequests, thread.id);
+
+  const lines: string[] = [
+    `# Thread: ${threadId}`,
+    '',
+    '| Field | Value |',
+    '|---|---|',
+    `| **Status** | \`${statusType}\` |`,
+    ...(thread.model ? [`| **Model** | \`${thread.model}\` |`] : []),
+    ...(thread.createdAt ? [`| **Created** | ${thread.createdAt} |`] : []),
+    '',
+  ];
+
+  if (operations.length > 0) {
+    lines.push('## Operations', '');
+    for (const op of operations) {
+      const time = op.completedAt ?? op.startedAt;
+      lines.push(`- \`${op.operationId}\` [${op.status}] ${op.method} -- ${time}`);
+    }
+    lines.push('');
+  }
+
+  if (threadRequests.length > 0) {
+    lines.push(`## Pending Requests (${threadRequests.length})`, '');
+    for (const req of threadRequests) {
+      lines.push(`### ${String(req.id)} (${req.method})`);
+      lines.push(`Use \`codex-request-respond\` with \`request_id: "${String(req.id)}"\` and \`decision: "accept"\`.`);
+      lines.push('');
+    }
+  }
+
+  lines.push('## What to do next', '');
+
+  if (threadRequests.length > 0) {
+    lines.push(`**ACTION REQUIRED** -- ${threadRequests.length} pending request(s) need your response. Use \`codex-request-list\` to see details, then \`codex-request-respond\` to approve or decline.`);
+  } else if (statusType === 'active') {
+    lines.push(`The agent is still working. Use \`codex-wait\` with \`thread_id: "${threadId}"\` to block until it finishes or needs approval.`);
+  } else if (statusType === 'idle' || statusType === 'completed') {
+    lines.push(`Thread is idle. Use \`codex-turn-start\` to send a new task, or \`codex-thread-read\` with \`include_turns: true\` for full conversation history.`);
+  } else {
+    lines.push(`Use \`codex-thread-resume\` to reload this thread before starting a turn.`);
+  }
+
+  return lines.join('\n');
+}
+
+export function renderThreadListMarkdown(
+  rawThreads: unknown[],
+  pendingRequests: PendingServerRequest[],
+): string {
+  const threads = rawThreads.map(extractThread);
+
+  const lines: string[] = [
+    `# Threads (${threads.length} total)`,
+    '',
+    '| ID | Status |',
+    '|---|---|',
+    ...threads.map((t) => `| ${t.id ?? 'unknown'} | ${t.status?.type ?? 'unknown'} |`),
+  ];
+
+  const pending = pendingRequests.filter((r) => r.status === 'pending');
+  if (pending.length > 0) {
+    lines.push('', `## Pending Requests (${pending.length})`, '');
+    for (const req of pending) {
+      const params = req.params as Record<string, unknown> | undefined;
+      const tid = typeof params?.threadId === 'string' ? params.threadId : '?';
+      lines.push(`- ${tid} / ${String(req.id)}: ${req.method}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function renderRequestListMarkdown(
+  requests: PendingServerRequest[],
+): string {
+  const pending = requests.filter((r) => r.status === 'pending');
+
+  if (pending.length === 0) {
+    return [
+      '**No pending requests**',
+      '',
+      'All agents are running without needing approval.',
+    ].join('\n');
+  }
+
+  const lines: string[] = [
+    `# Pending Requests (${pending.length})`,
+    '',
+    '| Request ID | Method | Created |',
+    '|---|---|---|',
+    ...pending.map((r) => `| ${String(r.id)} | ${r.method} | ${r.createdAt} |`),
+    '',
+    '## How to respond',
+    '',
+    'Use `codex-request-respond` with the `request_id` and `decision: "accept"` to approve, or `decision: "decline"` to reject.',
+  ];
+
+  return lines.join('\n');
+}

package/src/mcp/tool-banners.ts

@@ -0,0 +1,53 @@
+import type { CodexRuntime } from '../services/codex-runtime.js';
+
+export function buildThreadBanner(runtime: CodexRuntime): string {
+  const threadIds = runtime.listKnownThreadIds();
+  if (threadIds.length === 0) {
+    return '';
+  }
+
+  const operations = runtime.getAllOperations();
+  const requests = runtime.getPendingServerRequests(false);
+  const active = operations.filter((op) => op.status === 'running').length;
+  const pending = requests.length;
+
+  const lines = [
+    '---',
+    `AGENT STATUS: ${active} active | ${pending} pending requests`,
+  ];
+
+  for (const threadId of threadIds.slice(-3)) {
+    const threadOps = operations.filter((op) => op.threadId === threadId);
+    const threadReqs = requests.filter((r) => {
+      const params = r.params as Record<string, unknown> | undefined;
+      return params?.threadId === threadId;
+    });
+    const status = threadOps.some((op) => op.status === 'running') ? 'active' : 'idle';
+    const reqNote = threadReqs.length > 0 ? ` -- ${threadReqs.length} pending requests` : '';
+    lines.push(`- ${threadId} [${status}]${reqNote}`);
+  }
+
+  lines.push('Read codex://threads for full details.');
+  return lines.join('\n');
+}
+
+export function buildRequestBanner(runtime: CodexRuntime): string {
+  const requests = runtime.getPendingServerRequests(false);
+  if (requests.length === 0) {
+    return '';
+  }
+
+  const lines = [
+    '---',
+    `ACTION REQUIRED -- ${requests.length} request(s) waiting for your response:`,
+  ];
+
+  for (const req of requests.slice(0, 5)) {
+    const params = req.params as Record<string, unknown> | undefined;
+    const threadId = typeof params?.threadId === 'string' ? params.threadId : '?';
+    lines.push(`- ${String(req.id)} (${threadId}): ${req.method}`);
+  }
+
+  lines.push('Use codex-request-respond { "request_id": "<id>", "decision": "accept" }');
+  return lines.join('\n');
+}