@excitedjs/agent-runtime-claude-code 0.2.0-alpha.g0ddd418597ca

package/dist/rpc.js

@@ -0,0 +1,212 @@
+/**
+ * Claude Code stream-json turn RPC.
+ *
+ * The supervisor owns the child process. This class owns one in-flight turn,
+ * stdout line demux, turn aggregation, and defensive control-request replies.
+ */
+import { randomUUID } from 'node:crypto';
+import { buildCanUseToolAllow, buildControlAck, buildRemoteControlEnable, buildUserMessage, LineBuffer, parseLine, TurnAggregator, } from './stream.js';
+export class ClaudeCodeStreamRpc {
+    stdin;
+    options;
+    lineBuf = new LineBuffer();
+    pending = null;
+    remoteControlRequestId = null;
+    constructor(stdin, options) {
+        this.stdin = stdin;
+        this.options = options;
+    }
+    async submitTurn(prompt, options = {}) {
+        if (!this.stdin.writable) {
+            return Promise.reject(new Error('claude resident child is not running'));
+        }
+        if (this.pending !== null) {
+            return Promise.reject(new Error('claude resident session is already mid-turn'));
+        }
+        return new Promise((resolve, reject) => {
+            const pending = {
+                resolve,
+                reject,
+                aggregator: new TurnAggregator(),
+                timer: null,
+                settleImmediate: null,
+                steered: false,
+                deferredOutcome: null,
+            };
+            this.pending = pending;
+            // Arm the idle deadline (reset on every inbound stream line in `onLine`).
+            this.armIdleTimer(pending);
+            this.stdin.write(`${buildUserMessage(prompt, options)}\n`, (err) => {
+                if (err != null && this.pending === pending) {
+                    this.settlePending()?.reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+        });
+    }
+    async steerTurn(prompt, options = {}) {
+        if (!this.stdin.writable) {
+            return Promise.reject(new Error('claude resident child is not running'));
+        }
+        if (this.pending === null) {
+            return Promise.reject(new Error('claude resident session has no active turn'));
+        }
+        const pending = this.pending;
+        pending.steered = true;
+        return new Promise((resolve, reject) => {
+            this.stdin.write(`${buildUserMessage(prompt, { priority: 'now', ...options })}\n`, (err) => {
+                if (err != null) {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    onStdoutChunk(chunk) {
+        for (const line of this.lineBuf.push(chunk))
+            this.onLine(parseLine(line));
+    }
+    failPending(err) {
+        this.settlePending()?.reject(err);
+    }
+    enableRemoteControl() {
+        if (!this.stdin.writable)
+            return;
+        this.remoteControlRequestId = randomUUID();
+        this.stdin.write(`${buildRemoteControlEnable(this.remoteControlRequestId)}\n`);
+    }
+    /**
+     * Detach the in-flight turn: clear its deadline timer and null `pending`,
+     * returning it so the caller can resolve or reject it exactly once.
+     */
+    settlePending() {
+        const pending = this.pending;
+        if (pending === null)
+            return null;
+        if (pending.timer !== null)
+            clearTimeout(pending.timer);
+        if (pending.settleImmediate !== null)
+            clearImmediate(pending.settleImmediate);
+        this.pending = null;
+        return pending;
+    }
+    /**
+     * (Re)arm the per-turn idle deadline. `turnTimeoutMs` is a *max-idle* window,
+     * not a total-turn cap: any inbound stream line for this turn pushes it out
+     * (see `onLine`). A genuinely wedged child (no stream activity for the whole
+     * window) is still reaped — preserving the #120 anti-hang intent — but a long
+     * but continuously-streaming turn never trips the deadline (#156).
+     */
+    armIdleTimer(pending) {
+        if (pending.timer !== null)
+            clearTimeout(pending.timer);
+        pending.timer = setTimeout(() => {
+            if (this.pending !== pending)
+                return;
+            this.pending = null;
+            this.options.log?.('error', `claude turn stalled: no stream activity for ${this.options.turnTimeoutMs}ms; reaping resident child`);
+            pending.reject(new Error(`claude resident turn stalled: no stream activity for ${this.options.turnTimeoutMs}ms`));
+            this.options.reapOnTimeout();
+        }, this.options.turnTimeoutMs);
+    }
+    onLine(line) {
+        // Idle-timeout reset: any inbound stream line for the pending turn is
+        // activity, so push the deadline out. The terminal `result` clears the
+        // timer via `settlePending` below.
+        if (this.pending !== null)
+            this.armIdleTimer(this.pending);
+        switch (line.kind) {
+            case 'init':
+            case 'assistant':
+                this.pending?.aggregator.accept(line);
+                break;
+            case 'result': {
+                if (this.pending === null)
+                    break;
+                this.pending.aggregator.accept(line);
+                const outcome = this.pending.aggregator.outcome();
+                if (this.pending.steered) {
+                    this.deferSteeredResult(this.pending, outcome);
+                    break;
+                }
+                const pending = this.settlePending();
+                if (pending === null)
+                    break;
+                if (outcome !== null)
+                    pending.resolve(outcome);
+                else
+                    pending.reject(new Error('claude turn ended without a result'));
+                break;
+            }
+            case 'control_request':
+                this.onControlRequest(line.requestId, line.subtype, line.request);
+                break;
+            case 'control_response':
+                this.onControlResponse(line.requestId, line.ok, line.response, line.error);
+                break;
+            case 'parse_error':
+                this.options.log?.('warn', `claude stream-json parse error: ${line.raw}`);
+                break;
+            default:
+                break;
+        }
+    }
+    deferSteeredResult(pending, outcome) {
+        pending.deferredOutcome = outcome;
+        if (pending.settleImmediate !== null)
+            return;
+        // A stream-json `priority` steer can cause Claude Code to close the
+        // interrupted run and immediately drain the queued steer in the same stdout
+        // flush. Resolve on the next tick so those follow-up lines are still folded
+        // into this one Dreamux logical turn instead of becoming a silent late result.
+        pending.settleImmediate = setImmediate(() => {
+            if (this.pending !== pending)
+                return;
+            const finalOutcome = pending.deferredOutcome;
+            const settled = this.settlePending();
+            if (settled === null)
+                return;
+            if (finalOutcome !== null)
+                settled.resolve(finalOutcome);
+            else
+                settled.reject(new Error('claude turn ended without a result'));
+        });
+    }
+    onControlRequest(requestId, subtype, request) {
+        if (requestId === null || !this.stdin.writable)
+            return;
+        // Unattended posture: answer permission callbacks so a turn never wedges
+        // waiting on a human.
+        let reply;
+        if (subtype === 'can_use_tool') {
+            const rawInput = request['input'];
+            const input = typeof rawInput === 'object' &&
+                rawInput !== null &&
+                !Array.isArray(rawInput)
+                ? rawInput
+                : {};
+            reply = buildCanUseToolAllow(requestId, input);
+        }
+        else {
+            reply = buildControlAck(requestId);
+        }
+        this.stdin.write(`${reply}\n`);
+    }
+    onControlResponse(requestId, ok, response, error) {
+        if (requestId === null || requestId !== this.remoteControlRequestId)
+            return;
+        this.remoteControlRequestId = null;
+        if (ok && response !== null) {
+            const url = response['session_url'] ?? response['connect_url'];
+            if (typeof url === 'string') {
+                this.options.onRemoteControlUrl?.(url);
+            }
+            else {
+                this.options.log?.('warn', 'claude remote control enable succeeded without a URL');
+            }
+            return;
+        }
+        this.options.log?.('warn', `claude remote control enable failed${error !== null ? `: ${error}` : ''}`);
+    }
+}
+//# sourceMappingURL=rpc.js.map

package/dist/rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"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"}

package/dist/runtime.d.ts

@@ -0,0 +1,174 @@
+/**
+ * `builtin:claude-code` AgentRuntime (issue #110 PR6, resident stream-json
+ * transport since issue #120; extracted into `@excitedjs/agent-runtime-claude-code`
+ * in issue #209).
+ *
+ * A real second agent runtime that proves the AgentRuntimeProvider abstraction
+ * is not "Codex renamed". Like Codex it runs a **resident child process**
+ * supervised for the runtime's lifetime — but it differs in every
+ * runtime-specific dimension:
+ *
+ * - **Stream-json over stdio, not an app-server WebSocket.** The resident child
+ *   is `claude --print --input-format stream-json --output-format stream-json`
+ *   (see `./args.ts`); turns are NDJSON `user` lines on stdin and
+ *   `init`/`assistant`/`result` envelopes on stdout (see `./stream.ts`). There
+ *   is no `initialize` handshake — the child emits `init` lazily with the first
+ *   turn — so readiness is "child spawned", not "handshake completed".
+ * - **MCP injection is a JSON config document** (`--mcp-config <file>`), not
+ *   Codex's `-c mcp_servers.*` TOML CLI flags.
+ * - **Runtime-owned config** is `DispatcherClaudeCodeConfig` (bin / model /
+ *   permission_mode / remote_control / extra_args / extra_env), distinct from
+ *   the Codex config.
+ * - **Completion delivery** is a plain user turn (no fake task-notification),
+ *   not the Codex inbox-then-trigger path.
+ *
+ * Process spawning goes through an injectable {@link ClaudeCodeSessionFactory}
+ * seam (mirroring Codex's process-factory seam), so the lifecycle contract is
+ * fully unit-testable with a fake session. A live `claude` binary is exercised
+ * only by the opt-in live test.
+ *
+ * Failure contract (unchanged by #120): a turn failure (spawn error, child
+ * exit, error `result`) is never swallowed. For inbound/restart turns it drives
+ * the runtime to `degraded` with a persisted `last_error` (observable via
+ * status/doctor). For `completionInput` it surfaces as a `failed`
+ * result the caller can act on (PR8 delivery retry). `channelInput` still
+ * returns after accept (submit != completion) so the channel can ack promptly.
+ *
+ * Restart: an unexpected child exit marks the runtime `degraded`; the next turn
+ * re-spawns the resident child with `--resume <session_id>`, restoring the
+ * conversation. There is no background backoff timer — re-spawn is lazy and
+ * bound to the (serialized) turn queue, so it stays deterministic.
+ *
+ * Per-turn idle deadline: a turn whose still-alive child goes silent — never
+ * emitting another stream line (a stall, or a wait on input the runtime cannot
+ * satisfy) — would otherwise pend forever and wedge the serial queue, and behind
+ * it TeamMate completion delivery, which awaits this runtime. `turn_timeout_ms`
+ * is a *max-idle* window (issue #156): it is reset on every inbound stream line,
+ * so a long but continuously-streaming turn (e.g. a deep audit running many
+ * tool calls for far longer than the window) is never reaped, while a child that
+ * emits nothing for the whole window still is — turning an infinite hang into a
+ * normal degraded + `last_error` (inbound) or `failed` delivery result.
+ *
+ * Reference: the resident stream-json protocol model and process-supervision
+ * shape are adapted from the Claudemux `next` implementation; the AgentRuntime /
+ * Channel / DispatcherService boundaries (provider seam, runtime-owned MCP
+ * injection, degraded/last_error status, TeamMate delivery result contract) are
+ * Dreamux's own, per `.agents/decisions/agent-runtime-provider.md`.
+ */
+import type { DispatcherClaudeCodeConfig } from './config.js';
+import { type ClaudeCodeSessionFactory } from './supervisor.js';
+import type { AgentRuntimeCapabilities, AgentRuntime, AgentRuntimeIdentity, AgentRuntimeLastResult, AgentRuntimeMcpServer, AgentRuntimePathContext, AgentRuntimeResumeInput, AgentRuntimeSkillSource, AgentRuntimeStateCallbacks, AgentRuntimeStatus, AgentRuntimeSystemInput, AgentRuntimeTurnResult, CompletionEnvelope, DreamuxLogger, InboundDeliveryHooks, InboundTurnInput, TeamMateCompletionDeliveryResult, TurnSettledSignal } from '@excitedjs/dreamux-types';
+/**
+ * Everything the Claude Code runtime needs, assembled by the provider from the
+ * neutral create context plus host-supplied hooks. The host contracts the
+ * package must not reconstruct — the per-dispatcher path context, the durable
+ * state sink, and the base process env (`PATH` seeded with the host package
+ * bins) — arrive here; nothing references a Dreamux host module.
+ */
+export interface ClaudeCodeRuntimeDeps {
+    /** Provider-parsed Claude Code runtime config. */
+    config: DispatcherClaudeCodeConfig;
+    /** Working directory the resident `claude` child runs in. */
+    cwd: string;
+    /** Neutral state sink for status/thread transitions. */
+    state: AgentRuntimeStateCallbacks;
+    /** Neutral path context: the runtime derives its mcp-config / log subpaths here. */
+    paths: AgentRuntimePathContext;
+    /** MCP server descriptors translated into the `--mcp-config` JSON document. */
+    mcpServers: readonly AgentRuntimeMcpServer[];
+    /** Resident-session factory (tests inject a fake). */
+    sessionFactory: ClaudeCodeSessionFactory;
+    /** Host-level bin resolver (default: identity on the config bin). */
+    resolveBinPath: (bin: string) => string;
+    /**
+     * The host's neutral env-injection entries from the create context, merged
+     * into the resident child env before this provider's own `extra_env`.
+     * Empty/omitted means inject nothing (the common case).
+     */
+    injectEnv?: Record<string, string>;
+    /**
+     * Launcher-supplied role/system-prompt content, applied as an APPEND via
+     * `--append-system-prompt`. Omitted for launches that supply none (teammates).
+     */
+    systemPromptContent?: string;
+    /**
+     * Role-gated skill sources core selected (issue #209 slice 6). The
+     * add-dir-compatible ones become `--add-dir` flags on every (re)spawn.
+     */
+    skillSources?: readonly AgentRuntimeSkillSource[];
+    /** Fired each time a delivered turn reaches a terminal state. */
+    onTurnSettled?: (settled: TurnSettledSignal) => void;
+    /** Structured logger; falls back to a minimal `console.error` sink. */
+    logger?: DreamuxLogger;
+}
+/**
+ * The Claude Code agent runtime for one dispatcher. A single resident
+ * stream-json child serves every turn. Turns run serially (one at a time) and
+ * `channelInput` returns after the message is accepted — not after the turn
+ * completes — matching the Codex runtime's submit-then-serialize contract.
+ */
+export declare class ClaudeCodeRuntime implements AgentRuntime {
+    private readonly deps;
+    readonly providerRef = "builtin:claude-code";
+    private readonly dispatcherId;
+    private readonly config;
+    private readonly bin;
+    private readonly cwd;
+    private readonly mcpConfigPath;
+    private readonly mcpConfigDoc;
+    private readonly stderrLogPath;
+    private readonly completionSpillDir;
+    private readonly logger;
+    private status;
+    private threadId;
+    private resumed;
+    private stopped;
+    private readonly seen;
+    private queue;
+    private readonly runtimeInstanceId;
+    private turnCounter;
+    private session;
+    private lastResult;
+    private activeChannelTurn;
+    constructor(identity: AgentRuntimeIdentity, deps: ClaudeCodeRuntimeDeps);
+    getStatus(): AgentRuntimeStatus;
+    getCapabilities(): AgentRuntimeCapabilities;
+    getThreadId(): string | null;
+    wasThreadResumed(): boolean;
+    getLast(): Promise<AgentRuntimeLastResult | null>;
+    getContext(): Promise<null>;
+    resume(input?: AgentRuntimeResumeInput): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    systemInput(notice: AgentRuntimeSystemInput): Promise<AgentRuntimeTurnResult>;
+    channelInput(input: InboundTurnInput, hooks?: InboundDeliveryHooks): Promise<AgentRuntimeTurnResult>;
+    completionInput(completion: CompletionEnvelope): Promise<TeamMateCompletionDeliveryResult>;
+    /**
+     * Chain a turn onto the serial queue. Returns a promise that resolves when
+     * this turn completes and rejects when it fails, so awaiting callers (delivery)
+     * see the real outcome. The queue itself continues regardless of outcome so a
+     * failed turn does not wedge later turns.
+     */
+    private runTurnOnQueue;
+    private runChannelTurnOnQueue;
+    private runChannelTurn;
+    private steerChannelTurn;
+    private markTurnSucceeded;
+    private markTurnFailed;
+    /**
+     * Ensure a live resident session exists, spawning (or re-spawning after an
+     * unexpected exit) as needed. Re-spawn resumes the persisted session id so the
+     * conversation survives a crash.
+     */
+    private ensureSession;
+    /** React to an unexpected resident-child exit: degrade and drop the session. */
+    private onSessionExit;
+    private runTurn;
+    private runTurnWithSession;
+    private applyTurnOutcome;
+    private nextTurnId;
+    private buildProcessEnv;
+    private setStatus;
+    private log;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}