@hmharness/kernel 0.1.0

package/dist/mcp.js

@@ -0,0 +1,282 @@
+/**
+ * @hmharness/kernel - mcp
+ * A zero-dependency MCP (Model Context Protocol) client: JSON-RPC 2.0 over
+ * stdio (spawned server process) or Streamable HTTP (POST + SSE response).
+ * Remote tools are projected onto the same Tool shape as native ones, so the
+ * registry and loop never know where a capability came from. Borrowing the
+ * 5800+-server ecosystem instead of rebuilding it is the whole point.
+ */
+import { spawn } from 'node:child_process';
+const PROTOCOL_VERSION = '2025-06-18';
+const CLIENT_INFO = { name: 'hmharness', version: '0.1.0' };
+/** Call-local incremental id; the wire only needs uniqueness per session. */
+function nextId() {
+    nextId.n = (nextId.n ?? 0) + 1;
+    return nextId.n;
+}
+(function (nextId) {
+})(nextId || (nextId = {}));
+export class McpClient {
+    serverName;
+    config;
+    proc = null;
+    sessionId = null;
+    buffer = '';
+    stderrTail = '';
+    pending = new Map();
+    ready = false;
+    constructor(serverName, config) {
+        this.serverName = serverName;
+        this.config = config;
+    }
+    /** initialize handshake. Must be called exactly once before use. */
+    async connect(timeoutMs = 15_000) {
+        if (this.config.type === 'stdio')
+            this.spawnStdio();
+        await this.request('initialize', {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: CLIENT_INFO,
+        }, timeoutMs).then((r) => {
+            if (r.error)
+                throw new Error(`mcp/${this.serverName}: initialize failed: ${r.error.message}`);
+        });
+        // initialized is a notification (no id, no response expected)
+        if (this.config.type === 'stdio') {
+            this.proc?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+        }
+        else {
+            await this.notify('notifications/initialized');
+        }
+        this.ready = true;
+    }
+    /** Fire-and-forget notification over HTTP (server answers 202). */
+    async notify(method) {
+        const cfg = this.config;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            ...cfg.headers,
+        };
+        if (this.sessionId)
+            headers['Mcp-Session-Id'] = this.sessionId;
+        await fetch(cfg.url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ jsonrpc: '2.0', method }),
+        }).catch(() => undefined);
+    }
+    spawnStdio() {
+        const cfg = this.config;
+        // Allowlist, not passthrough: a spawned MCP server is third-party code;
+        // it must not inherit HMH_* keys or anything else not explicitly needed.
+        const SAFE_ENV = ['PATH', 'SYSTEMROOT', 'COMSPEC', 'TEMP', 'TMP', 'HOMEDRIVE', 'HOMEPATH', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'LANG', 'LC_ALL', 'TERM', 'NUMBER_OF_PROCESSORS'];
+        const env = {};
+        for (const k of SAFE_ENV) {
+            const v = process.env[k];
+            if (v !== undefined)
+                env[k] = v;
+        }
+        this.proc = spawn(cfg.command, cfg.args ?? [], {
+            env: { ...env, ...cfg.env },
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.proc.stdout.setEncoding('utf8');
+        this.proc.stdout.on('data', (chunk) => this.onStdioChunk(chunk));
+        this.proc.on('error', (err) => {
+            // spawn failure (ENOENT etc.) - fail all in-flight requests loudly
+            const e = new Error(`mcp/${this.serverName}: failed to start server: ${String(err)}`);
+            for (const p of this.pending.values())
+                p.reject(e);
+            this.pending.clear();
+        });
+        this.proc.on('exit', (code) => {
+            const detail = this.stderrTail.trim().slice(-300);
+            const err = new Error(`mcp/${this.serverName}: server exited (code ${code})${detail ? `: ${detail}` : ''}`);
+            for (const p of this.pending.values())
+                p.reject(err);
+            this.pending.clear();
+        });
+        this.proc.stderr.setEncoding('utf8');
+        // MCP servers are chatty on stderr by design (logging); keep only the
+        // tail so a crash can be diagnosed without spamming the console.
+        this.proc.stderr.on('data', (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk).slice(-500);
+        });
+    }
+    onStdioChunk(chunk) {
+        this.buffer += chunk;
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.slice(0, nl).trim();
+            this.buffer = this.buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                this.onMessage(JSON.parse(line));
+            }
+            catch {
+                /* non-JSON noise on stdout - ignore */
+            }
+        }
+    }
+    onMessage(msg) {
+        const id = typeof msg.id === 'number' ? msg.id : Number(msg.id);
+        const p = this.pending.get(id);
+        if (p) {
+            this.pending.delete(id);
+            p.resolve(msg);
+        }
+        // server-initiated requests/notifications are not needed yet - ignored.
+    }
+    /** One JSON-RPC round trip over whichever transport this server uses. */
+    async request(method, params, timeoutMs) {
+        const id = nextId();
+        const payload = { jsonrpc: '2.0', id, method, ...(params !== undefined ? { params } : {}) };
+        if (this.config.type === 'stdio') {
+            if (!this.proc?.stdin?.writable)
+                throw new Error(`mcp/${this.serverName}: server not connected`);
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    this.pending.delete(id);
+                    reject(new Error(`mcp/${this.serverName}: "${method}" timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+                this.pending.set(id, {
+                    resolve: (r) => { clearTimeout(timer); resolve(r); },
+                    reject: (e) => { clearTimeout(timer); reject(e); },
+                });
+                this.proc.stdin.write(JSON.stringify(payload) + '\n');
+            });
+        }
+        // Streamable HTTP: single POST; response is JSON or an SSE stream of one message.
+        const cfg = this.config;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            ...cfg.headers,
+        };
+        if (this.sessionId)
+            headers['Mcp-Session-Id'] = this.sessionId;
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            const res = await fetch(cfg.url, { method: 'POST', headers, body: JSON.stringify(payload), signal: ctrl.signal });
+            const sid = res.headers.get('mcp-session-id');
+            if (sid)
+                this.sessionId = sid;
+            if (!res.ok)
+                throw new Error(`mcp/${this.serverName}: HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
+            const ctype = res.headers.get('content-type') ?? '';
+            let body;
+            if (ctype.includes('text/event-stream')) {
+                body = await this.firstSseMessage(res);
+            }
+            else {
+                body = await res.json();
+            }
+            return body;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Read an SSE body up to the first `data:` JSON message, then stop. */
+    async firstSseMessage(res) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buf += decoder.decode(value, { stream: true });
+                let nl;
+                while ((nl = buf.indexOf('\n')) >= 0) {
+                    const line = buf.slice(0, nl).trim();
+                    buf = buf.slice(nl + 1);
+                    if (line.startsWith('data:')) {
+                        const data = line.slice(5).trim();
+                        if (data && data !== '[DONE]') {
+                            await reader.cancel().catch(() => undefined);
+                            return JSON.parse(data);
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        throw new Error(`mcp/${this.serverName}: SSE stream ended without a message`);
+    }
+    async listTools() {
+        if (!this.ready)
+            throw new Error(`mcp/${this.serverName}: not connected`);
+        const r = await this.request('tools/list', {}, 20_000);
+        if (r.error)
+            throw new Error(`mcp/${this.serverName}: tools/list failed: ${r.error.message}`);
+        const tools = r.result.tools ?? [];
+        return tools;
+    }
+    async callTool(name, args, timeoutMs = 60_000) {
+        const r = await this.request('tools/call', { name, arguments: args }, timeoutMs);
+        if (r.error)
+            return { output: `mcp/${this.serverName}: call failed: ${r.error.message}`, isError: true };
+        const res = r.result;
+        const text = (res.content ?? [])
+            .filter((c) => c.type === 'text' && typeof c.text === 'string')
+            .map((c) => c.text)
+            .join('\n');
+        const output = text || (res.structuredContent ? JSON.stringify(res.structuredContent) : '(empty result)');
+        return { output: output.length > 60_000 ? output.slice(0, 60_000) + '\n...[truncated]' : output, isError: res.isError === true };
+    }
+    close() {
+        for (const p of this.pending.values())
+            p.reject(new Error(`mcp/${this.serverName}: closed`));
+        this.pending.clear();
+        this.proc?.kill();
+        this.proc = null;
+    }
+}
+/** OpenAI function-name charset; MCP allows dots/dashes which it forbids. */
+export function sanitizeToolName(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+/**
+ * Connect + list + project. Separate from projectMcpTools so callers can
+ * distinguish "server down" from "server has no tools".
+ */
+export async function mcpServerTools(serverName, config) {
+    const client = new McpClient(serverName, config);
+    await client.connect();
+    const remote = await client.listTools();
+    const trusted = 'trusted' in config && config.trusted === true;
+    const tools = remote.map((t) => {
+        const localName = `mcp_${sanitizeToolName(serverName)}_${sanitizeToolName(t.name)}`.slice(0, 60);
+        const remoteName = t.name;
+        return {
+            name: localName,
+            description: `[mcp:${serverName}] ${t.description ?? t.name}`.slice(0, 400),
+            parameters: normalizeSchema(t.inputSchema),
+            needsApproval: trusted ? undefined : () => true,
+            async execute(args) {
+                return client.callTool(remoteName, args);
+            },
+        };
+    });
+    return { client, tools };
+}
+/** MCP inputSchema is already JSON-Schema; coerce loosely, never throw. */
+function normalizeSchema(schema) {
+    if (schema && typeof schema === 'object') {
+        const s = schema;
+        return {
+            type: s.type ?? 'object',
+            ...(s.properties ? { properties: s.properties } : {}),
+            ...(s.required ? { required: s.required } : {}),
+        };
+    }
+    return { type: 'object' };
+}

package/dist/provider.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @hmharness/kernel - provider
+ * OpenAI-compatible chat adapter. Works with any /v1/chat/completions
+ * endpoint: zhipu GLM, OpenAI, OpenRouter, NVIDIA NIM, vLLM, Ollama, ...
+ * Streaming (SSE) activates when onDelta is provided; reasoning deltas are
+ * surfaced separately so frontends can show the model thinking. One retry on
+ * transient 429/5xx before the stream starts; mid-stream failures surface.
+ */
+import type { ChatMessage, ProviderConfig } from './types.ts';
+export interface ChatResponse {
+    message: ChatMessage;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    };
+}
+export type DeltaKind = 'text' | 'reasoning';
+export interface ChatOptions {
+    timeoutMs?: number;
+    /** Streaming callback; presence switches the request to stream:true. */
+    onDelta?(kind: DeltaKind, chunk: string): void;
+}
+export declare function chat(cfg: ProviderConfig, messages: ChatMessage[], tools?: unknown[], opts?: ChatOptions): Promise<ChatResponse>;
+/**
+ * Single multimodal call: text prompt + one image (data URL). Used by the
+ * see_image tool; deliberately separate from chat() so the streaming path
+ * stays boring. Non-streaming, one retry, hard timeout.
+ */
+export declare function chatVision(cfg: ProviderConfig, prompt: string, imageDataUrl: string, opts?: {
+    timeoutMs?: number;
+    maxTokens?: number;
+}): Promise<string>;

package/dist/provider.js

@@ -0,0 +1,237 @@
+export async function chat(cfg, messages, tools, opts = {}) {
+    const streaming = typeof opts.onDelta === 'function';
+    const body = { model: cfg.model, messages };
+    if (tools && tools.length > 0)
+        body.tools = tools;
+    if (streaming) {
+        body.stream = true;
+        body.stream_options = { include_usage: true };
+    }
+    // auth scheme: standard Bearer, or a custom header (some gateways such as
+    // freellmapi only accept X-Api-Key). If Bearer gets a 401 we silently
+    // renegotiate once with X-Api-Key - misconfigured gateways then just work.
+    const mkHeaders = (scheme) => scheme === 'bearer'
+        ? { 'Content-Type': 'application/json', Authorization: `Bearer ${cfg.apiKey}` }
+        : { 'Content-Type': 'application/json', [typeof scheme === 'string' ? scheme : 'X-Api-Key']: cfg.apiKey };
+    let authScheme = cfg.authHeader ?? 'bearer';
+    let lastError = '';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 120_000);
+        try {
+            const res = await fetch(endpoint(cfg.baseUrl), {
+                method: 'POST',
+                headers: mkHeaders(authScheme),
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+            });
+            if (res.status === 429 || res.status >= 500) {
+                lastError = `HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`;
+                await sleep(1500 * (attempt + 1));
+                continue;
+            }
+            if (res.status === 401 && !cfg.authHeader && authScheme === 'bearer' && cfg.apiKey) {
+                // gateway rejected Bearer - try the other common scheme once
+                authScheme = 'X-Api-Key';
+                lastError = 'renegotiating auth: Bearer rejected, retrying with X-Api-Key';
+                attempt--;
+                continue;
+            }
+            if (!res.ok) {
+                throw new Error(`provider: HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+            }
+            if (streaming) {
+                clearTimeout(timer);
+                return await consumeStream(res, opts.onDelta);
+            }
+            const data = (await res.json());
+            const choice = data.choices?.[0];
+            if (!choice)
+                throw new Error('provider: response had no choices');
+            return {
+                message: {
+                    role: 'assistant',
+                    content: choice.message?.content ?? null,
+                    ...(choice.message?.tool_calls ? { tool_calls: choice.message.tool_calls } : {}),
+                },
+                usage: data.usage,
+            };
+        }
+        catch (err) {
+            lastError = String(err);
+            if (!/abort|fetch failed|ECONN|timeout/i.test(lastError))
+                throw err;
+            await sleep(1500 * (attempt + 1));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    throw new Error(`provider: failed after retry (${cfg.baseUrl}): ${lastError}`);
+}
+/** Assemble a ChatResponse from an SSE stream, emitting deltas as they land. */
+async function consumeStream(res, onDelta) {
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    let text = '';
+    let reasoning = '';
+    let usage;
+    // tool_calls accumulate across deltas, keyed by their index in the stream.
+    const calls = new Map();
+    // Idle guard rather than a total cap: generation length is unbounded.
+    const idleCtrl = new AbortController();
+    let idleTimer = setTimeout(() => idleCtrl.abort(), 180_000);
+    const bumpIdle = () => {
+        clearTimeout(idleTimer);
+        idleTimer = setTimeout(() => idleCtrl.abort(), 180_000);
+    };
+    const idlePromise = new Promise((_, reject) => {
+        idleCtrl.signal.addEventListener('abort', () => reject(new Error('provider: stream idle timeout')), { once: true });
+    });
+    const pump = async () => {
+        for (;;) {
+            const { done, value } = await Promise.race([reader.read(), idlePromise]);
+            if (done)
+                return;
+            bumpIdle();
+            buf += decoder.decode(value, { stream: true });
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (!line.startsWith('data:'))
+                    continue;
+                const data = line.slice(5).trim();
+                if (!data || data === '[DONE]')
+                    continue;
+                let chunk;
+                try {
+                    chunk = JSON.parse(data);
+                }
+                catch {
+                    continue; // keep-alive comment or malformed line
+                }
+                if (chunk.usage)
+                    usage = chunk.usage;
+                const delta = chunk.choices?.[0]?.delta;
+                if (!delta)
+                    continue;
+                if (typeof delta.reasoning_content === 'string' && delta.reasoning_content) {
+                    reasoning += delta.reasoning_content;
+                    onDelta('reasoning', delta.reasoning_content);
+                }
+                else if (typeof delta.reasoning === 'string' && delta.reasoning) {
+                    reasoning += delta.reasoning;
+                    onDelta('reasoning', delta.reasoning);
+                }
+                if (typeof delta.content === 'string' && delta.content) {
+                    text += delta.content;
+                    onDelta('text', delta.content);
+                }
+                if (Array.isArray(delta.tool_calls)) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index ?? 0;
+                        const cur = calls.get(idx) ?? { id: '', type: 'function', function: { name: '', arguments: '' } };
+                        if (tc.id)
+                            cur.id = tc.id;
+                        if (tc.function?.name)
+                            cur.function.name += tc.function.name;
+                        if (tc.function?.arguments)
+                            cur.function.arguments += tc.function.arguments;
+                        calls.set(idx, cur);
+                    }
+                }
+            }
+        }
+    };
+    try {
+        await pump();
+    }
+    finally {
+        clearTimeout(idleTimer);
+        reader.releaseLock();
+    }
+    const ordered = [...calls.entries()].sort((a, b) => a[0] - b[0]).map(([, c]) => c);
+    return {
+        message: {
+            role: 'assistant',
+            content: text || null,
+            ...(ordered.length > 0 ? { tool_calls: ordered } : {}),
+        },
+        usage,
+    };
+}
+/** Accept bases both with and without the /v1 suffix. */
+function endpoint(baseUrl) {
+    const b = baseUrl.replace(/\/+$/, '');
+    return b.endsWith('/v1') ? `${b}/chat/completions` : `${b}/v1/chat/completions`;
+}
+/**
+ * Single multimodal call: text prompt + one image (data URL). Used by the
+ * see_image tool; deliberately separate from chat() so the streaming path
+ * stays boring. Non-streaming, one retry, hard timeout.
+ */
+export async function chatVision(cfg, prompt, imageDataUrl, opts = {}) {
+    const body = {
+        model: cfg.model,
+        max_tokens: opts.maxTokens ?? 800,
+        messages: [
+            {
+                role: 'user',
+                content: [
+                    { type: 'text', text: prompt },
+                    { type: 'image_url', image_url: { url: imageDataUrl } },
+                ],
+            },
+        ],
+    };
+    let lastError = '';
+    // same auth negotiation as chat(): explicit header, Bearer, then X-Api-Key
+    let vAuth = cfg.authHeader ?? 'bearer';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 120_000);
+        try {
+            const vHeaders = vAuth === 'bearer'
+                ? { 'Content-Type': 'application/json', Authorization: `Bearer ${cfg.apiKey}` }
+                : { 'Content-Type': 'application/json', [vAuth]: cfg.apiKey };
+            const res = await fetch(endpoint(cfg.baseUrl), {
+                method: 'POST',
+                headers: vHeaders,
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+            });
+            if (res.status === 401 && !cfg.authHeader && vAuth === 'bearer' && cfg.apiKey) {
+                vAuth = 'X-Api-Key';
+                attempt--;
+                continue;
+            }
+            if (res.status === 429 || res.status >= 500) {
+                lastError = `HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`;
+                await sleep(1500 * (attempt + 1));
+                continue;
+            }
+            if (!res.ok)
+                throw new Error(`provider: HTTP ${res.status}: ${(await res.text()).slice(0, 300)}`);
+            const data = (await res.json());
+            const text = data.choices?.[0]?.message?.content;
+            if (typeof text !== 'string')
+                throw new Error('provider: vision response had no content');
+            return text;
+        }
+        catch (err) {
+            lastError = String(err);
+            if (!/abort|fetch failed|ECONN|timeout/i.test(lastError))
+                throw err;
+            await sleep(1500 * (attempt + 1));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    throw new Error(`provider: vision call failed after retry (${cfg.baseUrl}): ${lastError}`);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @hmharness/kernel - registry
+ * The capability registry. One Map, duplicate-name rejection, OpenAI shape
+ * projection. Boring on purpose: 2026 consensus is that the loop+registry
+ * core should stay simple while capability volume grows around it.
+ */
+import type { Tool } from './types.ts';
+export declare class Registry {
+    #private;
+    register(tool: Tool): this;
+    registerAll(tools: Tool[]): this;
+    get(name: string): Tool | undefined;
+    names(): string[];
+    list(): Tool[];
+    /** Project into the OpenAI chat.completions `tools` array. */
+    toOpenAITools(): Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: unknown;
+        };
+    }>;
+}

package/dist/registry.js

@@ -0,0 +1,31 @@
+export class Registry {
+    #tools = new Map();
+    register(tool) {
+        if (this.#tools.has(tool.name)) {
+            throw new Error(`kernel/registry: duplicate tool name "${tool.name}"`);
+        }
+        this.#tools.set(tool.name, tool);
+        return this;
+    }
+    registerAll(tools) {
+        for (const t of tools)
+            this.register(t);
+        return this;
+    }
+    get(name) {
+        return this.#tools.get(name);
+    }
+    names() {
+        return [...this.#tools.keys()];
+    }
+    list() {
+        return [...this.#tools.values()];
+    }
+    /** Project into the OpenAI chat.completions `tools` array. */
+    toOpenAITools() {
+        return this.list().map((t) => ({
+            type: 'function',
+            function: { name: t.name, description: t.description, parameters: t.parameters },
+        }));
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,61 @@
+import type { ChatMessage } from './types.ts';
+export type SessionEvent = {
+    t: 'session/start';
+    id: string;
+    time: string;
+    cwd: string;
+    model: string;
+} | {
+    t: 'user';
+    time: string;
+    text: string;
+} | {
+    t: 'assistant';
+    time: string;
+    text: string | null;
+    tool_calls?: unknown[];
+} | {
+    t: 'tool';
+    time: string;
+    name: string;
+    output: string;
+    isError: boolean;
+} | {
+    t: 'approval';
+    time: string;
+    tool: string;
+    granted: boolean;
+} | {
+    t: 'final';
+    time: string;
+    text: string;
+    turns: number;
+    toolUses: number;
+};
+export declare class Session {
+    readonly id: string;
+    readonly file: string;
+    /** Append chain: events serialize in call order, even fire-and-forget ones. */
+    private tail;
+    constructor(home: string, cwd: string, model: string);
+    append(event: SessionEvent): Promise<void>;
+    user(text: string): Promise<void>;
+    assistant(text: string | null, toolCalls?: unknown[]): Promise<void>;
+    tool(name: string, output: string, isError: boolean): Promise<void>;
+    approval(tool: string, granted: boolean): Promise<void>;
+    final(text: string, turns: number, toolUses: number): Promise<void>;
+}
+export interface SessionTranscript {
+    id: string;
+    model: string;
+    cwd: string;
+    messages: ChatMessage[];
+}
+/** Find the newest session file under home/sessions matching an id prefix. */
+export declare function latestSession(home: string, prefix?: string): Promise<string | null>;
+/**
+ * Rebuild a chat transcript from a session log. Tool events don't record
+ * tool_call_id, but the loop executes calls sequentially, so ids pair with
+ * the tool events that follow their assistant message in order.
+ */
+export declare function loadTranscript(file: string): Promise<SessionTranscript | null>;