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

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,45 @@ 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) |
+
+## Changes in 0.2.0-beta.3
+
+- `run()` with `sandbox: { mode: "read-only" }` passes
+  `--permission-mode manual` to claude (was `default`), and `run()` with
+  `mode: "full"` passes `--allow-dangerously-skip-permissions` next to
+  `bypassPermissions`, as sessions already did. One function
+  (`permissionModeArgs`) now decides how a mode reaches the CLI for run and
+  session alike; `manual` is the spelling `claude --help` (2.1.270) lists —
+  `default` is not among its choices — and the allow flag is what makes
+  `bypassPermissions` an option at all.
+- `agent.auth.check` for a home-dir material answers `unknown` when the
+  probe cannot start (no binary on PATH, spawn fault) instead of throwing —
+  the same policy the availability probe already had.
+- Internal structure (no API change): the facts of a CLI child process
+  (PATH resolution, output tails, redacted failure evidence, signal
+  escalation) live once in `core/cli-child.ts`; each built-in host spells
+  its vocabulary once in `agents/<host>/cli.ts`; the kernel drives every
+  Session (`kernel/session.ts`) and the host adapters only encode and
+  decode. `SessionEvent.turnId` is the host's turn id when it has one
+  (Codex) and a per-session counter otherwise (Claude).
+
+## 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/builtin.d.ts

@@ -4,8 +4,8 @@
  * the config layer reuses `BUILTIN_AGENT_ID` for its agent-config kinds —
  * so "codex"/"claude" is spelled once, not once per layer.
  */
-import { claude } from "./claude.js";
-import { codex } from "./codex.js";
+import { claude } from "./claude/index.js";
+import { codex } from "./codex/index.js";
 export declare const BUILTIN_AGENT_ID: {
     readonly codex: "codex";
     readonly claude: "claude";

package/dist/agents/builtin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../../src/agents/builtin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,qBAAqB;;;CAA6B,CAAC"}
+{"version":3,"file":"builtin.d.ts","sourceRoot":"","sources":["../../src/agents/builtin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE3D,wEAAwE;AACxE,eAAO,MAAM,qBAAqB;;;CAA6B,CAAC"}

package/dist/agents/builtin.js

@@ -4,11 +4,13 @@
  * the config layer reuses `BUILTIN_AGENT_ID` for its agent-config kinds —
  * so "codex"/"claude" is spelled once, not once per layer.
  */
-import { claude } from "./claude.js";
-import { codex } from "./codex.js";
+import { CLAUDE } from "./claude/cli.js";
+import { claude } from "./claude/index.js";
+import { CODEX } from "./codex/cli.js";
+import { codex } from "./codex/index.js";
 export const BUILTIN_AGENT_ID = {
-    codex: "codex",
-    claude: "claude",
+    codex: CODEX.id,
+    claude: CLAUDE.id,
 };
 /** Keyed record, not a branch: adding a built-in is adding an entry. */
 export const builtinAgentFactories = { claude, codex };

package/dist/agents/claude/cli.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The Claude CLI vocabulary, spelled once: command and flags, the
+ * permission-mode words and how the flag spells them, the stream-json
+ * record types and fields, and the host's own file names. The run adapter
+ * (`index.ts`), the session adapter (`session.ts`), and the host plane
+ * (`host.ts`) all read from here and never respell a word.
+ */
+import { type UnknownRecord } from "../../core/json.js";
+import type { AgentEvent } from "../../core/run.js";
+import type { CliResultCapture } from "../../kernel/cli-agent.js";
+export declare const CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR";
+export declare const CLAUDE_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+/** Spelled as the transcript's `permissionMode` records it. */
+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];
+export type ClaudeSessionPermissions = {
+    readonly mode: ClaudePermissionMode;
+};
+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 inputFormat: "--input-format";
+        readonly streamJson: "stream-json";
+        readonly permissionMode: "--permission-mode";
+        /** The flag spells the transcript's `default` mode `manual` (claude 2.1.270 `--help`). */
+        readonly manualPermissionMode: "manual";
+        readonly allowDangerouslySkipPermissions: "--allow-dangerously-skip-permissions";
+        readonly permissionPromptTool: "--permission-prompt-tool";
+        readonly stdio: "stdio";
+        readonly resume: "--resume";
+        readonly sessionId: "--session-id";
+        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 role: "role";
+            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 request: "request";
+            readonly requestId: "request_id";
+            readonly response: "response";
+            readonly subtype: "subtype";
+            readonly error: "error";
+            readonly toolName: "tool_name";
+            readonly description: "description";
+            readonly input: "input";
+            readonly isError: "is_error";
+            readonly behavior: "behavior";
+            readonly updatedInput: "updatedInput";
+        };
+        readonly type: {
+            readonly user: "user";
+            readonly assistant: "assistant";
+            readonly result: "result";
+            readonly text: "text";
+            readonly toolUse: "tool_use";
+            readonly controlRequest: "control_request";
+            readonly controlResponse: "control_response";
+        };
+        readonly subtype: {
+            readonly interrupt: "interrupt";
+            readonly canUseTool: "can_use_tool";
+            readonly success: "success";
+            readonly error: "error";
+        };
+        readonly behavior: {
+            readonly allow: "allow";
+            readonly deny: "deny";
+        };
+    };
+    readonly files: {
+        readonly root: ".claude";
+        readonly projects: "projects";
+        readonly sessions: "sessions";
+        readonly transcriptExtension: ".jsonl";
+        readonly registryExtension: ".json";
+        readonly cwd: "cwd";
+        readonly permissionMode: "permissionMode";
+        readonly sessionId: "sessionId";
+        readonly pid: "pid";
+        readonly entrypoint: "entrypoint";
+    };
+};
+/**
+ * The one rule for how a permission mode reaches the CLI: the flag spells
+ * `default` as `manual`, and `bypassPermissions` is only an option once
+ * `--allow-dangerously-skip-permissions` enables it (`claude --help`).
+ */
+export declare function permissionModeArgs(mode: ClaudePermissionMode): string[];
+export declare function parseClaudeLine(line: string): AgentEvent[];
+/** Events carried by one already-parsed stream-json record (`assistant` only). */
+export declare function parseClaudeRecord(record: UnknownRecord): AgentEvent[];
+export declare function parseClaudeResult(line: string): CliResultCapture | null;
+//# sourceMappingURL=cli.d.ts.map

package/dist/agents/claude/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../../src/agents/claude/cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAY,MAAM,mBAAmB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAElE,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAC7D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB;;;;;;;CAOzB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAC9B,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,OAAO,sBAAsB,CAAC,CAAC;AAEvE,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC,CAAC;AAEF,eAAO,MAAM,MAAM;;;;;;;;;;;QAWf,0FAA0F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkFpF,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAUvE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAG1D;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,UAAU,EAAE,CAgCrE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAkBvE"}

package/dist/agents/claude/cli.js

@@ -0,0 +1,182 @@
+/**
+ * The Claude CLI vocabulary, spelled once: command and flags, the
+ * permission-mode words and how the flag spells them, the stream-json
+ * record types and fields, and the host's own file names. The run adapter
+ * (`index.ts`), the session adapter (`session.ts`), and the host plane
+ * (`host.ts`) all read from here and never respell a word.
+ */
+import { readJsonRecord, readNumber, readRecord, readString, readUnknownRecord, } from "../../core/json.js";
+import { AGENT_EVENT_TYPE } from "../../core/run.js";
+export const CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR";
+export const CLAUDE_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
+/** Spelled as the transcript's `permissionMode` records it. */
+export const CLAUDE_PERMISSION_MODE = {
+    default: "default",
+    acceptEdits: "acceptEdits",
+    auto: "auto",
+    bypassPermissions: "bypassPermissions",
+    dontAsk: "dontAsk",
+    plan: "plan",
+};
+export const CLAUDE = {
+    id: "claude",
+    command: "claude",
+    cli: {
+        prompt: "-p",
+        model: "--model",
+        effort: "--effort",
+        outputFormat: "--output-format",
+        inputFormat: "--input-format",
+        streamJson: "stream-json",
+        permissionMode: "--permission-mode",
+        /** The flag spells the transcript's `default` mode `manual` (claude 2.1.270 `--help`). */
+        manualPermissionMode: "manual",
+        allowDangerouslySkipPermissions: "--allow-dangerously-skip-permissions",
+        permissionPromptTool: "--permission-prompt-tool",
+        stdio: "stdio",
+        resume: "--resume",
+        sessionId: "--session-id",
+        verbose: "--verbose",
+        tools: "--tools",
+        allowedTools: "--allowedTools",
+        safeMode: "--safe-mode",
+        strictMcpConfig: "--strict-mcp-config",
+        noSessionPersistence: "--no-session-persistence",
+    },
+    auth: {
+        statusArgs: ["auth", "status", "--json"],
+        loginArgs: ["auth", "login", "--claudeai"],
+    },
+    mcp: {
+        addJson: "add-json",
+        mcp: "mcp",
+        remove: "remove",
+        scope: "--scope",
+    },
+    plugin: {
+        plugin: "plugin",
+        install: "install",
+    },
+    json: {
+        field: {
+            type: "type",
+            message: "message",
+            role: "role",
+            content: "content",
+            text: "text",
+            name: "name",
+            usage: "usage",
+            result: "result",
+            inputTokens: "input_tokens",
+            outputTokens: "output_tokens",
+            totalCost: "total_cost_usd",
+            request: "request",
+            requestId: "request_id",
+            response: "response",
+            subtype: "subtype",
+            error: "error",
+            toolName: "tool_name",
+            description: "description",
+            input: "input",
+            isError: "is_error",
+            behavior: "behavior",
+            updatedInput: "updatedInput",
+        },
+        type: {
+            user: "user",
+            assistant: "assistant",
+            result: "result",
+            text: "text",
+            toolUse: "tool_use",
+            controlRequest: "control_request",
+            controlResponse: "control_response",
+        },
+        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",
+    },
+};
+/**
+ * The one rule for how a permission mode reaches the CLI: the flag spells
+ * `default` as `manual`, and `bypassPermissions` is only an option once
+ * `--allow-dangerously-skip-permissions` enables it (`claude --help`).
+ */
+export function permissionModeArgs(mode) {
+    return [
+        CLAUDE.cli.permissionMode,
+        mode === CLAUDE_PERMISSION_MODE.default
+            ? CLAUDE.cli.manualPermissionMode
+            : mode,
+        ...(mode === CLAUDE_PERMISSION_MODE.bypassPermissions
+            ? [CLAUDE.cli.allowDangerouslySkipPermissions]
+            : []),
+    ];
+}
+export function parseClaudeLine(line) {
+    const record = readJsonRecord(line);
+    return record === null ? [] : parseClaudeRecord(record);
+}
+/** Events carried by one already-parsed stream-json record (`assistant` only). */
+export function parseClaudeRecord(record) {
+    if (readString(record, CLAUDE.json.field.type) !== CLAUDE.json.type.assistant) {
+        return [];
+    }
+    const message = readRecord(record, CLAUDE.json.field.message);
+    const content = message?.[CLAUDE.json.field.content];
+    if (!Array.isArray(content)) {
+        return [{ type: AGENT_EVENT_TYPE.turn }];
+    }
+    const events = [{ type: AGENT_EVENT_TYPE.turn }];
+    for (const block of content) {
+        const blockRecord = readUnknownRecord(block);
+        if (blockRecord === null) {
+            continue;
+        }
+        const blockType = readString(blockRecord, CLAUDE.json.field.type);
+        if (blockType === CLAUDE.json.type.text) {
+            const text = readString(blockRecord, CLAUDE.json.field.text);
+            if (text !== null) {
+                events.push({ type: AGENT_EVENT_TYPE.message, text });
+            }
+        }
+        if (blockType === CLAUDE.json.type.toolUse) {
+            const name = readString(blockRecord, CLAUDE.json.field.name);
+            if (name !== null) {
+                events.push({ type: AGENT_EVENT_TYPE.tool, name });
+            }
+        }
+    }
+    return events;
+}
+export function parseClaudeResult(line) {
+    const record = readJsonRecord(line);
+    if (record === null ||
+        readString(record, CLAUDE.json.field.type) !== CLAUDE.json.type.result) {
+        return null;
+    }
+    const usageRecord = readRecord(record, CLAUDE.json.field.usage);
+    const usage = usageRecord === null
+        ? null
+        : {
+            inputTokens: readNumber(usageRecord, CLAUDE.json.field.inputTokens),
+            outputTokens: readNumber(usageRecord, CLAUDE.json.field.outputTokens),
+            costUsd: readNumber(record, CLAUDE.json.field.totalCost),
+        };
+    return { text: readString(record, CLAUDE.json.field.result), usage };
+}

package/dist/agents/claude/host.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The claude host plane: auth materials and sign-in, installed skills
+ * (`~/.claude/skills`, project `.claude/skills`, plugins), and MCP
+ * registration through the CLI. Outside a run and a session; every path
+ * comes from `HostContext.location`, never `os.homedir()`.
+ */
+import { type LoginCapability } from "../../auth/login.js";
+import type { MaterialHandlers } from "../../auth/material.js";
+import { type McpCapability, type SkillsCapability } from "../../host/capabilities.js";
+export declare const claudeAuth: MaterialHandlers;
+export declare const claudeLogin: LoginCapability;
+export declare const claudeSkills: SkillsCapability;
+export declare const claudeMcp: McpCapability;
+//# sourceMappingURL=host.d.ts.map

package/dist/agents/claude/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../../src/agents/claude/host.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAmB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAOhF,OAAO,EAML,KAAK,aAAa,EAKlB,KAAK,gBAAgB,EAEtB,MAAM,4BAA4B,CAAC;AA2WpC,eAAO,MAAM,UAAU,EAAE,gBAQxB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,eAIzB,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,gBAO1B,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,aAMvB,CAAC"}