@netnodeag/kraftwerk 0.43.0 → 0.45.0

package/README.md

@@ -237,6 +237,26 @@ pass-through. `--run-id` pins the run folder name for external triggers, which
 is what the inspector uses. `runner.json` in the run dir records container,
 exit code, and timing.
 
+### Runs in the inspector
+
+The runs screen shows every folder under `output/runs/`, live ones with
+their phase timeline, finished ones opening on their artifacts. A run's
+status comes from `trace.jsonl` first: a `run_summary` settles it, a failed
+or blocked phase fails it, and a trace nobody has written to for fifteen
+minutes counts as aborted. Two markers settle it earlier: `runner.json`
+(sandbox container exit code) and `trigger.json`, which the inspector
+writes when a launcher it started exits. A folder that never got a trace at
+all — the launcher died first, typically over a missing env var, and only
+`trigger.log` tells why — ages by its newest file and shows as failed
+instead of running forever; its workflow name is read from the run id.
+
+Every live run has a stop button (`POST /api/runs/:id/stop`): it ends the
+detached launcher process group for a local run this inspector started, or
+`docker stop`s the `kw-<run-id>` container for a sandboxed one, and answers
+404 when neither exists (a run started from the CLI in another terminal).
+Every finished run has a remove button (`DELETE /api/runs/:id`) that deletes
+the folder; a run that still looks live is refused with 409 — stop it first.
+
 `run` prompts for whatever is missing, both the workflow picker and the
 request input. Invalid workflows show up red in `list` with their validation
 error instead of breaking the listing. `create` is meant to be run BY an LLM
@@ -290,6 +310,46 @@ and write knowledge through `kraftwerk knowledge`, with writes stamped with
 the agent's own actor, `<slug>/<harness>`. So the agent triggers its own
 workflows when a request matches, and keeps its bundles current.
 
+A chat keeps the agent's own session. The ACP session id is stored with the
+chat (`sessions` in `meta.json`), and the next process — after an inspector
+restart, or once the idle reaper released the agent — resumes it over
+`session/resume`, so the agent continues with its memory rather than with
+the transcript as a summary. A session that cannot be resumed (its
+transcript is gone) falls back to a fresh one and says so in the thread.
+"Fork" branches a chat: a new chat with the same transcript whose agent
+continues from a copy of the session (`session/fork`, claude), leaving the
+original as it is. Chats over ACP negotiate claude's native subagent and
+async task streams: a delegated subagent shows as its own card with its
+stream folded underneath, background work (backgrounded shells, monitors)
+as task cards that outlive the tool call, and a context compaction as a
+"compact" card with the token counts. Session failures the harness reports
+(a rate limit, an expired login, a provider outage) arrive structured, not
+as prose: a card names the category and the action the harness recommends,
+retry, sign in again, or start a fresh session
+(`POST /api/chats/:id/reset-session` forgets the stored session id).
+
+The rest of what the adapters announce is in the chat too. The agent's
+plan is a checklist card that updates in place. Its questions (Claude's
+AskUserQuestion, MCP elicitations) are form cards answered in the thread —
+unattended sessions skip an unanswered question after the same deadline as
+permissions. A message sent while the agent works is steered into the
+running turn instead of waiting (`POST /api/chats/:id/steer`). The header
+shows who the agent is signed in as, and in expert mode its context use
+and cost plus the model and thinking settings it lets you change live
+(`POST /api/chats/:id/config`). The agent's slash commands join the
+skills in the `/` menu. Each turn ends with the files the agent says it
+changed. Background tasks that can be stopped have a stop button
+(`POST /api/chats/:id/task-stop`). Deleting a chat deletes the agent's own
+sessions with it, and "continue a session" on the new-chat screen lists
+the agent's sessions in the project (`GET /api/agent-sessions`) to pick
+one up as a chat.
+
+Files dropped, pasted or attached in the composer go with the message
+(`POST /api/chats/:id/attachments`, then `attachments` on the message):
+they are stored under the chat's folder, images reach the agent as image
+blocks (a screenshot is seen, not described), text files as embedded
+resources, everything else by path.
+
 Model and effort ride on backend-specific channels. The claude adapter takes
 the model via ACP session options and the thinking budget via
 `MAX_THINKING_TOKENS`. Codex gets a `CODEX_CONFIG` env override (`model`,
@@ -461,6 +521,14 @@ browser. API: `GET/POST /api/channels`, `GET/PUT/DELETE /api/channels/:slug`,
 `POST /api/channels/from-chat {chatId, name, members}`; messages go through
 the chat endpoint with `from` for the poster's name.
 
+Each member chip in a channel shows what that agent is on: the message
+that last addressed it, and while it works, its current step (the tool it
+is using, else the start of its reply). Clicking a chip opens the agent's
+own session — its stream alone, humans' messages for context, tool
+activity always visible — and a stop button interrupts just that agent
+(`POST /api/chats/:id/cancel {agent}`); "stop all" in the header
+interrupts every agent working in the channel.
+
 ## Knowledge
 
 Alongside runs and chats, a project can keep curated knowledge as

package/dist/acp.d.ts

@@ -1,5 +1,5 @@
 import { type ChildProcessWithoutNullStreams } from "node:child_process";
-import { ClientSideConnection, type Client, type McpServer } from "@agentclientprotocol/sdk";
+import { ClientSideConnection, type Client, type McpServer, type SessionConfigOption, type SessionModeState } from "@agentclientprotocol/sdk";
 import type { McpServerConfig } from "./harness.js";
 /**
  * Agent Client Protocol plumbing shared by the inspector's chats and the
@@ -23,6 +23,98 @@ export declare function adapterEnv(agent: AcpAgent, tuning: {
 }): NodeJS.ProcessEnv;
 /** Kraftwerk's MCP config (stdio or url) -> the protocol's session mcpServers entries. */
 export declare function acpMcpServers(servers?: Record<string, McpServerConfig>): McpServer[];
+/**
+ * Session updates beyond the published ACP schema, from the "AIR"
+ * extension claude-agent-acp negotiates (agent-client-protocol#1992 for
+ * subagents; async tasks alongside). A client that advertises the
+ * capabilities gets Claude's subagents as independent child sessions
+ * (`subagent_spawned`, then ordinary updates carrying the child's session
+ * id) and its background work (backgrounded shells, monitors, workflows)
+ * as async tasks — instead of the flattened generic Agent/Task tool call.
+ *
+ * The SDK validates every session/update against its schema and does not
+ * know these kinds yet, so they never reach the Client through the SDK:
+ * connectAcp diverts them off the wire before the SDK sees them.
+ */
+export type SubagentState = "completed" | "failed" | "cancelled" | "disconnected";
+export type AsyncTaskState = "running" | "paused" | "completed" | "failed" | "stopped";
+export type AcpExtensionUpdate = {
+    sessionUpdate: "subagent_spawned";
+    subagentSessionId: string;
+    name: string;
+    task: string;
+} | {
+    sessionUpdate: "subagent_state_update";
+    subagentSessionId: string;
+    state: SubagentState;
+} | {
+    sessionUpdate: "async_task_spawned";
+    asyncTaskId: string;
+    name: string;
+    taskType: string;
+    description: string;
+    showInTranscript?: boolean;
+    canStop?: boolean;
+    outputFilePath?: string;
+    toolCallId?: string;
+} | {
+    sessionUpdate: "async_task_progress";
+    asyncTaskId: string;
+    description?: string;
+    summary?: string;
+    lastToolName?: string;
+    outputFilePath?: string;
+    toolCallId?: string;
+} | {
+    sessionUpdate: "async_task_state_update";
+    asyncTaskId: string;
+    state: AsyncTaskState;
+    summary?: string;
+    outputFilePath?: string;
+    toolCallId?: string;
+};
+export interface AcpExtensionNotification {
+    sessionId: string;
+    update: AcpExtensionUpdate;
+}
+/**
+ * What kraftwerk advertises: the AIR extension's capability list in the
+ * client's `_meta` — native subagent and async task streams, session
+ * failures (rate limits, expired logins, provider outages) as structured
+ * `session_info_update` metadata with a recommended action instead of
+ * prose, and the per-turn file change report (see fileChangeReportMeta).
+ * Both adapters implement the extension; an adapter without it ignores
+ * the list and keeps its plain stream.
+ */
+export declare function extensionClientMeta(): Record<string, unknown>;
+/**
+ * Prompt `_meta` asking for a file change report at the end of the turn:
+ * the adapter gives the agent a `report_changed_files` tool and the
+ * result arrives as `session_info_update` metadata. One id per prompt.
+ */
+export declare function fileChangeReportMeta(requestId: string): Record<string, unknown>;
+/** Extension request methods the claude adapter offers (advertised in its initialize `_meta`). */
+export declare const EXT_METHODS: {
+    /** Inject a message into the running turn. */
+    readonly steer: "_session/steering";
+    /** Stop one background task without cancelling the turn. */
+    readonly stopAsyncTask: "_session/async_task/stop";
+};
+/** Extension notifications an adapter pushes to the client. */
+export declare const EXT_NOTIFICATIONS: {
+    /** Who the agent is signed in as (claude-agent-acp authStatus extension). */
+    readonly authStatus: "_auth/status_update";
+};
+/** The AIR payload for `capability` inside a `_meta`, if the peer sent one. */
+export declare function airMeta<T = Record<string, unknown>>(meta: unknown, capability: string): T | undefined;
+/** The extension notification on one wire line, if that is what the line is. */
+export declare function parseExtensionLine(line: string): AcpExtensionNotification | null;
+/**
+ * Filter the adapter's newline-delimited JSON-RPC output: extension
+ * session updates go to `onExtension`, everything else passes through
+ * byte-for-byte for the SDK. Lines may arrive split across chunks.
+ */
+export declare function divertExtensionUpdates(source: ReadableStream<Uint8Array>, onExtension: (n: AcpExtensionNotification) => void): ReadableStream<Uint8Array>;
 export interface AcpProcess {
     child: ChildProcessWithoutNullStreams;
     conn: ClientSideConnection;
@@ -32,12 +124,50 @@ export interface AcpProcess {
  * `client`, and run the initialize handshake. Process failures reach the
  * caller through the callbacks (a failed spawn is otherwise an unhandled
  * 'error' event that takes the host process down).
+ *
+ * `onExtension` opts into the native subagent / async task streams (see
+ * AcpExtensionUpdate); without it the adapter keeps its generic tool-call
+ * representation of that work.
  */
 export declare function connectAcp(agent: AcpAgent, opts: {
     cwd: string;
     env: NodeJS.ProcessEnv;
     client: Client;
     clientName: string;
+    onExtension?: (n: AcpExtensionNotification) => void;
+    /** The client answers form elicitations (`createElicitation` on the Client): agents may ask questions. */
+    elicitation?: boolean;
     onError(err: Error): void;
     onClose(code: number | null, stderr: string): void;
 }): Promise<AcpProcess>;
+/**
+ * Run `fn` against a short-lived adapter that opens no session: for
+ * listing or deleting the agent's own sessions. The adapter is gone when
+ * `fn` settles.
+ */
+export declare function withAdapter<T>(agent: AcpAgent, cwd: string, fn: (conn: ClientSideConnection) => Promise<T>): Promise<T>;
+/** The subset of the connection a session open needs (a test can stand in for it). */
+export type SessionOpener = Pick<ClientSideConnection, "newSession" | "resumeSession">;
+export interface OpenedSession {
+    sessionId: string;
+    modes?: SessionModeState | null;
+    /** Session settings the agent lets the client change (model, thinking depth, ...). */
+    configOptions?: SessionConfigOption[] | null;
+    /** The session continues an earlier one (same id, the agent's own history). */
+    resumed: boolean;
+    /** A resume was asked for but refused; a fresh session was opened instead. */
+    resumeError?: string;
+}
+/**
+ * Open a session: continue `resume` when given (session/resume — the
+ * agent's own transcript carries the history, no replay), else a new one.
+ * A refused resume (unknown id, adapter without the method, transcript
+ * gone) falls back to a new session and says so, instead of failing the
+ * chat: the conversation on disk is still there for the human, the agent
+ * just starts without it in context.
+ */
+export declare function openSession(conn: SessionOpener, req: {
+    cwd: string;
+    mcpServers: McpServer[];
+    _meta?: Record<string, unknown>;
+}, resume?: string): Promise<OpenedSession>;

package/dist/acp.js

@@ -44,11 +44,117 @@ export function acpMcpServers(servers = {}) {
             env: Object.entries(cfg.env ?? {}).map(([n, value]) => ({ name: n, value })),
         });
 }
+const EXTENSION_KINDS = new Set([
+    "subagent_spawned",
+    "subagent_state_update",
+    "async_task_spawned",
+    "async_task_progress",
+    "async_task_state_update",
+]);
+// Cheap pre-check so only candidate lines are parsed.
+const EXTENSION_LINE = /"sessionUpdate"\s*:\s*"(subagent_|async_task_)/;
+/**
+ * What kraftwerk advertises: the AIR extension's capability list in the
+ * client's `_meta` — native subagent and async task streams, session
+ * failures (rate limits, expired logins, provider outages) as structured
+ * `session_info_update` metadata with a recommended action instead of
+ * prose, and the per-turn file change report (see fileChangeReportMeta).
+ * Both adapters implement the extension; an adapter without it ignores
+ * the list and keeps its plain stream.
+ */
+export function extensionClientMeta() {
+    return {
+        jetbrains: {
+            air: { version: 1, capabilities: ["nativeSubagentSessions", "asyncTasks", "sessionFailure", "agentFileChangeReport"] },
+        },
+    };
+}
+/**
+ * Prompt `_meta` asking for a file change report at the end of the turn:
+ * the adapter gives the agent a `report_changed_files` tool and the
+ * result arrives as `session_info_update` metadata. One id per prompt.
+ */
+export function fileChangeReportMeta(requestId) {
+    return { jetbrains: { air: { version: 1, agentFileChangeReportRequest: { version: 1, requestId } } } };
+}
+/** Extension request methods the claude adapter offers (advertised in its initialize `_meta`). */
+export const EXT_METHODS = {
+    /** Inject a message into the running turn. */
+    steer: "_session/steering",
+    /** Stop one background task without cancelling the turn. */
+    stopAsyncTask: "_session/async_task/stop",
+};
+/** Extension notifications an adapter pushes to the client. */
+export const EXT_NOTIFICATIONS = {
+    /** Who the agent is signed in as (claude-agent-acp authStatus extension). */
+    authStatus: "_auth/status_update",
+};
+/** The AIR payload for `capability` inside a `_meta`, if the peer sent one. */
+export function airMeta(meta, capability) {
+    const air = meta?.jetbrains?.air;
+    const payload = air?.[capability];
+    return payload && typeof payload === "object" ? payload : undefined;
+}
+/** The extension notification on one wire line, if that is what the line is. */
+export function parseExtensionLine(line) {
+    if (!EXTENSION_LINE.test(line))
+        return null;
+    try {
+        const msg = JSON.parse(line);
+        if (msg.method !== "session/update")
+            return null;
+        const update = msg.params?.update;
+        if (!update || !EXTENSION_KINDS.has(update.sessionUpdate ?? "") || typeof msg.params?.sessionId !== "string")
+            return null;
+        return { sessionId: msg.params.sessionId, update: update };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Filter the adapter's newline-delimited JSON-RPC output: extension
+ * session updates go to `onExtension`, everything else passes through
+ * byte-for-byte for the SDK. Lines may arrive split across chunks.
+ */
+export function divertExtensionUpdates(source, onExtension) {
+    const decoder = new TextDecoder();
+    const encoder = new TextEncoder();
+    let buffered = "";
+    const handle = (line, ctrl, tail) => {
+        const ext = parseExtensionLine(line);
+        if (ext)
+            onExtension(ext);
+        else
+            ctrl.enqueue(encoder.encode(line + tail));
+    };
+    return source.pipeThrough(new TransformStream({
+        transform(chunk, ctrl) {
+            buffered += decoder.decode(chunk, { stream: true });
+            let nl;
+            while ((nl = buffered.indexOf("\n")) >= 0) {
+                const line = buffered.slice(0, nl);
+                buffered = buffered.slice(nl + 1);
+                handle(line, ctrl, "\n");
+            }
+        },
+        flush(ctrl) {
+            buffered += decoder.decode();
+            if (buffered)
+                handle(buffered, ctrl, "");
+            buffered = "";
+        },
+    }));
+}
 /**
  * Spawn the adapter for `agent` in `cwd`, wire the ACP connection to
  * `client`, and run the initialize handshake. Process failures reach the
  * caller through the callbacks (a failed spawn is otherwise an unhandled
  * 'error' event that takes the host process down).
+ *
+ * `onExtension` opts into the native subagent / async task streams (see
+ * AcpExtensionUpdate); without it the adapter keeps its generic tool-call
+ * representation of that work.
  */
 export async function connectAcp(agent, opts) {
     const entry = fileURLToPath(import.meta.resolve(ADAPTERS[agent]));
@@ -65,12 +171,67 @@ export async function connectAcp(agent, opts) {
     });
     child.on("error", opts.onError);
     child.on("close", (code) => opts.onClose(code, stderr.trim()));
-    const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+    let output = Readable.toWeb(child.stdout);
+    if (opts.onExtension)
+        output = divertExtensionUpdates(output, opts.onExtension);
+    const stream = ndJsonStream(Writable.toWeb(child.stdin), output);
     const conn = new ClientSideConnection(() => opts.client, stream);
     await conn.initialize({
         protocolVersion: PROTOCOL_VERSION,
-        clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+        clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false },
+            ...(opts.elicitation ? { elicitation: { form: {} } } : {}),
+            ...(opts.onExtension ? { _meta: extensionClientMeta() } : {}),
+        },
         clientInfo: { name: opts.clientName, version: "1.0.0" },
     });
     return { child, conn };
 }
+/**
+ * Run `fn` against a short-lived adapter that opens no session: for
+ * listing or deleting the agent's own sessions. The adapter is gone when
+ * `fn` settles.
+ */
+export async function withAdapter(agent, cwd, fn) {
+    const { child, conn } = await connectAcp(agent, {
+        cwd,
+        env: adapterEnv(agent, {}),
+        clientName: "kraftwerk",
+        client: {
+            sessionUpdate() { },
+            async requestPermission() {
+                return { outcome: { outcome: "cancelled" } };
+            },
+        },
+        onError() { },
+        onClose() { },
+    });
+    try {
+        return await fn(conn);
+    }
+    finally {
+        child.kill("SIGTERM");
+    }
+}
+/**
+ * Open a session: continue `resume` when given (session/resume — the
+ * agent's own transcript carries the history, no replay), else a new one.
+ * A refused resume (unknown id, adapter without the method, transcript
+ * gone) falls back to a new session and says so, instead of failing the
+ * chat: the conversation on disk is still there for the human, the agent
+ * just starts without it in context.
+ */
+export async function openSession(conn, req, resume) {
+    let resumeError;
+    if (resume) {
+        try {
+            const res = await conn.resumeSession({ sessionId: resume, ...req });
+            return { sessionId: resume, modes: res.modes, configOptions: res.configOptions, resumed: true };
+        }
+        catch (err) {
+            resumeError = err.message;
+        }
+    }
+    const res = await conn.newSession(req);
+    return { sessionId: res.sessionId, modes: res.modes, configOptions: res.configOptions, resumed: false, ...(resumeError ? { resumeError } : {}) };
+}

package/dist/harnesses/acp.js

@@ -1,5 +1,5 @@
 import { RequestError, } from "@agentclientprotocol/sdk";
-import { acpMcpServers, adapterEnv, connectAcp } from "../acp.js";
+import { acpMcpServers, adapterEnv, connectAcp, openSession } from "../acp.js";
 import { declineOption, unattendedMode } from "../inspector/chat/permissions.js";
 const live = new Map();
 // The run process is the adapters' only owner: never leave one behind.
@@ -31,7 +31,7 @@ export function toolTarget(u) {
     return target.length > 160 ? `${target.slice(0, 160)}…` : target;
 }
 const wait = (ms) => new Promise((r) => setTimeout(r, ms));
-async function open(agent, inv) {
+async function open(agent, inv, resume) {
     let ended;
     const closed = new Promise((r) => (ended = r));
     const state = {
@@ -92,11 +92,14 @@ async function open(agent, inv) {
     state.child = child;
     state.conn = conn;
     try {
-        const session = await conn.newSession({
+        const session = await openSession(conn, {
             cwd: inv.cwd,
             mcpServers: acpMcpServers(inv.mcpServers),
             ...(agent === "claude" ? { _meta: { claudeCode: { options: claudeSessionOptions(inv) } } } : {}),
-        });
+        }, resume);
+        if (session.resumeError) {
+            console.log(`  ⚠ could not resume session ${resume} (${session.resumeError}) — a new ${agent} session starts without the earlier phases in context`);
+        }
         state.sessionId = session.sessionId;
         const modeId = unattendedMode(agent, session.modes?.currentModeId);
         if (modeId) {
@@ -135,7 +138,8 @@ async function invoke(agent, inv) {
         live.delete(s.sessionId);
         s = undefined;
     }
-    s ??= await open(agent, inv);
+    // No live adapter for the id (a new process, or the adapter died): resume it in a fresh one.
+    s ??= await open(agent, inv, inv.resume);
     const turn = { text: "", onToolUse: inv.onToolUse, pending: new Map() };
     s.turn = turn;
     const prevCost = s.cost;

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

@@ -1,2 +1,48 @@
-import type { BackendHooks, BackendTuning, ChatBackend } from "./backend.js";
-export declare function startAcpBackend(agent: "claude" | "codex", cwd: string, hooks: BackendHooks, tuning?: BackendTuning): Promise<ChatBackend>;
+import { type ContentBlock, type SessionConfigOption, type SessionNotification } from "@agentclientprotocol/sdk";
+import { type AcpAgent, type AcpExtensionNotification } from "../../acp.js";
+import type { BackendHooks, BackendTuning, ChatBackend, PromptFile } from "./backend.js";
+import type { AuthStatus, ChatEvent, ConfigOption, ElicitationField, SessionFailure } from "./types.js";
+/** The session failure a `session_info_update` carries, if it is one (AIR `sessionFailure` in `_meta`). */
+export declare function failureOf(meta: unknown): SessionFailure | undefined;
+/** The file change report a `session_info_update` carries, if it is one (AIR `agentFileChangeReport`). */
+export declare function filesChangedOf(meta: unknown): Extract<ChatEvent, {
+    type: "files_changed";
+}> | undefined;
+/** The protocol's config options -> the chat's (select choices flattened, groups kept as a label). */
+export declare function configOptions(options: SessionConfigOption[] | null | undefined): ConfigOption[];
+/** The adapter's auth status notification -> the chat's. */
+export declare function authStatusOf(params: unknown): AuthStatus | undefined;
+/**
+ * A form elicitation's schema -> fields the UI can render. Claude's
+ * AskUserQuestion arrives as one select (oneOf) per question plus an
+ * "Other" text field flagged as its custom answer; MCP elicitations bring
+ * plain string/number/boolean/enum properties. Unknown property types
+ * degrade to text.
+ */
+export declare function elicitationFields(schema: unknown): ElicitationField[];
+/**
+ * One standard session update -> the chat event it means, or null for
+ * updates that carry no thread content (mode updates, ...).
+ * Updates from a session other than `root` come from a subagent and are
+ * tagged with that child's session id.
+ */
+export declare function translateUpdate(root: string, params: SessionNotification): ChatEvent | null;
+/** One extension update (subagent / async task lifecycle) -> its chat event. */
+export declare function translateExtension(n: AcpExtensionNotification): ChatEvent | null;
+/**
+ * A message with its files as ACP prompt blocks: images as image blocks
+ * (the agent sees the screenshot), text files as embedded resources, and
+ * anything else as a line naming the path — every file is on disk under
+ * the chat, so the agent can open it itself.
+ */
+export declare function promptBlocks(text: string, files?: PromptFile[]): Promise<ContentBlock[]>;
+/** The agent's own sessions in `cwd` (newest first), from a short-lived adapter. */
+export declare function listAgentSessions(agent: AcpAgent, cwd: string): Promise<Array<{
+    sessionId: string;
+    title?: string;
+    updatedAt?: string;
+    cwd: string;
+}>>;
+/** Remove one of the agent's sessions for good (its transcript on disk), from a short-lived adapter. */
+export declare function deleteAgentSession(agent: AcpAgent, cwd: string, sessionId: string): Promise<void>;
+export declare function startAcpBackend(agent: AcpAgent, cwd: string, hooks: BackendHooks, tuning?: BackendTuning): Promise<ChatBackend>;