@wix/pathgrade 0.29.0

package/dist/agents/claude/sdk-message-projector.js

@@ -0,0 +1,208 @@
+/**
+ * SDK message projector — typed `SDKMessage[]` → `AgentTurnResult`.
+ *
+ * Replaces the legacy NDJSON parser (`extractClaudeStreamJsonEvents`). Pure
+ * function: no I/O, no ask-bus, no session state. The Claude SDK driver
+ * buffers each turn's `SDKMessage` stream (`for await`) and hands the array
+ * here; the projector returns the public `AgentTurnResult` plus the
+ * `session_id` the orchestrator threads into the next turn's
+ * `Options.resume`.
+ *
+ * Boundary with the live ask-user bridge: for an `AskUserQuestion`
+ * tool-use block the projector emits a `ToolEvent` whose `arguments` shape
+ * is the structured `AskUserQuestionInput` (questions / headers / options /
+ * multiSelect) plus `answerSource: 'unknown'`. The bridge attaches the
+ * answer values and the `'reaction' | 'fallback' | 'declined'` source tag
+ * onto the same envelope; the projector itself never mints them.
+ */
+const SDK_ERROR_SUBTYPES = [
+    'error_during_execution',
+    'error_max_turns',
+    'error_max_budget_usd',
+    'error_max_structured_output_retries',
+];
+import { TOOL_NAME_MAP, buildSummary, enrichSkillEvents } from '../../tool-events.js';
+export function projectSdkMessages(input) {
+    let sessionId;
+    let initSkills;
+    let assistantText = '';
+    let resultText = '';
+    let exitCode = 0;
+    let isError = false;
+    let inputTokens;
+    let outputTokens;
+    let cacheCreationInputTokens;
+    let cacheReadInputTokens;
+    let costUsd;
+    let errorSubtype;
+    const toolEvents = [];
+    for (const msg of input.messages) {
+        switch (msg.type) {
+            case 'system': {
+                const sid = msg.session_id;
+                if (sid)
+                    sessionId = sid;
+                const sub = msg.subtype;
+                if (sub === 'init') {
+                    const skills = msg.skills;
+                    if (Array.isArray(skills))
+                        initSkills = skills.filter((s) => typeof s === 'string');
+                }
+                break;
+            }
+            case 'assistant': {
+                const content = msg
+                    .message?.content ?? [];
+                for (const block of content) {
+                    if (block.type === 'text' && typeof block.text === 'string') {
+                        assistantText += block.text;
+                        continue;
+                    }
+                    if (block.type === 'tool_use') {
+                        toolEvents.push(buildToolEvent(block, input.turnNumber, input.answerStore));
+                    }
+                }
+                break;
+            }
+            case 'result': {
+                const r = msg;
+                if (r.session_id)
+                    sessionId = r.session_id;
+                if (typeof r.result === 'string')
+                    resultText = r.result;
+                if (r.usage) {
+                    inputTokens =
+                        (r.usage.input_tokens ?? 0)
+                            + (r.usage.cache_creation_input_tokens ?? 0)
+                            + (r.usage.cache_read_input_tokens ?? 0);
+                    outputTokens = r.usage.output_tokens;
+                    // Additive cache-token breakdown. `inputTokens` above
+                    // keeps the existing pathgrade convention of including
+                    // cache volume — these fields just expose the SDK's own
+                    // breakdown for consumers that want to reason about cache
+                    // hits/creation separately.
+                    cacheCreationInputTokens = r.usage.cache_creation_input_tokens;
+                    cacheReadInputTokens = r.usage.cache_read_input_tokens;
+                }
+                // Surface SDK-reported turn cost on success and error result
+                // subtypes alike. The driver accumulates these into the
+                // conversation cost downstream.
+                if (typeof r.total_cost_usd === 'number') {
+                    costUsd = r.total_cost_usd;
+                }
+                if (r.is_error || (r.subtype && r.subtype !== 'success')) {
+                    isError = true;
+                    exitCode = 1;
+                    // Surface the SDK's typed error subtype so consumers can
+                    // triage without regex on text.
+                    if (r.subtype && SDK_ERROR_SUBTYPES.includes(r.subtype)) {
+                        errorSubtype = r.subtype;
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    const trimmedAssistant = assistantText.trim();
+    const trimmedResult = resultText.trim();
+    const visible = isError ? '' : (trimmedAssistant || trimmedResult);
+    const rawOutput = resultText || assistantText;
+    const enriched = enrichSkillEvents(toolEvents);
+    const finalToolEvents = prependSlashCommandSkillEvent(enriched, input.firstMessage, initSkills);
+    const traceOutput = input.messages.map((m) => JSON.stringify(m)).join('\n');
+    const result = {
+        rawOutput,
+        assistantMessage: visible,
+        visibleAssistantMessage: visible,
+        visibleAssistantMessageSource: 'assistant_message',
+        exitCode,
+        traceOutput,
+        toolEvents: finalToolEvents,
+        runtimePoliciesApplied: [],
+        inputTokens,
+        outputTokens,
+        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+        ...(errorSubtype !== undefined ? { errorSubtype } : {}),
+    };
+    return { result, sessionId };
+}
+/**
+ * If the first user message of the turn is `/<name>` and `<name>` is one of
+ * the skills the SDK reported in its `init.skills` array, prepend a synthetic
+ * `use_skill` tool event so scorers that key on `use_skill` see the implicit
+ * skill activation. The Claude SDK does not emit a tool_use for slash-command
+ * skill invocations the way an explicit `Skill` tool call does — this is the
+ * NDJSON-era behavior the legacy parser also synthesized, preserved here.
+ */
+function prependSlashCommandSkillEvent(events, firstMessage, initSkills) {
+    if (!firstMessage || !initSkills)
+        return events;
+    const match = firstMessage.match(/^\/([^\s]+)/);
+    if (!match)
+        return events;
+    const skillName = match[1];
+    if (!initSkills.includes(skillName))
+        return events;
+    return [
+        {
+            action: 'use_skill',
+            provider: 'claude',
+            providerToolName: 'Skill',
+            arguments: { skill: skillName },
+            skillName,
+            summary: `use_skill "${skillName}"`,
+            confidence: 'high',
+            rawSnippet: '(detected from slash command in prompt)',
+        },
+        ...events,
+    ];
+}
+function buildToolEvent(block, turnNumber, answerStore) {
+    const providerToolName = String(block.name || 'unknown');
+    const rawInput = block.input ?? undefined;
+    const toolUseId = typeof block.id === 'string' ? block.id : undefined;
+    const action = TOOL_NAME_MAP[providerToolName] ?? 'unknown';
+    const args = action === 'ask_user'
+        ? buildAskUserArguments(rawInput, answerStore?.get(toolUseId))
+        : rawInput;
+    const summary = buildSummary(action, providerToolName, args);
+    const rawSnippet = JSON.stringify(block).slice(0, 200);
+    return {
+        action,
+        provider: 'claude',
+        providerToolName,
+        turnNumber,
+        arguments: args,
+        summary,
+        confidence: 'high',
+        rawSnippet,
+    };
+}
+/**
+ * Boundary with the ask-user bridge.
+ *
+ * The projector emits the structured `AskUserQuestionInput` (questions /
+ * headers / options / multiSelect) plus `answerSource: 'unknown'`. The
+ * ask-user-bridge attaches the answer values and the
+ * `'reaction' | 'fallback' | 'declined'` source tag onto this same envelope.
+ *
+ * The projector itself never mints answer values, never mints a non-`unknown`
+ * source, and never reaches into the bus — it just stamps the boundary so a
+ * turn that produces an AskUserQuestion event without a bridge entry still
+ * has a snapshot-stable shape for scorers and reporters.
+ */
+function buildAskUserArguments(input, bridgeEntry) {
+    const base = input ? { ...input } : {};
+    if (bridgeEntry) {
+        return {
+            ...base,
+            answers: { ...bridgeEntry.answers },
+            answerSource: bridgeEntry.source,
+        };
+    }
+    return { ...base, answerSource: 'unknown' };
+}

package/dist/agents/claude/sdk-options.d.ts

@@ -0,0 +1,52 @@
+import type { CanUseTool, Options, SpawnedProcess, SpawnOptions as SdkSpawnOptions } from '@anthropic-ai/claude-agent-sdk';
+import type { McpServersObject } from '../../providers/mcp-config.js';
+export interface ClaudeSdkOptionsInputs {
+    /** Per-trial workspace; cwd for the SDK so project-staged skills resolve. */
+    workspacePath: string;
+    /** Custom spawn hook from the sandboxed-claude-spawn module. */
+    spawnClaudeCodeProcess: (opts: SdkSpawnOptions) => SpawnedProcess;
+    /** Custom tool-permission callback — the live ask-user bridge. */
+    canUseTool: CanUseTool;
+    /**
+     * The curated workspace runtime env, spread wholesale onto `Options.env`.
+     * Carries (1) ANTHROPIC_* credentials resolved by `resolveCredentials()`,
+     * (2) sandbox HOME/TMPDIR set by `prepareWorkspace`, and (3) any
+     * `createAgent({ env })` keys the user supplied. The driver does not
+     * gatekeep which keys reach the SDK subprocess — `prepareWorkspace`
+     * curates the workspace env upstream and the sandboxed-spawn module's
+     * `SAFE_HOST_VARS` filter defends host-env leakage from a different
+     * direction. This is the single env composition point the driver owns.
+     */
+    runtimeEnv: Record<string, string>;
+    /** Forwarded to the SDK only when set. */
+    model?: string;
+    /**
+     * Override for the bundled `claude` binary. Precedence (resolved by the
+     * caller): `AgentOptions.claudeCodeExecutable` > `PATHGRADE_CLAUDE_CODE_EXECUTABLE`
+     * > undefined (use SDK's bundled per-platform binary).
+     */
+    claudeCodeExecutable?: string;
+    /**
+     * Resume session id. Omitted on turn 1; set to the prior turn's
+     * `session_id` on every turn after.
+     */
+    resume?: string;
+    /** MCP servers in the SDK's object form, from `loadMcpServersForSdk`. */
+    mcpServers?: McpServersObject;
+}
+/**
+ * Pick the Claude executable. Precedence:
+ *
+ *   1. `AgentOptions.claudeCodeExecutable` — explicit run-level override.
+ *   2. `PATHGRADE_CLAUDE_CODE_EXECUTABLE` — process env override.
+ *   3. `undefined` — fall back to the SDK's bundled per-platform binary.
+ *
+ * `undefined` is intentional, not "missing": it tells `buildClaudeSdkOptions`
+ * to omit `Options.pathToClaudeCodeExecutable` so the SDK uses its bundled
+ * default.
+ */
+export declare function resolveClaudeCodeExecutable(args: {
+    agentOptionsExecutable?: string;
+    envExecutable?: string;
+}): string | undefined;
+export declare function buildClaudeSdkOptions(inputs: ClaudeSdkOptionsInputs): Options;

package/dist/agents/claude/sdk-options.js

@@ -0,0 +1,79 @@
+/**
+ * Pure builder that turns pathgrade's per-turn session inputs into the Claude
+ * Agent SDK's `Options` object passed to `query()`. The driver class is just
+ * orchestration over this builder, the sandboxed-spawn module, the live
+ * ask-user bridge, and the SDK message projector.
+ */
+import * as path from 'path';
+/**
+ * Per-workspace Claude config/home dir. Set via `Options.env.CLAUDE_CONFIG_DIR`
+ * so the bundled subprocess does not read host `~/.claude.json`, user memory,
+ * or ambient state.
+ */
+const CLAUDE_CONFIG_SUBDIR = '.pathgrade-claude-config';
+/**
+ * Pick the Claude executable. Precedence:
+ *
+ *   1. `AgentOptions.claudeCodeExecutable` — explicit run-level override.
+ *   2. `PATHGRADE_CLAUDE_CODE_EXECUTABLE` — process env override.
+ *   3. `undefined` — fall back to the SDK's bundled per-platform binary.
+ *
+ * `undefined` is intentional, not "missing": it tells `buildClaudeSdkOptions`
+ * to omit `Options.pathToClaudeCodeExecutable` so the SDK uses its bundled
+ * default.
+ */
+export function resolveClaudeCodeExecutable(args) {
+    if (args.agentOptionsExecutable)
+        return args.agentOptionsExecutable;
+    if (args.envExecutable)
+        return args.envExecutable;
+    return undefined;
+}
+export function buildClaudeSdkOptions(inputs) {
+    const opts = {
+        cwd: inputs.workspacePath,
+        systemPrompt: { type: 'preset', preset: 'claude_code' },
+        settingSources: ['project'],
+        // Disable auto-memory at the source. SDK 0.2.117 exposes the toggle
+        // through `Options.settings.autoMemoryEnabled` (the field lives on
+        // `Settings`, reachable here via the typed `Options.settings?: string
+        // | Settings` indirection), so the SDK never runs auto-memory recall,
+        // indexing, or writes during a trial. `CLAUDE_CONFIG_DIR` and
+        // `settingSources: ['project']` add defense-in-depth: the former
+        // redirects any per-trial state to a workspace-scoped scratch dir if
+        // the flag is ever ignored upstream, and the latter excludes the
+        // user-scope `~/.claude/settings.json` so a host-level
+        // `autoMemoryEnabled: true` cannot re-enable it.
+        settings: { autoMemoryEnabled: false },
+        permissionMode: 'default',
+        spawnClaudeCodeProcess: inputs.spawnClaudeCodeProcess,
+        canUseTool: inputs.canUseTool,
+    };
+    if (inputs.model !== undefined)
+        opts.model = inputs.model;
+    if (inputs.claudeCodeExecutable !== undefined) {
+        opts.pathToClaudeCodeExecutable = inputs.claudeCodeExecutable;
+    }
+    if (inputs.resume !== undefined)
+        opts.resume = inputs.resume;
+    if (inputs.mcpServers !== undefined)
+        opts.mcpServers = inputs.mcpServers;
+    // Env composition ownership: the driver does NOT pluck specific keys.
+    // `prepareWorkspace` curates the runtime env (safe host vars, sandbox
+    // HOME/TMPDIR, resolveCredentials() output, user-supplied
+    // `createAgent({ env })`); the sandboxed-spawn module's SAFE_HOST_VARS
+    // filter guards host-env leakage from a different direction. The
+    // driver's job is to spread that curated env wholesale onto Options.env,
+    // then layer driver-owned hermetic overrides on top — `CLAUDE_CONFIG_DIR`
+    // wins on collision so an upstream leak (or a user-supplied env value)
+    // cannot weaken the per-trial isolation invariant.
+    const env = {};
+    for (const [key, value] of Object.entries(inputs.runtimeEnv)) {
+        if (value === undefined)
+            continue;
+        env[key] = value;
+    }
+    env.CLAUDE_CONFIG_DIR = path.join(inputs.workspacePath, CLAUDE_CONFIG_SUBDIR);
+    opts.env = env;
+    return opts;
+}

package/dist/agents/claude.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Claude agent driver — Claude Agent SDK edition.
+ *
+ * Replaces the previous CLI-scraping driver with one built on
+ * `@anthropic-ai/claude-agent-sdk`. The driver class is just orchestration
+ * over five deep modules:
+ *
+ *   - `sandboxedClaudeSpawn`      — `Options.spawnClaudeCodeProcess` adapter
+ *                                   that filters env and (optionally) wraps
+ *                                   argv with macOS sandbox-exec.
+ *   - `loadMcpServersForSdk`      — reads pathgrade's MCP config JSON into
+ *                                   the SDK's `Options.mcpServers` shape.
+ *   - `buildClaudeSdkOptions`     — pure builder for the per-turn `Options`.
+ *   - `createAskUserBridge`       — live `canUseTool` that auto-allows
+ *                                   non-`AskUserQuestion` tools and resolves
+ *                                   `AskUserQuestion` through the ask-bus,
+ *                                   returning the SDK's documented `answers`
+ *                                   map shape on `updatedInput`. Per-turn
+ *                                   answer store feeds the projector.
+ *   - `projectSdkMessages`        — pure typed-message → `AgentTurnResult`
+ *                                   projector. Replaces the legacy NDJSON
+ *                                   parser wholesale.
+ */
+import { type Options as SdkOptions, type Query } from '@anthropic-ai/claude-agent-sdk';
+import { AgentCommandRunner, AgentSession, AgentSessionOptions, BaseAgent, EnvironmentHandle } from '../types.js';
+/** Shape of the SDK `query()` callable, narrowed for orchestration use. */
+export type ClaudeSdkQueryFn = (args: {
+    prompt: string | unknown;
+    options?: SdkOptions;
+}) => Query;
+export interface ClaudeAgentDeps {
+    /** Override the SDK `query()` for tests. Defaults to the real SDK. */
+    query?: ClaudeSdkQueryFn;
+    /** Override the host platform check for tests. Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
+    /** Override the host env for the spawn module's filter. Defaults to `process.env`. */
+    hostEnv?: NodeJS.ProcessEnv;
+    /** Override `process.env.PATHGRADE_CLAUDE_CODE_EXECUTABLE` for tests. */
+    envExecutable?: string;
+    /** Optional macOS sandbox-exec profile. None today; preserves the seam. */
+    sandboxProfile?: string;
+}
+export interface ClaudeAgentOptions {
+    /**
+     * Path to a Claude binary that overrides the SDK's bundled per-platform
+     * default. Run-level (set on the agent constructor); per-fixture override
+     * is intentionally out of scope.
+     */
+    claudeCodeExecutable?: string;
+}
+export declare class ClaudeAgent extends BaseAgent {
+    private readonly deps;
+    private readonly opts;
+    constructor(deps?: ClaudeAgentDeps, opts?: ClaudeAgentOptions);
+    createSession(runtime: EnvironmentHandle, _runCommand: AgentCommandRunner, sessionOptions?: AgentSessionOptions): Promise<AgentSession>;
+}

package/dist/agents/claude.js

@@ -0,0 +1,143 @@
+/**
+ * Claude agent driver — Claude Agent SDK edition.
+ *
+ * Replaces the previous CLI-scraping driver with one built on
+ * `@anthropic-ai/claude-agent-sdk`. The driver class is just orchestration
+ * over five deep modules:
+ *
+ *   - `sandboxedClaudeSpawn`      — `Options.spawnClaudeCodeProcess` adapter
+ *                                   that filters env and (optionally) wraps
+ *                                   argv with macOS sandbox-exec.
+ *   - `loadMcpServersForSdk`      — reads pathgrade's MCP config JSON into
+ *                                   the SDK's `Options.mcpServers` shape.
+ *   - `buildClaudeSdkOptions`     — pure builder for the per-turn `Options`.
+ *   - `createAskUserBridge`       — live `canUseTool` that auto-allows
+ *                                   non-`AskUserQuestion` tools and resolves
+ *                                   `AskUserQuestion` through the ask-bus,
+ *                                   returning the SDK's documented `answers`
+ *                                   map shape on `updatedInput`. Per-turn
+ *                                   answer store feeds the projector.
+ *   - `projectSdkMessages`        — pure typed-message → `AgentTurnResult`
+ *                                   projector. Replaces the legacy NDJSON
+ *                                   parser wholesale.
+ */
+import { query as sdkQuery, } from '@anthropic-ai/claude-agent-sdk';
+import { BaseAgent, getRuntimeEnv, getWorkspacePath, } from '../types.js';
+import { createSandboxedClaudeSpawn } from '../providers/sandboxed-claude-spawn.js';
+import { loadMcpServersForSdk } from '../providers/mcp-config.js';
+import { buildClaudeSdkOptions, resolveClaudeCodeExecutable, } from './claude/sdk-options.js';
+import { projectSdkMessages } from './claude/sdk-message-projector.js';
+import { createAskUserBridge } from './claude/ask-user-bridge.js';
+import { createAskUserAnswerStore } from './claude/ask-user-answer-store.js';
+import { requireAskBusForLiveBatches } from '../sdk/ask-bus/bus.js';
+export class ClaudeAgent extends BaseAgent {
+    deps;
+    opts;
+    constructor(deps = {}, opts = {}) {
+        super();
+        this.deps = deps;
+        this.opts = opts;
+    }
+    async createSession(runtime, _runCommand, sessionOptions) {
+        // Live ask-user batches require a real subscriber. Fail fast at session
+        // construction rather than silently sending an empty answer back to
+        // Claude on the wire when the bus is missing.
+        const askBus = requireAskBusForLiveBatches(sessionOptions, 'ClaudeSdkAgent');
+        const workspacePath = getWorkspacePath(runtime);
+        const queryFn = this.deps.query ?? sdkQuery;
+        const platform = this.deps.platform ?? process.platform;
+        const hostEnv = this.deps.hostEnv ?? process.env;
+        const envExecutable = this.deps.envExecutable ?? process.env.PATHGRADE_CLAUDE_CODE_EXECUTABLE;
+        const sandboxedSpawn = createSandboxedClaudeSpawn({
+            platform,
+            hostEnv,
+            sandboxProfile: this.deps.sandboxProfile,
+        });
+        const claudeCodeExecutable = resolveClaudeCodeExecutable({
+            agentOptionsExecutable: this.opts.claudeCodeExecutable,
+            envExecutable,
+        });
+        const mcpServers = await loadMcpServersForSdk(workspacePath);
+        let priorSessionId;
+        let turnNumber = 0;
+        // The live ask-user bridge resolves AskUserQuestion through the bus
+        // and writes the resulting answers + source into the per-turn answer
+        // store; the projector merges those onto the AskUserQuestion
+        // ToolEvent envelope. The store is rebuilt per turn so a question on
+        // turn 2 cannot read a stale answer from turn 1 even on toolUseID
+        // collisions.
+        let answerStore = createAskUserAnswerStore();
+        const bridge = createAskUserBridge({
+            askBus,
+            getTurnNumber: () => turnNumber,
+            answerStore: { record: (id, e) => answerStore.record(id, e), get: (id) => answerStore.get(id) },
+        });
+        const runTurn = async (message) => {
+            turnNumber += 1;
+            answerStore = createAskUserAnswerStore();
+            // Clear any ask-bus rejection captured on a prior turn so a
+            // stale error never causes a spurious result on this turn.
+            bridge.clearLastError();
+            const sdkOptions = buildClaudeSdkOptions({
+                workspacePath,
+                spawnClaudeCodeProcess: sandboxedSpawn,
+                canUseTool: bridge,
+                runtimeEnv: getRuntimeEnv(runtime),
+                model: sessionOptions?.model,
+                claudeCodeExecutable,
+                resume: priorSessionId,
+                mcpServers,
+            });
+            const messages = [];
+            const stream = queryFn({ prompt: message, options: sdkOptions });
+            for await (const msg of stream) {
+                messages.push(msg);
+            }
+            // The legacy NDJSON parser only synthesized the slash-command
+            // `use_skill` event from the *opening* user message. The Claude
+            // SDK emits a fresh `init` system message (carrying `skills`) on
+            // every `query()` call — each turn spawns a fresh subprocess —
+            // so passing the current turn's message into the projector on
+            // turn 2+ would re-fire synthesis for the same skill activation.
+            // Gate by turn number to preserve the legacy semantic: synthesize
+            // on turn 1 only, never thereafter.
+            const projectorFirstMessage = turnNumber === 1 ? message : undefined;
+            const projected = projectSdkMessages({
+                messages,
+                turnNumber,
+                firstMessage: projectorFirstMessage,
+                answerStore,
+            });
+            // Capture the SDK-reported session id BEFORE checking for a bus
+            // rejection so the next turn's `Options.resume` points at this
+            // turn's session even when the turn ended in an ask-bus error.
+            if (projected.sessionId)
+                priorSessionId = projected.sessionId;
+            // An ask-bus rejection (timeout, missing subscriber, handler
+            // throw) produced an SDK deny mid-turn AND captured the underlying
+            // error on the bridge. Returning an error `AgentTurnResult` rather
+            // than throwing lets the conversation runner project the partial
+            // turn through `pushModelAgentMessage` (`ask_batch`,
+            // `model_agent_result`, turn timings/details) before propagating
+            // the failure — preserving observability into what the agent
+            // attempted before being killed.
+            const bridgeError = bridge.lastError();
+            if (bridgeError) {
+                const errorMessage = bridgeError instanceof Error
+                    ? bridgeError.message
+                    : String(bridgeError);
+                return {
+                    ...projected.result,
+                    exitCode: 1,
+                    errorSubtype: 'bus_rejection',
+                    rawOutput: errorMessage,
+                };
+            }
+            return projected.result;
+        };
+        return {
+            start: ({ message }) => runTurn(message),
+            reply: ({ message }) => runTurn(message),
+        };
+    }
+}

package/dist/agents/codex-app-server/agent.d.ts

@@ -0,0 +1,35 @@
+import { AgentCommandRunner, AgentSession, AgentSessionOptions, BaseAgent, EnvironmentHandle } from '../../types.js';
+import { type AppServerSessionHandle } from './transport.js';
+type SandboxMode = 'workspace-write' | 'danger-full-access';
+export interface PermissionGrantLogEntry {
+    type: 'permissions_granted';
+    turnNumber: number;
+    requested: unknown;
+    scope: 'turn';
+    strictAutoReview: false;
+}
+export interface CodexAppServerAgentDeps {
+    /**
+     * Inject a transport factory for tests. Default: spawn `codex app-server`
+     * via child_process with NDJSON stdio wrapped in an AppServerSessionHandle.
+     *
+     * Tests using PassThrough streams can construct a handle via
+     * {@link createAppServerSessionHandle} with `child: null` — dispose() then
+     * only closes the transport and does not attempt any kill sequence.
+     */
+    createTransport?: (ctx: {
+        workspacePath: string;
+        env: NodeJS.ProcessEnv;
+    }) => Promise<AppServerSessionHandle>;
+    /** Sandbox mode for `thread/start`. Default: 'workspace-write'. */
+    sandboxMode?: SandboxMode;
+    /** Observer for per-grant audit entries (§7 of design decisions). */
+    onPermissionGrant?: (entry: PermissionGrantLogEntry) => void;
+}
+export declare class CodexAppServerAgent extends BaseAgent {
+    private deps;
+    constructor(deps?: CodexAppServerAgentDeps);
+    createSession(runtime: EnvironmentHandle, _runCommand: AgentCommandRunner, options?: AgentSessionOptions): Promise<AgentSession>;
+    private dispatchServerRequest;
+}
+export {};