Official

codex

Codex agent provider: runs the Codex CLI's app-server for each account.

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/codex@0.2.3

Permissions in 0.2.3

  • Provide agents agents.provideMediumAdds agents to the app.Provide the Codex agent and pass its tool calls to plugin tools
  • Run named programs processMediumStarts the listed programs.Run the Codex CLI, and ask or tell the installer that owns it (npm or Homebrew) about a newer versionPrograms: codexnpmbrew
  • Environment variables envMediumReads the listed environment variables.Find each account's Codex home, and pass extra app-server arguments set in CODEX_ARGSVariables: HOMECODEX_HOMECODEX_ARGS
  • Read files fs.readMediumReads files in the listed places.Read, once, the accounts the previous Codex provider keptPlaces: its own data folder

Files

agent.test.ts115.3 KB
// Ported from the Rust plugin's agent.rs tests: notifications are routed
// straight into the agent, and the tests that drove a real RpcClient
// against a scripted Python peer drive the SDK's process transport
// against a scripted fake peer instead.
import * as Effect from "effect/Effect";
import { test } from "node:test";
import assert from "node:assert/strict";
import { testAgent } from "./testing.test.ts";
import { CodexAgent, newSession, versionOf } from "./agent.ts";
import { defaultAccount } from "./instances.ts";
import type { FakePeer, TestMessage, HostScript, PeerScript } from "../sdk/testing.ts";
import type { Event } from "./types.ts";
import type { ProcessReport } from "../sdk/agent.ts";
import type * as wire from "./wire.ts";
import type { AgentMethods, HistoryAlias, TranscriptItem } from "divergence";
import * as z from "zod";
import { fakeApi, memoryStorage, settle } from "../sdk/testing.ts";
import { clearCache } from "../sdk/maintenance.ts";

const SESSION = "thread-1";
const RUN = "run-1";

/// A scripted app-server: answers `initialize`, every other request with
/// `handlers[method](params, message, peer)` (no answer when that returns
/// `undefined`), and a method it has no handler for with an error, as the
/// real one does.
type Handlers = Record<string, (params: Record<string, unknown>, message: TestMessage, peer: FakePeer) => unknown>;
type Keys<T> = T extends unknown ? keyof T : never;
type Field<T, K> = T extends unknown ? (K extends keyof T ? T[K] : never) : never;
type ObservedEvent = Event & { [K in Keys<Event>]?: Field<Event, K> };
function appServer(handlers: Handlers = {}): PeerScript {
  return (message, peer) => {
    if (message.method === undefined) return;
    if (message.method === "initialize") {
      peer.reply(message, { userAgent: "divergence/0.155.1 (Mac OS 26.5.0; arm64) iTerm.app" });
      return;
    }
    const handler = handlers[message.method];
    if (!handler) {
      if (message.id !== undefined)
        peer.send({
          jsonrpc: "2.0",
          id: message.id,
          error: { code: -32601, message: `unknown method ${message.method}` },
        });
      return;
    }
    const result = handler(message.params, message, peer);
    if (result !== undefined) peer.reply(message, result);
  };
}

/// An agent with one registered session and an active run.
function harness({
  handlers,
  onHost,
  env = { HOME: "/Users/me" },
}: { handlers?: Handlers; onHost?: HostScript; env?: Record<string, string> } = {}) {
  const api = fakeApi({ onSpawn: (program) => (program === "codex" ? appServer(handlers) : () => {}), onHost });
  const agent = testAgent(api, env);
  const events: ObservedEvent[] = [];
  agent.emit = (event) => events.push(event);
  const state = newSession("/w");
  state.run = RUN;
  state.turn = "turn-1";
  agent.sessions.set(SESSION, state);
  return { agent, events, api };
}

function notify(agent: ReturnType<typeof testAgent>, method: wire.Routed, params: wire.Notification) {
  agent.routeNotification(method, params);
}

const tasks = (events: ObservedEvent[]) => events.filter((event) => event.event === "task");

test("PTY commands surviving a turn remain tasks and receive late output and completion", () => {
  const { agent, events } = harness();
  const item = {
    type: "commandExecution",
    id: "build",
    processId: "42",
    command: "cargo build --release",
    status: "inProgress",
  };
  notify(agent, "item/started", { threadId: SESSION, turnId: "turn-1", item });
  notify(agent, "item/commandExecution/outputDelta", {
    threadId: SESSION,
    turnId: "turn-1",
    itemId: "build",
    delta: "compiling\n",
  });
  assert.equal(tasks(events).length, 0, "foreground commands keep their tool rows");
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  assert.equal(tasks(events).at(-1)?.status, "running");
  notify(agent, "item/commandExecution/outputDelta", {
    threadId: SESSION,
    turnId: "turn-1",
    itemId: "build",
    delta: "done\n",
  });
  assert.equal(tasks(events).at(-1)?.outputDelta, "done\n");
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: { ...item, status: "completed", aggregatedOutput: "compiling\ndone\n", exitCode: 0 },
  });
  assert.equal(tasks(events).at(-1)?.status, "completed");
  assert.equal(tasks(events).at(-1)?.kind, "terminal");
  assert.equal(agent.terminals.size, 0);
});

function spawnItem(id: string, sender: string, child: string, prompt: string) {
  return {
    type: "collabAgentToolCall",
    id,
    tool: "spawnAgent",
    status: "completed",
    senderThreadId: sender,
    receiverThreadIds: [child],
    prompt,
    model: "gpt-5.5",
    reasoningEffort: "low",
    agentsStates: { [child]: { status: "pendingInit", message: null } },
  };
}

test("text deltas accumulate under one item id", () => {
  const { agent, events } = harness();
  for (const delta of ["P", "ONG", " "]) {
    notify(agent, "item/agentMessage/delta", { threadId: SESSION, turnId: "turn-1", itemId: "msg_1", delta });
  }
  // The completed item must not repeat text that already streamed.
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    completedAtMs: 0,
    item: { type: "agentMessage", id: "msg_1", text: "PONG " },
  });
  assert.deepEqual(
    events.map((event) => [event.event, event.itemId, event.text, event.mode, event.runId, event.sessionId]),
    [
      ["text_delta", "msg_1", "P", "append", RUN, SESSION],
      ["text_delta", "msg_1", "ONG", "append", RUN, SESSION],
      ["text_delta", "msg_1", " ", "append", RUN, SESSION],
    ],
  );
});

test("unstreamed messages and reasoning arrive as replacements", () => {
  const { agent, events } = harness();
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: { type: "reasoning", id: "rs_1", summary: ["Weighing options"], content: [] },
  });
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: { type: "agentMessage", id: "msg_1", text: "done" },
  });
  assert.deepEqual(events[0], {
    sessionId: SESSION,
    runId: RUN,
    event: "reasoning_delta",
    itemId: "rs_1",
    text: "Weighing options",
    mode: "replace",
  });
  assert.deepEqual(events[1], {
    sessionId: SESSION,
    runId: RUN,
    event: "text_delta",
    itemId: "msg_1",
    text: "done",
    mode: "replace",
  });
});

test("reasoning summary parts are separated, and whitespace deltas are kept", () => {
  const { agent, events } = harness();
  notify(agent, "item/reasoning/summaryPartAdded", { threadId: SESSION, itemId: "rs_1" });
  assert.equal(events.length, 0, "no break before anything streamed");
  notify(agent, "item/reasoning/summaryTextDelta", { threadId: SESSION, itemId: "rs_1", delta: "**Plan**" });
  notify(agent, "item/reasoning/summaryPartAdded", { threadId: SESSION, itemId: "rs_1" });
  notify(agent, "item/reasoning/textDelta", { threadId: SESSION, itemId: "rs_1", delta: " " });
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: { type: "reasoning", id: "rs_1", summary: ["**Plan**"], content: [] },
  });
  assert.deepEqual(
    events.map((event) => event.text),
    ["**Plan**", "\n\n", " "],
  );
  assert.ok(events.every((event) => event.mode === "append"));
});

test("reasoning that is only the stdin notice of codex exec is left out", () => {
  const { agent, events } = harness();
  for (const delta of ["Reading additional ", "input from stdin..."]) {
    notify(agent, "item/reasoning/textDelta", { threadId: SESSION, itemId: "rs_stdin", delta });
  }
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: { type: "reasoning", id: "rs_stdin", summary: [], content: ["Reading additional input from stdin..."] },
  });
  // Unstreamed, the completed item alone is dropped too.
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: { type: "reasoning", id: "rs_2", summary: ["Reading additional input from stdin..."], content: [] },
  });
  assert.deepEqual(Array.from(events), []);

  // Text that starts the same way but goes on is sent whole.
  notify(agent, "item/reasoning/textDelta", { threadId: SESSION, itemId: "rs_3", delta: "Reading " });
  notify(agent, "item/reasoning/textDelta", { threadId: SESSION, itemId: "rs_3", delta: "the parser" });
  notify(agent, "item/reasoning/textDelta", { threadId: SESSION, itemId: "rs_3", delta: " first" });
  // A held prefix that ends the item is not lost.
  notify(agent, "item/reasoning/textDelta", { threadId: SESSION, itemId: "rs_4", delta: "Read" });
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: { type: "reasoning", id: "rs_4", summary: ["Read"], content: [] },
  });
  assert.deepEqual(
    events.map((event) => [event.itemId, event.text, event.mode]),
    [
      ["rs_3", "Reading the parser", "append"],
      ["rs_3", " first", "append"],
      ["rs_4", "Read", "append"],
    ],
  );
});

test("a command streams its output, then completes", () => {
  const { agent, events } = harness();
  const item = (status: string, output: string | null, exitCode: number | null) => ({
    type: "commandExecution",
    id: "exec-1",
    command: "ls -a",
    cwd: "/w",
    status,
    commandActions: [{ type: "listFiles", command: "ls -a", path: "/w" }],
    aggregatedOutput: output,
    exitCode,
  });
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    startedAtMs: 0,
    item: item("inProgress", null, null),
  });
  notify(agent, "item/commandExecution/outputDelta", {
    threadId: SESSION,
    turnId: "turn-1",
    itemId: "exec-1",
    delta: ".\n..\n",
  });
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    completedAtMs: 0,
    item: item("completed", ".\n..\n", 0),
  });
  const [started, output, completed] = events;
  assert.equal(started.event, "tool_call_started");
  assert.deepEqual([started.id, started.kind, started.status], ["exec-1", "search", "running"]);
  assert.deepEqual(output, {
    sessionId: SESSION,
    runId: RUN,
    event: "tool_call_updated",
    id: "exec-1",
    outputDelta: ".\n..\n",
  });
  assert.equal(completed.event, "tool_call_updated");
  assert.equal(completed.status, "completed");
  assert.deepEqual(completed.content, [
    { type: "terminal", command: "ls -a", cwd: "/w", output: ".\n..\n", exitCode: 0 },
  ]);
  assert.deepEqual(completed.locations, [{ path: "/w" }]);
});

test("a command that outlives its turn still completes its row", () => {
  const { agent, events } = harness();
  const item = (status: string, exitCode: number | null) => ({
    type: "commandExecution",
    id: "exec-late",
    command: "sleep 60",
    cwd: "/w",
    status,
    commandActions: [{ type: "unknown", command: "sleep 60" }],
    aggregatedOutput: null,
    exitCode,
  });
  notify(agent, "item/started", { threadId: SESSION, turnId: "turn-1", item: item("inProgress", null) });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  // The next turn has begun when the old command ends.
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "turn-2", status: "inProgress" } });
  events.length = 0;
  notify(agent, "item/completed", { threadId: SESSION, turnId: "turn-1", item: item("completed", 0) });
  assert.deepEqual(
    events.map((event) => [event.event, event.id, event.status]),
    [["tool_call_updated", "exec-late", "completed"]],
  );
  // A late item that is not a tool neither starts a row nor reaches the chat.
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: { type: "agentMessage", id: "msg-late", text: "stale" },
  });
  assert.equal(events.length, 1);
});

test("a tool that completes without starting is reported once, as started", () => {
  const { agent, events } = harness();
  notify(agent, "item/completed", { threadId: SESSION, item: { type: "webSearch", id: "ws-1", query: "rust" } });
  assert.deepEqual(
    events.map((event) => event.event),
    ["tool_call_started"],
  );
});

test("a file edit reports a unified diff, and patch updates replace it", () => {
  const { agent, events } = harness();
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    startedAtMs: 0,
    item: {
      type: "fileChange",
      id: "fc-1",
      status: "inProgress",
      changes: [{ path: "/w/a.rs", kind: { type: "update", move_path: null }, diff: "@@ -1 +1 @@\n-a\n+b\n" }],
    },
  });
  notify(agent, "item/fileChange/patchUpdated", {
    threadId: SESSION,
    itemId: "fc-1",
    changes: [{ path: "/w/a.rs", diff: "@@ -1 +1 @@\n-a\n+c\n" }],
  });
  const [started, patched] = events;
  assert.equal(started.kind, "edit");
  assert.equal(present(started.locations)[0].path, "/w/a.rs");
  assert.deepEqual(started.content, [{ type: "diff", path: "/w/a.rs", diff: "@@ -1 +1 @@\n-a\n+b\n" }]);
  assert.deepEqual(patched.content, [{ type: "diff", path: "/w/a.rs", diff: "@@ -1 +1 @@\n-a\n+c\n" }]);
});

test("a completed turn finishes the run exactly once", () => {
  const { agent, events } = harness();
  const completed = {
    threadId: SESSION,
    turn: { id: "turn-1", items: [], itemsView: "summary", status: "completed", error: null },
  };
  notify(agent, "turn/completed", completed);
  notify(agent, "turn/completed", completed);
  assert.deepEqual(events, [
    { sessionId: SESSION, runId: RUN, event: "run_finished", outcome: { status: "completed" } },
  ]);
  assert.equal(present(agent.sessions.get(SESSION)).turn, null);
});

test("an interrupted turn is cancelled and a failed one reports the codex message", () => {
  const { agent, events } = harness();
  notify(agent, "turn/completed", {
    threadId: SESSION,
    turn: { id: "turn-1", items: [], status: "failed", error: { message: "model overloaded" } },
  });
  assert.deepEqual(events[0].outcome, { status: "failed", message: "model overloaded" });
  const other = harness();
  notify(other.agent, "turn/completed", {
    threadId: SESSION,
    turn: { id: "turn-1", items: [], status: "interrupted" },
  });
  assert.deepEqual(other.events[0].outcome, { status: "cancelled" });
  const third = harness();
  notify(third.agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "inProgress" } });
  assert.equal(third.events.length, 0, "a turn still in progress ends nothing");
});

test("error notifications leave notices, a retried one only a warning, but only a terminal turn fails the run", () => {
  const { agent, events } = harness();
  notify(agent, "error", { threadId: SESSION, turnId: "turn-1", willRetry: true, error: { message: "retrying" } });
  notify(agent, "error", {
    threadId: SESSION,
    turnId: "turn-1",
    willRetry: false,
    error: { message: "stream closed" },
  });
  assert.equal(agent.runOf(SESSION), RUN);
  assert.equal(events.filter((event) => event.event === "run_finished").length, 0);
  notify(agent, "turn/completed", {
    threadId: SESSION,
    turn: { id: "turn-1", status: "failed", error: { message: "stream closed" } },
  });
  assert.deepEqual(
    events.map((event) => [
      event.event,
      event.level ?? event.outcome?.status,
      event.message ?? (event.outcome?.status === "failed" ? event.outcome.message : undefined),
    ]),
    [
      ["notice", "warning", "retrying"],
      ["notice", "error", "stream closed"],
      ["run_finished", "failed", "stream closed"],
    ],
  );
});

test("token usage and thread names reach the host", () => {
  const { agent, events } = harness();
  const breakdown = (totalTokens: number) => ({
    totalTokens,
    inputTokens: 0,
    cachedInputTokens: 0,
    cacheWriteInputTokens: 0,
    outputTokens: 0,
    reasoningOutputTokens: 0,
  });
  notify(agent, "thread/tokenUsage/updated", {
    threadId: SESSION,
    turnId: "turn-1",
    tokenUsage: { total: breakdown(100), last: breakdown(40), modelContextWindow: 1000 },
  });
  notify(agent, "thread/name/updated", { threadId: SESSION, threadName: "Fix the parser" });
  assert.deepEqual(events[0], { sessionId: SESSION, runId: RUN, event: "usage", usedTokens: 40, contextWindow: 1000 });
  assert.deepEqual(events[1], { sessionId: SESSION, runId: RUN, event: "session_info", title: "Fix the parser" });
});

test("automatic approval successes are quiet while rejections and failures remain visible", () => {
  const { agent, events } = harness();
  agent.onNotification("guardianWarning", {
    threadId: SESSION,
    message: "Automatic approval review approved (risk: low, authorization: high): User requested this.",
  });
  assert.equal(events.length, 0, "a successful automatic review must not notify the user");
  const messages = [
    "Automatic approval review denied (risk: high, authorization: low): Upload was not approved.",
    "Automatic approval review failed: Reviewer unavailable.",
    "Automatic approval review rejected too many approval requests for this turn; interrupting the turn.",
  ];
  for (const message of messages) agent.onNotification("guardianWarning", { threadId: SESSION, message });
  assert.deepEqual(
    events.map((event) => event.message),
    messages,
  );
  assert.ok(events.every((event) => event.event === "notice" && event.level === "warning"));
  agent.onNotification("warning", { threadId: SESSION, message: "Automatic approval review approved elsewhere." });
  assert.equal(events.length, 4, "only the provider's automatic-review success diagnostic is suppressed");
});

test("plans, warnings, reroutes and rate limits reach the host", () => {
  const { agent, events } = harness();
  notify(agent, "turn/plan/updated", { threadId: SESSION, plan: [{ step: "one", status: "inProgress" }] });
  notify(agent, "warning", { threadId: SESSION, message: "slow" });
  notify(agent, "warning", { message: "no thread" });
  notify(agent, "configWarning", { message: "bad key" });
  notify(agent, "model/rerouted", { threadId: SESSION, fromModel: "a", toModel: "b" });
  notify(agent, "item/mcpToolCall/progress", { threadId: SESSION, itemId: "m1", message: "halfway" });
  notify(agent, "account/rateLimits/updated", { rateLimits: { primary: { usedPercent: 5, windowDurationMins: 300 } } });
  notify(agent, "item/started", { threadId: SESSION, item: { type: "contextCompaction", id: "c1" } });
  notify(agent, "item/completed", { threadId: SESSION, item: { type: "contextCompaction", id: "c1" } });
  assert.deepEqual(
    events.map((event) => event.event),
    ["plan", "notice", "notice", "notice", "tool_call_updated", "usage_limits", "compacting", "compacted"],
  );
  assert.deepEqual(events[0].entries, [{ content: "one", status: "in_progress" }]);
  assert.deepEqual([events[2].sessionId, events[2].level, events[2].message], ["", "warning", "bad key"]);
  assert.equal(events[3].message, "Codex switched from a to b.");
  assert.equal(events[4].outputDelta, "halfway\n");
  assert.equal(events[5].sessionId, SESSION);
  assert.equal(present(events[5].windows)[0].label, "5 hours");
});

test("an approval holds the server request until the user answers", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 7,
    method: "item/commandExecution/requestApproval",
    params: {
      kind: "command",
      threadId: SESSION,
      turnId: "turn-1",
      itemId: "exec-9",
      startedAtMs: 0,
      environmentId: null,
      command: "rm -rf build",
      cwd: "/w",
      commandActions: [{ type: "unknown", command: "rm -rf build" }],
    },
  });
  await settle();
  const request = present(events.find((event) => event.event === "approval"));
  assert.equal(request.title, "Run a command");
  assert.equal(present(request.toolCall).id, "exec-9");
  assert.equal(present(request.toolCall).kind, "execute");
  assert.equal(present(request.toolCall).status, "pending");
  assert.deepEqual(
    present(request.options).map((option) => option.kind),
    ["allow_once", "allow_always", "reject_once", "reject_always"],
  );
  assert.equal(
    peer.received.some((message) => message.id === 7),
    false,
    "nothing is answered before the user",
  );

  await agent.respondToApproval({ approvalId: request.id, optionId: "acceptForSession" });
  const reply = await peer.waitFor((message) => message.id === 7);
  assert.deepEqual(reply.result, { decision: "acceptForSession" });
  assert.equal(agent.approvals.size, 0);
  assert.deepEqual(
    await agent.respondToApproval({ approvalId: request.id, optionId: "accept" }),
    { notPending: true },
    "a second answer finds nothing waiting, which is not an error",
  );
});

test("an unknown approval option declines, and a file change asks with its reason", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 8,
    method: "item/fileChange/requestApproval",
    params: { threadId: SESSION, turnId: "t", itemId: "fc-2", grantRoot: "/w/out" },
  });
  await settle();
  const request = present(events.find((event) => event.event === "approval"));
  assert.equal(request.title, "Allow writes under /w/out");
  assert.deepEqual([present(request.toolCall).kind, present(request.toolCall).name], ["edit", "apply_patch"]);
  await agent.respondToApproval({ approvalId: request.id, optionId: "maybe" });
  assert.deepEqual((await peer.waitFor((message) => message.id === 8)).result, { decision: "decline" });
});

// Codex's file change approval names the item only: the card shows the
// changes the item started with.
test("a file change approval carries the item's diffs", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "t",
    startedAtMs: 0,
    item: {
      type: "fileChange",
      id: "fc-3",
      status: "inProgress",
      changes: [{ path: "/w/new.js", kind: { type: "add" }, diff: "x;\n" }],
    },
  });
  peer.send({
    jsonrpc: "2.0",
    id: 9,
    method: "item/fileChange/requestApproval",
    params: { threadId: SESSION, turnId: "t", itemId: "fc-3", startedAtMs: 0 },
  });
  await settle();
  const request = present(events.find((event) => event.event === "approval"));
  assert.equal(request.title, "Apply file changes");
  assert.deepEqual(present(request.toolCall).content, [
    { type: "diff", path: "/w/new.js", oldText: "", newText: "x;\n" },
  ]);
});

// An approval answered in another Codex client used to leave our card
// waiting for an answer that could never arrive.
test("an approval answered elsewhere is withdrawn and never answered", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 11,
    method: "item/commandExecution/requestApproval",
    params: { threadId: SESSION, turnId: "turn-1", itemId: "exec-9", command: "rm -rf build" },
  });
  await settle();
  const approval = present(events.find((event) => event.event === "approval"));
  peer.send({ jsonrpc: "2.0", method: "serverRequest/resolved", params: { threadId: SESSION, requestId: 11 } });
  await settle();
  const resolved = present(events.find((event) => event.event === "approval_resolved"));
  assert.equal(resolved.id, approval.id);
  assert.equal(agent.approvals.size, 0);
  await settle();
  assert.equal(
    peer.received.some((message) => message.id === 11),
    false,
    "a late reply was sent for a resolved request",
  );
});

test("a question is answered with codex's answer map, or withdrawn", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: "q-1",
    method: "item/tool/requestUserInput",
    params: {
      threadId: SESSION,
      turnId: "t",
      itemId: "i",
      questions: [
        {
          id: "target",
          header: "Target",
          question: "Which one?",
          isOther: true,
          options: [
            { label: "Desktop", description: "The app" },
            { label: "Mobile", description: "" },
          ],
        },
        { id: "notes", header: "", question: "Anything else?", isOther: false, options: null },
        { id: "flag", header: "Flag", question: "", options: null },
      ],
    },
  });
  await settle();
  const question = present(events.find((event) => event.event === "question"));
  assert.equal(question.responseMode, "tool");
  assert.deepEqual(question.fields[0], {
    id: "target",
    label: "Target",
    description: "Which one?",
    kind: "select",
    allowOther: true,
    required: true,
    options: [
      { value: "Desktop", label: "Desktop", description: "The app" },
      { value: "Mobile", label: "Mobile" },
    ],
  });
  assert.deepEqual(
    [question.fields[1].label, question.fields[1].kind, question.fields[1].allowOther],
    ["Anything else?", "text", false],
  );
  await agent.respondToQuestion({
    questionId: question.id,
    answer: { values: { target: "Mobile", notes: ["a", "b"], flag: true }, cancelled: false },
  });
  const reply = await peer.waitFor((message) => message.id === "q-1");
  assert.deepEqual(reply.result, {
    answers: { target: { answers: ["Mobile"] }, notes: { answers: ["a", "b"] }, flag: { answers: ["true"] } },
  });

  peer.send({
    jsonrpc: "2.0",
    id: 12,
    method: "item/tool/requestUserInput",
    params: { threadId: SESSION, questions: [{ id: "x", question: "?" }] },
  });
  await settle();
  peer.send({ jsonrpc: "2.0", method: "serverRequest/resolved", params: { requestId: 12 } });
  await settle();
  assert.equal(events.filter((event) => event.event === "question_resolved").length, 1);
  assert.equal(agent.questions.size, 0);
});

test("server requests nobody here answers are refused at once", async () => {
  const { agent, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({ jsonrpc: "2.0", id: 21, method: "item/permissions/requestApproval", params: {} });
  const reply = await peer.waitFor((message) => message.id === 21);
  assert.equal(z.object({ code: z.number() }).parse(reply.error).code, -32601);
  // An elicitation in a mode nothing here renders is refused the same way.
  peer.send({
    jsonrpc: "2.0",
    id: 22,
    method: "mcpServer/elicitation/request",
    params: { threadId: SESSION, mode: "telepathy", message: "?" },
  });
  assert.equal(
    z.object({ code: z.number() }).parse((await peer.waitFor((message) => message.id === 22)).error).code,
    -32601,
  );
});

// Computer Use and other MCP tools ask through an elicitation rather than
// either of Codex's command/file approval methods. The advertised
// persistence scopes must become choices, then return in response
// metadata instead of being copied into ordinary form content.
test("an MCP tool elicitation becomes an approval with persistence", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 8,
    method: "mcpServer/elicitation/request",
    params: {
      threadId: SESSION,
      turnId: "turn-1",
      serverName: "cua_repl",
      mode: "form",
      _meta: {
        codex_approval_kind: "mcp_tool_call",
        persist: ["session", "always"],
        tool_name: "get_app_state",
        tool_params_display: [{ display_name: "App", value: "Divergence Dev" }],
      },
      message: 'Allow Computer Use to use "Divergence Dev"?',
      requestedSchema: { type: "object", properties: {} },
    },
  });
  await settle();
  const request = present(events.find((event) => event.event === "approval"));
  assert.equal(request.title, 'Allow Computer Use to use "Divergence Dev"?');
  assert.deepEqual(
    present(request.options).map((option) => [option.id, option.name]),
    [
      ["accept", "Allow once"],
      ["acceptForSession", "Allow for this session"],
      ["acceptAlways", "Always allow"],
      ["cancel", "Cancel"],
    ],
  );
  assert.equal(
    peer.received.some((message) => message.id === 8),
    false,
    "nothing is answered before the user",
  );

  await agent.respondToApproval({ approvalId: request.id, optionId: "acceptAlways" });
  const reply = await peer.waitFor((message) => message.id === 8);
  assert.deepEqual(reply.result, { action: "accept", content: {}, _meta: { persist: "always" } });
  assert.equal(agent.approvals.size, 0);

  // A single advertised scope offers only that scope.
  peer.send({
    jsonrpc: "2.0",
    id: 18,
    method: "mcpServer/elicitation/request",
    params: {
      threadId: SESSION,
      mode: "form",
      _meta: { codex_approval_kind: "mcp_tool_call", persist: "session" },
      message: "Allow?",
    },
  });
  await settle();
  const second = events.filter((event) => event.event === "approval")[1];
  assert.deepEqual(
    present(second.options).map((option) => option.id),
    ["accept", "acceptForSession", "cancel"],
  );
  await agent.respondToApproval({ approvalId: second.id, optionId: "cancel" });
  assert.deepEqual((await peer.waitFor((message) => message.id === 18)).result, {
    action: "cancel",
    content: null,
    _meta: null,
  });
});

test("an MCP form elicitation round-trips structured answers", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 9,
    method: "mcpServer/elicitation/request",
    params: {
      threadId: SESSION,
      turnId: "turn-1",
      serverName: "deploy",
      mode: "form",
      _meta: null,
      message: "Configure the deployment",
      requestedSchema: {
        type: "object",
        properties: {
          branch: { type: "string", title: "Branch", description: "Git branch to deploy" },
          force: { type: "boolean", title: "Force" },
          target: {
            type: "string",
            title: "Target",
            oneOf: [
              { const: "main", title: "Production" },
              { const: "dev", title: "Staging" },
            ],
          },
          reviewers: { type: "array", title: "Reviewers", items: { type: "string", enum: ["ada", "grace"] } },
          attempts: { type: "integer", title: "Attempts" },
        },
        required: ["branch", "target"],
      },
    },
  });
  await settle();
  const request = present(events.find((event) => event.event === "question"));
  assert.equal(request.message, "Configure the deployment");
  const field = (id: string) => present(request.fields.find((candidate) => candidate.id === id));
  assert.equal(field("branch").label, "Branch");
  assert.equal(field("branch").description, "Git branch to deploy");
  assert.equal(field("branch").kind, "text");
  assert.equal(field("branch").required, true);
  assert.equal(field("force").kind, "boolean");
  assert.equal(field("force").required, false);
  assert.equal(field("target").kind, "select");
  assert.equal(present(field("target").options)[0].label, "Production");
  assert.equal(field("reviewers").kind, "multi_select");
  assert.deepEqual(
    present(field("reviewers").options).map((option) => option.value),
    ["ada", "grace"],
  );
  assert.equal(field("attempts").kind, "text");

  await agent.respondToQuestion({
    questionId: request.id,
    answer: {
      values: { branch: "feature/cua", force: true, target: "dev", reviewers: ["ada", "grace"], attempts: "3" },
      cancelled: false,
    },
  });
  const reply = await peer.waitFor((message) => message.id === 9);
  assert.deepEqual(reply.result, {
    action: "accept",
    content: { branch: "feature/cua", force: true, target: "dev", reviewers: ["ada", "grace"], attempts: 3 },
    _meta: null,
  });
  assert.equal(agent.questions.size, 0);
});

test("an MCP URL elicitation becomes an external link question", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 10,
    method: "mcpServer/elicitation/request",
    params: {
      threadId: SESSION,
      turnId: "turn-1",
      serverName: "github",
      mode: "url",
      _meta: null,
      message: "Sign in to GitHub to continue",
      url: "https://example.com/oauth/start",
      elicitationId: "oauth-1",
    },
  });
  await settle();
  const request = present(events.find((event) => event.event === "question"));
  assert.equal(request.message, "Sign in to GitHub to continue");
  assert.equal(request.url, "https://example.com/oauth/start");
  assert.deepEqual(request.fields, []);

  await agent.respondToQuestion({ questionId: request.id, answer: { values: {}, cancelled: false } });
  assert.deepEqual((await peer.waitFor((message) => message.id === 10)).result, {
    action: "accept",
    content: null,
    _meta: null,
  });

  // Anything but an HTTP(S) page is refused with a notice, never shown.
  peer.send({
    jsonrpc: "2.0",
    id: 11,
    method: "mcpServer/elicitation/request",
    params: { threadId: SESSION, mode: "url", message: "Open", url: "file:///etc/passwd" },
  });
  assert.deepEqual((await peer.waitFor((message) => message.id === 11)).result, {
    action: "cancel",
    content: null,
    _meta: null,
  });
  assert.equal(events.filter((event) => event.event === "question").length, 1);
  assert.ok(
    events.some(
      (event) => event.event === "notice" && event.level === "error" && /invalid external URL/.test(event.message),
    ),
  );
});

// `item/tool/call` goes to the host with the agent's id, the session and
// Codex's call id, and the host's result goes back as content items.
test("a dynamic tool call is answered with the host's result", async () => {
  const { agent, api } = harness({
    onHost: (method, params) => {
      if (method === "host/tools.call") return { content: [{ type: "text", text: "12:00" }] };
      return {};
    },
  });
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 5,
    method: "item/tool/call",
    params: {
      threadId: SESSION,
      turnId: "turn-1",
      callId: "call-7",
      namespace: null,
      tool: "now",
      arguments: { zone: "UTC" },
    },
  });
  const reply = await peer.waitFor((message) => message.id === 5);
  assert.deepEqual(reply.result, { contentItems: [{ type: "inputText", text: "12:00" }], success: true });
  assert.deepEqual(present(api.hostCalls.find((call) => call.method === "host/tools.call")).params, {
    agentId: "codex",
    sessionId: SESSION,
    name: "now",
    input: { zone: "UTC" },
    callId: "call-7",
  });
});

test("a subagent's tool call belongs to the chat that spawned it, and a failure is a failed result", async () => {
  const { agent, api } = harness({
    onHost: (method) => {
      if (method === "host/tools.call") throw new Error("no tool named now");
      return {};
    },
  });
  await agent.client();
  notify(agent, "item/started", { threadId: SESSION, item: spawnItem("call-1", SESSION, "child-1", "One") });
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 6,
    method: "item/tool/call",
    params: { threadId: "child-1", callId: "c", tool: "now", arguments: {} },
  });
  const reply = await peer.waitFor((message) => message.id === 6);
  assert.deepEqual(reply.result, { contentItems: [{ type: "inputText", text: "no tool named now" }], success: false });
  assert.equal(present(api.hostCalls.find((call) => call.method === "host/tools.call")).params.sessionId, SESSION);
});

test("a dynamic tool call item shows its result", () => {
  const { agent, events } = harness();
  const item = (status: string, contentItems: wire.Item["contentItems"], success: boolean | null) => ({
    threadId: SESSION,
    turnId: "turn-1",
    item: {
      type: "dynamicToolCall",
      id: "call-7",
      namespace: null,
      tool: "execute",
      arguments: { code: "return await now()" },
      status,
      contentItems,
      success,
      durationMs: null,
    },
  });
  notify(agent, "item/started", item("inProgress", null, null));
  notify(agent, "item/completed", item("failed", [{ type: "inputText", text: "no clock" }], false));
  assert.equal(events[0].event, "tool_call_started");
  assert.equal(events[0].title, "execute");
  assert.equal(events[0].status, "running");
  assert.equal(z.object({ code: z.string() }).parse(events[0].input).code, "return await now()");
  assert.equal(events[1].event, "tool_call_updated");
  assert.equal(events[1].status, "failed");
  assert.deepEqual(events[1].content, [{ type: "text", text: "no clock" }]);
});

// Codex runs each subagent in its own thread. Its events must reach the
// parent chat tagged with the task.
test("a spawned subagent becomes a task", () => {
  const { agent, events } = harness();
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    item: {
      type: "collabAgentToolCall",
      id: "collab-1",
      tool: "spawnAgent",
      senderThreadId: SESSION,
      receiverThreadIds: ["child-1"],
      agentsStates: {},
      prompt: "Search the tests\nand report",
    },
  });
  const task = present(events.shift());
  assert.equal(task.event, "task");
  assert.deepEqual(
    [task.id, task.title, task.status, task.sessionId, task.taskId],
    ["child-1", "Search the tests", "running", SESSION, undefined],
  );
  notify(agent, "item/agentMessage/delta", {
    threadId: "child-1",
    turnId: "turn-9",
    itemId: "msg_1",
    delta: "found it",
  });
  const text = present(events.shift());
  assert.equal(text.sessionId, SESSION, "the child's events belong to the parent chat");
  assert.equal(text.taskId, "child-1");
});

// Multi-agent v1: a `spawnAgent` call names the child, and `wait` reports
// its final answer in `agentsStates`. The answer is the result; the title
// stays the prompt's first line.
test("a v1 subagent keeps its prompt title and shows its answer", () => {
  const { agent, events } = harness();
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: spawnItem("call-spawn", SESSION, "child-1", "Count the tests\nthen report"),
  });
  let task = present(events.pop());
  assert.equal(task.title, "Count the tests");
  assert.equal(task.prompt, "Count the tests\nthen report");
  assert.equal(task.toolCallId, "call-spawn");
  assert.deepEqual([task.model, task.effort], ["gpt-5.5", "low"]);
  assert.equal(task.status, "running");
  assert.equal(task.parentTaskId, undefined);

  // The child's own record names it.
  notify(agent, "thread/started", {
    thread: {
      id: "child-1",
      preview: "Count the tests\nthen report",
      createdAt: 1,
      updatedAt: 1,
      parentThreadId: SESSION,
      agentNickname: "Euler",
      agentRole: "explorer",
      source: {
        subAgent: {
          thread_spawn: {
            parent_thread_id: SESSION,
            depth: 1,
            agent_path: null,
            agent_nickname: "Euler",
            agent_role: "explorer",
          },
        },
      },
    },
  });
  task = present(events.pop());
  assert.equal(task.name, "Euler");
  assert.equal(task.title, "Count the tests");
  assert.equal(task.startedAt, new Date(1000).toISOString(), "the earlier start wins");

  // Its turn ends: done for now, but it can be given more.
  notify(agent, "turn/started", { threadId: "child-1", turn: { id: "turn-c1", items: [], status: "inProgress" } });
  notify(agent, "item/completed", {
    threadId: "child-1",
    turnId: "turn-c1",
    item: { type: "agentMessage", id: "msg-c1", text: "There are 42 tests." },
  });
  notify(agent, "turn/completed", { threadId: "child-1", turn: { id: "turn-c1", items: [], status: "completed" } });
  const last = present(tasks(events).pop());
  assert.equal(last.status, "idle");
  assert.equal(last.summary, "There are 42 tests.");
  assert.ok(last.endedAt);
  assert.equal(
    events.some((event) => event.event === "run_finished"),
    false,
    "a child's turn is not the chat's run",
  );

  // `wait` returns the final answer and closes it for good.
  events.length = 0;
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: {
      type: "collabAgentToolCall",
      id: "call-wait",
      tool: "wait",
      status: "completed",
      senderThreadId: SESSION,
      receiverThreadIds: ["child-1"],
      prompt: null,
      agentsStates: { "child-1": { status: "completed", message: "Final: 42 tests." } },
    },
  });
  task = present(events.pop());
  assert.equal(task.status, "completed");
  assert.equal(task.summary, "Final: 42 tests.");
  assert.equal(task.title, "Count the tests", "the answer never becomes the title");
  // A later finished turn does not reopen it.
  notify(agent, "turn/completed", { threadId: "child-1", turn: { id: "turn-c2", status: "completed" } });
  assert.equal(present(agent.subagents.get("child-1")).task.status, "completed");
});

// A grandchild reports into the same chat, inside the middle child's task;
// its usage stays on its task.
test("a grandchild reaches the chat inside its parent task", () => {
  const { agent, events } = harness();
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    item: spawnItem("call-1", SESSION, "child-1", "Plan the work"),
  });
  notify(agent, "item/started", {
    threadId: "child-1",
    turnId: "turn-c1",
    item: spawnItem("call-2", "child-1", "grandchild-1", "Read the parser"),
  });
  const grandchild = present(events.at(-1));
  assert.equal(grandchild.id, "grandchild-1");
  assert.equal(grandchild.parentTaskId, "child-1");
  assert.ok(events.every((event) => event.sessionId === SESSION));
  assert.equal(grandchild.taskId, undefined, "a task event itself is placed by parentTaskId");

  notify(agent, "item/agentMessage/delta", {
    threadId: "grandchild-1",
    turnId: "turn-g1",
    itemId: "msg-g",
    delta: "parsed",
  });
  const text = present(events.at(-1));
  assert.equal(text.sessionId, SESSION);
  assert.equal(text.taskId, "grandchild-1");

  const breakdown = (totalTokens: number) => ({
    totalTokens,
    inputTokens: 0,
    cachedInputTokens: 0,
    outputTokens: 0,
    reasoningOutputTokens: 0,
  });
  notify(agent, "thread/tokenUsage/updated", {
    threadId: "grandchild-1",
    turnId: "turn-g1",
    tokenUsage: { total: breakdown(900), last: breakdown(300), modelContextWindow: 1000 },
  });
  const usage = present(events.at(-1));
  assert.deepEqual(usage, { sessionId: SESSION, runId: RUN, taskId: "grandchild-1", event: "usage", usedTokens: 900 });
  assert.deepEqual(present(agent.subagents.get("grandchild-1")).task.usage, { usedTokens: 900 });
});

test("a subagent's tools count and show as its activity", () => {
  const { agent, events } = harness();
  notify(agent, "item/started", { threadId: SESSION, item: spawnItem("call-1", SESSION, "child-1", "One") });
  const command = (status: string) => ({
    type: "commandExecution",
    id: "exec-c",
    command: "cargo test",
    status,
    commandActions: [],
  });
  notify(agent, "item/started", { threadId: "child-1", item: command("inProgress") });
  let task = present(tasks(events).at(-1));
  assert.deepEqual([task.toolUses, task.activity], [1, "cargo test"]);
  notify(agent, "item/completed", { threadId: "child-1", item: command("completed") });
  const update = present(events.at(-1));
  assert.equal(update.event, "tool_call_updated", "a started tool is updated, not started again");
  assert.equal(update.taskId, "child-1");
  notify(agent, "turn/completed", { threadId: "child-1", turn: { id: "t", status: "completed" } });
  task = present(tasks(events).at(-1));
  assert.equal(task.activity, undefined, "an ended subagent has no activity");
});

// Multi-agent v2 spawns appear only as `subAgentActivity`. Inside a child,
// an activity naming `/root` is a message to the chat, not a subagent.
test("a v2 activity starts and ends a subagent", async () => {
  const { agent, events } = harness();
  const activity = (thread: string, kind: string, target: string, path: string) => ({
    threadId: thread,
    turnId: "t",
    item: { type: "subAgentActivity", id: `act-${kind}-${target}`, kind, agentThreadId: target, agentPath: path },
  });
  notify(agent, "item/completed", activity(SESSION, "started", "child-2", "/root/scout"));
  const task = present(events.shift());
  assert.deepEqual(
    [task.id, task.title, task.status],
    ["child-2", "scout", "running"],
    "the task name, since v2 encrypts the instruction",
  );

  notify(agent, "item/completed", activity("child-2", "interacted", SESSION, "/root"));
  assert.equal(events.length, 0, "a message to the chat changes nothing");
  assert.equal(agent.subagents.has(SESSION), false);

  notify(agent, "item/completed", activity(SESSION, "completed", "child-2", "/root/scout"));
  assert.equal(present(events.shift()).status, "completed");
});

test("late child activity survives retirement of its parent turn", () => {
  const { agent, events } = harness();
  notify(agent, "item/started", { threadId: SESSION, item: spawnItem("spawn", SESSION, "child", "Scout") });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  const state = present(agent.sessions.get(SESSION));
  state.run = "successor";
  state.turn = "turn-2";
  notify(agent, "item/completed", {
    threadId: SESSION,
    turnId: "turn-1",
    item: {
      type: "subAgentActivity",
      id: "activity",
      kind: "completed",
      agentThreadId: "child",
      agentPath: "/root/scout",
    },
  });
  assert.equal(tasks(events).at(-1)?.status, "completed");
  assert.equal(state.run, "successor");
});

test("a v2 child without a prompt or name is described from its own thread record", async () => {
  const { agent, events } = harness({
    handlers: {
      "thread/read": (params) => ({
        thread: { id: params.threadId, preview: "", agentNickname: "Scout", createdAt: 1 },
      }),
    },
  });
  await agent.client();
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: {
      type: "subAgentActivity",
      id: "a",
      kind: "started",
      agentThreadId: "child-3",
      agentPath: "/root/find_todos",
    },
  });
  await settle();
  const task = present(tasks(events).at(-1));
  assert.equal(task.name, "Scout");
  assert.equal(task.title, "find todos");
});

test("a child spawned before a restart is adopted when the chat addresses it", async () => {
  const { agent, events } = harness({
    handlers: {
      "thread/read": () => ({
        thread: { id: "old-child", preview: "Audit the build\nplease", agentNickname: "Kepler" },
      }),
    },
  });
  await agent.client();
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: {
      type: "collabAgentToolCall",
      id: "w",
      tool: "wait",
      senderThreadId: SESSION,
      receiverThreadIds: ["old-child"],
      agentsStates: { "old-child": { status: "completed", message: "Done." } },
    },
  });
  await settle();
  const task = present(tasks(events).at(-1));
  assert.deepEqual(
    [task.id, task.status, task.summary, task.title, task.name],
    ["old-child", "completed", "Done.", "Audit the build", "Kepler"],
  );
  // `listAgents` adopts nobody.
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: {
      type: "collabAgentToolCall",
      id: "l",
      tool: "listAgents",
      receiverThreadIds: ["stranger"],
      agentsStates: {},
    },
  });
  assert.equal(agent.subagents.has("stranger"), false);
});

// `thread/started` reports every thread of the app-server; a review or a
// stranger's subagent is not a task of this chat.
test("only spawned threads of known chats become tasks", () => {
  const { agent, events } = harness();
  notify(agent, "thread/started", {
    thread: { id: "review-1", preview: "", createdAt: 1, updatedAt: 1, source: { subAgent: "review" } },
  });
  notify(agent, "thread/started", {
    thread: {
      id: "other-child",
      preview: "x",
      createdAt: 1,
      updatedAt: 1,
      parentThreadId: "someone-else",
      source: { subAgent: { thread_spawn: { parent_thread_id: "someone-else", depth: 1 } } },
    },
  });
  assert.equal(events.length, 0);
  assert.equal(agent.subagents.size, 0);
});

// A subagent's approval flips it to waiting.
test("a subagent waiting on the user is waiting", () => {
  const { agent, events } = harness();
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    item: spawnItem("call-1", SESSION, "child-1", "Edit the file"),
  });
  events.length = 0;
  notify(agent, "thread/status/changed", {
    threadId: "child-1",
    status: { type: "active", activeFlags: ["waitingOnApproval"] },
  });
  assert.equal(present(events.shift()).status, "waiting");
  notify(agent, "thread/status/changed", { threadId: "child-1", status: { type: "active", activeFlags: [] } });
  assert.equal(present(events.shift()).status, "running");
  notify(agent, "thread/status/changed", { threadId: "child-1", status: { type: "idle" } });
  assert.equal(events.length, 0);
});

// Stop interrupts every live subagent turn before the chat's own, and
// releases the approvals the subagents wait on.
test("stop interrupts subagents first and releases their approvals", async () => {
  const interrupts: unknown[][] = [];
  const { agent, events, api } = harness({
    handlers: {
      "turn/interrupt": (params) => {
        interrupts.push([params.threadId, params.turnId]);
        return {};
      },
    },
  });
  await agent.client();
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    item: spawnItem("call-1", SESSION, "child-1", "One"),
  });
  notify(agent, "item/started", {
    threadId: "child-1",
    turnId: "turn-c1",
    item: spawnItem("call-2", "child-1", "grandchild-1", "Two"),
  });
  for (const [thread, turn] of [
    ["child-1", "turn-c1"],
    ["grandchild-1", "turn-g1"],
  ]) {
    notify(agent, "turn/started", { threadId: thread, turn: { id: turn, items: [], status: "inProgress" } });
  }
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 9,
    method: "item/commandExecution/requestApproval",
    params: { threadId: "grandchild-1", itemId: "x", command: "rm" },
  });
  await settle();
  const approval = present(events.find((event) => event.event === "approval"));
  assert.equal(approval.taskId, "grandchild-1", "a subagent's approval is tagged with its task");

  await agent.cancel({ sessionId: SESSION });
  assert.ok(events.some((event) => event.event === "run_finished"), "the run ends before Codex answers");
  await peer.waitFor((message) => message.method === "turn/interrupt" && message.params.threadId === SESSION);
  assert.deepEqual(interrupts.at(-1), [SESSION, "turn-1"], "the chat last");
  assert.deepEqual(interrupts.slice(0, 2).sort(), [
    ["child-1", "turn-c1"],
    ["grandchild-1", "turn-g1"],
  ]);
  const released = await peer.waitFor((message) => message.id === 9);
  assert.deepEqual(released.result, { decision: "cancel" });
  assert.ok(events.some((event) => event.event === "run_finished" && event.outcome.status === "cancelled"));
});

// Stop pressed before Codex names the turn still interrupts it, whichever
// of the `turn/start` reply and `turn/started` comes first, and the turn
// neither reopens the chat nor streams into it.
for (const first of ["reply", "turn/started"] as const) {
  test(`stop before codex names the turn interrupts it once named (${first} first)`, async () => {
    const { agent, events, api } = harness({
      handlers: { "turn/start": () => undefined, "turn/interrupt": () => ({}) },
    });
    const state = present(agent.sessions.get(SESSION));
    state.run = null;
    state.turn = null;
    const { runId } = await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "hi" }] } });
    const peer = api.peers[0];
    const start = await peer.waitFor((message) => message.method === "turn/start");
    await agent.cancel({ sessionId: SESSION });
    assert.deepEqual(
      events.filter((event) => event.event === "run_finished").map((event) => [event.runId, event.outcome?.status]),
      [[runId, "cancelled"]],
    );
    const started = () =>
      notify(agent, "turn/started", { threadId: SESSION, turn: { id: "turn-new", items: [], status: "inProgress" } });
    if (first === "turn/started") started();
    peer.reply(start, { turn: { id: "turn-new" } });
    await settle();
    if (first === "reply") started();
    const interrupt = await peer.waitFor((message) => message.method === "turn/interrupt");
    assert.deepEqual(interrupt.params, { threadId: SESSION, turnId: "turn-new" });
    notify(agent, "item/agentMessage/delta", { threadId: SESSION, turnId: "turn-new", itemId: "late", delta: "x" });
    notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-new", status: "interrupted" } });
    await peer.waitFor((message) => message.method === "thread/unsubscribe");
    const methods = peer.received.map((message) => message.method);
    assert.ok(methods.indexOf("turn/interrupt") < methods.indexOf("thread/unsubscribe"), "let go only after the interrupt");
    assert.equal(methods.filter((method) => method === "turn/interrupt").length, 1);
    assert.equal(agent.runOf(SESSION), null);
    assert.deepEqual(
      events.filter((event) => ["run_started", "text_delta", "run_finished"].includes(event.event)).length,
      1,
    );
  });
}

// A server request the plugin cannot handle is refused, as before, and
// the chat now says so instead of the approval vanishing silently.
test("a malformed server request is refused with a notice in its chat", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  const peer = api.peers[0];
  peer.send({
    jsonrpc: "2.0",
    id: 41,
    method: "item/commandExecution/requestApproval",
    params: { threadId: SESSION, command: "rm" },
  });
  const answer = await peer.waitFor((message) => message.id === 41);
  assert.ok(answer.error, "Codex gets an error, not a decision");
  const notice = present(events.find((event) => event.event === "notice"));
  assert.equal(notice.sessionId, SESSION);
  assert.equal(notice.level, "warning");
  assert.match(String(notice.message), /could not handle Codex's item\/commandExecution\/requestApproval/);
});

// `cancel_task` stops one subagent (and what it started) and leaves the
// chat's run alone.
test("cancel_task interrupts only that subagent", async () => {
  const interrupts: Record<string, unknown>[] = [];
  const { agent } = harness({
    handlers: {
      "turn/interrupt": (params) => {
        interrupts.push(params);
        return {};
      },
    },
  });
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    item: spawnItem("call-1", SESSION, "child-1", "One"),
  });
  await assert.rejects(agent.cancelTask({ sessionId: SESSION, taskId: "child-1" }), /not running/, "no live turn yet");
  notify(agent, "turn/started", { threadId: "child-1", turn: { id: "turn-c1", items: [], status: "inProgress" } });
  await assert.rejects(
    agent.cancelTask({ sessionId: "another-chat", taskId: "child-1" }),
    /no codex subagent/,
    "not this chat's",
  );
  await agent.cancelTask({ sessionId: SESSION, taskId: "child-1" });
  assert.deepEqual(interrupts, [{ threadId: "child-1", turnId: "turn-c1" }]);
  assert.equal(present(agent.sessions.get(SESSION)).run, RUN, "the chat keeps running");
});

test("versions come from the app-server's user agent", () => {
  assert.equal(versionOf("divergence/0.155.1 (Mac OS 26.5.0; arm64) iTerm.app"), "0.155.1");
  assert.equal(versionOf("nothing"), null);
  assert.equal(versionOf(null), null);
});

test("CODEX_ARGS is split like a shell command line", async () => {
  const { agent, api } = harness({
    env: { HOME: "/Users/me", CODEX_ARGS: `-c 'model_provider="my provider"' --flag` },
  });
  await agent.client();
  assert.deepEqual(api.peers[0].args, [
    "app-server",
    "-c",
    "thread_unload_delay_secs=5",
    "-c",
    'model_provider="my provider"',
    "--flag",
  ]);
});

// A deadlock inside `initialize` once left every agent listing empty; here
// initialize must answer with the app-server's facts.
test("initialize starts the app-server once and describes the agent", async () => {
  clearCache();
  const { agent, api } = harness({
    handlers: {
      "account/read": () => ({ account: { type: "chatgpt", email: "me@example.com" }, requiresOpenaiAuth: true }),
    },
    onHost: (method) => {
      if (method === "host/process.which") return { path: "/usr/local/bin/codex", realPath: "/usr/local/bin/codex" };
      return {};
    },
  });
  const [info] = await Promise.all([agent.initialize(), agent.client()]);
  assert.equal(api.peers.filter((peer) => peer.program === "codex").length, 1, "one app-server for concurrent callers");
  const peer = api.peers[0];
  assert.deepEqual(peer.args, ["app-server", "-c", "thread_unload_delay_secs=5"]);
  assert.deepEqual(peer.options.env, { CODEX_HOME: "/Users/me/.codex" });
  const init = present(peer.received.find((message) => message.method === "initialize"));
  assert.ok(init);
  assert.deepEqual(init.params.capabilities, { experimentalApi: true, requestAttestation: false });
  assert.equal(z.object({ name: z.string() }).parse(init.params.clientInfo).name, "divergence");
  assert.ok(peer.received.some((message) => message.method === "initialized" && message.id === undefined));
  assert.equal(info.id, "codex");
  assert.equal(info.version, "0.155.1");
  assert.deepEqual(info.status, { state: "ready" });
  assert.equal(present(info.capabilities).subagents, true);
  assert.equal(present(info.capabilities).slashCommands, false);
  assert.equal(info.family, "codex");
  assert.equal(info.continuationKey, "/Users/me/.codex");
  assert.ok(present(info.icon).startsWith("<svg"));
  assert.equal(info.usageLimits, undefined, "limits are the host's periodic read, not part of every status check");
  assert.ok(!peer.received.some((message) => message.method === "account/rateLimits/read"));
  assert.deepEqual(
    info.maintenance,
    { canUpdate: false, installedVersion: "0.155.1" },
    "an unproven installer stays manual",
  );
});

test("a signed-out account needs a login, and a missing CLI is an error", async () => {
  const { agent } = harness({ handlers: { "account/read": () => ({ account: null, requiresOpenaiAuth: true }) } });
  const info = await agent.initialize();
  assert.deepEqual(info.status, { state: "auth_required", message: "Sign in with `codex login`" });

  const api = fakeApi({ onSpawn: () => new Error("codex is not on the PATH") });
  const missing = testAgent(api);
  await assert.rejects(missing.initialize(), /codex CLI could not be started.*not on the PATH/);
});

test("the maintenance check asks the installer that owns the CLI", async () => {
  clearCache();
  const npmReal = "/Users/me/.nvm/v24/lib/node_modules/@openai/codex/bin/codex.js";
  const { agent, api } = harness({
    handlers: { "account/read": () => ({ account: {} }) },
    onHost: (method) =>
      method === "host/process.which" ? { path: "/Users/me/.nvm/v24/bin/codex", realPath: npmReal } : {},
  });
  const original = api.process.start;
  api.process.start = (async (program, args, { outsideSandbox: _outside, ...options } = {}) => {
    const child = await original(program, args, options);
    if (program === "npm") {
      queueMicrotask(() => {
        const peer = present(api.peers.at(-1));
        peer.stdout.push("0.160.0\n");
        peer.exit(0);
      });
    }
    return child;
  }) as typeof api.process.start;
  const info = await agent.initialize();
  assert.deepEqual(info.maintenance, {
    canUpdate: true,
    installedVersion: "0.155.1",
    latestVersion: "0.160.0",
    manager: "npm",
  });
  const npm = present(api.peers.find((peer) => peer.program === "npm"));
  assert.deepEqual(npm.args, ["view", "@openai/codex", "version", "--prefix", "/Users/me/.nvm/v24"]);
});

test("options come from the live catalog and the user's config", async () => {
  const { agent } = harness({
    handlers: {
      "model/list": (params) =>
        params.cursor === null
          ? {
              data: [
                {
                  id: "gpt-5.5",
                  displayName: "GPT-5.5",
                  isDefault: true,
                  supportedReasoningEfforts: [{ reasoningEffort: "high", description: "" }],
                  defaultReasoningEffort: "high",
                },
              ],
              nextCursor: "p2",
            }
          : {
              data: [
                { id: "hidden", hidden: true },
                { id: "gpt-mini", supportedReasoningEfforts: [{ reasoningEffort: "low", description: "" }] },
              ],
              nextCursor: null,
            },
      "config/read": (params) => {
        assert.equal(params.cwd, "/w");
        return { config: { approval_policy: "on-request", sandbox_mode: "workspace-write" } };
      },
    },
  });
  const { options } = await agent.listOptions({ workspace: "/w" });
  const model = present(options.find((option) => option.id === "model"));
  assert.deepEqual(
    present(model.choices).map((choice) => choice.value),
    ["gpt-5.5", "gpt-mini"],
    "hidden models are left out, all pages read",
  );
  assert.equal(present(options.find((option) => option.id === "permission_mode")).value, "auto_edits");

  // Changing the model clears the reasoning chosen for the old one.
  await agent.setOption({ sessionId: SESSION, optionId: "reasoning", value: "high" });
  const { options: after } = await agent.setOption({ sessionId: SESSION, optionId: "model", value: "gpt-mini" });
  assert.equal(present(agent.sessions.get(SESSION)).options.reasoning, undefined);
  assert.equal(present(after.find((option) => option.id === "reasoning")).value, "low");
});

// A failed `config/read` leaves the user's own approval mode, model and
// effort out of effect; the chat keeps working on the defaults, and the
// app says so once rather than on every options read.
test("a configuration Codex cannot read is reported once, and the defaults apply", async () => {
  const { agent, events } = harness({
    handlers: {
      "model/list": () => ({ data: [{ id: "gpt-5.5" }], nextCursor: null }),
      "config/read": (_params, message, peer) => {
        peer.send({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: "config.toml: bad table" } });
        return undefined;
      },
    },
  });
  const first = await agent.listOptions({ workspace: "/w" });
  await agent.listOptions({ workspace: "/w" });
  assert.equal(present(first.options.find((option) => option.id === "permission_mode")).value, "auto");
  const notices = events.filter((event) => event.event === "notice");
  assert.equal(notices.length, 1, "reported once");
  assert.equal(present(notices[0]).sessionId, "", "an app notice: no chat owns the options read");
  assert.match(String(present(notices[0]).message), /could not read its configuration.*bad table/);
});

// An empty model list is an error the user sees, never a chat without a
// Model choice, and it is asked for again rather than kept.
test("a model list with nothing to run fails and is read again", async () => {
  let reads = 0;
  const { agent } = harness({
    handlers: {
      "model/list": () => (reads++, { data: reads === 1 ? [] : [{ id: "gpt-5.5" }], nextCursor: null }),
      "config/read": () => ({ config: {} }),
    },
  });
  await assert.rejects(agent.listOptions({ workspace: "/w" }), /listed no models/);
  const again = await agent.listOptions({ workspace: "/w" });
  assert.ok(again.options.some((option) => option.id === "model"));
});

// A notification this plugin cannot read or fails to handle may lose part
// of a turn, so its chat is told instead of the log alone.
test("an unreadable or unhandled notification reaches its chat as a notice", () => {
  const { agent, events } = harness();
  agent.onNotification("turn/completed", { threadId: SESSION, turn: "not an object" });
  assert.match(String(events.at(-1)?.message), /cannot read.*turn/);
  assert.equal(events.at(-1)?.sessionId, SESSION);
  agent.routeNotification = () => {
    throw new Error("a bug");
  };
  agent.onNotification("turn/started", { threadId: SESSION, turn: { id: "turn-1" } });
  assert.equal(events.at(-1)?.event, "notice");
  assert.match(String(events.at(-1)?.message), /failed to handle Codex's turn\/started: a bug/);
  agent.onNotification("account/updated", {});
  assert.equal(events.at(-1)?.sessionId, "", "no thread: the whole app is told");
});

// Codex reports each MCP server's startup with a string `status`, a name
// this plugin reads as an object on the thread notifications it handles.
// It does not read those reports, so they are no reason to warn anyone.
test("a notification this plugin does not read is not checked or reported", () => {
  const { agent, events } = harness();
  for (const status of ["starting", "ready", "failed"])
    agent.onNotification("mcpServer/startupStatus/updated", {
      threadId: null,
      name: "linear",
      status,
      error: status === "failed" ? "handshake failed" : null,
      failureReason: null,
    });
  assert.equal(events.length, 0);
});

// Codex says when a watched skill folder changed; the host then lists the
// skills again for every open chat.
test("a skills change in Codex tells the host for the whole agent", () => {
  const { agent, events } = harness();
  agent.onNotification("skills/changed", {});
  assert.deepEqual(events.at(-1), { sessionId: "", event: "skills_changed" });
});

test("a prompt starts a turn with the session's settings, and one during a turn steers it", async () => {
  const started: Record<string, unknown>[] = [];
  const { agent, events, api } = harness({
    handlers: {
      "thread/start": (params) => {
        started.push(params);
        return { thread: { id: "thread-new" } };
      },
      "turn/start": (params) => ({
        turn: {
          id: `turn-for-${z.array(z.object({ text: z.string() })).parse(params.input)[0].text}`,
          items: [],
          status: "inProgress",
        },
      }),
      "turn/steer": () => ({ turnId: "x" }),
    },
  });
  const { sessionId } = await agent.createSession({
    workspace: "/w2",
    options: { model: "gpt-5.5", reasoning: "high", permission_mode: "full" },
    tools: [{ name: "now", description: "Time", inputSchema: { type: "object", properties: {} } }],
    instructions: "Be brief.",
  });
  assert.equal(sessionId, "thread-new");
  assert.equal(started[0].cwd, "/w2");
  assert.equal(started[0].developerInstructions, "Be brief.");
  assert.equal(z.array(z.object({ name: z.string() })).parse(started[0].dynamicTools)[0].name, "now");

  const { runId } = await agent.prompt({
    sessionId,
    input: { blocks: [{ type: "text", text: "hi" }], itemId: "host-item-1" },
  });
  assert.match(runId, /^codex-run-/);
  const peer = api.peers[0];
  const turn = await peer.waitFor((message) => message.method === "turn/start");
  assert.deepEqual(
    [
      turn.params.threadId,
      turn.params.model,
      turn.params.effort,
      turn.params.approvalPolicy,
      z.object({ type: z.string() }).parse(turn.params.sandboxPolicy).type,
    ],
    ["thread-new", "gpt-5.5", "high", "never", "dangerFullAccess"],
  );
  await settle();
  assert.equal(present(agent.sessions.get(sessionId)).turn, "turn-for-hi");
  assert.equal(
    present(agent.sessions.get(sessionId)).turns.get("host-item-1"),
    "turn-for-hi",
    "the host's message id names its turn",
  );

  const steered = await agent.prompt({ sessionId, input: { blocks: [{ type: "text", text: "also this" }] } });
  assert.equal(steered.runId, runId, "a steer shares the run");
  const steer = await peer.waitFor((message) => message.method === "turn/steer");
  assert.deepEqual(steer.params, {
    threadId: sessionId,
    input: [{ type: "text", text: "also this", text_elements: [] }],
    expectedTurnId: "turn-for-hi",
  });

  peer.send({
    jsonrpc: "2.0",
    method: "turn/completed",
    params: { threadId: sessionId, turn: { id: "turn-for-hi", status: "completed" } },
  });
  await settle();
  assert.deepEqual(
    events.filter((event) => event.event === "run_finished").map((event) => event.runId),
    [runId],
  );
});

test("steering waits for start-in-flight without a second start or a replacement run", async () => {
  const { agent, api } = harness({
    handlers: { "turn/start": () => undefined, "turn/steer": () => ({ turnId: "turn-new" }) },
  });
  const state = present(agent.sessions.get(SESSION));
  state.run = null;
  state.turn = null;
  const first = agent.prompt({
    sessionId: SESSION,
    input: {
      delivery: { inputId: "first", attemptId: "start-attempt", intent: "send" },
      blocks: [{ type: "text", text: "Inspect alpha" }],
    },
  });
  await settle();
  const peer = api.peers[0];
  const start = await peer.waitFor((message) => message.method === "turn/start");
  const originalRun = state.run;
  const second = agent.prompt({
    sessionId: SESSION,
    input: {
      delivery: { inputId: "second", attemptId: "steer-attempt", intent: "steer" },
      blocks: [{ type: "text", text: "Do not change beta" }],
    },
  });
  await settle();
  assert.deepEqual(
    peer.received.filter((message) => message.method?.startsWith("turn/")).map((message) => message.method),
    ["turn/start"],
  );
  peer.send({ method: "turn/started", params: { threadId: SESSION, turn: { id: "turn-new", status: "inProgress" } } });
  const steer = await peer.waitFor((message) => message.method === "turn/steer");
  assert.equal(steer.params.expectedTurnId, "turn-new");
  assert.equal(steer.params.clientUserMessageId, "steer-attempt");
  assert.equal(start.params.clientUserMessageId, "start-attempt");
  peer.reply(start, { turn: { id: "turn-new" } });
  const [started, steered] = await Promise.all([first, second]);
  assert.equal(started.runId, originalRun);
  assert.equal(steered.runId, originalRun);
  assert.equal(state.run, originalRun);
  assert.equal(peer.received.filter((message) => message.method === "turn/start").length, 1);
  assert.deepEqual(steered.receipt, { evidence: "native_admission", nativeInputId: "steer-attempt" });
});

test("a turn that ends before its start reply positively rejects a waiting steer", async () => {
  const { agent, events, api } = harness({ handlers: { "turn/start": () => undefined } });
  const state = present(agent.sessions.get(SESSION));
  state.run = null;
  state.turn = null;
  const { runId } = await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "hi" }] } });
  const peer = api.peers[0];
  const start = await peer.waitFor((message) => message.method === "turn/start");
  const steer = agent.prompt({
    sessionId: SESSION,
    input: {
      delivery: { inputId: "second", attemptId: "attempt", intent: "steer" },
      blocks: [{ type: "text", text: "also" }],
    },
  });
  const rejected = assert.rejects(steer, /ended before steering/);
  await settle();
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-new", status: "completed" } });
  await rejected;
  peer.reply(start, { turn: { id: "turn-new" } });
  await settle();
  assert.equal(state.run, null);
  assert.equal(state.turn, null);
  assert.equal(peer.received.filter((message) => message.method === "turn/start").length, 1);
  assert.equal(peer.received.filter((message) => message.method === "turn/steer").length, 0);
  assert.equal(events.find((event) => event.event === "input_rejected")?.attemptId, "attempt");
  assert.deepEqual(
    events.filter((event) => event.event === "run_finished").map((event) => event.runId),
    [runId],
  );
});

for (const failure of ["precondition", "transport", "malformed", "server"] as const) {
  test(`steer ${failure} failure distinguishes rejection from uncertain admission`, async () => {
    const { agent, events, api } = harness({
      handlers: {
        "turn/steer": (_params, message, peer) => {
          if (failure === "transport") {
            present(agent.proc).connection.close("lost the steer reply");
          } else if (failure === "malformed") {
            peer.reply(message, {});
          } else {
            peer.send({
              id: message.id,
              error: {
                code: failure === "precondition" ? -32600 : -32603,
                message: "expected active turn id `turn-1` but found `turn-2`",
              },
            });
          }
        },
      },
    });
    await assert.rejects(
      agent.prompt({
        sessionId: SESSION,
        input: {
          delivery: { inputId: "followup", attemptId: "attempt", intent: "steer" },
          blocks: [{ type: "text", text: "also" }],
        },
      }),
      /turn\/steer failed/,
    );
    const rejection = events.find((event) => event.event === "input_rejected");
    assert.equal(Boolean(rejection), failure === "precondition");
    if (rejection) assert.deepEqual([rejection.inputId, rejection.attemptId], ["followup", "attempt"]);
    assert.equal(present(agent.sessions.get(SESSION)).inputs.has("attempt"), failure !== "precondition");
    assert.equal(agent.runOf(SESSION), RUN);
    assert.equal(
      events.some((event) => event.event === "run_finished"),
      false,
    );
    assert.equal(api.peers[0].received.filter((message) => message.method === "turn/start").length, 0);
  });
}

test("clientUserMessageId consumption is correlated, one-shot and retains its original run", async () => {
  const { agent, events, api } = harness({ handlers: { "turn/steer": () => ({ turnId: "turn-1" }) } });
  const result = await agent.prompt({
    sessionId: SESSION,
    input: {
      delivery: { inputId: "followup", attemptId: "attempt", intent: "steer" },
      blocks: [{ type: "text", text: "same text" }],
    },
  });
  assert.equal(result.receipt?.evidence, "native_admission");
  assert.equal(
    events.some((event) => event.event === "input_consumed"),
    false,
    "a native reply alone is not consumption",
  );
  const peer = api.peers[0];
  assert.equal(
    (await peer.waitFor((message) => message.method === "turn/steer")).params.clientUserMessageId,
    "attempt",
  );
  const item = {
    type: "userMessage",
    id: "native-user",
    clientId: "attempt",
    content: [{ type: "text", text: "same text" }],
  };
  notify(agent, "item/completed", { threadId: SESSION, item: { ...item, clientId: "unrelated" } });
  notify(agent, "item/completed", { threadId: "other-thread", item });
  assert.equal(
    events.some((event) => event.event === "input_consumed"),
    false,
  );
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  const state = present(agent.sessions.get(SESSION));
  state.run = "successor";
  state.turn = "turn-2";
  notify(agent, "item/started", { threadId: SESSION, turnId: "turn-1", item });
  notify(agent, "item/completed", { threadId: SESSION, turnId: "turn-1", item });
  assert.deepEqual(
    events.filter((event) => event.event === "input_consumed"),
    [{ sessionId: SESSION, runId: RUN, event: "input_consumed", inputId: "followup", nativeInputId: "native-user" }],
  );
  assert.equal(state.run, "successor");
});

test("old terminal events and late start replies cannot finish or retarget a successor", async () => {
  const { agent, events, api } = harness({ handlers: { "turn/start": () => undefined } });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  const { runId } = await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "new work" }] } });
  const start = await api.peers[0].waitFor((message) => message.method === "turn/start");
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "failed" } });
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "turn-1", status: "inProgress" } });
  notify(agent, "error", {
    threadId: SESSION,
    turnId: "turn-1",
    error: { message: "old quota", codexErrorInfo: "usageLimitExceeded" },
  });
  assert.equal(agent.runOf(SESSION), runId);
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "turn-2", status: "inProgress" } });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "unrecognized-old", status: "completed" } });
  assert.equal(agent.runOf(SESSION), runId);
  agent.finishRun(SESSION, { status: "cancelled" });
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "turn-3", status: "inProgress" } });
  const successor = agent.runOf(SESSION);
  assert.ok(successor);
  api.peers[0].reply(start, { turn: { id: "turn-2" } });
  await settle();
  assert.equal(present(agent.sessions.get(SESSION)).turn, "turn-3");
  assert.equal(agent.runOf(SESSION), successor);
  assert.equal(events.filter((event) => event.event === "run_finished").length, 2);
  assert.equal(
    events.some((event) => event.event === "usage_blocked"),
    false,
  );
});

test("autonomous turns start and finish once and a changed native turn is not filtered", () => {
  const { agent, events } = harness();
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "turn-next", status: "inProgress" } });
  assert.equal(present(agent.sessions.get(SESSION)).turn, "turn-next");
  assert.equal(agent.runOf(SESSION), RUN, "the active response keeps its run identity");
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  assert.equal(agent.runOf(SESSION), RUN);
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-next", status: "completed" } });
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "autonomous", status: "inProgress" } });
  notify(agent, "turn/started", { threadId: SESSION, turn: { id: "autonomous", status: "inProgress" } });
  const run = agent.runOf(SESSION);
  assert.ok(run);
  assert.notEqual(run, RUN);
  notify(agent, "item/agentMessage/delta", {
    threadId: SESSION,
    turnId: "autonomous",
    itemId: "answer",
    delta: "done",
  });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "autonomous", status: "completed" } });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "autonomous", status: "completed" } });
  assert.deepEqual(
    events.filter((event) => event.event === "run_started").map((event) => event.runId),
    [run],
  );
  assert.deepEqual(
    events.filter((event) => event.event === "run_finished").map((event) => event.runId),
    [RUN, run],
  );
  assert.equal(events.find((event) => event.event === "text_delta")?.runId, run);
});

test("native quota warnings and retries leave tools and the run alive until turn/completed", async () => {
  const { agent, events } = harness({
    handlers: {
      "account/rateLimits/read": () => ({
        ordinaryUsageAllowed: false,
        accountId: "account-one",
        rateLimits: {
          limitId: "codex",
          rateLimitReachedType: "rate_limit_reached",
          primary: { usedPercent: 100, resetsAt: 1_900_000_000 },
        },
      }),
    },
  });
  await agent.limits();
  notify(agent, "item/started", {
    threadId: SESSION,
    turnId: "turn-1",
    item: { type: "commandExecution", id: "tool", command: "sleep 1", status: "inProgress" },
  });
  notify(agent, "warning", { threadId: SESSION, message: "limit nearly reached" });
  for (const codexErrorInfo of [
    "rateLimitExceeded",
    "unauthorized",
    "contextWindowExceeded",
    { httpConnectionFailed: { httpStatusCode: 429 } },
  ]) {
    notify(agent, "error", {
      threadId: SESSION,
      turnId: "turn-1",
      willRetry: true,
      error: { message: "not quota evidence", codexErrorInfo },
    });
  }
  assert.equal(
    events.some((event) => event.event === "usage_blocked"),
    false,
  );
  for (const willRetry of [true, false]) {
    notify(agent, "error", {
      threadId: SESSION,
      turnId: "turn-1",
      willRetry,
      error: { message: "quota exhausted", codexErrorInfo: "usageLimitExceeded" },
    });
    assert.equal(agent.runOf(SESSION), RUN);
    assert.equal(
      events.some((event) => event.event === "run_finished"),
      false,
    );
  }
  notify(agent, "item/commandExecution/outputDelta", {
    threadId: SESSION,
    turnId: "turn-1",
    itemId: "tool",
    delta: "still running",
  });
  assert.equal(events.at(-1)?.outputDelta, "still running");
  const recovery = present(events.find((event) => event.event === "usage_blocked")?.recovery);
  assert.deepEqual(
    [recovery.identity, recovery.scope, recovery.resetsAt],
    ["account-one", undefined, new Date(1_900_000_000_000).toISOString()],
  );
  notify(agent, "turn/completed", {
    threadId: SESSION,
    turn: {
      id: "turn-1",
      status: "failed",
      error: { message: "quota exhausted", codexErrorInfo: "usageLimitExceeded" },
    },
  });
  assert.equal(agent.runOf(SESSION), null);
  assert.deepEqual(events.at(-1)?.outcome, { status: "failed", message: "quota exhausted" });
});

test("usage reads return cached native identity, latest reset and real availability", async () => {
  let accountId = "account-one";
  let snapshotAccount: string | null = null;
  let allowed: boolean | null = false;
  const { agent, events } = harness({
    handlers: {
      "account/read": () => ({ account: { type: "chatgpt" }, workspaceRouting: { chatgptAccountId: accountId } }),
      "account/rateLimits/read": () => ({
        accountId: snapshotAccount,
        ordinaryUsageAllowed: allowed,
        rateLimits: {
          limitId: "codex",
          rateLimitReachedType: "rate_limit_reached",
          primary: { usedPercent: 100, resetsAt: 1_900_000_000 },
          secondary: { usedPercent: 100, resetsAt: 1_900_100_000 },
        },
      }),
    },
  });
  const limits = present(await agent.limits());
  const recovery = present(limits.recovery);
  assert.deepEqual(
    [recovery.identity, recovery.availability, recovery.resetsAt],
    ["account-one", "blocked", new Date(1_900_100_000_000).toISOString()],
  );
  assert.deepEqual(agent.quotaFacts, recovery);
  agent.onNotification("account/rateLimits/updated", { rateLimits: { primary: { usedPercent: 1 } } });
  assert.equal(events.at(-1)?.recovery?.availability, "unknown", "a sparse meter cannot grant usage");
  assert.equal(agent.quotaFacts?.identity, "account-one");
  allowed = null;
  assert.equal((await agent.limits())?.recovery?.availability, "unknown");
  allowed = true;
  assert.equal(
    (await agent.limits())?.recovery?.availability,
    "allowed",
    "only native permission grants usage, even at 100%",
  );
  accountId = "account-two";
  snapshotAccount = "account-one";
  const mismatch = present((await agent.limits())?.recovery);
  assert.equal(mismatch.availability, "unknown");
  assert.equal(mismatch.resetsAt, undefined);
  notify(agent, "account/updated", {});
  assert.equal(agent.quotaFacts, null);
  snapshotAccount = null;
  allowed = false;
  assert.equal((await agent.limits())?.recovery?.identity, "account-two");
});

test("an account change during a native usage read invalidates the in-flight evidence", async () => {
  const { agent, api } = harness({
    handlers: {
      "account/read": () => ({ workspaceRouting: { chatgptAccountId: "account-one" } }),
      "account/rateLimits/read": () => undefined,
    },
  });
  const reading = agent.limits();
  await settle();
  const peer = api.peers[0];
  const request = await peer.waitFor((message) => message.method === "account/rateLimits/read");
  notify(agent, "account/updated", {});
  peer.reply(request, { accountId: "account-one", ordinaryUsageAllowed: true });
  assert.equal(await reading, null);
  assert.equal(agent.quotaFacts, null);
});

test("a turn codex refuses fails the run with its message", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  api.peers[0].onMessage = (message, peer) => {
    if (message.method === "config/read") peer.reply(message, { config: {} });
    if (message.method === "turn/start")
      peer.send({ jsonrpc: "2.0", id: message.id, error: { code: -32000, message: "model not found" } });
  };
  present(agent.sessions.get(SESSION)).run = null;
  const { runId } = await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "hi" }] } });
  await settle();
  const finished = present(events.find((event) => event.event === "run_finished"));
  assert.equal(finished.runId, runId);
  assert.deepEqual(finished.outcome, { status: "failed", message: "turn/start failed: model not found" });
  assert.equal(present(events.find((event) => event.event === "notice")).level, "error");
});

test("an app-server that exits fails every run and every live subagent", async () => {
  const { agent, events, api } = harness();
  await agent.client();
  notify(agent, "item/started", { threadId: SESSION, item: spawnItem("call-1", SESSION, "child-1", "One") });
  api.peers[0].exit(1);
  await settle(10);
  assert.equal(present(agent.subagents.get("child-1")).task.status, "failed");
  assert.equal(present(agent.subagents.get("child-1")).task.summary, "The codex app-server exited");
  const finished = present(events.find((event) => event.event === "run_finished"));
  assert.deepEqual(finished.outcome, { status: "failed", message: "the codex app-server exited" });
  // The next call starts a new one.
  await agent.client();
  assert.equal(api.peers.length, 2);
});

test("after the app-server restarts, an open thread is resumed before its next turn", async () => {
  const { agent, api } = harness({
    handlers: {
      "thread/resume": () => ({ thread: { id: SESSION } }),
      "turn/start": () => ({ turn: { id: "turn-2" } }),
    },
  });
  await agent.client();
  api.peers[0].exit(1);
  await settle(10);
  await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "again" }] } });
  const peer = api.peers[1];
  await peer.waitFor((message) => message.method === "turn/start");
  const methods = peer.received.map((message) => message.method).filter((method) => method?.startsWith("t"));
  assert.deepEqual(methods, ["thread/resume", "turn/start"]);
  const resume = present(peer.received.find((message) => message.method === "thread/resume"));
  assert.equal(resume.params.threadId, SESSION);
  assert.equal(resume.params.cwd, "/w");
  // Loaded now: the next turn goes straight out.
  await settle();
  present(agent.sessions.get(SESSION)).run = null;
  present(agent.sessions.get(SESSION)).turn = null;
  await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "more" }] } });
  await settle();
  assert.equal(peer.received.filter((message) => message.method === "thread/resume").length, 1);
});

test("the app-server is one shared pool process that reports its loaded threads", async () => {
  const { agent, api } = harness({
    handlers: {
      "thread/start": () => ({ thread: { id: "thread-2" } }),
      "thread/resume": (params) => ({ thread: { id: params.threadId } }),
      "thread/unsubscribe": () => ({}),
    },
  });
  const reports: ProcessReport[] = [];
  agent.report = (report) => reports.push(report);
  await agent.createSession({ workspace: "/w" });
  await agent.resumeSession({ sessionId: SESSION, workspace: "/w" });
  await agent.resumeSession({ sessionId: SESSION, workspace: "/w" });
  await agent.closeSession({ sessionId: "thread-2" });
  const processId = present(reports[0]).processId;
  const shape = (state: ProcessReport["state"], sessions: string[]) => ({
    processId,
    state,
    sessions,
    shared: true,
    external: false,
  });
  assert.deepEqual(reports, [
    shape("started", []),
    shape("sessions", ["thread-2"]),
    shape("sessions", ["thread-2", SESSION]),
    shape("sessions", [SESSION]),
  ]);
  api.peers[0].exit(0);
  await settle(10);
  assert.deepEqual(reports.at(-1), shape("stopped", []));
});

test("stop_process stops the app-server; its threads resume in the next one on their next prompt", async () => {
  const { agent, api } = harness({
    handlers: {
      "thread/resume": (params) => ({ thread: { id: params.threadId } }),
      "turn/start": () => ({ turn: { id: "turn-2" } }),
    },
  });
  const reports: ProcessReport[] = [];
  agent.report = (report) => reports.push(report);
  const state = present(agent.sessions.get(SESSION));
  state.run = null;
  state.turn = null;
  await agent.resumeSession({ sessionId: SESSION, workspace: "/w" });
  const processId = present(agent.processId);
  assert.equal(typeof agent.definition().stop_process, "function");
  await agent.stopProcess({ processId: "codex-app-server-gone" });
  assert.equal(api.peers[0].status, null, "an id of an exited app-server stops nothing");
  await agent.stopProcess({ processId });
  await settle(10);
  assert.notEqual(api.peers[0].status, null);
  assert.equal(agent.proc, null);
  assert.equal(state.unloaded, true);
  assert.deepEqual(reports.at(-1), { processId, state: "stopped", sessions: [], shared: true, external: false });

  await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "again" }] } });
  const peer = api.peers[1];
  await peer.waitFor((message) => message.method === "turn/start");
  assert.deepEqual(
    peer.received.map((message) => message.method).filter((method) => method?.startsWith("t")),
    ["thread/resume", "turn/start"],
  );
  assert.notEqual(agent.processId, processId);
  assert.deepEqual(
    reports.slice(-2).map((report) => [report.state, report.sessions]),
    [
      ["started", []],
      ["sessions", [SESSION]],
    ],
  );
});

test("a chat lets go of its thread once its turn ends and resumes it before the next prompt", async () => {
  const { agent, api } = harness({
    handlers: {
      "thread/resume": (params) => ({ thread: { id: params.threadId } }),
      "thread/unsubscribe": () => ({ status: "unsubscribed" }),
      "turn/start": () => ({ turn: { id: "turn-2" } }),
    },
  });
  await agent.resumeSession({ sessionId: SESSION, workspace: "/w" });
  const peer = api.peers[0];
  const threads = () => peer.received.map((message) => message.method).filter((method) => method?.startsWith("t"));
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  await peer.waitFor((message) => message.method === "thread/unsubscribe");
  assert.equal(present(agent.sessions.get(SESSION)).unloaded, true);
  await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "text", text: "again" }] } });
  await peer.waitFor((message) => message.method === "turn/start");
  assert.deepEqual(threads(), ["thread/resume", "thread/unsubscribe", "thread/resume", "turn/start"]);
});

test("a background terminal or subagent keeps the thread until it ends", async () => {
  const { agent, api } = harness({
    handlers: {
      "thread/resume": (params) => ({ thread: { id: params.threadId } }),
      "thread/unsubscribe": () => ({ status: "unsubscribed" }),
    },
  });
  await agent.resumeSession({ sessionId: SESSION, workspace: "/w" });
  const peer = api.peers[0];
  const released = () => peer.received.filter((message) => message.method === "thread/unsubscribe").length;
  const item = (status: string) => ({
    type: "commandExecution",
    id: "server",
    processId: "42",
    command: "pnpm dev",
    cwd: "/w",
    status,
    commandActions: [{ type: "unknown", command: "pnpm dev" }],
    aggregatedOutput: null,
    exitCode: status === "inProgress" ? null : 0,
  });
  notify(agent, "item/started", { threadId: SESSION, turnId: "turn-1", item: item("inProgress") });
  notify(agent, "thread/started", {
    thread: {
      id: "child-1",
      parentThreadId: SESSION,
      source: { subAgent: { thread_spawn: { parent_thread_id: SESSION, depth: 1 } } },
    },
  });
  notify(agent, "turn/completed", { threadId: SESSION, turn: { id: "turn-1", status: "completed" } });
  await settle(10);
  assert.equal(released(), 0, "the terminal and the subagent still run");
  notify(agent, "item/completed", { threadId: SESSION, turnId: "turn-1", item: item("completed") });
  await settle(10);
  assert.equal(released(), 0, "the subagent still runs");
  notify(agent, "turn/completed", { threadId: "child-1", turn: { id: "child-turn", status: "completed" } });
  await peer.waitFor((message) => message.method === "thread/unsubscribe");
  assert.equal(released(), 1);
});

test("a thread another Codex program is writing is refused in plain words", async () => {
  const { agent } = harness({
    handlers: {
      "thread/resume": (params, message, peer) => {
        peer.send({
          jsonrpc: "2.0",
          id: message.id,
          error: { code: -32600, message: `thread ${params.threadId} already has an active writer` },
        });
        return undefined;
      },
    },
  });
  await assert.rejects(agent.resumeSession({ sessionId: SESSION, workspace: "/w" }), (error: unknown) => {
    assert.ok(error instanceof Error);
    assert.match(error.message, /^Another Codex program, such as the Codex app or the CLI, has this conversation open/);
    return true;
  });
});

test("sessions are listed for the workspace, every page of them, without subagents", async () => {
  const { agent } = harness({
    handlers: {
      "thread/list": (params) => {
        if (params.cursor === "page-2") {
          assert.deepEqual(params, { cwd: "/w", limit: 100, cursor: "page-2" });
          return { data: [{ id: "c", preview: "Older work" }], nextCursor: null };
        }
        assert.deepEqual(params, { cwd: "/w", limit: 100 });
        return {
          data: [
            {
              id: "a",
              name: null,
              preview: "Fix the parser\nplease",
              createdAt: 1_700_000_000,
              updatedAt: 1_700_000_100,
            },
            { id: "b", preview: "x", parentThreadId: "a" },
          ],
          nextCursor: "page-2",
        };
      },
    },
  });
  const { sessions } = await agent.listSessions({ workspace: "/w" });
  assert.deepEqual(sessions, [
    {
      id: "a",
      title: "Fix the parser",
      createdAt: new Date(1_700_000_000_000).toISOString(),
      updatedAt: new Date(1_700_000_100_000).toISOString(),
    },
    { id: "c", title: "Older work" },
  ]);
});

test("reading a session pages its turns, rebuilds its subagents and names it", async () => {
  const { agent, events } = harness({
    handlers: {
      "thread/read": (params) =>
        params.threadId === "root"
          ? { thread: { id: "root", name: null, preview: "Count the tests", historyMode: "paginated" } }
          : { thread: { id: params.threadId, preview: "Child work", agentNickname: "Euler" } },
      "thread/turns/list": (params) => {
        if (params.threadId === "child-1") {
          return {
            data: [{ id: "tc", status: "completed", items: [{ type: "agentMessage", id: "cm", text: "42." }] }],
            nextCursor: null,
          };
        }
        assert.equal(params.itemsView, "full");
        assert.equal(params.sortDirection, "desc");
        return params.cursor === null
          ? {
              data: [
                {
                  id: "t2",
                  status: "completed",
                  items: [
                    spawnItem("s", "root", "child-1", "Child work"),
                    { type: "agentMessage", id: "m", text: "Done" },
                  ],
                },
              ],
              nextCursor: "c2",
            }
          : {
              data: [
                {
                  id: "t1",
                  status: "completed",
                  items: [{ type: "userMessage", id: "u1", content: [{ type: "text", text: "Count the tests" }] }],
                },
              ],
              nextCursor: null,
            };
      },
    },
  });
  const { items } = await agent.readSession({ workspace: "/w", sessionId: "root" });
  assert.deepEqual(
    items.map((item) => item.role),
    ["user", "task", "assistant"],
  );
  assert.ok(items[1].role === "task");
  assert.equal(items[1].task.name, "Euler");
  assert.deepEqual(
    present(items[1].items).map((item) => {
      assert.ok(item.role === "assistant");
      return item.text;
    }),
    ["42."],
  );
  assert.deepEqual(present(events.at(-1)), { sessionId: "root", event: "session_info", title: "Count the tests" });
});

/// An image sent as a file path (Codex's own app, its CLI) shows as the
/// picture, read through Codex; one whose file is gone shows its path.
test("a thread's images sent by path are read back as pictures", async () => {
  const { agent } = harness({
    handlers: {
      "thread/read": () => ({ thread: { id: "pics", preview: "" } }),
      "thread/turns/list": () => ({
        data: [
          {
            id: "t",
            status: "completed",
            items: [
              {
                type: "userMessage",
                id: "u",
                content: [
                  { type: "text", text: "compare" },
                  { type: "localImage", path: "/shots/a.PNG" },
                  { type: "localImage", path: "/shots/gone.jpg" },
                ],
              },
            ],
          },
        ],
        nextCursor: null,
      }),
      "fs/readFile": (params, message, peer) => {
        if (params.path === "/shots/a.PNG") return { dataBase64: "AAA=" };
        peer.send({ jsonrpc: "2.0", id: message.id, error: { code: -32000, message: "not found" } });
        return undefined;
      },
    },
  });
  const { items } = await agent.readSession({ workspace: "/w", sessionId: "pics" });
  assert.deepEqual(items[0]?.role === "user" && items[0].blocks, [
    { type: "text", text: "compare" },
    { type: "image", mimeType: "image/png", data: "AAA=" },
    { type: "file_ref", path: "/shots/gone.jpg" },
  ]);
});

// A thread longer than the import cap keeps its latest turns and says the
// older ones are left out.
test("reading a very long thread keeps its newest turns and says it was cut", async () => {
  const TOTAL = 2150;
  const { agent } = harness({
    handlers: {
      "thread/read": () => ({ thread: { id: "long", preview: "", historyMode: "paginated" } }),
      "thread/turns/list": (params) => {
        // Newest first: turn TOTAL - 1 is the latest.
        const from = params.cursor === null ? TOTAL - 1 : Number(params.cursor);
        const ids = Array.from({ length: Math.min(100, from + 1) }, (_, i) => from - i);
        const last = ids.at(-1) ?? 0;
        return {
          data: ids.map((n) => ({
            id: `t${n}`,
            status: "completed",
            items: [{ type: "agentMessage", id: `m${n}`, text: `reply ${n}` }],
          })),
          nextCursor: last > 0 ? String(last - 1) : null,
        };
      },
    },
  });
  const { items } = await agent.readSession({ workspace: "/w", sessionId: "long" });
  assert.deepEqual(items[0], {
    id: "long/cut",
    role: "notice",
    text: "Only the latest 2000 turns of this Codex conversation are shown.",
  });
  const replies = items.slice(1).map((item) => (item.role === "assistant" ? item.text : item.role));
  assert.equal(replies.length, 2000);
  assert.equal(replies[0], "reply 150", "the oldest turns are the ones left out");
  assert.equal(replies.at(-1), `reply ${TOTAL - 1}`, "the latest turn is kept, last");
});

test("a legacy thread without paged turns falls back to thread/read", async () => {
  const { agent } = harness({
    handlers: {
      "thread/read": (params) =>
        params.includeTurns
          ? {
              thread: {
                id: "old",
                turns: [
                  { id: "t", status: "completed", items: [{ type: "agentMessage", id: "m", text: "old reply" }] },
                ],
              },
            }
          : { thread: { id: "old", preview: "" } },
      "thread/turns/list": () => ({ data: [], nextCursor: null }),
    },
  });
  const { items } = await agent.readSession({ workspace: "/w", sessionId: "old" });
  assert.deepEqual(
    items.map((item) => {
      assert.ok(item.role === "assistant");
      return item.text;
    }),
    ["old reply"],
  );
});

test("a thread Codex no longer has adds nothing to the chat, and other read failures still fail", async () => {
  const error = (code: number, message: string) => (_: Record<string, unknown>, request: TestMessage, peer: FakePeer) => {
    peer.send({ jsonrpc: "2.0", id: request.id, error: { code, message } });
    return undefined;
  };
  const gone = harness({ handlers: { "thread/read": error(-32600, "thread not loaded: gone") } }).agent;
  assert.deepEqual(await gone.readSession({ workspace: "/w", sessionId: "gone" }), { items: [], aliases: [], echoes: [] });
  const broken = harness({ handlers: { "thread/read": error(-32603, "failed to read thread: disk") } }).agent;
  await assert.rejects(broken.readSession({ workspace: "/w", sessionId: "gone" }), /failed to read thread: disk/);
});

test("history aliases survive reload only through genuine native/client identity", async () => {
  const storage = memoryStorage();
  const key = (kind: string, id: string) => `history:${JSON.stringify([kind, "codex", SESSION, id])}`;
  const handlers: Handlers = {
    "turn/steer": (params) => {
      assert.equal(params.clientUserMessageId, "attempt-user");
      assert.equal(storage.values.get(key("client", "attempt-user")), "host-user", "persist before native delivery");
      return { turnId: "turn-1" };
    },
    "thread/read": () => ({ thread: { id: SESSION, historyMode: "paginated" } }),
    "thread/turns/list": () => ({
      data: [
        {
          id: "turn-1",
          status: "completed",
          items: [
            { type: "userMessage", id: "native-user", content: [{ type: "text", text: "same text" }] },
            { type: "userMessage", id: "external-user", content: [{ type: "text", text: "same text" }] },
            // An admission attempt token is not, by itself, a native history alias.
            { type: "userMessage", id: "attempt-user", content: [{ type: "text", text: "same text" }] },
          ],
        },
      ],
      nextCursor: null,
    }),
  };
  const { agent } = harness({ handlers, onHost: storage });
  await agent.prompt({
    sessionId: SESSION,
    input: {
      itemId: "host-user",
      delivery: { inputId: "host-user", attemptId: "attempt-user", intent: "steer" },
      blocks: [{ type: "text", text: "same text" }],
    },
  });
  notify(agent, "item/completed", {
    threadId: SESSION,
    item: { type: "userMessage", id: "native-user", clientId: "attempt-user" },
  });
  await settle();
  assert.equal(storage.values.get(key("native", "native-user")), "host-user");
  const reloaded = harness({ handlers, onHost: storage }).agent;
  const history = await reloaded.readSession({ workspace: "/w", sessionId: SESSION });
  assert.deepEqual(history.aliases, [{ itemId: "host-user", nativeItemId: "native-user" }]);
  assert.equal(history.items.length, 3, "identical genuine messages remain distinct");
  assert.deepEqual((await reloaded.readSession({ workspace: "/w", sessionId: "other-thread" })).aliases, []);
});

test("legacy Alpha input ids are persisted and submitted for positive history correlation", async () => {
  const storage = memoryStorage();
  const { agent } = harness({
    onHost: storage,
    handlers: {
      "turn/steer": (params) => {
        assert.equal(params.clientUserMessageId, "alpha-host-user");
        return { turnId: "turn-1" };
      },
      "thread/read": () => ({ thread: { id: SESSION, historyMode: "paginated" } }),
      "thread/turns/list": () => ({
        data: [
          {
            id: "turn-1",
            status: "completed",
            items: [
              {
                type: "userMessage",
                id: "native-alpha",
                clientId: "alpha-host-user",
                content: [{ type: "text", text: "request" }],
              },
            ],
          },
        ],
        nextCursor: null,
      }),
    },
  });
  await agent.prompt({
    sessionId: SESSION,
    input: { itemId: "alpha-host-user", blocks: [{ type: "text", text: "request" }] },
  });
  assert.deepEqual((await agent.readSession({ workspace: "/w", sessionId: SESSION })).aliases, [
    { itemId: "alpha-host-user", nativeItemId: "native-alpha" },
  ]);
});

test("a failed identity write rejects before native delivery", async () => {
  const { agent, api, events } = harness({
    handlers: { "turn/steer": () => assert.fail("must not deliver without persisted identity") },
    onHost: (method) => {
      if (method === "host/storage.set") throw new Error("storage unavailable");
      return null;
    },
  });
  await assert.rejects(
    agent.prompt({
      sessionId: SESSION,
      input: {
        itemId: "host-user",
        delivery: { inputId: "host-user", attemptId: "attempt-user", intent: "steer" },
        blocks: [{ type: "text", text: "request" }],
      },
    }),
    /Could not retain input identity/,
  );
  assert.ok(events.some((event) => event.event === "input_rejected" && event.inputId === "host-user"));
  assert.equal(
    api.peers.flatMap((peer) => peer.received).filter((message) => message.method === "turn/steer").length,
    0,
  );
});

// Explicit after-run queues stay on the host: the provider refuses the
// prompt with evidence for the input and its context, and no native write.
test("a queued prompt is rejected with its context and without the intent", async () => {
  const { agent, api, events } = harness({});
  await assert.rejects(
    agent.prompt({
      sessionId: SESSION,
      input: {
        delivery: { inputId: "held", attemptId: "attempt-held", intent: "queue" },
        context: { id: "ctx-held", instructions: "Historical reference", text: "Past work", artifacts: [] },
        blocks: [{ type: "text", text: "later" }],
      },
    }),
    /held by the host/,
  );
  assert.deepEqual(
    events.filter((event) => event.event === "input_rejected" || event.event === "context_rejected"),
    [
      {
        sessionId: SESSION,
        event: "input_rejected",
        inputId: "held",
        attemptId: "attempt-held",
        reason: "Queued input must remain held by the host",
      },
      {
        sessionId: SESSION,
        event: "context_rejected",
        attemptId: "attempt-held",
        contextId: "ctx-held",
        reason: "Queued input must remain held by the host",
      },
    ],
  );
  assert.equal(
    api.peers.flatMap((peer) => peer.received).filter((message) => message.method?.startsWith("turn/")).length,
    0,
  );
});

test("skills are listed per workspace and their paths kept for prompts", async () => {
  const { agent, api } = harness({
    handlers: {
      "skills/list": (params) => {
        assert.deepEqual(params, { cwds: ["/w"], forceReload: true });
        return {
          data: [
            {
              skills: [
                {
                  name: "review",
                  description: "Long",
                  shortDescription: "Short",
                  path: "/s/review",
                  scope: "user",
                  enabled: true,
                },
                { name: "off", description: "", path: "/s/off", enabled: false },
              ],
            },
          ],
        };
      },
      "turn/start": () => ({ turn: { id: "t" } }),
    },
  });
  const { skills } = await agent.listSkills({ workspace: "/w" });
  assert.deepEqual(skills, [{ name: "review", description: "Short", source: "user", manualOnly: false }]);
  present(agent.sessions.get(SESSION)).run = null;
  await agent.prompt({ sessionId: SESSION, input: { blocks: [{ type: "skill", name: "review", input: "" }] } });
  const turn = await api.peers[0].waitFor((message) => message.method === "turn/start");
  assert.deepEqual(turn.params.input, [
    { type: "text", text: "$review", text_elements: [] },
    { type: "skill", name: "review", path: "/s/review" },
  ]);
});

test("rollback reverts from the turn the host's message started", async () => {
  const reverts: Record<string, unknown>[] = [];
  const { agent } = harness({
    handlers: {
      "thread/revert": (params) => {
        reverts.push(params);
        return {};
      },
      "thread/turns/list": () => ({
        data: [{ id: "turn-a", items: [{ type: "userMessage", id: "codex-item", content: [] }] }],
        nextCursor: null,
      }),
    },
  });
  present(agent.sessions.get(SESSION)).turns.set("host-item", "turn-7");
  await agent.rollback({ sessionId: SESSION, itemId: "host-item" });
  await agent.rollback({ sessionId: SESSION, itemId: "codex-item" });
  assert.deepEqual(reverts, [
    { threadId: SESSION, beforeTurnId: "turn-7" },
    { threadId: SESSION, beforeTurnId: "turn-a" },
  ]);
  await assert.rejects(agent.rollback({ sessionId: SESSION, itemId: "nobody" }), /codex does not know message nobody/);
});

test("a fork before a message keeps the turns before the one it started", async () => {
  const forks: Record<string, unknown>[] = [];
  const { agent } = harness({
    handlers: {
      "thread/fork": (params) => {
        forks.push(params);
        return { thread: { id: `forked-${forks.length}` } };
      },
      "thread/turns/list": () => ({
        data: [
          // Newest first, as Codex pages them.
          { id: "turn-c", items: [{ type: "userMessage", id: "third", content: [] }] },
          { id: "turn-b", items: [{ type: "userMessage", id: "codex-item", content: [] }] },
          { id: "turn-a", items: [{ type: "userMessage", id: "first", content: [] }] },
        ],
        nextCursor: null,
      }),
    },
  });
  present(agent.sessions.get(SESSION)).turns.set("host-item", "turn-c");
  await agent.forkSession({ sessionId: SESSION, workspace: "/w", options: {}, itemId: "codex-item" });
  await agent.forkSession({ sessionId: SESSION, workspace: "/w", options: {}, itemId: "host-item" });
  await agent.forkSession({ sessionId: SESSION, workspace: "/w", options: {} });
  assert.deepEqual(
    forks.map((params) => params.lastTurnId),
    ["turn-a", "turn-b", undefined],
  );
  await assert.rejects(
    agent.forkSession({ sessionId: SESSION, workspace: "/w", options: {}, itemId: "first" }),
    /nothing comes before the first message/,
  );
  await assert.rejects(
    agent.forkSession({ sessionId: SESSION, workspace: "/w", options: {}, itemId: "nobody" }),
    /codex does not know message nobody/,
  );
});

test("fork, compact, close, logout and sign-in go to their codex methods", async () => {
  const seen: [string | undefined, Record<string, unknown>][] = [];
  let opened = null;
  const record = (result: unknown) => (params: Record<string, unknown>, message: TestMessage) => {
    seen.push([message.method, params]);
    return result;
  };
  const { agent, api } = harness({
    handlers: {
      "thread/fork": record({ thread: { id: "forked" } }),
      "thread/compact/start": record({}),
      "thread/unsubscribe": record({}),
      "account/logout": record({}),
      "account/login/start": record({ type: "chatgpt", loginId: "l1", authUrl: "https://auth.openai.com/oauth?x=1" }),
      "account/login/cancel": record({ status: "canceled" }),
    },
  });
  api.openUrl = async (url) => {
    opened = url;
    return { opened: true };
  };
  assert.deepEqual(
    await agent.forkSession({ sessionId: SESSION, workspace: "/w", options: {}, instructions: "Rules" }),
    { sessionId: "forked" },
  );
  assert.ok(agent.sessions.has("forked"));
  await agent.compact({ sessionId: SESSION });
  await agent.logout();
  // The sign-in answers when the browser has finished it, not when the page opens.
  let signedIn = false;
  const signingIn = agent.authenticate({ method: "chatgpt" }).then(() => (signedIn = true));
  await new Promise((resolve) => setTimeout(resolve, 20));
  assert.equal(opened, "https://auth.openai.com/oauth?x=1");
  assert.equal(signedIn, false);
  agent.onNotification("account/login/completed", { loginId: "l1", success: true, error: null });
  await signingIn;
  const failing = agent.authenticate({ method: "chatgpt" });
  await new Promise((resolve) => setTimeout(resolve, 20));
  agent.onNotification("account/login/completed", { loginId: "l1", success: false, error: "Login timed out" });
  await assert.rejects(failing, /Login timed out/);
  await agent.closeSession({ sessionId: SESSION });
  assert.equal(agent.sessions.has(SESSION), false);
  assert.deepEqual(
    seen.map(([method]) => method),
    ["thread/fork", "thread/compact/start", "account/logout", "account/login/start", "account/login/start", "thread/unsubscribe"],
  );
  assert.equal(seen[0][1].developerInstructions, "Rules");
  assert.deepEqual(seen[3][1], { type: "chatgpt" });
  assert.equal(opened, "https://auth.openai.com/oauth?x=1");
  // A link the runtime did not open is the sign-in's error, with its reason.
  api.openUrl = async () => ({ opened: false, reason: "only web and mail links open" });
  await assert.rejects(
    agent.authenticate({ method: "chatgpt" }),
    /open https:\/\/auth\.openai\.com\/oauth\?x=1 in a browser to sign in \(only web and mail links open\)/,
  );
  // That sign-in is cancelled, so Codex does not keep waiting for a browser.
  assert.deepEqual(seen.at(-1), ["account/login/cancel", { loginId: "l1" }]);
});

test("resume re-attaches with the chat's settings", async () => {
  const resumedCalls: Record<string, unknown>[] = [];
  const { agent } = harness({
    handlers: {
      "thread/resume": (params) => {
        resumedCalls.push(params);
        return { thread: { id: params.threadId } };
      },
    },
  });
  await agent.resumeSession({
    sessionId: "thread-9",
    workspace: "/w9",
    options: { permission_mode: "auto" },
    instructions: "Rules",
  });
  const resumed = resumedCalls[0];
  assert.deepEqual(
    [resumed.threadId, resumed.cwd, resumed.excludeTurns, resumed.approvalsReviewer, resumed.developerInstructions],
    ["thread-9", "/w9", true, "auto_review", "Rules"],
  );
  assert.equal(present(agent.sessions.get("thread-9")).workspace, "/w9");
});

test("resume recovers only the exact native missing-rollout error, not auth or transport failures", async () => {
  for (const [code, message, missing] of [
    [-32600, `no rollout found for thread id ${SESSION}`, true],
    [-32600, "thread is archived", false],
    [-32600, "no rollout found for thread id different-thread", false],
    [-32603, `no rollout found for thread id ${SESSION}`, false],
    [-32603, "connection closed", false],
    [-32001, "unauthorized", false],
  ] as const) {
    const { agent } = harness({
      handlers: {
        "thread/resume": (_params, request, peer) => {
          peer.send({ jsonrpc: "2.0", id: request.id, error: { code, message } });
        },
      },
    });
    if (missing) {
      assert.match(
        (await agent.resumeSession({ sessionId: SESSION, requireResume: true })).unavailable!,
        /no persisted history/,
      );
      await assert.rejects(
        agent.resumeSession({ sessionId: SESSION }),
        /thread\/resume failed/,
        "older Alpha must not mistake unavailability for a successful resume",
      );
    } else
      await assert.rejects(agent.resumeSession({ sessionId: SESSION, requireResume: true }), /thread\/resume failed/);
  }
});

test("the handlers the host calls are the agent protocol's methods", () => {
  const { agent } = harness();
  const definition = agent.definition();
  for (const method of [
    "initialize",
    "list_options",
    "list_commands",
    "list_sessions",
    "read_session",
    "list_skills",
    "create_session",
    "resume_session",
    "close_session",
    "fork_session",
    "prompt",
    "cancel",
    "cancel_task",
    "set_option",
    "respond_to_approval",
    "respond_to_question",
    "rollback",
    "compact",
    "usage_limits",
    "update",
    "authenticate",
    "logout",
  ]) {
    assert.equal(typeof Reflect.get(definition, method), "function", method);
  }
  assert.deepEqual([definition.id, definition.name], ["codex", "Codex"]);
});

function present<T>(value: T | null | undefined): T {
  assert.ok(value != null);
  return value;
}

test("concurrent first calls share one scoped app-server", async () => {
  const { agent, api } = harness();
  const peers = await Promise.all([agent.client(), agent.client(), agent.client()]);
  assert.equal(api.peers.length, 1);
  assert.ok(peers.every((peer) => peer === peers[0]));
  assert.equal(api.peers[0].received.filter((message) => message.method === "initialize").length, 1);
});

test("background jobs offered before the consumer runs are retained in order", async () => {
  const { agent } = harness();
  const seen: number[] = [];
  // Synchronous notification routing can enqueue work before the forked
  // consumer gets its first turn; a subscription stream would lose it.
  agent.enqueue(
    Effect.sync(() => {
      seen.push(1);
    }),
  );
  agent.enqueue(
    Effect.sync(() => {
      seen.push(2);
    }),
  );
  await settle();
  assert.deepEqual(seen, [1, 2]);
});

test("the additive history contract still accepts readonly provider records", () => {
  // A compile-time regression: adding aliases must not require providers
  // that already return readonly histories to make them mutable.
  const items: readonly TranscriptItem[] = [{ id: "host", role: "assistant", text: "reply" }];
  const aliases: readonly HistoryAlias[] = [{ itemId: "host", nativeItemId: "native" }];
  const legacy: AgentMethods["read_session"]["result"] = { items };
  const correlated: AgentMethods["read_session"]["result"] = { items, aliases };
  assert.equal(legacy.items, items);
  assert.equal(correlated.aliases, aliases);
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.5latestNov 21, 2026>=5 <6121.1 KB4 permissionsListed
0.2.4Nov 16, 2026>=5 <6120.2 KB4 permissionsListed
0.2.3Nov 11, 2026>=5 <695.2 KB4 permissionsListed
0.2.2Nov 9, 2026>=5 <688.9 KB4 permissionsListed
0.2.1Oct 27, 2026>=2 <484.1 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.