@alpacakit/agents 0.1.0-beta.39 → 0.2.0-beta.2

package/README.md

@@ -150,6 +150,109 @@ Each recovery call performs one authenticated termination convergence. A
 typed `pending` result invokes no lifecycle callback; the host owns the
 cancellable retry cadence and calls `recover` again when appropriate.
 
+## Sessions: hold a conversation and talk to it (`agent.session`)
+
+`run()` is one prompt, one process, one answer. A **Session** is the other
+shape a host offers: one Claude (`claude -p --input-format stream-json`) or
+Codex (`codex app-server` thread) process held open across turns, which a
+UI or an orchestrator keeps talking to. `agent.session` is `null` when the
+definition has no session facet; `claude()` and `codex()` provide one.
+
+```ts
+const runtime = createAgentRuntime({ agents: [claude(), codex()], baseEnv: processEnv() });
+const sessions = runtime.agent("codex").session!;
+
+const session = await sessions.open({
+  workspace: "/work/repo",
+  permissions: {
+    approvalPolicy: "on-request",
+    approvalsReviewer: "user",
+    sandbox: { type: "read-only" },
+  },
+});
+void (async () => {
+  for await (const event of session.events) {
+    // turn_started / message / tool / approval_requested / turn_ended / exited
+    if (event.type === "approval_requested") await session.respond(event.requestId, "accept");
+  }
+})();
+const turn = await session.send("Summarize the failing tests.");   // { turnId, outcome, text }
+await session.steer("Also list the flaky ones.");                  // into the running turn
+await session.interrupt();                                         // turn ends with outcome "interrupted"
+await session.close();                                             // EOF, then signals; releases the host's lock
+
+const facts = await sessions.inspect(session.id, { homeDir });      // { workspace, lastPermissions, owner, archived } | null
+const again = await sessions.resume(session.id, { workspace: facts!.workspace, permissions: facts!.lastPermissions! });
+// An archived Codex thread resumes only with `unarchive: true` (see below).
+```
+
+`send()` starts one turn and resolves when the host ends it; exactly one
+turn runs at a time (`send` needs idle — including while a Codex
+`turn/start` is still unanswered — and `steer` / `interrupt` need a running
+turn; anything else is a typed `invalid_input`). `Session.id` is the host's
+own conversation id (Claude `session_id`, Codex thread id), so it is what
+the host's files, `--resume`, and `thread/resume` know.
+
+`approval_requested.decisions` is always `["accept", "decline"]`: Claude's
+`can_use_tool` takes allow or deny, and Codex takes `decline` for every
+request even when its own `availableDecisions` lists only `accept` plus
+amendment / `cancel` variants. Requests belong to the turn that raised
+them — once the turn ends, `respond` for them is an `invalid_input`; after
+the session ended it is "session is closed" for both hosts.
+
+Permissions are **per host**, never the neutral `Sandbox` of `run()`:
+`ClaudeSessionPermissions { mode }` (spelled as the transcript's
+`permissionMode`; the CLI flag spells `default` as `manual`, and
+`bypassPermissions` also passes `--allow-dangerously-skip-permissions`;
+every Claude session passes `--permission-prompt-tool stdio` so approval
+prompts reach `events` instead of being auto-denied) and `CodexSessionPermissions
+{ approvalPolicy, approvalsReviewer, sandbox }` with `sandbox` being
+`read-only`, `danger-full-access`, or `workspace-write { writableRoots,
+networkAccess, excludeTmpdirEnvVar, excludeSlashTmp }` (sent as config.toml
+overrides on `thread/start` / `thread/resume`). `resume` always passes them
+explicitly: a Codex `thread/resume` without `sandbox` ran as
+danger-full-access in the lab.
+
+Facts hosts write that `inspect` reads (through `HostLocation.homeDir`, never
+`os.homedir()`): Claude `~/.claude/projects/*/<id>.jsonl` (first `cwd`, last
+`permissionMode`) and `~/.claude/sessions/<pid>.json` (`owner.pid`,
+`owner.entrypoint`); Codex `~/.codex/sessions/YYYY/MM/DD/rollout-*-<id>.jsonl`
+or `archived_sessions/` (`archived`), `session_meta.cwd`, last
+`turn_context`, and `thread-writer-locks/<id>.lock` (`owner` with `pid: null`
+— the lock does not say who). `inspect` reports what is recorded; it does not
+probe whether a recorded pid is alive.
+
+**Codex trust note.** `open()` with a writable sandbox (`workspace-write`,
+`danger-full-access`) makes Codex append a `trust_level` entry for the
+workspace to `~/.codex/config.toml` (observed with codex 0.153.4);
+`read-only` does not. Surface that before offering a writable `open()`.
+Whether `resume()` with a writable sandbox appends the same entry is
+**unverified** (the lab only resumed with `read-only`).
+
+**Codex archive note.** `resume()` of an archived thread fails by default
+with the server's "is archived" message (`inspect(id).archived` tells you
+beforehand). Pass `unarchive: true` to `thread/unarchive` it first — that
+also moves the thread back into the ChatGPT app's active list, which is
+why it is opt-in. Claude has no archive; the option is ignored there.
+
+Design conditions this facet keeps (T60 v3):
+
+- C1 — permissions are host-typed; the neutral `Sandbox` never learns `workspace-write`.
+- C2 — a Session holds a plain `Exec` child with `keepStdinOpen`; it does not go through `ControlledExec`. If the embedding process restarts, `resume` is the recovery path.
+- C3 — the app-server client never kills the process on a request timeout; only that request fails. `close()` is the one place the process is ended.
+- C4 — every host-file read goes through `HostLocation.homeDir`.
+- C5 — Claude approvals were verified in the lab (`--permission-prompt-tool stdio` → `control_request` / `can_use_tool` → `control_response` allow/deny), so `respond` is supported for both hosts.
+- C6 — consumers pin an exact version of this package and upgrade libs first, then the consumer, when a host CLI changes its protocol.
+
+Not supported (by choice, or unverified):
+
+- Claude control requests other than `can_use_tool` are ignored (logged) — if the CLI ever waits on one, that turn hangs until `interrupt()`; Codex server requests other than `item/commandExecution/requestApproval` and `item/fileChange/requestApproval` are refused with JSON-RPC -32601 so a turn never hangs on them. Neither case has been observed in the lab.
+- Claude's stream carries no turn id, so a `steer()` that lands after the host has already ended the turn is taken by the CLI as the next turn's prompt; the following `send()` then resolves with that orphan turn's result. Steer only while a `tool` event has shown the turn is still working.
+- Decisions are `accept` / `decline` only — no `acceptForSession`, execpolicy amendments, or `cancel`; Codex `approvalPolicy` is `untrusted` / `on-request` / `never` (the granular object form and `externalSandbox` decode to `lastPermissions: null` in `inspect`).
+- No per-turn limits or guards on a Session; use `interrupt()`. `open()` takes no `AbortSignal`; use `close()`.
+- `claude({ customizations: "disabled" })` sessions pass `--safe-mode --strict-mcp-config` but keep session persistence (a Session is the recorded conversation).
+- The Claude child needs `USER` in `baseEnv` (keychain lookup); with only `PATH` / `HOME` the CLI reports "Not logged in".
+
 ## Structured output
 
 Any Standard Schema validator (zod v4 etc.) works. Repair happens within
@@ -303,7 +406,24 @@ installed skills and MCP servers remains in progress.
 | `/config/xdg` | XDG Base Directory config-root preset (general apps) |
 | `/config/extension` | custom agent-config kinds (`defineAgentConfigType`) |
 | `/testing` | `fakeExec`, `fakeClock`, `fakeAgent`, `fakeSecretResolver` — no subprocess ever spawns |
-| `/codex` | codex app-server JSON-RPC client (advanced) |
+| `/codex` | codex app-server JSON-RPC client: typed requests, `incoming` notifications / server requests, `respond` (advanced) |
+
+## Breaking changes in 0.2.0
+
+- `Agent.session` (and `AgentDefinition.session`) are new; `AgentDefinition`
+  and `Agent` gained a session-permissions type parameter, and `AgentRuntime`
+  a second parameter for the definition list so `runtime.agent(id).session`
+  is typed per agent (defaults keep existing annotations compiling).
+  `claude()` / `codex()` return definitions typed with their permission
+  shapes.
+- `@alpacakit/agents/codex`: `CodexAppServer` gained `incoming`, `respond`,
+  `exit`, and `stderrTail`; a request timeout no longer kills the server
+  process; `close()` ends stdin and waits for the child to exit, escalating
+  to SIGTERM after 5 s and SIGKILL after another 5 s. Host-plane calls
+  (`agent.skills.list`, `agent.mcp.list` for codex) therefore take up to
+  10 s longer than before when the server hangs, instead of being killed at
+  once. `thread/*` and `turn/*` methods are registered.
+- `run()` behavior is unchanged.
 
 ## Status
 

package/dist/agents/claude-session.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Claude session adapter: one `claude -p --input-format stream-json
+ * --output-format stream-json` process held open across turns.
+ *
+ * Protocol facts (claude 2.1.270, T52 / T61 lab runs):
+ * - a turn is one user line `{"type":"user","message":{"role":"user","content":…}}`
+ *   and ends with the `result` line; a user line written mid-turn is absorbed
+ *   into the running turn at its next tool boundary (`steer`);
+ * - `{"type":"control_request","request_id":…,"request":{"subtype":"interrupt"}}`
+ *   is answered by a `control_response`, and the turn then ends with
+ *   `is_error: true` / `terminal_reason: "aborted_tools"`;
+ * - approval prompts reach stdout only with `--permission-prompt-tool stdio`, as
+ *   `control_request` / `can_use_tool`, and are answered with a
+ *   `control_response` whose `behavior` is `allow` (+ `updatedInput`) or `deny`;
+ * - `--session-id <uuid>` fixes the id before the first turn (no `init` line
+ *   is emitted until then), `--resume <id>` continues a recorded one;
+ * - the child needs `USER` in its env: without it the CLI reports "Not logged in".
+ */
+import { type SessionCapability } from "../kernel/session.js";
+export declare const CLAUDE_PERMISSION_MODE: {
+    readonly default: "default";
+    readonly acceptEdits: "acceptEdits";
+    readonly auto: "auto";
+    readonly bypassPermissions: "bypassPermissions";
+    readonly dontAsk: "dontAsk";
+    readonly plan: "plan";
+};
+export type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODE)[keyof typeof CLAUDE_PERMISSION_MODE];
+/** Spelled as the transcript's `permissionMode` records it. */
+export type ClaudeSessionPermissions = {
+    readonly mode: ClaudePermissionMode;
+};
+export type ClaudeSessionOptions = {
+    readonly customizations: "inherit" | "disabled";
+};
+export declare function claudeSessions(options: ClaudeSessionOptions): SessionCapability<ClaudeSessionPermissions>;
+//# sourceMappingURL=claude-session.d.ts.map

package/dist/agents/claude-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-session.d.ts","sourceRoot":"","sources":["../../src/agents/claude-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkCH,OAAO,EAGL,KAAK,iBAAiB,EAKvB,MAAM,sBAAsB,CAAC;AAG9B,eAAO,MAAM,sBAAsB;;;;;;;CAOzB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAC9B,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,OAAO,sBAAsB,CAAC,CAAC;AAEvE,+DAA+D;AAC/D,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC,CAAC;AA6EF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,CAAC;CACjD,CAAC;AA4YF,wBAAgB,cAAc,CAC5B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAAC,wBAAwB,CAAC,CAoB7C"}

package/dist/agents/claude-session.js

@@ -0,0 +1,419 @@
+/**
+ * Claude session adapter: one `claude -p --input-format stream-json
+ * --output-format stream-json` process held open across turns.
+ *
+ * Protocol facts (claude 2.1.270, T52 / T61 lab runs):
+ * - a turn is one user line `{"type":"user","message":{"role":"user","content":…}}`
+ *   and ends with the `result` line; a user line written mid-turn is absorbed
+ *   into the running turn at its next tool boundary (`steer`);
+ * - `{"type":"control_request","request_id":…,"request":{"subtype":"interrupt"}}`
+ *   is answered by a `control_response`, and the turn then ends with
+ *   `is_error: true` / `terminal_reason: "aborted_tools"`;
+ * - approval prompts reach stdout only with `--permission-prompt-tool stdio`, as
+ *   `control_request` / `can_use_tool`, and are answered with a
+ *   `control_response` whose `behavior` is `allow` (+ `updatedInput`) or `deny`;
+ * - `--session-id <uuid>` fixes the id before the first turn (no `init` line
+ *   is emitted until then), `--resume <id>` continues a recorded one;
+ * - the child needs `USER` in its env: without it the CLI reports "Not logged in".
+ */
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { AGENT_ERROR_CODE, AgentError, TIMEOUT_KIND } from "../core/error.js";
+import { readJsonRecord, readNumber, readRecord, readString, } from "../core/json.js";
+import { redactSecrets } from "../core/redact.js";
+import { AGENT_EVENT_TYPE } from "../core/run.js";
+import { APPROVAL_DECISION, SESSION_EVENT_TYPE, SESSION_OWNER_KIND, TURN_OUTCOME, } from "../core/session.js";
+import { fileExists, readDirectoryNames, readJsonFile, scanJsonlFirstLast, } from "../host/session-files.js";
+import { assertHostSessionId, SessionProcess, SessionState, sessionStateError, } from "../kernel/session.js";
+import { CLAUDE, parseClaudeLine } from "./claude-stream.js";
+export const CLAUDE_PERMISSION_MODE = {
+    default: "default",
+    acceptEdits: "acceptEdits",
+    auto: "auto",
+    bypassPermissions: "bypassPermissions",
+    dontAsk: "dontAsk",
+    plan: "plan",
+};
+const CLAUDE_SESSION = {
+    cli: {
+        inputFormat: "--input-format",
+        permissionPromptTool: "--permission-prompt-tool",
+        stdio: "stdio",
+        resume: "--resume",
+        sessionId: "--session-id",
+        allowDangerouslySkipPermissions: "--allow-dangerously-skip-permissions",
+        /** The CLI spells the transcript's `default` mode `manual` on its flag. */
+        manualPermissionMode: "manual",
+    },
+    stream: {
+        type: {
+            user: "user",
+            assistant: "assistant",
+            result: "result",
+            controlRequest: "control_request",
+            controlResponse: "control_response",
+        },
+        field: {
+            type: "type",
+            message: "message",
+            role: "role",
+            content: "content",
+            request: "request",
+            requestId: "request_id",
+            response: "response",
+            subtype: "subtype",
+            error: "error",
+            toolName: "tool_name",
+            description: "description",
+            input: "input",
+            isError: "is_error",
+            result: "result",
+            behavior: "behavior",
+            updatedInput: "updatedInput",
+        },
+        subtype: {
+            interrupt: "interrupt",
+            canUseTool: "can_use_tool",
+            success: "success",
+            error: "error",
+        },
+        behavior: { allow: "allow", deny: "deny" },
+    },
+    files: {
+        root: ".claude",
+        projects: "projects",
+        sessions: "sessions",
+        transcriptExtension: ".jsonl",
+        registryExtension: ".json",
+        cwd: "cwd",
+        permissionMode: "permissionMode",
+        sessionId: "sessionId",
+        pid: "pid",
+        entrypoint: "entrypoint",
+    },
+};
+const CONTROL_RESPONSE_TIMEOUT_MS = 30_000;
+const DECLINED_MESSAGE = "Declined by the session owner";
+const CLAUDE_APPROVAL_DECISIONS = [
+    APPROVAL_DECISION.accept,
+    APPROVAL_DECISION.decline,
+];
+function sessionArgs(permissions, target, options) {
+    const mode = permissions.mode === CLAUDE_PERMISSION_MODE.default
+        ? CLAUDE_SESSION.cli.manualPermissionMode
+        : permissions.mode;
+    return [
+        CLAUDE.cli.prompt,
+        CLAUDE_SESSION.cli.inputFormat,
+        CLAUDE.cli.streamJson,
+        CLAUDE.cli.outputFormat,
+        CLAUDE.cli.streamJson,
+        CLAUDE.cli.verbose,
+        CLAUDE.cli.permissionMode,
+        mode,
+        ...(permissions.mode === CLAUDE_PERMISSION_MODE.bypassPermissions
+            ? [CLAUDE_SESSION.cli.allowDangerouslySkipPermissions]
+            : []),
+        CLAUDE_SESSION.cli.permissionPromptTool,
+        CLAUDE_SESSION.cli.stdio,
+        // A session's whole point is the recorded conversation, so `disabled`
+        // drops only the customization flags, never `--no-session-persistence`.
+        ...(options.customizations === "disabled"
+            ? [CLAUDE.cli.safeMode, CLAUDE.cli.strictMcpConfig]
+            : []),
+        target.kind === "resume"
+            ? CLAUDE_SESSION.cli.resume
+            : CLAUDE_SESSION.cli.sessionId,
+        target.sessionId,
+    ];
+}
+class ClaudeSession {
+    id;
+    process;
+    ctx;
+    state = new SessionState(CLAUDE.id);
+    pendingApprovals = new Map();
+    pendingControls = new Map();
+    reading;
+    turnCount = 0;
+    interruptRequested = false;
+    constructor(id, process, ctx) {
+        this.id = id;
+        this.process = process;
+        this.ctx = ctx;
+        this.reading = this.read();
+    }
+    get events() {
+        return this.state.events;
+    }
+    async send(text) {
+        this.state.requireIdle();
+        this.turnCount += 1;
+        const turn = this.state.beginTurn(String(this.turnCount));
+        this.writeUserLine(text);
+        return turn;
+    }
+    async steer(text) {
+        this.state.requireActive();
+        this.writeUserLine(text);
+    }
+    async interrupt() {
+        this.state.requireActive();
+        const requestId = randomUUID();
+        this.interruptRequested = true;
+        const answered = this.awaitControlResponse(requestId);
+        this.process.writeLine(JSON.stringify({
+            type: CLAUDE_SESSION.stream.type.controlRequest,
+            [CLAUDE_SESSION.stream.field.requestId]: requestId,
+            request: { subtype: CLAUDE_SESSION.stream.subtype.interrupt },
+        }));
+        try {
+            await answered;
+        }
+        catch (error) {
+            // An unanswered interrupt must not color the next turn's outcome.
+            this.interruptRequested = false;
+            throw error;
+        }
+    }
+    async respond(requestId, decision) {
+        this.state.requireOpen();
+        if (!this.pendingApprovals.has(requestId)) {
+            throw sessionStateError(CLAUDE.id, `no pending approval request "${requestId}"`);
+        }
+        const input = this.pendingApprovals.get(requestId);
+        this.pendingApprovals.delete(requestId);
+        const response = decision === APPROVAL_DECISION.accept
+            ? {
+                behavior: CLAUDE_SESSION.stream.behavior.allow,
+                updatedInput: input,
+            }
+            : {
+                behavior: CLAUDE_SESSION.stream.behavior.deny,
+                message: DECLINED_MESSAGE,
+            };
+        this.process.writeLine(JSON.stringify({
+            type: CLAUDE_SESSION.stream.type.controlResponse,
+            response: {
+                subtype: CLAUDE_SESSION.stream.subtype.success,
+                [CLAUDE_SESSION.stream.field.requestId]: requestId,
+                response,
+            },
+        }));
+    }
+    async close() {
+        await this.process.close();
+        await this.reading;
+    }
+    writeUserLine(text) {
+        this.process.writeLine(JSON.stringify({
+            type: CLAUDE_SESSION.stream.type.user,
+            message: { role: CLAUDE_SESSION.stream.type.user, content: text },
+        }));
+    }
+    awaitControlResponse(requestId) {
+        return new Promise((resolve, reject) => {
+            const cancelTimeout = this.ctx.clock.setTimeout(() => {
+                this.pendingControls.delete(requestId);
+                reject(new AgentError({
+                    code: AGENT_ERROR_CODE.timeout,
+                    classification: AgentError.agentFailure(AGENT_ERROR_CODE.timeout),
+                    message: "Claude did not answer the control request in time",
+                    data: {
+                        kind: TIMEOUT_KIND.total,
+                        limitMs: CONTROL_RESPONSE_TIMEOUT_MS,
+                    },
+                    agentId: CLAUDE.id,
+                }));
+            }, CONTROL_RESPONSE_TIMEOUT_MS);
+            this.pendingControls.set(requestId, { resolve, reject, cancelTimeout });
+        });
+    }
+    async read() {
+        try {
+            for await (const line of this.process.lines()) {
+                const record = readJsonRecord(line);
+                if (record !== null) {
+                    this.handleRecord(record, line);
+                }
+            }
+        }
+        catch (error) {
+            this.ctx.logger.log("error", "claude session reader failed", error);
+        }
+        finally {
+            // Whatever happened above, the stream must end so `events` consumers
+            // and `close()` are released.
+            const exit = await this.process.exit;
+            for (const pending of this.pendingControls.values()) {
+                pending.cancelTimeout();
+                pending.reject(sessionStateError(CLAUDE.id, "session process exited"));
+            }
+            this.pendingControls.clear();
+            this.pendingApprovals.clear();
+            this.interruptRequested = false;
+            this.state.end(exit, this.process.stderr);
+        }
+    }
+    handleRecord(record, line) {
+        const type = readString(record, CLAUDE_SESSION.stream.field.type);
+        if (type === CLAUDE_SESSION.stream.type.assistant) {
+            for (const event of parseClaudeLine(line)) {
+                if (event.type === AGENT_EVENT_TYPE.message) {
+                    this.state.message(event.text);
+                }
+                else if (event.type === AGENT_EVENT_TYPE.tool) {
+                    this.state.emit({ type: SESSION_EVENT_TYPE.tool, name: event.name });
+                }
+            }
+            return;
+        }
+        if (type === CLAUDE_SESSION.stream.type.result) {
+            this.handleResult(record);
+            return;
+        }
+        if (type === CLAUDE_SESSION.stream.type.controlRequest) {
+            this.handleControlRequest(record);
+            return;
+        }
+        if (type === CLAUDE_SESSION.stream.type.controlResponse) {
+            this.handleControlResponse(record);
+        }
+    }
+    handleResult(record) {
+        const isError = record[CLAUDE_SESSION.stream.field.isError] === true;
+        const outcome = this.interruptRequested
+            ? TURN_OUTCOME.interrupted
+            : isError
+                ? TURN_OUTCOME.failed
+                : TURN_OUTCOME.completed;
+        this.interruptRequested = false;
+        // Approval requests belong to the turn that raised them.
+        this.pendingApprovals.clear();
+        this.state.endTurn(outcome, readString(record, CLAUDE_SESSION.stream.field.result));
+    }
+    handleControlRequest(record) {
+        const requestId = readString(record, CLAUDE_SESSION.stream.field.requestId);
+        const request = readRecord(record, CLAUDE_SESSION.stream.field.request);
+        const subtype = request === null
+            ? null
+            : readString(request, CLAUDE_SESSION.stream.field.subtype);
+        if (requestId === null || request === null) {
+            return;
+        }
+        if (subtype !== CLAUDE_SESSION.stream.subtype.canUseTool) {
+            this.ctx.logger.log("warn", `ignoring unsupported claude control request "${subtype ?? "?"}"`);
+            return;
+        }
+        this.pendingApprovals.set(requestId, request[CLAUDE_SESSION.stream.field.input]);
+        const toolName = readString(request, CLAUDE_SESSION.stream.field.toolName) ?? "";
+        const description = readString(request, CLAUDE_SESSION.stream.field.description);
+        this.state.emit({
+            type: SESSION_EVENT_TYPE.approvalRequested,
+            requestId,
+            summary: description === null ? toolName : `${toolName} ${description}`,
+            decisions: CLAUDE_APPROVAL_DECISIONS,
+        });
+    }
+    handleControlResponse(record) {
+        const response = readRecord(record, CLAUDE_SESSION.stream.field.response);
+        const requestId = response === null
+            ? null
+            : readString(response, CLAUDE_SESSION.stream.field.requestId);
+        if (response === null || requestId === null) {
+            return;
+        }
+        const pending = this.pendingControls.get(requestId);
+        if (pending === undefined) {
+            return;
+        }
+        this.pendingControls.delete(requestId);
+        pending.cancelTimeout();
+        if (readString(response, CLAUDE_SESSION.stream.field.subtype) ===
+            CLAUDE_SESSION.stream.subtype.error) {
+            pending.reject(sessionStateError(CLAUDE.id, redactSecrets(readString(response, CLAUDE_SESSION.stream.field.error) ??
+                "control request failed")));
+            return;
+        }
+        pending.resolve();
+    }
+}
+async function openClaudeSession(target, options, ctx, sessionOptions) {
+    const process = await SessionProcess.spawn({
+        command: CLAUDE.command,
+        args: sessionArgs(options.permissions, target, sessionOptions),
+        cwd: options.workspace,
+        ctx,
+        agentId: CLAUDE.id,
+    });
+    return new ClaudeSession(target.sessionId, process, ctx);
+}
+function claudeRoot(ctx, ...segments) {
+    return path.join(ctx.location.homeDir, CLAUDE_SESSION.files.root, ...segments);
+}
+/** `~/.claude/projects/<encoded cwd>/<id>.jsonl` — the project directory name is not derivable, so scan. */
+async function findClaudeTranscript(ctx, id) {
+    const root = claudeRoot(ctx, CLAUDE_SESSION.files.projects);
+    for (const project of await readDirectoryNames(root)) {
+        const candidate = path.join(root, project, `${id}${CLAUDE_SESSION.files.transcriptExtension}`);
+        if (await fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** `~/.claude/sessions/<pid>.json` — one file per live CLI process, keyed by pid. */
+async function claudeRegistryOwner(ctx, id) {
+    const root = claudeRoot(ctx, CLAUDE_SESSION.files.sessions);
+    for (const name of await readDirectoryNames(root)) {
+        if (!name.endsWith(CLAUDE_SESSION.files.registryExtension)) {
+            continue;
+        }
+        const entry = await readJsonFile(path.join(root, name));
+        if (entry === null ||
+            readString(entry, CLAUDE_SESSION.files.sessionId) !== id) {
+            continue;
+        }
+        return {
+            kind: SESSION_OWNER_KIND.process,
+            pid: readNumber(entry, CLAUDE_SESSION.files.pid),
+            entrypoint: readString(entry, CLAUDE_SESSION.files.entrypoint),
+        };
+    }
+    return { kind: SESSION_OWNER_KIND.none };
+}
+function permissionModeFrom(value) {
+    return value !== null &&
+        Object.values(CLAUDE_PERMISSION_MODE).includes(value)
+        ? value
+        : null;
+}
+async function inspectClaudeSession(id, ctx) {
+    assertHostSessionId(id, CLAUDE.id);
+    const transcript = await findClaudeTranscript(ctx, id);
+    if (transcript === null) {
+        return null;
+    }
+    const cwd = await scanJsonlFirstLast(transcript, (record) => readString(record, CLAUDE_SESSION.files.cwd));
+    if (cwd.first === null) {
+        return null;
+    }
+    const modes = await scanJsonlFirstLast(transcript, (record) => readString(record, CLAUDE_SESSION.files.permissionMode));
+    const mode = permissionModeFrom(modes.last);
+    return {
+        workspace: cwd.first,
+        lastPermissions: mode === null ? null : { mode },
+        owner: await claudeRegistryOwner(ctx, id),
+        archived: false,
+    };
+}
+export function claudeSessions(options) {
+    return {
+        open: (resolved, ctx) => openClaudeSession({ kind: "new", sessionId: randomUUID() }, resolved, ctx, options),
+        resume: async (id, resolved, ctx) => {
+            assertHostSessionId(id, CLAUDE.id);
+            return openClaudeSession({ kind: "resume", sessionId: id }, resolved, ctx, options);
+        },
+        inspect: inspectClaudeSession,
+    };
+}

package/dist/agents/claude-stream.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Claude CLI stream-json vocabulary and line readers, shared by the
+ * one-shot run adapter (`claude.ts`) and the long-lived session adapter
+ * (`claude-session.ts`): one place spells the CLI's flags and the NDJSON
+ * field names both of them read.
+ */
+import type { AgentEvent } from "../core/run.js";
+import type { CliResultCapture } from "../kernel/cli-agent.js";
+export declare const CLAUDE: {
+    readonly id: "claude";
+    readonly command: "claude";
+    readonly cli: {
+        readonly prompt: "-p";
+        readonly model: "--model";
+        readonly effort: "--effort";
+        readonly outputFormat: "--output-format";
+        readonly streamJson: "stream-json";
+        readonly permissionMode: "--permission-mode";
+        readonly bypassPermissions: "bypassPermissions";
+        readonly defaultPermissionMode: "default";
+        readonly verbose: "--verbose";
+        readonly tools: "--tools";
+        readonly allowedTools: "--allowedTools";
+        readonly safeMode: "--safe-mode";
+        readonly strictMcpConfig: "--strict-mcp-config";
+        readonly noSessionPersistence: "--no-session-persistence";
+    };
+    readonly auth: {
+        readonly statusArgs: readonly ["auth", "status", "--json"];
+        readonly loginArgs: readonly ["auth", "login", "--claudeai"];
+    };
+    readonly mcp: {
+        readonly addJson: "add-json";
+        readonly mcp: "mcp";
+        readonly remove: "remove";
+        readonly scope: "--scope";
+    };
+    readonly plugin: {
+        readonly plugin: "plugin";
+        readonly install: "install";
+    };
+    readonly json: {
+        readonly field: {
+            readonly type: "type";
+            readonly message: "message";
+            readonly content: "content";
+            readonly text: "text";
+            readonly name: "name";
+            readonly usage: "usage";
+            readonly result: "result";
+            readonly inputTokens: "input_tokens";
+            readonly outputTokens: "output_tokens";
+            readonly totalCost: "total_cost_usd";
+        };
+        readonly type: {
+            readonly assistant: "assistant";
+            readonly result: "result";
+            readonly text: "text";
+            readonly toolUse: "tool_use";
+        };
+    };
+};
+export declare function parseClaudeLine(line: string): AgentEvent[];
+export declare function parseClaudeResult(line: string): CliResultCapture | null;
+//# sourceMappingURL=claude-stream.d.ts.map

package/dist/agents/claude-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-stream.d.ts","sourceRoot":"","sources":["../../src/agents/claude-stream.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,gBAAgB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqDT,CAAC;AAEX,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAkC1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAkBvE"}