chivgent 0.6.0

package/dist/render.js

@@ -0,0 +1,95 @@
+const MAX_ARGUMENT_CHARACTERS = 120;
+const MAX_RESULT_CHARACTERS = 100;
+const DIM = "\u001B[2m";
+const RED = "\u001B[31m";
+const RESET = "\u001B[0m";
+/**
+ * Renders runtime events for a terminal. The answer goes to stdout so it stays
+ * pipeable; tool activity and run status go to stderr.
+ */
+export function createEventRenderer(streams, options = {}) {
+    const stream = options.stream ?? true;
+    const showToolActivity = options.showToolActivity ?? true;
+    const color = options.color ?? false;
+    const paint = (value, code) => color ? `${code}${value}${RESET}` : value;
+    let lineOpen = false;
+    const endLine = () => {
+        if (lineOpen) {
+            streams.stdout.write("\n");
+            lineOpen = false;
+        }
+    };
+    return (event) => {
+        switch (event.type) {
+            case "message_update":
+                if (stream && event.delta.length > 0) {
+                    streams.stdout.write(event.delta);
+                    lineOpen = !event.delta.endsWith("\n");
+                }
+                return;
+            case "message_end":
+                if (!stream && event.message.content.length > 0) {
+                    streams.stdout.write(`${event.message.content}\n`);
+                }
+                endLine();
+                return;
+            case "tool_execution_start":
+                if (showToolActivity) {
+                    streams.stderr.write(paint(`· ${event.toolName} ${summariseArguments(event.arguments)}\n`, DIM));
+                }
+                return;
+            case "tool_execution_end":
+                if (showToolActivity) {
+                    const summary = `  ↳ ${summariseResult(event.content, event.isError)}\n`;
+                    streams.stderr.write(paint(summary, event.isError ? RED : DIM));
+                }
+                return;
+            case "agent_end":
+                endLine();
+                if (event.status === "max_turns") {
+                    streams.stderr.write(`Stopped after ${event.turnCount} turns without a final answer.\n`);
+                }
+                else if (event.status === "aborted") {
+                    streams.stderr.write("Interrupted.\n");
+                }
+                // A failed run is reported by whoever awaited it, with the real error.
+                return;
+            default:
+                return;
+        }
+    };
+}
+/**
+ * Writes one JSON object per line: the session header first, then every event.
+ * This is the machine-readable counterpart of the terminal renderer.
+ */
+export function createJsonEventWriter(output, header) {
+    if (header !== undefined) {
+        output.write(`${JSON.stringify(header)}\n`);
+    }
+    return (event) => {
+        output.write(`${JSON.stringify(event)}\n`);
+    };
+}
+function summariseArguments(value) {
+    let text;
+    try {
+        text = typeof value === "string" ? value : (JSON.stringify(value) ?? "");
+    }
+    catch {
+        text = "[unserialisable arguments]";
+    }
+    return truncate(text.replaceAll(/\s+/g, " "), MAX_ARGUMENT_CHARACTERS);
+}
+function summariseResult(content, isError) {
+    const firstLine = content.split("\n", 1)[0] ?? "";
+    const lineCount = content.length === 0 ? 0 : content.split("\n").length;
+    const suffix = lineCount > 1 ? ` (${lineCount} lines)` : "";
+    return `${isError ? "error: " : ""}${truncate(firstLine, MAX_RESULT_CHARACTERS)}${suffix}`;
+}
+function truncate(value, maxCharacters) {
+    return value.length <= maxCharacters
+        ? value
+        : `${value.slice(0, maxCharacters - 1)}…`;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

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

package/dist/repl.d.ts

@@ -0,0 +1,29 @@
+import type { AgentSession } from "./session.js";
+import type { OutputStream } from "./render.js";
+export declare const REPL_PROMPT = "\u203A ";
+export type SlashCommandOutcome = "handled" | "exit" | "not-a-command";
+export interface SlashCommandContext {
+    readonly session: AgentSession;
+    readonly write: (text: string) => void;
+    readonly sessionFile?: string;
+}
+/**
+ * Interprets one line of REPL input. Returns `not-a-command` when the line is
+ * an ordinary prompt for the model.
+ */
+export declare function handleSlashCommand(line: string, context: SlashCommandContext): SlashCommandOutcome;
+export interface ReplOptions {
+    readonly session: AgentSession;
+    readonly input: NodeJS.ReadableStream;
+    readonly output: NodeJS.WritableStream;
+    readonly stderr: OutputStream;
+    readonly banner?: string;
+    readonly sessionFile?: string;
+}
+/**
+ * Reads prompts until the user leaves. One run at a time: Ctrl+C cancels the
+ * answer in progress instead of killing the process, so the transcript and the
+ * session log survive an interrupt.
+ */
+export declare function runRepl(options: ReplOptions): Promise<number>;
+//# sourceMappingURL=repl.d.ts.map

package/dist/repl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repl.d.ts","sourceRoot":"","sources":["../src/repl.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,WAAW,YAAO,CAAC;AAEhC,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,eAAe,CAAC;AAEvE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAYD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAC3B,mBAAmB,CAmCrB;AAeD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CA6DnE"}

package/dist/repl.js

@@ -0,0 +1,119 @@
+import { createInterface } from "node:readline";
+export const REPL_PROMPT = "› ";
+const HELP = `Commands:
+  /help      Show this help
+  /session   Show the current session id, workspace, and size
+  /tools     List the tools available to the model
+  /clear     Start a new transcript in the same session
+  /exit      Leave chivgent (Ctrl+D also works)
+
+Anything else is sent to the model. Ctrl+C stops the answer in progress.
+`;
+/**
+ * Interprets one line of REPL input. Returns `not-a-command` when the line is
+ * an ordinary prompt for the model.
+ */
+export function handleSlashCommand(line, context) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("/")) {
+        return "not-a-command";
+    }
+    switch (trimmed.split(/\s+/, 1)[0]) {
+        case "/help":
+        case "/?":
+            context.write(HELP);
+            return "handled";
+        case "/session":
+            context.write(describeSession(context));
+            return "handled";
+        case "/tools":
+            context.write(`${context.session.toolNames.map((name) => `  ${name}`).join("\n")}\n`);
+            return "handled";
+        case "/clear":
+            context.session.clear();
+            context.write("Transcript cleared.\n");
+            return "handled";
+        case "/exit":
+        case "/quit":
+            return "exit";
+        default:
+            context.write(`Unknown command: ${trimmed}. Try /help.\n`);
+            return "handled";
+    }
+}
+function describeSession(context) {
+    const lines = [
+        `id:        ${context.session.id}`,
+        `workspace: ${context.session.cwd}`,
+        `prompts:   ${context.session.turns}`,
+        `messages:  ${context.session.messages.length}`,
+    ];
+    if (context.sessionFile !== undefined) {
+        lines.push(`log:       ${context.sessionFile}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Reads prompts until the user leaves. One run at a time: Ctrl+C cancels the
+ * answer in progress instead of killing the process, so the transcript and the
+ * session log survive an interrupt.
+ */
+export async function runRepl(options) {
+    const write = (text) => {
+        options.stderr.write(text);
+    };
+    const readline = createInterface({
+        input: options.input,
+        output: options.output,
+        terminal: true,
+        prompt: REPL_PROMPT,
+    });
+    let controller;
+    readline.on("SIGINT", () => {
+        if (controller === undefined) {
+            write("Press Ctrl+D or /exit to leave.\n");
+            readline.prompt();
+            return;
+        }
+        controller.abort();
+    });
+    if (options.banner !== undefined) {
+        write(options.banner);
+    }
+    readline.prompt();
+    for await (const line of readline) {
+        if (line.trim().length === 0) {
+            readline.prompt();
+            continue;
+        }
+        const outcome = handleSlashCommand(line, {
+            session: options.session,
+            write,
+            ...(options.sessionFile === undefined
+                ? {}
+                : { sessionFile: options.sessionFile }),
+        });
+        if (outcome === "exit") {
+            break;
+        }
+        if (outcome === "handled") {
+            readline.prompt();
+            continue;
+        }
+        controller = new AbortController();
+        try {
+            await options.session.prompt(line, { signal: controller.signal });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            write(`Agent failed: ${message}\n`);
+        }
+        finally {
+            controller = undefined;
+        }
+        readline.prompt();
+    }
+    readline.close();
+    return 0;
+}
+//# sourceMappingURL=repl.js.map

package/dist/repl.js.map

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

package/dist/retry.d.ts

@@ -0,0 +1,42 @@
+import { type LLMClient, type LLMRequest, type LLMResponse, type LLMStreamHandlers } from "./llm.js";
+export declare class LLMTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+export interface RetryOptions {
+    /** Total attempts, including the first one. Defaults to 3. */
+    readonly maxAttempts?: number;
+    readonly initialDelayMs?: number;
+    readonly maxDelayMs?: number;
+    /** Per-attempt deadline. Use 0 to disable. Defaults to 120000. */
+    readonly requestTimeoutMs?: number;
+    /** Injected so tests do not depend on wall-clock time. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    readonly onRetry?: (info: RetryAttempt) => void;
+}
+export interface RetryAttempt {
+    readonly attempt: number;
+    readonly delayMs: number;
+    readonly reason: string;
+}
+/**
+ * Wraps a Provider with per-attempt timeouts and bounded exponential backoff.
+ * Retries stay invisible to the Agent Loop: it still sees one call that either
+ * resolves with an assistant message or fails.
+ */
+export declare class RetryingLLMClient implements LLMClient {
+    readonly stream?: (request: LLMRequest, handlers: LLMStreamHandlers) => Promise<LLMResponse>;
+    private readonly inner;
+    private readonly maxAttempts;
+    private readonly initialDelayMs;
+    private readonly maxDelayMs;
+    private readonly requestTimeoutMs;
+    private readonly sleep;
+    private readonly onRetry;
+    constructor(inner: LLMClient, options?: RetryOptions);
+    complete(request: LLMRequest): Promise<LLMResponse>;
+    private runStream;
+    private withRetries;
+    private backoffDelay;
+    private createDeadline;
+}
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,UAAU,CAAC;AAkBlB,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,SAAS,EAAE,MAAM,EAG5B;CACF;AAED,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAChB,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,iBAAiB,KACxB,OAAO,CAAC,WAAW,CAAC,CAAC;IAE1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsD;IAC5E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6C;IAErE,YAAY,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,YAAiB,EAgBvD;IAEK,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAIxD;YAEa,SAAS;YAoBT,WAAW;IA0CzB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,cAAc;CAqCvB"}

package/dist/retry.js

@@ -0,0 +1,186 @@
+import { isAbortError, LLMAbortError, } from "./llm.js";
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 8_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+const RETRYABLE_STATUS_CODES = new Set([408, 409, 425, 429]);
+const RETRYABLE_ERROR_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+export class LLMTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`The Provider call exceeded ${timeoutMs}ms.`);
+        this.name = "LLMTimeoutError";
+    }
+}
+/**
+ * Wraps a Provider with per-attempt timeouts and bounded exponential backoff.
+ * Retries stay invisible to the Agent Loop: it still sees one call that either
+ * resolves with an assistant message or fails.
+ */
+export class RetryingLLMClient {
+    stream;
+    inner;
+    maxAttempts;
+    initialDelayMs;
+    maxDelayMs;
+    requestTimeoutMs;
+    sleep;
+    onRetry;
+    constructor(inner, options = {}) {
+        this.inner = inner;
+        this.maxAttempts = positiveInteger(options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS, "maxAttempts");
+        this.initialDelayMs = options.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+        this.maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+        this.requestTimeoutMs =
+            options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.onRetry = options.onRetry;
+        if (inner.stream !== undefined) {
+            this.stream = (request, handlers) => this.runStream(request, handlers);
+        }
+    }
+    async complete(request) {
+        return this.withRetries(request, (attemptRequest) => this.inner.complete(attemptRequest));
+    }
+    async runStream(request, handlers) {
+        const stream = this.inner.stream;
+        if (stream === undefined) {
+            throw new TypeError("The wrapped Provider does not support streaming.");
+        }
+        return this.withRetries(request, async (attemptRequest, markCommitted) => stream.call(this.inner, attemptRequest, {
+            onTextDelta: (delta) => {
+                // Text already shown to the user cannot be replayed by a retry.
+                markCommitted();
+                handlers.onTextDelta(delta);
+            },
+        }));
+    }
+    async withRetries(request, call) {
+        let lastError;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt += 1) {
+            throwIfAborted(request.signal);
+            const deadline = this.createDeadline(request.signal);
+            let committed = false;
+            try {
+                return await call({ ...request, signal: deadline.signal }, () => {
+                    committed = true;
+                });
+            }
+            catch (error) {
+                lastError = deadline.timedOut ? new LLMTimeoutError(this.requestTimeoutMs) : error;
+                throwIfAborted(request.signal);
+                if (isAbortError(error) && !deadline.timedOut) {
+                    throw error;
+                }
+                if (committed || attempt === this.maxAttempts || !isRetryable(lastError)) {
+                    throw lastError;
+                }
+                const delayMs = this.backoffDelay(attempt);
+                this.onRetry?.({
+                    attempt,
+                    delayMs,
+                    reason: describeError(lastError),
+                });
+                await this.sleep(delayMs, request.signal);
+            }
+            finally {
+                deadline.dispose();
+            }
+        }
+        throw lastError ?? new Error("The Provider call failed.");
+    }
+    backoffDelay(attempt) {
+        const exponential = this.initialDelayMs * 2 ** (attempt - 1);
+        return Math.min(this.maxDelayMs, exponential);
+    }
+    createDeadline(signal) {
+        const controller = new AbortController();
+        const state = { timedOut: false };
+        const forward = () => {
+            controller.abort(signal?.reason);
+        };
+        if (signal !== undefined) {
+            if (signal.aborted) {
+                forward();
+            }
+            else {
+                signal.addEventListener("abort", forward, { once: true });
+            }
+        }
+        const timer = this.requestTimeoutMs > 0
+            ? setTimeout(() => {
+                state.timedOut = true;
+                controller.abort(new LLMTimeoutError(this.requestTimeoutMs));
+            }, this.requestTimeoutMs)
+            : undefined;
+        timer?.unref?.();
+        return {
+            signal: controller.signal,
+            get timedOut() {
+                return state.timedOut;
+            },
+            dispose() {
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                signal?.removeEventListener("abort", forward);
+            },
+        };
+    }
+}
+function isRetryable(error) {
+    if (error instanceof LLMTimeoutError) {
+        return true;
+    }
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    if ("status" in error && typeof error.status === "number") {
+        return (RETRYABLE_STATUS_CODES.has(error.status) ||
+            (error.status >= 500 && error.status <= 599));
+    }
+    if ("code" in error && typeof error.code === "string") {
+        return RETRYABLE_ERROR_CODES.has(error.code);
+    }
+    return ("name" in error &&
+        (error.name === "APIConnectionError" ||
+            error.name === "APIConnectionTimeoutError"));
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        return `${error.name}: ${error.message}`;
+    }
+    return "Unknown Provider error";
+}
+function throwIfAborted(signal) {
+    if (signal !== undefined && signal.aborted) {
+        throw new LLMAbortError();
+    }
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive safe integer.`);
+    }
+    return value;
+}
+function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new LLMAbortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

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

package/dist/session-store.d.ts

@@ -0,0 +1,66 @@
+import type { AgentEvent } from "./events.js";
+import type { Message } from "./messages.js";
+export declare const SESSION_FORMAT_VERSION = 1;
+export interface SessionHeader {
+    readonly type: "session";
+    readonly version: number;
+    readonly id: string;
+    readonly timestamp: string;
+    readonly cwd: string;
+}
+/**
+ * One JSONL line. The header comes first, then the run events. `message_update`
+ * deltas are not persisted: they are reconstructible from `message_end`, and
+ * keeping them would make a session file grow with every token.
+ */
+export type SessionRecord = SessionHeader | AgentEvent;
+export interface SessionTranscript {
+    readonly header: SessionHeader;
+    readonly messages: readonly Message[];
+    readonly prompts: readonly string[];
+}
+export interface SessionSummary {
+    readonly id: string;
+    readonly cwd: string;
+    readonly timestamp: string;
+    readonly updatedAt: string;
+    readonly promptCount: number;
+    readonly lastPrompt?: string;
+}
+export interface SessionListOptions {
+    /** Keep only sessions recorded for this workspace. */
+    readonly cwd?: string;
+    readonly limit?: number;
+}
+export interface SessionStore {
+    append(id: string, record: SessionRecord): Promise<void>;
+    read(id: string): Promise<SessionTranscript | undefined>;
+    list(options?: SessionListOptions): Promise<readonly SessionSummary[]>;
+    location(id: string): string;
+    /** Resolves once every queued append has settled. */
+    flush?(): Promise<void>;
+}
+export declare function defaultSessionHome(environment?: NodeJS.ProcessEnv): string;
+export declare function createSessionId(now?: Date): string;
+/**
+ * Appends session records as JSON lines under `<home>/sessions/<id>.jsonl`.
+ * Writes are serialised per session so events keep their emission order.
+ */
+export declare class FileSessionStore implements SessionStore {
+    private readonly directory;
+    private pendingWrites;
+    constructor(home?: string);
+    location(id: string): string;
+    append(id: string, record: SessionRecord): Promise<void>;
+    flush(): Promise<void>;
+    read(id: string): Promise<SessionTranscript | undefined>;
+    list(options?: SessionListOptions): Promise<readonly SessionSummary[]>;
+    private summarise;
+}
+/**
+ * Rebuilds a transcript from a session file. The authoritative message list is
+ * the one carried by the last `agent_end`, so a partially written file degrades
+ * to the last completed run instead of failing to load.
+ */
+export declare function parseTranscript(contents: string): SessionTranscript | undefined;
+//# sourceMappingURL=session-store.d.ts.map

package/dist/session-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAMxC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,UAAU,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IACzD,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CAAC;IACvE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,qDAAqD;IACrD,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAChC,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,MAAM,CAKR;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,IAAiB,GAAG,MAAM,CAG9D;AAED;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,aAAa,CAAoC;IAEzD,YAAY,IAAI,GAAE,MAA6B,EAE9C;IAED,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3B;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAavD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3B;IAEK,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAW7D;IAEK,IAAI,CACR,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC,CA6BpC;YAEa,SAAS;CA0BxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,GACf,iBAAiB,GAAG,SAAS,CAiC/B"}