@netnodeag/kraftwerk 0.4.0 → 0.6.0

package/dist/inspector/chat/acp.js

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
+/**
+ * ACP-backed chat: spawn an adapter (claude-agent-acp / codex-acp) as a
+ * subprocess, speak Agent Client Protocol over its stdio, and translate
+ * session/update notifications into chat events. One subprocess lives for
+ * the whole chat; the ACP session id carries the conversation.
+ *
+ * Auth rides on the local CLI logins (Claude Code / Codex) via the
+ * inherited environment — same story as the kraftwerk harnesses.
+ */
+const ADAPTERS = {
+    claude: "@agentclientprotocol/claude-agent-acp/dist/index.js",
+    codex: "@agentclientprotocol/codex-acp/dist/index.js",
+};
+/** Effort tier -> Claude thinking budget (the adapter reads MAX_THINKING_TOKENS). */
+const CLAUDE_THINKING_BUDGET = {
+    low: 2048,
+    medium: 8192,
+    high: 16384,
+    xhigh: 32000,
+    max: 63999,
+};
+/**
+ * Model/effort overrides ride on adapter-specific channels: the claude
+ * adapter takes the model via session `_meta.claudeCode.options` and the
+ * thinking budget via env; codex-acp merges a CODEX_CONFIG env JSON into
+ * the session config it hands to `codex app-server`.
+ */
+function tuningEnv(agent, tuning) {
+    const env = { ...process.env };
+    if (agent === "claude" && tuning.effort && CLAUDE_THINKING_BUDGET[tuning.effort]) {
+        env.MAX_THINKING_TOKENS = String(CLAUDE_THINKING_BUDGET[tuning.effort]);
+    }
+    if (agent === "codex" && (tuning.model || tuning.effort)) {
+        env.CODEX_CONFIG = JSON.stringify({
+            ...(tuning.model ? { model: tuning.model } : {}),
+            ...(tuning.effort ? { model_reasoning_effort: tuning.effort } : {}),
+        });
+    }
+    return env;
+}
+function contentText(content) {
+    return content.type === "text" ? content.text : "";
+}
+export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
+    const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
+    const child = spawn(process.execPath, [entry], {
+        cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+        env: tuningEnv(agent, tuning),
+    });
+    let stderr = "";
+    child.stderr.on("data", (c) => {
+        stderr += c.toString("utf8");
+        if (stderr.length > 20_000)
+            stderr = stderr.slice(-20_000);
+    });
+    let dead = false;
+    child.on("close", (code) => {
+        dead = true;
+        if (code !== 0 && code !== null) {
+            hooks.emit({
+                type: "error",
+                message: `${agent} agent exited (code ${code})${stderr.trim() ? `: ${stderr.trim().slice(-500)}` : ""}`,
+            });
+        }
+    });
+    const client = {
+        sessionUpdate(params) {
+            const u = params.update;
+            switch (u.sessionUpdate) {
+                case "agent_message_chunk": {
+                    const text = contentText(u.content);
+                    if (text)
+                        hooks.emit({ type: "text", text });
+                    break;
+                }
+                case "agent_thought_chunk": {
+                    const text = contentText(u.content);
+                    if (text)
+                        hooks.emit({ type: "thought", text });
+                    break;
+                }
+                case "tool_call":
+                    hooks.emit({
+                        type: "tool_call",
+                        callId: u.toolCallId,
+                        title: u.title,
+                        kind: u.kind ?? undefined,
+                        status: u.status ?? undefined,
+                    });
+                    break;
+                case "tool_call_update":
+                    hooks.emit({
+                        type: "tool_update",
+                        callId: u.toolCallId,
+                        title: u.title ?? undefined,
+                        status: u.status ?? undefined,
+                    });
+                    break;
+                // plans, mode/config updates etc. carry no thread content — skip.
+            }
+        },
+        async requestPermission(params) {
+            const optionId = await hooks.askPermission(params.toolCall.title ?? params.toolCall.toolCallId, params.options.map((o) => ({ optionId: o.optionId, name: o.name, kind: o.kind })));
+            return optionId
+                ? { outcome: { outcome: "selected", optionId } }
+                : { outcome: { outcome: "cancelled" } };
+        },
+    };
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+    const conn = new ClientSideConnection(() => client, stream);
+    await conn.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+        clientInfo: { name: "kraftwerk-inspector", version: "1.0.0" },
+    });
+    const session = await conn.newSession({
+        cwd,
+        mcpServers: [],
+        ...(agent === "claude" && tuning.model
+            ? { _meta: { claudeCode: { options: { model: tuning.model } } } }
+            : {}),
+    });
+    const sessionId = session.sessionId;
+    return {
+        async prompt(text) {
+            if (dead)
+                throw new Error(`${agent} agent process is gone — start a new chat`);
+            try {
+                const res = await conn.prompt({
+                    sessionId,
+                    prompt: [{ type: "text", text }],
+                });
+                return res.stopReason;
+            }
+            catch (err) {
+                if (err instanceof RequestError)
+                    throw new Error(`${agent} agent: ${err.message}`);
+                throw err;
+            }
+        },
+        cancel() {
+            if (!dead)
+                void conn.cancel({ sessionId }).catch(() => { });
+        },
+        dispose() {
+            if (!dead)
+                child.kill("SIGTERM");
+        },
+    };
+}

package/dist/inspector/chat/backend.d.ts

@@ -0,0 +1,36 @@
+import type { ChatEvent } from "./types.js";
+/**
+ * A chat backend is one live agent conversation: prompt() runs a full turn
+ * (resolves when the agent finishes), streaming intermediate activity
+ * through the hooks. ACP agents (claude, codex) keep a subprocess alive for
+ * the whole chat; pi respawns per message and resumes via --session-id.
+ */
+export interface BackendHooks {
+    /** Stream a thread event (text chunk, tool call, ...) to the session. */
+    emit(ev: ChatEvent): void;
+    /**
+     * Surface a permission request to the user; resolves with the chosen
+     * optionId, or null when the user (or a cancel) dismissed it.
+     */
+    askPermission(title: string, options: Array<{
+        optionId: string;
+        name: string;
+        kind?: string;
+    }>): Promise<string | null>;
+}
+/**
+ * Optional per-chat model/effort overrides (from a team member definition).
+ * Each backend maps them onto whatever its agent actually supports.
+ */
+export interface BackendTuning {
+    model?: string;
+    effort?: string;
+}
+export interface ChatBackend {
+    /** Send one user message; resolves with the stop reason at turn end. */
+    prompt(text: string): Promise<string>;
+    /** Interrupt the current turn (the running prompt() still resolves). */
+    cancel(): void;
+    /** Kill the agent subprocess, if any. */
+    dispose(): void;
+}

package/dist/inspector/chat/backend.js

@@ -0,0 +1 @@
+export {};

package/dist/inspector/chat/pi.d.ts

@@ -0,0 +1,2 @@
+import type { BackendHooks, BackendTuning, ChatBackend } from "./backend.js";
+export declare function startPiBackend(cwd: string, hooks: BackendHooks, tuning?: BackendTuning): ChatBackend;

package/dist/inspector/chat/pi.js

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+const clip = (raw) => {
+    const oneLine = String(raw ?? "").replace(/\s+/g, " ").trim();
+    return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
+};
+export function startPiBackend(cwd, hooks, tuning = {}) {
+    const sessionId = randomUUID();
+    let child = null;
+    let cancelled = false;
+    const tuningArgs = [
+        ...(tuning.model ? ["--model", tuning.model] : []),
+        ...(tuning.effort ? ["--thinking", tuning.effort] : []),
+    ];
+    return {
+        prompt(text) {
+            cancelled = false;
+            return new Promise((resolve, reject) => {
+                const proc = spawn("pi", ["-p", "--mode", "json", "--session-id", sessionId, ...tuningArgs], {
+                    cwd,
+                    stdio: ["pipe", "pipe", "pipe"],
+                    env: process.env,
+                });
+                child = proc;
+                proc.stdin.write(text);
+                proc.stdin.end();
+                let sawAssistant = false;
+                let failure;
+                let stderr = "";
+                let buffer = "";
+                let toolSeq = 0;
+                const handleLine = (line) => {
+                    if (!line.trim())
+                        return;
+                    let event;
+                    try {
+                        event = JSON.parse(line);
+                    }
+                    catch {
+                        return; // non-JSON noise on stdout
+                    }
+                    if (event.type === "tool_execution_start" && event.toolName) {
+                        const a = event.args ?? {};
+                        const target = clip(a.path ?? a.file_path ?? a.command ?? a.pattern ?? "");
+                        hooks.emit({
+                            type: "tool_call",
+                            callId: `pi-${sessionId}-${toolSeq++}`,
+                            title: target ? `${event.toolName} ${target}` : event.toolName,
+                            status: "completed",
+                        });
+                    }
+                    if (event.type === "message_end" && event.message?.role === "assistant") {
+                        sawAssistant = true;
+                        for (const block of event.message.content ?? []) {
+                            if (block?.type === "text" && block.text?.trim()) {
+                                hooks.emit({ type: "text", text: block.text });
+                            }
+                            if (block?.type === "thinking" && block.text?.trim()) {
+                                hooks.emit({ type: "thought", text: block.text });
+                            }
+                        }
+                    }
+                    if (event.type === "error") {
+                        failure = typeof event.error === "string" ? event.error : line;
+                    }
+                    // API failures don't exit non-zero: they ride on turn_end as
+                    // stopReason "error" with an empty assistant message.
+                    if (event.type === "turn_end" && event.message?.stopReason === "error") {
+                        failure = clip(event.message.errorMessage ?? "unknown pi error");
+                    }
+                };
+                proc.stdout.on("data", (chunk) => {
+                    buffer += chunk.toString("utf8");
+                    const lines = buffer.split("\n");
+                    buffer = lines.pop() ?? "";
+                    lines.forEach(handleLine);
+                });
+                proc.stderr.on("data", (chunk) => {
+                    stderr += chunk.toString("utf8");
+                });
+                proc.on("error", (err) => reject(new Error(`could not spawn pi: ${err.message}`)));
+                proc.on("close", (code) => {
+                    child = null;
+                    handleLine(buffer);
+                    if (cancelled)
+                        return resolve("cancelled");
+                    if (failure || code !== 0 || !sawAssistant) {
+                        reject(new Error(`pi failed (exit ${code})` +
+                            (failure ? `: ${failure}` : "") +
+                            (stderr.trim() ? `\nstderr: ${stderr.trim().slice(-1000)}` : "")));
+                        return;
+                    }
+                    resolve("end_turn");
+                });
+            });
+        },
+        cancel() {
+            cancelled = true;
+            child?.kill("SIGTERM");
+        },
+        dispose() {
+            child?.kill("SIGTERM");
+        },
+    };
+}

package/dist/inspector/chat/sessions.d.ts

@@ -0,0 +1,29 @@
+import type { ChatAgentId, ChatMeta, ChatScope, StoredChatEvent } from "./types.js";
+export declare function createChat(opts: {
+    agent: ChatAgentId;
+    scope: ChatScope;
+    /** Preset title (e.g. routine runs); otherwise the first message names the chat. */
+    title?: string;
+}): Promise<ChatMeta>;
+export declare function listChats(): Promise<Array<ChatMeta & {
+    busy: boolean;
+}>>;
+export declare function getChat(id: string): Promise<{
+    meta: ChatMeta;
+    events: StoredChatEvent[];
+    busy: boolean;
+} | null>;
+export declare function postMessage(id: string, text: string): Promise<{
+    error?: string;
+}>;
+export declare function resolvePermission(id: string, requestId: string, optionId: string | null): Promise<{
+    error?: string;
+}>;
+export declare function cancelChat(id: string): Promise<{
+    error?: string;
+}>;
+/**
+ * SSE subscription: replays events after `afterSeq`, then streams new ones.
+ * Returns an unsubscribe function.
+ */
+export declare function subscribeChat(id: string, afterSeq: number, fn: (ev: StoredChatEvent) => void): Promise<(() => void) | null>;

package/dist/inspector/chat/sessions.js

@@ -0,0 +1,316 @@
+import { randomUUID } from "node:crypto";
+import { getOutputDir, getProjectRoot } from "../context.js";
+import { knowledgeIndex } from "../knowledge.js";
+import { getRun, listRuns, safeRunDir } from "../runs.js";
+import { listWorkflows } from "../workflows.js";
+import { getMember } from "../team.js";
+import { startAcpBackend } from "./acp.js";
+import { startPiBackend } from "./pi.js";
+import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, writeMeta } from "./store.js";
+const states = new Map();
+async function loadState(id) {
+    const existing = states.get(id);
+    if (existing)
+        return existing;
+    const meta = await readMeta(id);
+    if (!meta)
+        return null;
+    const state = {
+        meta,
+        events: await readEvents(id),
+        subscribers: new Set(),
+        backend: null,
+        busy: false,
+        pendingPermissions: new Map(),
+        writeChain: Promise.resolve(),
+    };
+    // Two racing loads: keep whichever registered first.
+    return states.get(id) ?? (states.set(id, state), state);
+}
+function emit(state, ev) {
+    const stored = {
+        ...ev,
+        seq: (state.events[state.events.length - 1]?.seq ?? 0) + 1,
+        ts: new Date().toISOString(),
+    };
+    state.events.push(stored);
+    state.meta.updatedAt = stored.ts;
+    state.writeChain = state.writeChain
+        .then(() => appendEvent(state.meta.id, stored))
+        .catch(() => { });
+    for (const fn of state.subscribers)
+        fn(stored);
+    return stored;
+}
+/* ---------- scope context ---------- */
+/** "## Your knowledge" block for a team member's connected OKF bundles. */
+async function teamKnowledgeContext(member) {
+    if (member.knowledge.length === 0)
+        return "";
+    const { bundles } = await knowledgeIndex().catch(() => ({ bundles: [] }));
+    const lines = member.knowledge
+        .map((name) => {
+        const b = bundles.find((x) => x.name === name);
+        return b
+            ? `- ${b.name} (${b.concepts} concepts${b.updatedAt ? `, updated ${b.updatedAt.slice(0, 10)}` : ""})`
+            : `- ${name} (not found in knowledge/ — tell the user if you need it)`;
+    })
+        .join("\n");
+    return (`## Your knowledge\nThese OKF knowledge bundles (markdown + YAML frontmatter under knowledge/) are ` +
+        `part of your job. Consult them before answering questions in their domain, and keep them current ` +
+        `when you learn something durable:\n${lines}\n\n` +
+        `Read with \`npx kraftwerk knowledge list <bundle>\`, \`get <bundle>/<path>\`, \`search <text>\`. ` +
+        `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor ${member.slug}/${member.harness}\` ` +
+        `(write the markdown to a temp file first; the CLI stamps provenance and maintains index.md/log.md). ` +
+        `Never hand-edit index.md or log.md, and never add \`verified\` yourself — verification is the human's ` +
+        `click in the UI.\n\n`);
+}
+async function scopeContext(scope, agent) {
+    if (scope.kind === "team") {
+        const member = await getMember(scope.member).catch(() => null);
+        if (!member) {
+            return `You were opened as team agent "${scope.member}", but its definition under agents/ is missing. Tell the user and ask them to recreate it.`;
+        }
+        const { workflows } = await listWorkflows().catch(() => ({ workflows: [] }));
+        const connected = workflows.filter((w) => member.workflows.includes(w.slug));
+        const missing = member.workflows.filter((slug) => !connected.some((w) => w.slug === slug));
+        const wfLines = connected
+            .map((w) => `- ${w.slug}: ${w.description ?? w.name ?? ""} (${w.steps} steps)`)
+            .join("\n");
+        return (`You are ${member.emoji} ${member.name}, a persistent agent teammate on this project's team ` +
+            `(defined in agents/${member.slug}/). The user works with you like with a colleague: every session ` +
+            `is a conversation with the same ${member.name}, so keep this role consistently. You are an AI agent, ` +
+            `not a human — never pretend otherwise, but do own your role.\n\n` +
+            `## Your role\n${member.system || "(no system prompt written yet — ask the user what your job should be)"}\n\n` +
+            (member.workflows.length > 0
+                ? `## Your workflows\nThese kraftwerk workflows are part of your job. When the user's request matches one, ` +
+                    `run it yourself instead of doing the work by hand:\n${wfLines || "(none found)"}\n` +
+                    (missing.length > 0
+                        ? `(configured but not found in this project: ${missing.join(", ")})\n`
+                        : "") +
+                    `\nRun a workflow with:\n` +
+                    `  KRAFTWERK_YES=1 npx kraftwerk run <workflow> "<request>"\n` +
+                    `The command blocks until the run finishes; artifacts land in output/run-*/ — tell the user the ` +
+                    `run id and summarize the result. Confirm with the user before starting a long or expensive run ` +
+                    `unless they clearly asked for it.\n\n`
+                : "") +
+            (await teamKnowledgeContext(member)) +
+            `The working directory is the project root. Stay within your role; if a request is clearly outside it, ` +
+            `say so and suggest which teammate or tool fits better.` +
+            (scope.routine
+                ? `\n\nThis session was started automatically by your scheduled routine "${scope.routine}" — ` +
+                    `nobody may be watching live. Complete the task autonomously (tool permissions are ` +
+                    `auto-approved) and end with a clear, self-contained summary of what you did and found.`
+                : ""));
+    }
+    if (scope.kind === "knowledge") {
+        const { root, bundles } = await knowledgeIndex().catch(() => ({ root: "", bundles: [] }));
+        const bundleLines = bundles
+            .map((b) => `- ${b.name} (${b.concepts} concepts${b.updatedAt ? `, updated ${b.updatedAt.slice(0, 10)}` : ""})`)
+            .join("\n");
+        return (`You are the knowledge curator inside the kraftwerk inspector ("Context & Knowledge"). ` +
+            `This project keeps knowledge as OKF v0.2 bundles (Open Knowledge Format): directories of markdown ` +
+            `files with YAML frontmatter under ${root || "knowledge/"}. Each direct subdirectory is one bundle; each .md file ` +
+            `(except the reserved index.md and log.md) is one concept.\n\n` +
+            `Existing bundles:\n${bundleLines || "(none yet)"}\n` +
+            (scope.bundle ? `\nThe user wants to work on the "${scope.bundle}" bundle.\n` : "") +
+            `\nOKF essentials:\n` +
+            `- Frontmatter needs exactly one required key: \`type\` (free-form, e.g. Playbook, Metric, Reference, API Endpoint). ` +
+            `Recommended: title, description, tags, resource (canonical URI of the described asset).\n` +
+            `- Provenance/trust families (all optional): \`sources\` (list of { id, resource, title, author, usage_count, last_modified }), ` +
+            `\`generated: { by, at }\`, \`verified: [{ by, at }]\`, \`status\` (draft|stable|deprecated), \`stale_after\` (ISO datetime).\n` +
+            `- Actors: \`<producer>/<version>\` for agents, \`human:<id>\` for people, \`process:<id>\` for automation.\n` +
+            `- Concepts cross-link with normal markdown links, bundle-absolute (\`/path/concept.md\`) preferred. ` +
+            `Per-claim attribution uses markdown footnotes whose label is a \`sources[].id\`.\n` +
+            `- Favor structural markdown (headings, tables, lists) over prose.\n\n` +
+            `ALWAYS write through the kraftwerk CLI so provenance is stamped and the bundle log/index stay maintained:\n` +
+            `- \`npx kraftwerk knowledge init <bundle>\` — new bundle\n` +
+            `- \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor kraftwerk-chat/${agent}\` — create/update a concept ` +
+            `(write the markdown to a temp file first; the CLI stamps generated.by/at, appends log.md, regenerates index.md)\n` +
+            `- \`npx kraftwerk knowledge list [bundle]\`, \`get <bundle>/<path>\`, \`search <text>\`, \`validate\`\n` +
+            `Do not hand-edit index.md or log.md (derived/maintained), and do not add \`verified\` yourself — ` +
+            `verification is the human's click in the UI. Ask the user what knowledge to capture, then author concise, well-typed concepts.`);
+    }
+    if (scope.kind === "kraftwerk") {
+        const [{ workflows }, runs] = await Promise.all([listWorkflows(), listRuns()]);
+        const wfLines = workflows
+            .map((w) => `- ${w.name ?? w.slug}: ${w.description ?? ""} (${w.steps} steps, ${w.agents} agents)`)
+            .join("\n");
+        const runLines = runs
+            .slice(0, 10)
+            .map((r) => `- ${r.id} — ${r.workflow ?? "?"} [${r.status}] ${r.request ?? ""}`.trim())
+            .join("\n");
+        return (`You are the assistant inside the kraftwerk inspector, a UI for a workflow-as-code agent framework. ` +
+            `The consumer project root is ${getProjectRoot()}; run outputs live in ${getOutputDir()} (one run-* folder per run, each with a trace.jsonl and working files).\n\n` +
+            `Workflows in this project:\n${wfLines || "(none)"}\n\nRecent runs:\n${runLines || "(none)"}\n\n` +
+            `Answer questions about workflows and runs by reading these files. Do not modify run outputs unless asked.`);
+    }
+    if (scope.kind === "run") {
+        const run = await getRun(scope.runId);
+        if (!run)
+            return `The user wants to discuss kraftwerk run ${scope.runId}, but it was not found.`;
+        const phases = run.phases
+            .map((p) => `- ${p.phase} [${p.status}]${p.summary ? `: ${p.summary}` : ""}`)
+            .join("\n");
+        const files = run.files.map((f) => `- ${f.name} (${f.size} bytes)`).join("\n");
+        return (`You are the assistant for one kraftwerk workflow run. Your working directory is the run's output folder.\n\n` +
+            `Run ${run.id} — workflow "${run.workflow ?? "?"}", status ${run.status}.\n` +
+            `Request: ${run.request ?? "(none)"}\n\nPhases:\n${phases || "(none)"}\n\nFiles in this folder:\n${files || "(none)"}\n\n` +
+            `trace.jsonl holds the full event log. Read files as needed to answer; do not modify the run's artifacts unless asked.`);
+    }
+    return "";
+}
+/* ---------- backend lifecycle ---------- */
+/** Team chats carry the member's model/effort; resolved live so edits apply to new backends. */
+async function backendTuning(scope) {
+    if (scope.kind !== "team")
+        return {};
+    const member = await getMember(scope.member).catch(() => null);
+    return {
+        ...(member?.model ? { model: member.model } : {}),
+        ...(member?.effort ? { effort: member.effort } : {}),
+    };
+}
+async function ensureBackend(state) {
+    if (state.backend)
+        return state.backend;
+    const hooks = {
+        emit: (ev) => void emit(state, ev),
+        askPermission: (title, options) => {
+            // Routine-triggered sessions run unattended: auto-approve, but keep
+            // the request/resolution pair in the thread as an audit trail.
+            const scope = state.meta.scope;
+            if (scope.kind === "team" && scope.routine) {
+                const allow = options.find((o) => o.kind?.startsWith("allow")) ?? options[0];
+                const requestId = randomUUID();
+                emit(state, { type: "permission_request", requestId, title, options });
+                emit(state, { type: "permission_resolved", requestId, optionId: allow?.optionId ?? null });
+                return Promise.resolve(allow?.optionId ?? null);
+            }
+            return new Promise((resolve) => {
+                const requestId = randomUUID();
+                state.pendingPermissions.set(requestId, (optionId) => {
+                    state.pendingPermissions.delete(requestId);
+                    emit(state, { type: "permission_resolved", requestId, optionId });
+                    resolve(optionId);
+                });
+                emit(state, { type: "permission_request", requestId, title, options });
+            });
+        },
+    };
+    const { agent, cwd } = state.meta;
+    const tuning = await backendTuning(state.meta.scope);
+    state.backend =
+        agent === "pi"
+            ? startPiBackend(cwd, hooks, tuning)
+            : await startAcpBackend(agent, cwd, hooks, tuning);
+    return state.backend;
+}
+/* ---------- public API (used by server.ts) ---------- */
+export async function createChat(opts) {
+    const cwd = opts.scope.kind === "run" ? safeRunDir(opts.scope.runId) : getProjectRoot();
+    const now = new Date().toISOString();
+    const meta = {
+        id: newChatId(),
+        agent: opts.agent,
+        title: opts.title ?? "",
+        cwd,
+        scope: opts.scope,
+        createdAt: now,
+        updatedAt: now,
+    };
+    await writeMeta(meta);
+    states.set(meta.id, {
+        meta,
+        events: [],
+        subscribers: new Set(),
+        backend: null,
+        busy: false,
+        pendingPermissions: new Map(),
+        writeChain: Promise.resolve(),
+    });
+    return meta;
+}
+export async function listChats() {
+    const metas = await listChatMetas();
+    return metas.map((m) => ({
+        ...(states.get(m.id)?.meta ?? m),
+        busy: states.get(m.id)?.busy ?? false,
+    }));
+}
+export async function getChat(id) {
+    const state = await loadState(id);
+    if (!state)
+        return null;
+    return { meta: state.meta, events: state.events, busy: state.busy };
+}
+export async function postMessage(id, text) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    if (state.busy)
+        return { error: "agent is still working — wait for the turn to finish" };
+    state.busy = true;
+    const isFirst = !state.events.some((e) => e.type === "user_message");
+    if (isFirst && !state.meta.title) {
+        state.meta.title = text.replace(/\s+/g, " ").trim().slice(0, 80);
+        void writeMeta(state.meta).catch(() => { });
+    }
+    emit(state, { type: "user_message", text });
+    // The turn runs in the background; the HTTP request returns immediately
+    // and the browser follows along on the SSE stream.
+    void (async () => {
+        try {
+            const backend = await ensureBackend(state);
+            const context = isFirst ? await scopeContext(state.meta.scope, state.meta.agent) : "";
+            const promptText = context ? `<context>\n${context}\n</context>\n\n${text}` : text;
+            const stopReason = await backend.prompt(promptText);
+            emit(state, { type: "turn_end", stopReason });
+        }
+        catch (err) {
+            emit(state, { type: "error", message: err.message });
+            // A failed turn may mean a dead subprocess; drop it so the next
+            // message spawns a fresh agent (thread history stays on disk).
+            state.backend?.dispose();
+            state.backend = null;
+        }
+        finally {
+            state.busy = false;
+            void writeMeta(state.meta).catch(() => { });
+        }
+    })();
+    return {};
+}
+export async function resolvePermission(id, requestId, optionId) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    const resolve = state.pendingPermissions.get(requestId);
+    if (!resolve)
+        return { error: "no such pending permission request" };
+    resolve(optionId);
+    return {};
+}
+export async function cancelChat(id) {
+    const state = await loadState(id);
+    if (!state)
+        return { error: "not found" };
+    for (const resolve of state.pendingPermissions.values())
+        resolve(null);
+    state.backend?.cancel();
+    return {};
+}
+/**
+ * SSE subscription: replays events after `afterSeq`, then streams new ones.
+ * Returns an unsubscribe function.
+ */
+export async function subscribeChat(id, afterSeq, fn) {
+    const state = await loadState(id);
+    if (!state)
+        return null;
+    for (const ev of state.events)
+        if (ev.seq > afterSeq)
+            fn(ev);
+    state.subscribers.add(fn);
+    return () => state.subscribers.delete(fn);
+}

package/dist/inspector/chat/store.d.ts

@@ -0,0 +1,8 @@
+import type { ChatMeta, StoredChatEvent } from "./types.js";
+export declare function safeChatDir(id: string): string;
+export declare function newChatId(): string;
+export declare function writeMeta(meta: ChatMeta): Promise<void>;
+export declare function readMeta(id: string): Promise<ChatMeta | null>;
+export declare function appendEvent(id: string, ev: StoredChatEvent): Promise<void>;
+export declare function readEvents(id: string): Promise<StoredChatEvent[]>;
+export declare function listChatMetas(): Promise<ChatMeta[]>;