@moxxy/plugin-provider-codex-agent 0.0.0-stage → 0.46.0

package/src/protocol.ts

@@ -0,0 +1,256 @@
+/**
+ * The part of the `codex app-server` protocol Moxxy speaks, written by hand
+ * from `codex app-server generate-ts` (0.155.1, checked against 0.163.0). Codex sends far more than
+ * this; anything not listed here is read as unknown and left alone.
+ */
+
+export type CodexApprovalPolicy =
+  | 'untrusted'
+  | 'on-request'
+  | 'never'
+  | { readonly granular: Readonly<Record<string, boolean>> };
+
+export type CodexSandboxPolicy =
+  | { readonly type: 'dangerFullAccess' }
+  | { readonly type: 'readOnly'; readonly networkAccess?: boolean }
+  | { readonly type: 'workspaceWrite'; readonly [key: string]: unknown }
+  | { readonly type: 'externalSandbox'; readonly [key: string]: unknown };
+
+/** The thread's settings in `thread/settings/updated` (only what Moxxy reads). */
+export interface CodexThreadSettingsReport {
+  readonly approvalPolicy: CodexApprovalPolicy;
+  readonly approvalsReviewer: CodexApprovalsReviewer;
+  readonly sandboxPolicy: CodexSandboxPolicy;
+}
+
+/** What `thread/start` and `thread/resume` answer: the thread as Codex really runs it. */
+export interface CodexThreadResponse {
+  readonly thread: { readonly id: string };
+  readonly model: string;
+  readonly approvalPolicy: CodexApprovalPolicy;
+  readonly sandbox: CodexSandboxPolicy;
+  readonly approvalsReviewer?: CodexApprovalsReviewer;
+  readonly reasoningEffort: string | null;
+  readonly serviceTier?: string | null;
+}
+
+/** Who answers Codex's approvals: the person, or Codex's own reviewer. */
+export type CodexApprovalsReviewer = 'user' | 'auto_review' | 'guardian_subagent';
+
+/** What `config/read` answers: the person's effective Codex config, as far as Moxxy reads it. */
+/** The person's Codex config as `config/read` reports it for the folder (only what Moxxy reads). */
+/** `skills/list`: the skills Codex has where each folder asked for runs (generated `SkillsListResponse`, fields Moxxy reads). */
+export interface CodexSkillsList {
+  readonly data: ReadonlyArray<{
+    readonly cwd: string;
+    readonly skills: ReadonlyArray<{ readonly name: string; readonly description: string; readonly enabled: boolean }>;
+  }>;
+}
+
+/**
+ * `thread/backgroundTerminals/list` (experimental, 0.155.1 and later): the
+ * commands still running in a thread, by the item that started them. An
+ * interrupted turn's commands stay here until `terminate` ends them.
+ */
+export interface CodexBackgroundTerminals {
+  readonly data: ReadonlyArray<{ readonly itemId: string; readonly processId: string }>;
+  readonly nextCursor: string | null;
+}
+
+export interface CodexConfigRead {
+  readonly config: {
+    readonly model_reasoning_summary?: string | null;
+    readonly approval_policy?: CodexApprovalPolicy | null;
+    readonly sandbox_mode?: 'read-only' | 'workspace-write' | 'danger-full-access' | null;
+    readonly sandbox_workspace_write?: {
+      readonly writable_roots: ReadonlyArray<string>;
+      readonly network_access: boolean;
+      readonly exclude_tmpdir_env_var: boolean;
+      readonly exclude_slash_tmp: boolean;
+    } | null;
+    readonly approvals_reviewer?: CodexApprovalsReviewer | null;
+    readonly tools?: { readonly update_plan?: { readonly enabled?: boolean } | null } | null;
+    /** The person's own MCP servers, by name. */
+    readonly mcp_servers?: Readonly<Record<string, { readonly enabled?: boolean }>> | null;
+  };
+}
+
+/** `model/list`: one page of the models Codex offers the account (generated `ModelListResponse`, fields Moxxy reads). */
+export interface CodexModelList {
+  readonly data: ReadonlyArray<{
+    readonly id: string;
+    readonly hidden?: boolean;
+    readonly inputModalities?: ReadonlyArray<string>;
+    readonly supportedReasoningEfforts?: ReadonlyArray<unknown>;
+    readonly additionalSpeedTiers?: ReadonlyArray<string>;
+  }>;
+  readonly nextCursor?: string | null;
+}
+
+export type CodexUserInput =
+  | { readonly type: 'text'; readonly text: string; readonly text_elements: ReadonlyArray<never> }
+  | { readonly type: 'image'; readonly url: string }
+  | { readonly type: 'localImage'; readonly path: string };
+
+export type CodexCollaborationMode = {
+  readonly mode: 'plan' | 'default';
+  readonly settings: { readonly model: string; readonly reasoning_effort: string | null; readonly developer_instructions: null };
+};
+
+/** Fields of `thread/settings/update`; each applies to the thread's later turns. */
+export interface CodexThreadSettings {
+  readonly approvalPolicy?: CodexApprovalPolicy;
+  readonly sandboxPolicy?: CodexSandboxPolicy;
+  readonly model?: string;
+  readonly effort?: string;
+  readonly collaborationMode?: CodexCollaborationMode;
+}
+
+export type CodexTurnStatus = 'completed' | 'interrupted' | 'failed' | 'inProgress';
+
+export interface CodexTurn {
+  readonly id: string;
+  readonly status: CodexTurnStatus;
+  /** `codexErrorInfo` is Codex's code for the failure: a string (`usageLimitExceeded`) or an object for some. */
+  readonly error?: { readonly message: string; readonly codexErrorInfo?: unknown } | null;
+}
+
+/** `resetsAt` is in epoch seconds. */
+export interface CodexRateLimitWindow {
+  readonly usedPercent: number;
+  readonly windowDurationMins: number | null;
+  readonly resetsAt: number | null;
+}
+
+/** `account/rateLimits/updated`: a sparse update, where a missing window keeps the one seen before. */
+export interface CodexRateLimitSnapshot {
+  readonly primary?: CodexRateLimitWindow | null;
+  readonly secondary?: CodexRateLimitWindow | null;
+  readonly rateLimitReachedType?: string | null;
+}
+
+export type CodexGoalStatus = 'active' | 'paused' | 'blocked' | 'usageLimited' | 'budgetLimited' | 'complete';
+
+export interface CodexGoal {
+  readonly objective: string;
+  readonly status: CodexGoalStatus;
+}
+
+/** A question Codex's plan mode asks inside its message (`delivery: 'async'`). */
+export interface CodexAsyncQuestion {
+  readonly title: string;
+  readonly options: ReadonlyArray<string> | null;
+}
+
+export type CodexItem =
+  | {
+      readonly type: 'agentMessage';
+      readonly id: string;
+      readonly text: string;
+      readonly phase?: string | null;
+      readonly delivery?: 'async' | null;
+      readonly questions?: ReadonlyArray<CodexAsyncQuestion> | null;
+    }
+  | { readonly type: 'plan'; readonly id: string; readonly text: string }
+  | { readonly type: 'reasoning'; readonly id: string; readonly summary: ReadonlyArray<string>; readonly content: ReadonlyArray<string> }
+  | {
+      readonly type: 'commandExecution';
+      readonly id: string;
+      readonly command: string;
+      readonly cwd: string;
+      readonly status: string;
+      readonly aggregatedOutput: string | null;
+      readonly exitCode: number | null;
+      readonly commandActions?: ReadonlyArray<{ readonly command?: string }>;
+    }
+  | {
+      readonly type: 'fileChange';
+      readonly id: string;
+      readonly status: string;
+      readonly changes: ReadonlyArray<CodexFileChange>;
+    }
+  | {
+      readonly type: 'mcpToolCall';
+      readonly id: string;
+      readonly server: string;
+      readonly tool: string;
+      readonly status: string;
+      readonly arguments: unknown;
+      readonly result: unknown;
+      readonly error: { readonly message: string } | null;
+    }
+  | { readonly type: 'webSearch'; readonly id: string; readonly query: string; readonly action?: CodexWebSearchAction | null }
+  | { readonly type: 'imageView'; readonly id: string; readonly path: string }
+  | { readonly type: 'sleep'; readonly id: string; readonly durationMs: number }
+  | {
+      readonly type: 'imageGeneration';
+      readonly id: string;
+      readonly status: string;
+      readonly revisedPrompt: string | null;
+      /** The picture, base64. */
+      readonly result: string;
+      readonly failure: { readonly type: string } | null;
+      readonly savedPath?: string;
+    };
+
+export type CodexWebSearchAction =
+  | { readonly type: 'search'; readonly query?: string; readonly queries?: ReadonlyArray<string> }
+  | { readonly type: 'open_page'; readonly url?: string }
+  | { readonly type: 'find_in_page'; readonly url?: string; readonly pattern?: string }
+  | { readonly type: 'other' };
+
+/** One file of a `fileChange`: for `add` the diff is the new content, for `update` a unified diff; `move_path` names where an update moved it. */
+export interface CodexFileChange {
+  readonly path: string;
+  readonly kind: { readonly type: string; readonly move_path?: string | null };
+  readonly diff?: string;
+}
+
+const KNOWN_ITEMS = new Set<string>(['agentMessage', 'plan', 'reasoning', 'commandExecution', 'fileChange', 'mcpToolCall', 'webSearch', 'imageView', 'sleep', 'imageGeneration']);
+
+/** Items Moxxy leaves out of the chat on purpose, and why. Every other kind shows: one Moxxy does not know, as a call named after it. */
+export const CODEX_ITEMS_LEFT_OUT: Readonly<Record<string, string>> = {
+  userMessage: "the person's own message, which Moxxy already shows",
+  hookPrompt: "text the person's Codex hooks add to the prompt, not something Codex did",
+  contextCompaction: "Codex shortening its own context; Moxxy's record of the conversation stays whole",
+  collabAgentToolCall: "Codex starting, waiting on or messaging its subagents, which their own rows show",
+  subAgentActivity: 'shown as the subagent row, read before the turn items',
+};
+
+/** An item Moxxy reads, or `undefined` for one it shows as a plain call or leaves out. */
+export function knownItem(value: unknown): CodexItem | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const { type, id } = value as { type?: unknown; id?: unknown };
+  return typeof type === 'string' && typeof id === 'string' && KNOWN_ITEMS.has(type) ? (value as CodexItem) : undefined;
+}
+
+/** An item of a kind Moxxy neither reads nor leaves out: its fields, without the id, kind and status. */
+export interface CodexOtherItem {
+  readonly type: string;
+  readonly id: string;
+  readonly status?: string;
+  readonly fields: Readonly<Record<string, unknown>>;
+}
+
+export function otherItem(value: unknown): CodexOtherItem | undefined {
+  if (typeof value !== 'object' || value === null || knownItem(value)) return undefined;
+  const { type, id, status, ...fields } = value as Record<string, unknown>;
+  if (typeof type !== 'string' || typeof id !== 'string' || type in CODEX_ITEMS_LEFT_OUT) return undefined;
+  return { type, id, ...(typeof status === 'string' ? { status } : {}), fields };
+}
+
+export interface CodexTokenUsage {
+  readonly inputTokens: number;
+  readonly cachedInputTokens: number;
+  readonly outputTokens: number;
+}
+
+/** `item/tool/requestUserInput` (experimental): a blocking question with ids. */
+export interface CodexUserInputQuestion {
+  readonly id: string;
+  readonly header: string;
+  readonly question: string;
+  readonly isOther: boolean;
+  readonly isSecret: boolean;
+  readonly options: ReadonlyArray<{ readonly label: string; readonly description: string }> | null;
+}

package/src/subagents.test.ts

@@ -0,0 +1,47 @@
+/** Codex's subagents, shaped as Codex 0.155 reports them: activity items on the conversation's thread, the work on the subagent's own. */
+import { describe, expect, it } from 'vitest';
+import { CodexSubagents } from './subagents.js';
+
+const CHILD = 'thread-child';
+const activity = (kind: 'started' | 'completed') => ({ type: 'subAgentActivity', id: `act-${kind}`, kind, agentThreadId: CHILD, agentPath: '/root/inspect_folder' });
+const onChild = (item: Record<string, unknown>) => ({ threadId: CHILD, turnId: 'turn-child', item });
+
+describe("Codex's subagents", () => {
+  it('start once, named after their path, however often Codex reports the start', () => {
+    const subagents = new CodexSubagents();
+
+    expect(subagents.activity(activity('started'))).toEqual([{ type: 'subagent_started', id: CHILD, label: 'inspect folder', agentType: 'default' }]);
+    expect(subagents.activity(activity('started'))).toEqual([]);
+  });
+
+  it('show the tools a subagent runs in its own thread, and end with its answer and tokens', () => {
+    const subagents = new CodexSubagents();
+    subagents.activity(activity('started'));
+
+    const ran = subagents.fromThread('item/completed', onChild({ type: 'commandExecution', id: 'exec-1', command: "/bin/zsh -lc 'ls -la'", cwd: '/repo', status: 'completed', aggregatedOutput: 'a.txt', exitCode: 0 }));
+    subagents.fromThread('item/completed', onChild({ type: 'agentMessage', id: 'msg-1', text: 'Two files.', phase: 'final_answer' }));
+    subagents.fromThread('thread/tokenUsage/updated', { threadId: CHILD, turnId: 'turn-child', tokenUsage: { total: { totalTokens: 47282 }, last: { totalTokens: 23747 } } });
+
+    expect(ran).toEqual([{ type: 'subagent_tool_call', id: CHILD, name: 'Bash', input: { command: 'ls -la', cwd: '/repo' } }]);
+    expect(subagents.activity(activity('completed'))).toEqual([{ type: 'subagent_completed', id: CHILD, text: 'Two files.', tokensUsed: 47282 }]);
+    expect(subagents.activity(activity('completed'))).toEqual([]);
+  });
+
+  it("end as stopped when their own turn is interrupted, since Codex reports no interruption on the conversation's thread between turns", () => {
+    const subagents = new CodexSubagents();
+    subagents.activity(activity('started'));
+    subagents.fromThread('turn/started', { threadId: CHILD, turn: { id: 'turn-child', status: 'inProgress' } });
+
+    expect(subagents.fromThread('turn/completed', { threadId: CHILD, turn: { id: 'turn-child', status: 'interrupted' } })).toEqual([
+      { type: 'subagent_completed', id: CHILD, text: '', error: 'The subagent was stopped.', stopped: true },
+    ]);
+    expect(subagents.running()).toEqual([]);
+    expect(subagents.activity({ ...activity('completed'), kind: 'interrupted' })).toEqual([]);
+  });
+
+  it('leave out threads that are not a subagent Codex announced', () => {
+    const subagents = new CodexSubagents();
+
+    expect(subagents.fromThread('item/completed', onChild({ type: 'commandExecution', id: 'exec-1', command: 'ls', cwd: '/repo', status: 'completed' }))).toEqual([]);
+  });
+});

package/src/subagents.ts

@@ -0,0 +1,98 @@
+import type { AgentBackgroundWork, AgentStepEvent } from '@moxxy/sdk';
+import { toolCallOf } from './translate.js';
+import type { CodexItem } from './protocol.js';
+
+interface Running {
+  readonly label: string;
+  text: string;
+  tokens: number | undefined;
+  done: boolean;
+  /** The turn running in its thread now, which Stop interrupts. */
+  turn?: string;
+}
+
+/**
+ * Codex's subagents. Codex announces one with a `subAgentActivity` item on the conversation's
+ * thread and runs it in a thread of its own; its tool calls and answer come from that thread.
+ * They outlive a Moxxy turn, so the session keeps them.
+ */
+export class CodexSubagents {
+  private readonly agents = new Map<string, Running>();
+
+  /** A `subAgentActivity` item on the conversation's thread. */
+  activity(item: unknown): AgentStepEvent[] {
+    const a = (item ?? {}) as { kind?: unknown; agentThreadId?: unknown; agentPath?: unknown };
+    if (typeof a.agentThreadId !== 'string') return [];
+    const id = a.agentThreadId;
+    const known = this.agents.get(id);
+    if (a.kind === 'started') {
+      if (known) return [];
+      const label = labelOf(a.agentPath);
+      this.agents.set(id, { label, text: '', tokens: undefined, done: false });
+      return [{ type: 'subagent_started', id, label, agentType: 'default' }];
+    }
+    if ((a.kind !== 'completed' && a.kind !== 'interrupted') || !known || known.done) return [];
+    return [end(id, known, a.kind === 'interrupted')];
+  }
+
+  /** A notification from a thread other than the conversation's: a subagent's work, if it is one. */
+  fromThread(method: string, params: Record<string, unknown>): AgentStepEvent[] {
+    const id = typeof params.threadId === 'string' ? params.threadId : '';
+    const agent = this.agents.get(id);
+    if (!agent || agent.done) return [];
+    if (method === 'turn/started' || method === 'turn/completed') {
+      const turn = params.turn as { id?: unknown; status?: unknown } | undefined;
+      if (method === 'turn/started') {
+        if (typeof turn?.id === 'string') agent.turn = turn.id;
+        return [];
+      }
+      delete agent.turn;
+      // Between the conversation's turns Codex reports a stopped subagent only here.
+      return turn?.status === 'interrupted' ? [end(id, agent, true)] : [];
+    }
+    if (method === 'thread/tokenUsage/updated') {
+      const total = (params.tokenUsage as { total?: { totalTokens?: unknown } } | undefined)?.total;
+      if (total && typeof total.totalTokens === 'number') agent.tokens = total.totalTokens;
+      return [];
+    }
+    if (method !== 'item/completed') return [];
+    const item = params.item as CodexItem | undefined;
+    if (!item) return [];
+    if (item.type === 'agentMessage') {
+      if (!item.text) return [];
+      agent.text = item.text;
+      // The final answer shows as the subagent's answer when it ends.
+      return (item as { phase?: unknown }).phase === 'final_answer' ? [] : [{ type: 'subagent_message', id, text: item.text }];
+    }
+    const call = toolCallOf(item);
+    return call ? [{ type: 'subagent_tool_call', id, name: call.name, input: call.input }] : [];
+  }
+
+  /** The subagents still working, as background work. */
+  running(): AgentBackgroundWork[] {
+    return [...this.agents].flatMap(([id, agent]) => (agent.done ? [] : [{ id, kind: 'agent' as const, label: agent.label }]));
+  }
+
+  /** The turn running in a working subagent's thread, if any. */
+  turnOf(id: string): string | undefined {
+    const agent = this.agents.get(id);
+    return agent && !agent.done ? agent.turn : undefined;
+  }
+}
+
+function end(id: string, agent: Running, stopped: boolean): AgentStepEvent {
+  agent.done = true;
+  return {
+    type: 'subagent_completed',
+    id,
+    text: agent.text,
+    ...(agent.tokens !== undefined ? { tokensUsed: agent.tokens } : {}),
+    ...(stopped ? { error: 'The subagent was stopped.', stopped: true as const } : {}),
+  };
+}
+
+/** "/root/inspect_folder" → "inspect folder". */
+export function labelOf(path: unknown): string {
+  const last = typeof path === 'string' ? path.split('/').filter(Boolean).pop() : undefined;
+  return last ? last.replace(/[_-]+/g, ' ') : 'subagent';
+}

package/src/translate.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+import { TurnTranslator } from './translate.js';
+
+describe("Codex's web searches", () => {
+  it('are shown once finished, with the query Codex only knows by then', () => {
+    const translator = new TurnTranslator();
+    const started = { type: 'webSearch', id: 'ws1', query: '', action: null, results: null };
+    expect(translator.translate('item/started', { item: started })).toEqual([]);
+
+    const completed = { ...started, action: { type: 'search', query: 'frankfurter api v2' } };
+    expect(translator.translate('item/completed', { item: completed })).toEqual([
+      { type: 'tool_call', callId: 'ws1', name: 'web_search', input: { query: 'frankfurter api v2' } },
+      { type: 'tool_result', callId: 'ws1', ok: true, output: '' },
+    ]);
+  });
+
+  it('show the page Codex opened', () => {
+    const translator = new TurnTranslator();
+    const item = { type: 'webSearch', id: 'ws2', query: '', action: { type: 'open_page', url: 'https://frankfurter.dev/' }, results: null };
+    expect(translator.translate('item/completed', { item })[0]).toEqual({
+      type: 'tool_call',
+      callId: 'ws2',
+      name: 'web_search',
+      input: { url: 'https://frankfurter.dev/' },
+    });
+  });
+});
+
+describe("Codex's file changes", () => {
+  const change = (path: string, kind: Record<string, unknown>, diff: string) => ({ path, kind, diff });
+  const completed = (id: string, changes: unknown[]) => ({ type: 'fileChange', id, status: 'completed', changes });
+
+  it('show a change to one file as a diff, from the unified diff Codex sends', () => {
+    const translator = new TurnTranslator('/repo');
+    const diff = '@@ -1,2 +1,2 @@\n const host = "x";\n-const port = 5432;\n+const port = 5433;\n';
+    const [, result] = translator.translate('item/completed', { item: completed('fc1', [change('/repo/src/db.ts', { type: 'update', move_path: null }, diff)]) });
+
+    expect(result).toMatchObject({
+      type: 'tool_result',
+      callId: 'fc1',
+      ok: true,
+      output: { forModel: diff, display: { kind: 'file-diff', path: 'src/db.ts', mode: 'update', added: 1, removed: 1 } },
+    });
+  });
+
+  it('show a new file as all added, from the content Codex sends for it', () => {
+    const translator = new TurnTranslator('/repo');
+    const [, result] = translator.translate('item/completed', { item: completed('fc2', [change('/repo/notes.md', { type: 'add' }, '# Notes\nport 5433\n')]) });
+
+    expect(result).toMatchObject({ output: { display: { kind: 'file-diff', path: 'notes.md', mode: 'create', added: 2, removed: 0 } } });
+  });
+
+  it('keep a change to several files, or a deleted file, as the text Codex sends', () => {
+    const translator = new TurnTranslator('/repo');
+    const two = completed('fc3', [change('/repo/a.ts', { type: 'add' }, 'a\n'), change('/repo/b.ts', { type: 'add' }, 'b\n')]);
+    const removed = completed('fc4', [change('/repo/old.ts', { type: 'delete' }, 'gone\n')]);
+
+    expect(translator.translate('item/completed', { item: two })[1]).toMatchObject({ ok: true, output: 'a\n\nb\n' });
+    expect(translator.translate('item/completed', { item: removed })[1]).toMatchObject({ ok: true, output: 'gone\n' });
+  });
+});
+
+describe("Codex's images", () => {
+  it('keep the screenshot an MCP tool returned, once, with its text', () => {
+    const translator = new TurnTranslator('/repo');
+    const shot = { type: 'image', data: '/9j/AAA', mimeType: 'image/jpeg', _meta: { 'codex/imageDetail': 'original' } };
+    const item = {
+      type: 'mcpToolCall',
+      id: 'm1',
+      server: 'cua_repl',
+      tool: 'js',
+      status: 'completed',
+      arguments: { code: 'await nodeRepl.emitImage(await app.getScreenshot());', title: 'Oglądam testy w przeglądarce' },
+      result: { content: [{ type: 'text', text: 'Arc, tests.html' }, shot, shot], structuredContent: null, _meta: {} },
+      error: null,
+    };
+
+    expect(translator.translate('item/completed', { item })[1]).toEqual({
+      type: 'tool_result',
+      callId: 'm1',
+      ok: true,
+      output: { forModel: 'Arc, tests.html', mediaType: 'image/jpeg', base64: '/9j/AAA' },
+    });
+  });
+
+  it('keep every different screenshot an MCP tool returned, each once, in order', () => {
+    const translator = new TurnTranslator('/repo');
+    const shot = (data: string) => ({ type: 'image', data, mimeType: 'image/jpeg' });
+    const content = [{ type: 'text', text: 'Three windows' }, shot('/9j/ONE'), shot('/9j/ONE'), shot('/9j/TWO'), shot('/9j/TWO'), shot('/9j/THREE')];
+    const item = { type: 'mcpToolCall', id: 'm3', server: 'cua_repl', tool: 'js', status: 'completed', arguments: {}, result: { content }, error: null };
+
+    expect(translator.translate('item/completed', { item })[1]).toMatchObject({
+      output: {
+        forModel: 'Three windows',
+        base64: '/9j/ONE',
+        moreImages: [
+          { mediaType: 'image/jpeg', base64: '/9j/TWO' },
+          { mediaType: 'image/jpeg', base64: '/9j/THREE' },
+        ],
+      },
+    });
+  });
+
+  it('keep the result of an MCP tool without an image as Codex sent it', () => {
+    const translator = new TurnTranslator('/repo');
+    const result = { content: [{ type: 'text', text: 'ok' }], structuredContent: null };
+    const item = { type: 'mcpToolCall', id: 'm2', server: 'docs', tool: 'search', status: 'completed', arguments: {}, result, error: null };
+
+    expect(translator.translate('item/completed', { item })[1]).toMatchObject({ ok: true, output: result });
+  });
+
+  it('show the image file Codex viewed, read from disk', () => {
+    const read: string[] = [];
+    const translator = new TurnTranslator('/repo', (path) => {
+      read.push(path);
+      return { mediaType: 'image/png', base64: 'iVBOR' };
+    });
+
+    expect(translator.translate('item/completed', { item: { type: 'imageView', id: 'v1', path: '/repo/shot.png' } })).toEqual([
+      { type: 'tool_call', callId: 'v1', name: 'view_image', input: { path: '/repo/shot.png' } },
+      { type: 'tool_result', callId: 'v1', ok: true, output: { forModel: '/repo/shot.png', mediaType: 'image/png', base64: 'iVBOR' } },
+    ]);
+    expect(read).toEqual(['/repo/shot.png']);
+  });
+});
+
+describe("Codex's checklist", () => {
+  it('shows each plan update as a call whose result is the whole list, with why Codex changed it', () => {
+    const translator = new TurnTranslator();
+    const plan = [
+      { step: 'Create a.txt', status: 'completed' },
+      { step: 'Create b.txt', status: 'inProgress' },
+      { step: 'Create c.txt', status: 'pending' },
+    ];
+
+    const events = translator.translate('turn/plan/updated', { threadId: 't1', turnId: 'turn-1', explanation: 'a.txt is done', plan });
+
+    expect(events).toEqual([
+      { type: 'tool_call', callId: 'plan-turn-1-1', name: 'update_plan', input: { plan, explanation: 'a.txt is done' } },
+      {
+        type: 'tool_result',
+        callId: 'plan-turn-1-1',
+        ok: true,
+        output: {
+          forModel: '[x] Create a.txt\n[ ] Create b.txt\n[ ] Create c.txt',
+          display: {
+            kind: 'step-list',
+            explanation: 'a.txt is done',
+            steps: [
+              { text: 'Create a.txt', status: 'completed' },
+              { text: 'Create b.txt', status: 'in_progress' },
+              { text: 'Create c.txt', status: 'pending' },
+            ],
+          },
+        },
+      },
+    ]);
+    expect(translator.translate('turn/plan/updated', { threadId: 't1', turnId: 'turn-1', explanation: null, plan })[0]).toMatchObject({ callId: 'plan-turn-1-2' });
+  });
+});