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

package/dist/stream.js

@@ -0,0 +1,289 @@
+/**
+ * The Claude Code stream-json wire protocol (issue #120).
+ *
+ * A clean-room model of the NDJSON envelopes the `claude` CLI emits and accepts
+ * on stdio under `--input-format stream-json --output-format stream-json`. This
+ * is what makes the `builtin:claude-code` runtime *resident*: one long-lived
+ * `claude --print` process consumes user-message lines on stdin and streams
+ * `init` / `assistant` / `result` envelopes on stdout, instead of a fresh
+ * one-shot process per turn.
+ *
+ * Two design rules, both load-bearing:
+ *
+ *  - **Forward-tolerant by construction.** The CLI's real envelope set is much
+ *    wider than anything Dreamux consumes (extra `system` subtypes, rate-limit
+ *    events, hook lifecycle, streamlined variants, and extra `result` fields).
+ *    This parser never validates a closed schema and never throws on an unknown
+ *    `type` / `subtype`; it reads only the fields the runtime needs and ignores
+ *    the rest. A wider or newer CLI build cannot break a turn.
+ *
+ *  - **Pure, no IO.** No process, no clock, no filesystem — so the line framer,
+ *    the line parser, and the turn aggregator are unit-tested against synthetic
+ *    envelope sequences (hand-authored to the real wire shapes) with no live
+ *    `claude` binary.
+ *
+ * Public-safety note: this module is a generic protocol model. It carries no
+ * Feishu identifiers, tokens, private paths, or environment-specific details.
+ */
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === 'string' ? v : null;
+}
+// ─── Line framing ───────────────────────────────────────────────────────────
+/**
+ * Incremental newline framer. The child's stdout is NDJSON but arrives in
+ * arbitrary chunks; `push` returns the complete lines so far and buffers a
+ * trailing partial line until its newline lands. Blank lines are dropped.
+ */
+export class LineBuffer {
+    buf = '';
+    push(chunk) {
+        this.buf += chunk;
+        const out = [];
+        let nl = this.buf.indexOf('\n');
+        while (nl >= 0) {
+            const line = this.buf.slice(0, nl);
+            this.buf = this.buf.slice(nl + 1);
+            const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line;
+            if (trimmed.length > 0)
+                out.push(trimmed);
+            nl = this.buf.indexOf('\n');
+        }
+        return out;
+    }
+    /** Any buffered bytes with no trailing newline (e.g. at stream end). */
+    flush() {
+        const rest = this.buf.trim();
+        this.buf = '';
+        return rest.length > 0 ? rest : null;
+    }
+}
+/**
+ * Join the text blocks of an Anthropic assistant `message.content` array.
+ * `thinking` and `tool_use` blocks contribute no visible text and are skipped.
+ */
+export function assistantText(message) {
+    if (!isObject(message))
+        return '';
+    const content = message['content'];
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (!isObject(block))
+            continue;
+        if (block['type'] === 'text') {
+            const t = str(block['text']);
+            if (t !== null)
+                parts.push(t);
+        }
+    }
+    return parts.join('');
+}
+function parseResult(o) {
+    const subtype = str(o['subtype']);
+    const errorsRaw = o['errors'];
+    const errors = Array.isArray(errorsRaw)
+        ? errorsRaw.filter((e) => typeof e === 'string')
+        : [];
+    let isError;
+    if (subtype !== null) {
+        isError = subtype !== 'success';
+    }
+    else {
+        isError = o['is_error'] === true || errors.length > 0;
+    }
+    return {
+        subtype,
+        isError,
+        text: str(o['result']),
+        sessionId: str(o['session_id']),
+        errors,
+    };
+}
+/**
+ * Decode one stdout line. Never throws: a non-JSON line becomes `parse_error`,
+ * and a JSON object of an unmodelled type becomes `other`.
+ */
+export function parseLine(line) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { kind: 'parse_error', raw: line };
+    }
+    if (!isObject(parsed))
+        return { kind: 'parse_error', raw: line };
+    const type = str(parsed['type']);
+    const subtype = str(parsed['subtype']);
+    switch (type) {
+        case 'system':
+            if (subtype === 'init') {
+                return {
+                    kind: 'init',
+                    sessionId: str(parsed['session_id']),
+                    model: str(parsed['model']),
+                    raw: parsed,
+                };
+            }
+            return { kind: 'other', type, subtype, raw: parsed };
+        case 'assistant':
+            return {
+                kind: 'assistant',
+                text: assistantText(parsed['message']),
+                sessionId: str(parsed['session_id']),
+                raw: parsed,
+            };
+        case 'result':
+            return { kind: 'result', outcome: parseResult(parsed), raw: parsed };
+        case 'control_request': {
+            const request = parsed['request'];
+            return {
+                kind: 'control_request',
+                requestId: str(parsed['request_id']),
+                subtype: isObject(request) ? str(request['subtype']) : null,
+                request: isObject(request) ? request : {},
+                raw: parsed,
+            };
+        }
+        case 'control_response': {
+            const response = parsed['response'];
+            if (isObject(response)) {
+                const inner = response['response'];
+                return {
+                    kind: 'control_response',
+                    requestId: str(response['request_id']),
+                    ok: response['subtype'] === 'success',
+                    response: isObject(inner) ? inner : null,
+                    error: str(response['error']),
+                    raw: parsed,
+                };
+            }
+            return {
+                kind: 'control_response',
+                requestId: null,
+                ok: false,
+                response: null,
+                error: null,
+                raw: parsed,
+            };
+        }
+        default:
+            return { kind: 'other', type, subtype, raw: parsed };
+    }
+}
+// ─── Outbound message builders (stdin) ──────────────────────────────────────
+/**
+ * One user turn as a stream-json `user` message line (no trailing newline).
+ *
+ * `isSynthetic` / `priority` are siblings of `message` on the stdin envelope
+ * (claude-code SDKUserMessage schema), not part of the message body. They are
+ * only set for the native completion-notification idiom; a plain channel turn
+ * omits them entirely and reads as a normal human user turn.
+ */
+export function buildUserMessage(text, options = {}) {
+    const envelope = {
+        type: 'user',
+        message: { role: 'user', content: [{ type: 'text', text }] },
+    };
+    if (options.isSynthetic === true)
+        envelope['isSynthetic'] = true;
+    if (options.priority !== undefined)
+        envelope['priority'] = options.priority;
+    return JSON.stringify(envelope);
+}
+/** Enable Claude Code Remote Control via a stream-json control request. */
+export function buildRemoteControlEnable(requestId) {
+    return JSON.stringify({
+        type: 'control_request',
+        request_id: requestId,
+        request: { subtype: 'remote_control', enabled: true },
+    });
+}
+/**
+ * Answer a `can_use_tool` control request with `allow`. A Dreamux dispatcher
+ * runs unattended, so the answer for a runtime that has no human to consult is
+ * "allow"; `updatedInput` echoes the tool's original input back unchanged.
+ *
+ * This is a defensive path: under a bypassing permission mode the CLI does not
+ * gate tools, so `can_use_tool` is not normally emitted. It is wired so that if
+ * a build or mode does emit one, the runtime answers it rather than leaving the
+ * turn waiting on an unanswered control request.
+ */
+export function buildCanUseToolAllow(requestId, input) {
+    return JSON.stringify({
+        type: 'control_response',
+        response: {
+            subtype: 'success',
+            request_id: requestId,
+            response: { behavior: 'allow', updatedInput: input },
+        },
+    });
+}
+/** Acknowledge any other control request with a bare success so the CLI proceeds. */
+export function buildControlAck(requestId) {
+    return JSON.stringify({
+        type: 'control_response',
+        response: { subtype: 'success', request_id: requestId, response: {} },
+    });
+}
+// ─── Turn aggregation ───────────────────────────────────────────────────────
+/**
+ * Accumulates the envelopes of a single turn and resolves a `TurnOutcome` when
+ * the `result` lands. One aggregator per turn: feed every `ParsedLine`, then
+ * read `outcome()` once `done` is true.
+ *
+ * The final text prefers the `result.result` (the CLI's own canonical answer)
+ * and falls back to the latest `assistant` snapshot — so a turn that ends
+ * tool-only or whose result text is empty still surfaces whatever the model
+ * last said.
+ */
+export class TurnAggregator {
+    lastAssistantText = '';
+    result = null;
+    initSessionId = null;
+    /** Returns `true` once the terminal `result` has been seen. */
+    get done() {
+        return this.result !== null;
+    }
+    /** The session id from `init` (or the result), once known. */
+    get sessionId() {
+        return this.result?.sessionId ?? this.initSessionId;
+    }
+    accept(line) {
+        switch (line.kind) {
+            case 'init':
+                if (line.sessionId !== null)
+                    this.initSessionId = line.sessionId;
+                break;
+            case 'assistant':
+                if (line.text.length > 0)
+                    this.lastAssistantText = line.text;
+                break;
+            case 'result':
+                this.result = line.outcome;
+                break;
+            default:
+                break;
+        }
+    }
+    outcome() {
+        const r = this.result;
+        if (r === null)
+            return null;
+        const text = r.text !== null && r.text.length > 0 ? r.text : this.lastAssistantText;
+        return {
+            isError: r.isError,
+            text,
+            sessionId: r.sessionId ?? this.initSessionId,
+            subtype: r.subtype,
+            errors: r.errors,
+        };
+    }
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

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

package/dist/supervisor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Claude Code resident child process supervisor.
+ *
+ * Mirrors `codex/supervisor.ts` for the `builtin:claude-code` transport:
+ * spawn the long-lived `claude --print --input-format stream-json` child,
+ * own its process group, surface unexpected exits, and delegate turn RPC to
+ * `claude-code/rpc.ts`.
+ */
+import type { ClaudeCodeSession, ClaudeCodeSessionSpec } from './types.js';
+/**
+ * The default factory: spawns the real `claude` binary. The returned session
+ * exposes a `setOnExit` registration the runtime uses to react to an unexpected
+ * child death (degrade + re-spawn next turn).
+ */
+export declare function createDefaultClaudeCodeSession(spec: ClaudeCodeSessionSpec): ClaudeCodeSession;
+export type { ClaudeCodeSession, ClaudeCodeSessionFactory, ClaudeCodeSessionSpec, TurnOutcome, TurnSubmitOptions, } from './types.js';
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../src/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EAGtB,MAAM,YAAY,CAAC;AA6JpB;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,qBAAqB,GAC1B,iBAAiB,CAEnB;AAED,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,EACX,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/supervisor.js

@@ -0,0 +1,170 @@
+/**
+ * Claude Code resident child process supervisor.
+ *
+ * Mirrors `codex/supervisor.ts` for the `builtin:claude-code` transport:
+ * spawn the long-lived `claude --print --input-format stream-json` child,
+ * own its process group, surface unexpected exits, and delegate turn RPC to
+ * `claude-code/rpc.ts`.
+ */
+import { spawn } from 'node:child_process';
+import { mkdir, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isProcessAlive, killProcessGroup, removeEmptyLogFile, } from '@excitedjs/dreamux-utils';
+import { ClaudeCodeStreamRpc } from './rpc.js';
+/** The live session: spawns and supervises the real `claude` child. */
+class LiveClaudeCodeSession {
+    spec;
+    child = null;
+    pid = null;
+    exited = false;
+    stopped = false;
+    rpc = null;
+    onExitHandler = null;
+    constructor(spec) {
+        this.spec = spec;
+    }
+    isAlive() {
+        return this.child !== null && !this.exited;
+    }
+    async start() {
+        if (this.child !== null) {
+            throw new Error('ClaudeCodeSession.start: already started');
+        }
+        await mkdir(this.spec.cwd, { recursive: true });
+        await mkdir(dirname(this.spec.stderrLogPath), { recursive: true });
+        // Open the stderr log as a FileHandle and hand its fd to the child. The
+        // handle is closed once the child owns the inherited fd (the finally),
+        // matching the timing discipline in codex/supervisor.ts.
+        const stderrHandle = await open(this.spec.stderrLogPath, 'a', 0o600);
+        const spawnOpts = {
+            cwd: this.spec.cwd,
+            env: this.spec.env,
+            // Own process group so a leaked grandchild is group-killable on reap.
+            detached: true,
+            stdio: ['pipe', 'pipe', stderrHandle.fd],
+        };
+        let child;
+        try {
+            child = await new Promise((resolve, reject) => {
+                let settled = false;
+                const c = spawn(this.spec.bin, this.spec.args, spawnOpts);
+                c.once('error', (e) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    reject(e instanceof Error ? e : new Error(String(e)));
+                });
+                c.once('spawn', () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(c);
+                });
+            });
+        }
+        finally {
+            await stderrHandle.close();
+        }
+        if (child.pid === undefined) {
+            throw new Error('claude resident child spawned without a pid');
+        }
+        this.child = child;
+        this.pid = child.pid;
+        // Post-spawn `error` must not crash the host event loop.
+        child.on('error', (err) => {
+            this.spec.log?.('warn', 'claude resident child error', err);
+        });
+        const stdin = child.stdin;
+        if (stdin === null) {
+            throw new Error('claude resident child spawned without stdin');
+        }
+        const rpc = new ClaudeCodeStreamRpc(stdin, {
+            turnTimeoutMs: this.spec.turnTimeoutMs,
+            log: this.spec.log,
+            reapOnTimeout: () => {
+                void this.stop().catch(() => {
+                    /* reap is best-effort */
+                });
+            },
+            onRemoteControlUrl: this.spec.onRemoteControlUrl,
+        });
+        this.rpc = rpc;
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            rpc.onStdoutChunk(chunk);
+        });
+        if (this.spec.remoteControl)
+            rpc.enableRemoteControl();
+        child.once('exit', () => this.onChildExit());
+    }
+    async submitTurn(prompt, options = {}) {
+        if (this.stopped) {
+            return Promise.reject(new Error('claude resident session is stopped'));
+        }
+        if (this.child === null || this.exited || this.rpc === null) {
+            return Promise.reject(new Error('claude resident child is not running'));
+        }
+        return this.rpc.submitTurn(prompt, options);
+    }
+    async steerTurn(prompt, options = {}) {
+        if (this.stopped) {
+            return Promise.reject(new Error('claude resident session is stopped'));
+        }
+        if (this.child === null || this.exited || this.rpc === null) {
+            return Promise.reject(new Error('claude resident child is not running'));
+        }
+        return this.rpc.steerTurn(prompt, options);
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        // Mark exited up front so the child's own `exit` event (fired by the kill
+        // below) is treated as a deliberate stop, never an unexpected exit that
+        // would fire `onExit` and degrade the runtime we are intentionally tearing
+        // down.
+        this.exited = true;
+        this.rpc?.failPending(new Error('claude resident session stopped mid-turn'));
+        const pid = this.pid;
+        if (pid !== null) {
+            if (isProcessAlive(pid)) {
+                killProcessGroup(pid, 'SIGTERM');
+                const deadline = Date.now() + 1000;
+                while (Date.now() < deadline) {
+                    if (!isProcessAlive(pid))
+                        break;
+                    await new Promise((r) => setTimeout(r, 25));
+                }
+            }
+            // Always SIGKILL the group — a reparented grandchild outliving its leader
+            // is the exact leak this guards against.
+            killProcessGroup(pid, 'SIGKILL');
+        }
+        this.exited = true;
+        this.rpc = null;
+        this.child = null;
+        // The child is gone, so its inherited stderr fd is released. Drop the stderr
+        // log if it stayed empty — claude traffic flows over the resident stream, so
+        // it usually captures nothing (issue #182 logs stage).
+        await removeEmptyLogFile(this.spec.stderrLogPath);
+    }
+    onChildExit() {
+        if (this.exited)
+            return;
+        this.exited = true;
+        this.rpc?.failPending(new Error('claude resident child exited mid-turn'));
+        this.onExitHandler?.();
+    }
+    setOnExit(handler) {
+        this.onExitHandler = handler;
+    }
+}
+/**
+ * The default factory: spawns the real `claude` binary. The returned session
+ * exposes a `setOnExit` registration the runtime uses to react to an unexpected
+ * child death (degrade + re-spawn next turn).
+ */
+export function createDefaultClaudeCodeSession(spec) {
+    return new LiveClaudeCodeSession(spec);
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/supervisor.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Claude Code stream-json protocol and resident-session types.
+ *
+ * These are data contracts only: no IO, no process spawning, no timers.
+ */
+/** A parsed JSON object, or `null` for anything that is not a JSON object. */
+export type JsonObject = Record<string, unknown>;
+/**
+ * One decoded stdout line. `kind` is Dreamux's coarse classification, not the
+ * CLI's `type` — it groups the wire types by how the runtime reacts.
+ */
+export type ParsedLine = {
+    kind: 'init';
+    sessionId: string | null;
+    model: string | null;
+    raw: JsonObject;
+} | {
+    kind: 'assistant';
+    text: string;
+    sessionId: string | null;
+    raw: JsonObject;
+} | {
+    kind: 'result';
+    outcome: ResultEnvelope;
+    raw: JsonObject;
+} | {
+    kind: 'control_request';
+    requestId: string | null;
+    subtype: string | null;
+    request: JsonObject;
+    raw: JsonObject;
+} | {
+    kind: 'control_response';
+    requestId: string | null;
+    ok: boolean;
+    response: JsonObject | null;
+    error: string | null;
+    raw: JsonObject;
+} | {
+    kind: 'other';
+    type: string | null;
+    subtype: string | null;
+    raw: JsonObject;
+} | {
+    kind: 'parse_error';
+    raw: string;
+};
+/** The terminal `result` envelope, reduced to what the runtime records per turn. */
+export interface ResultEnvelope {
+    /** `success` or one of the `error_*` subtypes. Unknown subtypes pass through. */
+    readonly subtype: string | null;
+    readonly isError: boolean;
+    /** The success-path final text (`result`); `null` for error subtypes. */
+    readonly text: string | null;
+    readonly sessionId: string | null;
+    /** Error subtypes may carry a message list; empty otherwise. */
+    readonly errors: readonly string[];
+}
+/**
+ * Per-turn stdin delivery options. The default (an absent object) produces a
+ * plain human-equivalent user turn; completion delivery opts into the native
+ * notification idiom.
+ */
+export interface TurnSubmitOptions {
+    /**
+     * Mark the stdin user message synthetic. claude-code maps this to its
+     * internal `isMeta`: hidden in the TUI transcript but model-visible and sent
+     * to the API like a normal user turn — the native channel for a background /
+     * sub-agent completion notification. Never set on human channel turns.
+     */
+    isSynthetic?: boolean;
+    /** Optional stdin delivery priority (claude-code `priority`). */
+    priority?: 'now' | 'next' | 'later';
+}
+/** The reduced outcome of one assistant turn, terminated by a `result`. */
+export interface TurnOutcome {
+    readonly isError: boolean;
+    /** Final reply text: the `result.result`, falling back to the last assistant snapshot. */
+    readonly text: string;
+    readonly sessionId: string | null;
+    readonly subtype: string | null;
+    readonly errors: readonly string[];
+}
+/** Everything needed to spawn one resident `claude` stream-json child. */
+export interface ClaudeCodeSessionSpec {
+    bin: string;
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Where to append the child's stderr (its stdout is the in-process data plane). */
+    stderrLogPath: string;
+    /**
+     * Per-turn deadline (ms). If the still-alive child never emits a terminal
+     * `result` within this window, the turn is failed and the child is reaped so
+     * the serial turn queue (and TeamMate completion delivery behind it) cannot
+     * wedge forever. Must be > 0.
+     */
+    turnTimeoutMs: number;
+    /**
+     * Enable Claude Code Remote Control for this resident session at startup.
+     * Implemented as a stream-json control request, not as a user turn.
+     */
+    remoteControl: boolean;
+    /** Surface the local-only Remote Control URL when Claude returns one. */
+    onRemoteControlUrl?: (url: string) => void;
+    /** Diagnostic logger for protocol-level events (parse errors, control answers). */
+    log?: (level: 'info' | 'warn' | 'error', msg: string, err?: unknown) => void;
+}
+/**
+ * A resident Claude Code session. Full turns are serialized by the caller;
+ * `steerTurn` is the one allowed concurrent write, used to steer the active
+ * turn without creating a second completion subscription.
+ */
+export interface ClaudeCodeSession {
+    /** Spawn the child and resolve once it is up (reject on spawn error). */
+    start(): Promise<void>;
+    /** Submit one user turn; resolve with the outcome when `result` lands. */
+    submitTurn(prompt: string, options?: TurnSubmitOptions): Promise<TurnOutcome>;
+    /** Send a user message into the active turn without awaiting a separate result. */
+    steerTurn(prompt: string, options?: TurnSubmitOptions): Promise<void>;
+    /** Whether the child is currently alive. */
+    isAlive(): boolean;
+    /**
+     * Register a one-shot handler fired when the child exits unexpectedly (not via
+     * {@link stop}). The runtime uses it to mark itself degraded and re-spawn on
+     * the next turn. Register before {@link start}.
+     */
+    setOnExit(handler: () => void): void;
+    /** Reap the child (SIGTERM -> SIGKILL group). Idempotent. */
+    stop(): Promise<void>;
+}
+export type ClaudeCodeSessionFactory = (spec: ClaudeCodeSessionSpec) => ClaudeCodeSession;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Claude Code stream-json protocol and resident-session types.
+ *
+ * These are data contracts only: no IO, no process spawning, no timers.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}