@coralai/claude-code-agent 0.1.0

package/dist/internal/session-accumulator.js.map

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

package/dist/prompt-handle.d.ts

@@ -0,0 +1,70 @@
+/**
+ * PromptHandle — the value returned by `agent.prompt()`.
+ *
+ * Per Eng D1 decision (2026-05-14): `updates` is **broadcast** — every
+ * SessionUpdate is buffered, every consumer (including late or repeat
+ * iterators) sees the full ordered stream. Memory cost: ~100KB per turn
+ * (typically <100 updates × <1KB each). This eliminates the race where
+ * awaiting `result` first drains the stream before iterating `updates`.
+ *
+ * Per codex finding #4 + #5 (2026-05-14): `cancel()` cancels only this
+ * turn — not the session, not queued sibling prompts. Use
+ * `agent.cancelAll()` for session-level cancel.
+ *
+ * Spec: vision doc §3 + §13 D1.
+ */
+import type * as schema from '@agentclientprotocol/sdk';
+import { AgentError } from './errors.js';
+/** A single streamed update for one turn. Re-uses the SDK shape directly so
+ *  this package tracks ACP protocol evolution without a translation layer. */
+export type SessionUpdate = schema.SessionNotification['update'];
+export type StopReason = 'end_turn' | 'cancelled' | 'error' | 'max_tokens';
+export interface UsageSummary {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** USD; sourced from `usage_update.cost` if shim provides, undefined otherwise. */
+    estimatedCostUsd?: number;
+}
+export interface PromptResult {
+    /** Concatenated text from all `assistant_message_chunk` updates. */
+    text: string;
+    /** Every SessionUpdate emitted during this turn, in order. */
+    updates: SessionUpdate[];
+    usage?: UsageSummary;
+    stopReason: StopReason;
+    turnId: string;
+}
+export interface PromptHandle {
+    /** Unique per turn — useful as OTel span attribute and recording key. */
+    readonly turnId: string;
+    /** Session this turn belongs to. */
+    readonly sessionId: string;
+    /** Resolves when the turn completes; rejects on error/timeout/cancel. */
+    readonly result: Promise<PromptResult>;
+    /** Async iterable of updates. **Broadcast**: multi-consumer safe; late
+     *  consumers see the full buffered history from the start. */
+    readonly updates: AsyncIterable<SessionUpdate>;
+    /** Cancel ONLY this turn. Returns when cancel ACK received from agent. */
+    cancel(): Promise<void>;
+}
+/** Internal handle: agent code pushes updates / settles result via the
+ *  controller; consumers see only the PromptHandle face. */
+export interface PromptHandleController {
+    handle: PromptHandle;
+    pushUpdate(update: SessionUpdate): void;
+    settle(result: PromptResult): void;
+    fail(error: AgentError): void;
+    /** Called by Agent when caller invokes handle.cancel(); the agent runs the
+     *  actual ACP cancel and then calls fail() with PROMPT_CANCELLED. */
+    setCancelImpl(impl: () => Promise<void>): void;
+}
+/** Build a new handle + its controller. The agent keeps the controller and
+ *  returns the handle to the caller. */
+export declare function createPromptHandle(turnId: string, sessionId: string): PromptHandleController;
+/** Walk a buffer of updates and produce a final PromptResult. The agent
+ *  calls this when the agent-side stream emits `end_turn` (or equivalent).
+ *  Centralized so tests can pin the aggregation behavior. */
+export declare function aggregateResult(turnId: string, updates: SessionUpdate[], stopReason: StopReason): PromptResult;
+//# sourceMappingURL=prompt-handle.d.ts.map

package/dist/prompt-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-handle.d.ts","sourceRoot":"","sources":["../src/prompt-handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,KAAK,MAAM,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC;8EAC8E;AAC9E,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAEjE,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,YAAY,CAAC;AAE3E,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACvC;kEAC8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAC/C,0EAA0E;IAC1E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAID;4DAC4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,YAAY,CAAC;IACrB,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B;yEACqE;IACrE,aAAa,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAChD;AAED;wCACwC;AACxC,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,sBAAsB,CAyGxB;AAID;;6DAE6D;AAC7D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,EAAE,EACxB,UAAU,EAAE,UAAU,GACrB,YAAY,CAiCd"}

package/dist/prompt-handle.js

@@ -0,0 +1,137 @@
+import { AgentError } from './errors.js';
+/** Build a new handle + its controller. The agent keeps the controller and
+ *  returns the handle to the caller. */
+export function createPromptHandle(turnId, sessionId) {
+    // Buffer of all updates, in insertion order. Broadcast semantics: each
+    // iterator reads from index 0 independently.
+    const buffer = [];
+    // Iterator-level resolvers waiting for next update or done signal.
+    const waiters = new Set();
+    // Final state: 'pending' | 'done' (buffer is the final list).
+    let done = false;
+    // Promise for the aggregated result. Resolved via controller.settle().
+    let resolveResult;
+    let rejectResult;
+    const result = new Promise((res, rej) => {
+        resolveResult = res;
+        rejectResult = rej;
+    });
+    // Prevent unhandled-rejection warnings if caller never awaits result.
+    result.catch(() => { });
+    // Cancel implementation set by agent after handle construction (so the
+    // agent can wire it to its own ACP cancel call referencing turnId).
+    let cancelImpl = async () => {
+        // Default: just settle with PROMPT_CANCELLED — agent overrides this.
+        const err = new AgentError('PROMPT_CANCELLED', 'Cancel requested before agent attached', {
+            context: { turnId, sessionId },
+        });
+        rejectResult(err);
+        done = true;
+        notifyWaiters();
+    };
+    function notifyWaiters() {
+        for (const wake of waiters)
+            wake();
+        waiters.clear();
+    }
+    function pushUpdate(update) {
+        if (done)
+            return; // post-settle updates ignored
+        buffer.push(update);
+        notifyWaiters();
+    }
+    function settle(value) {
+        if (done)
+            return;
+        done = true;
+        resolveResult(value);
+        notifyWaiters();
+    }
+    function fail(error) {
+        if (done)
+            return;
+        done = true;
+        rejectResult(error);
+        notifyWaiters();
+    }
+    function setCancelImpl(impl) {
+        cancelImpl = impl;
+    }
+    // Broadcast async iterable. Each call to [Symbol.asyncIterator]() gets a
+    // fresh cursor starting at buffer[0]. Multiple consumers can iterate
+    // concurrently or sequentially with identical results.
+    const updates = {
+        [Symbol.asyncIterator]() {
+            let cursor = 0;
+            return {
+                async next() {
+                    // Drain buffer first
+                    while (cursor < buffer.length) {
+                        const update = buffer[cursor];
+                        cursor++;
+                        if (update !== undefined) {
+                            return { value: update, done: false };
+                        }
+                    }
+                    // Caught up. If turn is done, signal end.
+                    if (done) {
+                        return { value: undefined, done: true };
+                    }
+                    // Wait for next push or settle.
+                    await new Promise((resolve) => {
+                        waiters.add(resolve);
+                    });
+                    // Recurse — drain again.
+                    return this.next();
+                },
+                return() {
+                    // Consumer abandoned this iterator. Don't affect other consumers
+                    // or the underlying turn — just stop yielding from this cursor.
+                    return Promise.resolve({ value: undefined, done: true });
+                },
+            };
+        },
+    };
+    const handle = {
+        turnId,
+        sessionId,
+        result,
+        updates,
+        cancel: () => cancelImpl(),
+    };
+    return { handle, pushUpdate, settle, fail, setCancelImpl };
+}
+// ─── Helper: aggregate updates into PromptResult ───────────────
+/** Walk a buffer of updates and produce a final PromptResult. The agent
+ *  calls this when the agent-side stream emits `end_turn` (or equivalent).
+ *  Centralized so tests can pin the aggregation behavior. */
+export function aggregateResult(turnId, updates, stopReason) {
+    let text = '';
+    let usage;
+    for (const update of updates) {
+        const u = update;
+        if (u.sessionUpdate === 'agent_message_chunk' && u.content?.type === 'text' && typeof u.content.text === 'string') {
+            text += u.content.text;
+        }
+        if (u.sessionUpdate === 'usage_update') {
+            const raw = u;
+            // Shim emits incremental usage; the last update wins. We accept the
+            // raw fields here; the agent layer maps `used` → outputTokens estimate.
+            // For v0.1, expose raw cost if present.
+            if (raw.cost && typeof raw.cost.amount === 'number') {
+                const existing = usage ?? { inputTokens: 0, outputTokens: 0 };
+                usage = { ...existing, estimatedCostUsd: raw.cost.amount };
+            }
+        }
+    }
+    const result = {
+        text,
+        updates,
+        stopReason,
+        turnId,
+    };
+    if (usage !== undefined)
+        result.usage = usage;
+    return result;
+}
+//# sourceMappingURL=prompt-handle.js.map

package/dist/prompt-handle.js.map

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

package/dist/recording/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Recording subsystem barrel.
+ *
+ * Step 1.4.6 ships writer + minimal replayer. Hook divergence validation
+ * (REPLAY_MISMATCH) lives in Step 1.4.8 when static replay() wires the
+ * replayer back into a fake agent.
+ */
+export { RecordingWriter, type RecordingEvent } from './writer.js';
+export { RecordingReplayer } from './replayer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/recording/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/recording/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/recording/index.js

@@ -0,0 +1,10 @@
+/**
+ * Recording subsystem barrel.
+ *
+ * Step 1.4.6 ships writer + minimal replayer. Hook divergence validation
+ * (REPLAY_MISMATCH) lives in Step 1.4.8 when static replay() wires the
+ * replayer back into a fake agent.
+ */
+export { RecordingWriter } from './writer.js';
+export { RecordingReplayer } from './replayer.js';
+//# sourceMappingURL=index.js.map

package/dist/recording/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/recording/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,eAAe,EAAuB,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/dist/recording/replayer.d.ts

@@ -0,0 +1,17 @@
+import type { RecordingEvent } from './writer.js';
+export declare class RecordingReplayer {
+    private readonly events;
+    private cursor;
+    constructor(path: string);
+    /** Number of parsed events. */
+    get length(): number;
+    /** All events in order. */
+    all(): readonly RecordingEvent[];
+    /** Read next event of type `kind`, advancing cursor past skipped events. */
+    nextOfType(kind: string): RecordingEvent | null;
+    /** Look at the next event without advancing. */
+    peek(): RecordingEvent | null;
+    /** Throw REPLAY_EOF if cursor reached end. */
+    expectMore(reason: string): void;
+}
+//# sourceMappingURL=replayer.d.ts.map

package/dist/recording/replayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayer.d.ts","sourceRoot":"","sources":["../../src/recording/replayer.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,MAAM,CAAK;gBAEP,IAAI,EAAE,MAAM;IA6BxB,+BAA+B;IAC/B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,2BAA2B;IAC3B,GAAG,IAAI,SAAS,cAAc,EAAE;IAIhC,4EAA4E;IAC5E,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAQ/C,gDAAgD;IAChD,IAAI,IAAI,cAAc,GAAG,IAAI;IAI7B,8CAA8C;IAC9C,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CASjC"}

package/dist/recording/replayer.js

@@ -0,0 +1,68 @@
+/**
+ * RecordingReplayer — read jsonl recording and yield events.
+ *
+ * Step 1.4.6 scope: minimal reader that parses jsonl + iterates events.
+ * Step 1.4.8 adds REPLAY_MISMATCH validation (hook IO must match recording)
+ * + REPLAY_EOF handling (recording ended before turn settled).
+ */
+import { readFileSync } from 'node:fs';
+import { AgentError } from '../errors.js';
+export class RecordingReplayer {
+    events;
+    cursor = 0;
+    constructor(path) {
+        let raw;
+        try {
+            raw = readFileSync(path, 'utf-8');
+        }
+        catch (e) {
+            throw new AgentError('REPLAY_EOF', `Recording file not readable at ${path}: ${e instanceof Error ? e.message : String(e)}`, {
+                ...(e instanceof Error ? { cause: e } : {}),
+                context: { path },
+            });
+        }
+        this.events = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed.type === 'string') {
+                    this.events.push(parsed);
+                }
+            }
+            catch {
+                /* skip malformed lines — replay is best-effort */
+            }
+        }
+    }
+    /** Number of parsed events. */
+    get length() {
+        return this.events.length;
+    }
+    /** All events in order. */
+    all() {
+        return this.events;
+    }
+    /** Read next event of type `kind`, advancing cursor past skipped events. */
+    nextOfType(kind) {
+        while (this.cursor < this.events.length) {
+            const event = this.events[this.cursor++];
+            if (event && event.type === kind)
+                return event;
+        }
+        return null;
+    }
+    /** Look at the next event without advancing. */
+    peek() {
+        return this.events[this.cursor] ?? null;
+    }
+    /** Throw REPLAY_EOF if cursor reached end. */
+    expectMore(reason) {
+        if (this.cursor >= this.events.length) {
+            throw new AgentError('REPLAY_EOF', `Recording ended unexpectedly: ${reason}`, { context: { cursor: this.cursor, total: this.events.length } });
+        }
+    }
+}
+//# sourceMappingURL=replayer.js.map

package/dist/recording/replayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replayer.js","sourceRoot":"","sources":["../../src/recording/replayer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1C,MAAM,OAAO,iBAAiB;IACX,MAAM,CAAmB;IAClC,MAAM,GAAG,CAAC,CAAC;IAEnB,YAAY,IAAY;QACtB,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,UAAU,CAClB,YAAY,EACZ,kCAAkC,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EACvF;gBACE,GAAG,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,OAAO,EAAE,EAAE,IAAI,EAAE;aAClB,CACF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;QACjB,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO;gBAAE,SAAS;YACvB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAmB,CAAC;gBACrD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACpC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC3B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,kDAAkD;YACpD,CAAC;QACH,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,2BAA2B;IAC3B,GAAG;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,4EAA4E;IAC5E,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACzC,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,KAAK,CAAC;QACjD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gDAAgD;IAChD,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;IAC1C,CAAC;IAED,8CAA8C;IAC9C,UAAU,CAAC,MAAc;QACvB,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,UAAU,CAClB,YAAY,EACZ,iCAAiC,MAAM,EAAE,EACzC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/recording/writer.d.ts

@@ -0,0 +1,32 @@
+export interface RecordingEvent {
+    /** ISO-8601 timestamp; set by writer if absent. */
+    ts?: string;
+    /** Event kind; see file format docs above. */
+    type: string;
+    /** Arbitrary payload fields. */
+    [key: string]: unknown;
+}
+export declare class RecordingWriter {
+    private readonly path;
+    private readonly stream;
+    private buffer;
+    private bufferedBytes;
+    private flushTimer;
+    private closed;
+    /** Resolves when close() finishes flushing + closing the stream. */
+    private closePromise;
+    constructor(path: string);
+    /** Path being written. */
+    get filePath(): string;
+    /** Append one event. ts auto-filled if absent. */
+    write(event: RecordingEvent): void;
+    /** Drain buffer to stream now. Synchronous append; no awaiting drain. */
+    private flushNow;
+    /**
+     * Force flush pending bytes and close the stream. Idempotent.
+     * Resolves only after the FS drain completes — safe to await before
+     * shutting down the process.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=writer.d.ts.map

package/dist/recording/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../src/recording/writer.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAGrC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,aAAa,CAAK;IAE1B,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,MAAM,CAAS;IACvB,oEAAoE;IACpE,OAAO,CAAC,YAAY,CAA8B;gBAEtC,IAAI,EAAE,MAAM;IAcxB,0BAA0B;IAC1B,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,kDAAkD;IAClD,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI;IAsBlC,yEAAyE;IACzE,OAAO,CAAC,QAAQ;IAsBhB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAW7B"}

package/dist/recording/writer.js

@@ -0,0 +1,122 @@
+/**
+ * RecordingWriter — captures agent session as jsonl for replay-based testing.
+ *
+ * Per Eng D3/D4 decisions (2026-05-14):
+ * - Captures ACP raw frames + hook IO + turn boundaries + permissions
+ *   + elicitation answers (D3)
+ * - Async batch flush: 100ms tick OR 64KB buffered, whichever first (D4)
+ * - close() force-flushes pending bytes
+ *
+ * Privacy: jsonl contains raw prompts/responses/tool IO. Treat as sensitive.
+ * The agent README emits a warning when `recording` is set; this writer
+ * does not encrypt or redact.
+ *
+ * File format: one JSON object per line, schema:
+ *   { ts: ISO-8601, type: <event-kind>, ...payload }
+ *
+ * Common event kinds (v0.1):
+ *   - "session_start"   { sessionId, pid?, cwd }
+ *   - "session_stop"    { reason, code? }
+ *   - "turn_start"      { turnId, prompt }
+ *   - "turn_end"        { turnId, stopReason, usage? }
+ *   - "session_update"  { turnId, update }       — every SessionUpdate
+ *   - "hook_call"       { hook, input, output? } — fs/terminal/permission/elicitation
+ *
+ * Step 1.4.6 scope: writer + batch flushing + close(). Replayer that
+ * validates hook divergence (REPLAY_MISMATCH) → 1.4.8.
+ */
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+const FLUSH_INTERVAL_MS = 100;
+const FLUSH_THRESHOLD_BYTES = 64 * 1024; // 64 KB
+export class RecordingWriter {
+    path;
+    stream;
+    // In-memory buffer: jsonl lines waiting to flush
+    buffer = [];
+    bufferedBytes = 0;
+    flushTimer = null;
+    closed = false;
+    /** Resolves when close() finishes flushing + closing the stream. */
+    closePromise = null;
+    constructor(path) {
+        this.path = path;
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        catch {
+            /* parent dir may already exist */
+        }
+        this.stream = createWriteStream(path, { flags: 'a', encoding: 'utf-8' });
+        // Stream errors get swallowed; recording must never crash the agent.
+        this.stream.on('error', () => {
+            /* best effort */
+        });
+    }
+    /** Path being written. */
+    get filePath() {
+        return this.path;
+    }
+    /** Append one event. ts auto-filled if absent. */
+    write(event) {
+        if (this.closed)
+            return;
+        const line = JSON.stringify({
+            ts: event.ts ?? new Date().toISOString(),
+            ...event,
+        }) + '\n';
+        this.buffer.push(line);
+        this.bufferedBytes += Buffer.byteLength(line, 'utf-8');
+        if (this.bufferedBytes >= FLUSH_THRESHOLD_BYTES) {
+            // Threshold flush — fire-and-forget
+            this.flushNow();
+            return;
+        }
+        if (this.flushTimer === null) {
+            this.flushTimer = setTimeout(() => this.flushNow(), FLUSH_INTERVAL_MS);
+            // Don't keep the event loop alive just for the recording flush
+            this.flushTimer.unref?.();
+        }
+    }
+    /** Drain buffer to stream now. Synchronous append; no awaiting drain. */
+    flushNow() {
+        if (this.buffer.length === 0) {
+            if (this.flushTimer !== null) {
+                clearTimeout(this.flushTimer);
+                this.flushTimer = null;
+            }
+            return;
+        }
+        const chunk = this.buffer.join('');
+        this.buffer = [];
+        this.bufferedBytes = 0;
+        if (this.flushTimer !== null) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        try {
+            this.stream.write(chunk);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    /**
+     * Force flush pending bytes and close the stream. Idempotent.
+     * Resolves only after the FS drain completes — safe to await before
+     * shutting down the process.
+     */
+    async close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closed = true;
+        this.flushNow();
+        this.closePromise = new Promise((resolve) => {
+            this.stream.end(() => {
+                resolve();
+            });
+        });
+        return this.closePromise;
+    }
+}
+//# sourceMappingURL=writer.js.map

package/dist/recording/writer.js.map

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

package/dist/telemetry/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Telemetry barrel.
+ *
+ * Public OTel adapter for caller-supplied Tracer (peer dep
+ * `@opentelemetry/api ≥1.7 <2`, optional). Zero cost when not used.
+ */
+export { SpanManager, SpanStatusCode, setAttributeSafe, truncateAttributeValue, type Attributes, type AttributeValue, type Span, type Tracer, } from './otel-adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,IAAI,EACT,KAAK,MAAM,GACZ,MAAM,mBAAmB,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,8 @@
+/**
+ * Telemetry barrel.
+ *
+ * Public OTel adapter for caller-supplied Tracer (peer dep
+ * `@opentelemetry/api ≥1.7 <2`, optional). Zero cost when not used.
+ */
+export { SpanManager, SpanStatusCode, setAttributeSafe, truncateAttributeValue, } from './otel-adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/telemetry/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,WAAW,EACX,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GAKvB,MAAM,mBAAmB,CAAC"}

package/dist/telemetry/otel-adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * OpenTelemetry adapter — wraps session/prompt/tool lifecycle in OTel spans.
+ *
+ * Per Eng D4 (2026-05-14):
+ * - Span hierarchy: agent.session (root) → agent.prompt → agent.tool.call /
+ *   agent.permission.request / agent.elicitation.request
+ * - Attributes follow OTel GenAI semantic conventions:
+ *     gen_ai.system: 'claude'
+ *     gen_ai.usage.input_tokens / output_tokens / cache_read_tokens / cache_write_tokens
+ *     gen_ai.response.finish_reason
+ * - Attribute payloads > 8 KB are truncated and marked `truncated: true`
+ *
+ * Peer dependency: `@opentelemetry/api` ≥1.7 <2 (OPTIONAL — only loaded when
+ * caller passes a tracer). The adapter never imports `@opentelemetry/api`;
+ * it uses a minimal structural `Tracer` interface that matches the real type.
+ * This keeps zero-dep cost for callers who don't use telemetry.
+ *
+ * Caller pattern:
+ *
+ *   import { trace } from '@opentelemetry/api';
+ *   const agent = new ClaudeCodeAgent({ cwd, tracer: trace.getTracer('myapp') });
+ *
+ * Step 1.4.7 ships the adapter + 8 KB truncation. Span hierarchy is wired
+ * for session.start, prompt, and turn-end. Tool/permission/elicitation
+ * spans land in Step 1.4.8 alongside their respective wirings.
+ */
+/** Subset of OTel SpanAttributeValue we use. */
+export type AttributeValue = string | number | boolean | Array<string | number | boolean>;
+export interface Attributes {
+    [key: string]: AttributeValue;
+}
+/** Minimal Span structural interface. */
+export interface Span {
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setAttributes(attrs: Attributes): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(error: Error): unknown;
+    end(endTime?: number): unknown;
+}
+/** Minimal Tracer structural interface. */
+export interface Tracer {
+    startSpan(name: string, options?: {
+        attributes?: Attributes;
+    }): Span;
+}
+/** Truncate a string-valued attribute if it exceeds 8 KB. Returns the
+ *  possibly-truncated value paired with a `_truncated` flag attribute name.
+ *  Callers should write both: setAttribute(key, value) + setAttribute(key+'.truncated', true)
+ *  when the result is truncated. */
+export declare function truncateAttributeValue(value: string): {
+    value: string;
+    truncated: boolean;
+};
+/** Helper: set an attribute with auto-truncation when the value is a string. */
+export declare function setAttributeSafe(span: Span, key: string, value: AttributeValue): void;
+/** SpanStatusCode mirrors OTel: UNSET=0, OK=1, ERROR=2. */
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+/**
+ * Coordinates the span hierarchy for one ClaudeCodeAgent instance.
+ * The agent owns a single SpanManager that opens session-scoped spans on
+ * start, prompt-scoped spans during each turn, and closes them on settle/fail.
+ */
+export declare class SpanManager {
+    private readonly tracer;
+    private sessionSpan;
+    private promptSpan;
+    constructor(tracer: Tracer);
+    /** Open the root span for the agent's session. Returns the span so the
+     *  caller can stash it (typically just rely on `this.sessionSpan`). */
+    startSession(attrs: {
+        sessionId: string;
+        cwd: string;
+        pid?: number;
+    }): Span;
+    /** Mark session ended. Idempotent. */
+    endSession(opts?: {
+        error?: Error;
+        code?: number;
+    }): void;
+    /** Open a child span for one prompt turn. */
+    startPrompt(attrs: {
+        turnId: string;
+        promptPreview: string;
+    }): Span;
+    /** Close the prompt span with finish reason + usage. */
+    endPrompt(opts: {
+        stopReason: string;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+            cacheReadTokens?: number;
+            cacheWriteTokens?: number;
+            estimatedCostUsd?: number;
+        };
+        error?: Error;
+    }): void;
+}
+//# sourceMappingURL=otel-adapter.d.ts.map