@netnodeag/kraftwerk 0.42.1 → 0.44.0

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

@@ -42,30 +42,213 @@ export interface ChatMeta {
     scope: ChatScope;
     /** Slug of the vibeable open in this chat's preview pane (cwd is its folder while set). */
     vibeable?: string;
+    /**
+     * The agent's own session id per seat ("main", or the agent slug in a
+     * channel): after a restart or the idle reaper, the next backend resumes
+     * it (session/resume) so the agent keeps its context instead of starting
+     * over with the transcript as a summary.
+     */
+    sessions?: Record<string, string>;
     createdAt: string;
     updatedAt: string;
 }
-/** One thread event; `seq` orders them and drives SSE resume (?after=seq). */
-export type ChatEvent = {
+/** A context compaction the agent ran, as reported on its synthetic tool call (`_meta.contextCompaction`). */
+export interface Compaction {
+    trigger?: "manual" | "automatic";
+    preTokens?: number;
+    postTokens?: number;
+    durationMs?: number;
+    error?: string;
+}
+/**
+ * A failure the agent's session ran into, as the harness reports it
+ * (AIR `sessionFailure`): what broke, how bad, and what a human can do.
+ * The same `id` with a higher `revision` replaces an earlier report.
+ */
+export interface SessionFailure {
+    id: string;
+    revision: number;
+    category: "connection" | "access" | "limit" | "request" | "service" | "unknown";
+    severity: "warning" | "error";
+    title: string;
+    details?: string;
+    /** Machine-readable refinement of the failure (e.g. why a login was refused). */
+    reason?: string;
+    actions: Array<"retry" | "login" | "new_session">;
+}
+/** One step of the agent's plan (Claude's todo list), as ACP reports it. */
+export interface PlanEntry {
+    content: string;
+    priority: "high" | "medium" | "low";
+    status: "pending" | "in_progress" | "completed";
+}
+/** A slash command the agent offers (`available_commands_update`). */
+export interface AgentCommand {
+    name: string;
+    description: string;
+    /** What the command takes after its name, if anything. */
+    hint?: string;
+}
+/** One session setting the agent lets the client change (`configOptions`). */
+export type ConfigOption = {
+    id: string;
+    name: string;
+    description?: string;
+    /** model | thought_level | model_config | mode | ... (agent-defined) */
+    category?: string;
+} & ({
+    type: "select";
+    value: string;
+    choices: Array<{
+        value: string;
+        name: string;
+        description?: string;
+        group?: string;
+    }>;
+} | {
+    type: "boolean";
+    value: boolean;
+});
+/** Who the agent is signed in as (`_auth/status_update`). */
+export interface AuthStatus {
+    kind: "account" | "api_key" | "gateway" | "external" | "none";
+    label: string;
+    detail?: string;
+    email?: string;
+    organization?: string;
+    plan?: string;
+}
+/** One field of a question the agent asks (an ACP form elicitation, e.g. Claude's AskUserQuestion). */
+export interface ElicitationField {
+    key: string;
+    title?: string;
+    description?: string;
+    kind: "select" | "multiselect" | "text" | "number" | "boolean";
+    options?: Array<{
+        value: string;
+        label: string;
+        description?: string;
+    }>;
+    required?: boolean;
+    /** A free-text alternative to the select above it ("Other"). */
+    custom?: boolean;
+}
+/** A file that travels with a message (dropped or pasted into the composer); stored under the chat's folder. */
+export interface Attachment {
+    /** File name inside the chat's attachments/ folder (unique, safe). */
+    name: string;
+    mimeType: string;
+    size: number;
+}
+export type ElicitationAnswer = {
+    action: "accept";
+    content: Record<string, string | number | boolean | string[]>;
+} | {
+    action: "decline";
+} | {
+    action: "cancel";
+};
+/**
+ * One thread event; `seq` orders them and drives SSE resume (?after=seq).
+ * `subagent` on text/thought/tool events names the child session that
+ * produced them (see the `subagent` event); absent = the main agent.
+ */
+export type ChatEvent = 
+/** `steered`: handed into the running turn instead of starting the next one. */
+{
     type: "user_message";
     text: string;
+    steered?: boolean;
+    attachments?: Attachment[];
 } | {
     type: "text";
     text: string;
+    subagent?: string;
 } | {
     type: "thought";
     text: string;
+    subagent?: string;
 } | {
     type: "tool_call";
     callId: string;
     title: string;
     kind?: string;
     status?: string;
+    subagent?: string;
+    compaction?: Compaction;
 } | {
     type: "tool_update";
     callId: string;
     title?: string;
     status?: string;
+    subagent?: string;
+    compaction?: Compaction;
+}
+/** The agent delegated to a subagent running as its own session; its events follow tagged with `subagent: sessionId`. */
+ | {
+    type: "subagent";
+    sessionId: string;
+    name: string;
+    task: string;
+} | {
+    type: "subagent_state";
+    sessionId: string;
+    state: "completed" | "failed" | "cancelled" | "disconnected";
+}
+/** Background work the agent started (a backgrounded shell, a monitor, a workflow) — outlives the tool call that started it. */
+ | {
+    type: "task";
+    taskId: string;
+    name: string;
+    taskType: string;
+    description: string;
+    toolCallId?: string;
+    canStop?: boolean;
+} | ({
+    type: "failure";
+} & SessionFailure)
+/** The agent's current plan; null when it dropped it. Replaces the previous one. */
+ | {
+    type: "plan";
+    entries: PlanEntry[] | null;
+}
+/** Context window use (tokens used of size) and the session's cost so far. */
+ | {
+    type: "usage";
+    used: number;
+    size: number;
+    costUsd?: number;
+} | {
+    type: "commands";
+    commands: AgentCommand[];
+} | {
+    type: "config";
+    options: ConfigOption[];
+} | ({
+    type: "auth";
+} & AuthStatus)
+/** What the agent says it changed this turn (AIR file change report); `unavailable` names why there is no list. */
+ | {
+    type: "files_changed";
+    paths: string[];
+    complete: boolean;
+    uncertainty?: string;
+    unavailable?: string;
+} | {
+    type: "elicitation_request";
+    requestId: string;
+    message: string;
+    fields: ElicitationField[];
+} | ({
+    type: "elicitation_resolved";
+    requestId: string;
+} & ElicitationAnswer) | {
+    type: "task_update";
+    taskId: string;
+    state?: "running" | "paused" | "completed" | "failed" | "stopped";
+    description?: string;
+    summary?: string;
+    outputFilePath?: string;
 } | {
     type: "permission_request";
     requestId: string;

package/dist/inspector/git.js

@@ -6,8 +6,8 @@ import { ENV_FILE } from "../runner/docker.js";
 import { getOutputDir, getProjectRoot } from "./context.js";
 /**
  * Workspace git sync. Several people run kraftwerk against one git repo, so
- * knowledge, agents, skills and workflows travel between them like any other
- * tracked file. The inspector shows what changed, lets a human pick files and
+ * knowledge, agents, skills, channels and workflows travel between them like
+ * any other tracked file. The inspector shows what changed, lets a human pick files and
  * commit them, and pushes on request.
  *
  * Deliberate limits, because this runs git on someone's repo from a web UI
@@ -203,9 +203,9 @@ async function checkedOut(repo) {
 }
 /**
  * The roots that may be committed, as repo-relative paths: the workflows,
- * knowledge, agents, skills and vibeables roots this project declares, plus
- * kraftwerk.yml. The output directory is excluded even when it lives inside
- * one of them.
+ * knowledge, agents, skills, channels and vibeables roots this project
+ * declares, plus kraftwerk.yml and the project README. The output directory
+ * is excluded even when it lives inside one of them.
  */
 function scopeFor({ project, repoRoot }) {
     // rev-parse reports the repo root with symlinks resolved; the project root
@@ -230,9 +230,12 @@ function scopeFor({ project, repoRoot }) {
         path.resolve(project.root, project.config.knowledge ?? "knowledge"),
         path.resolve(project.root, project.config.agents ?? "agents"),
         path.resolve(project.root, project.config.skills ?? "skills"),
+        // Channels have no configurable root: channels/ under the project.
+        path.resolve(project.root, "channels"),
         // Vibeables are the workspace's own apps: versioned with it, unlike clones.
         vibeablesRootFor(project),
         project.configPath,
+        path.resolve(project.root, "README.md"),
     ];
     const mapped = roots.filter((r) => !!r).map(rel).filter((r) => !!r);
     // Clones under the repos root are other people's history, never this

package/dist/inspector/instances.d.ts

@@ -1,4 +1,5 @@
 import type { AgentSummary } from "./agents.js";
+import type { ChannelSummary } from "./channels.js";
 /** Durable per-project record. The root is the key; everything else derives from it. */
 export interface ProjectRecord {
     root: string;
@@ -9,6 +10,8 @@ export interface ProjectRecord {
     startCount: number;
     /** Active agents, as last seen by the instance serving this root. */
     agents?: AgentSummary[];
+    /** Channels, as last seen by the instance serving this root. */
+    channels?: ChannelSummary[];
 }
 /** A verified running instance, shaped like a switcher entry. */
 export interface DiscoveredInstance {
@@ -58,13 +61,8 @@ export declare function unregisterInstance(): void;
 export declare function discoverInstances(): Promise<DiscoveredInstance[]>;
 /** Upsert the project record for a root (call on every inspector start). */
 export declare function registerProject(root: string): Promise<void>;
-/**
- * Write the roster into the project's record. Called on every roster read
- * (the UI polls it, routines tick it), so a record only changes when the
- * roster did. Roots with no record (a CLI run in a project that never
- * started the inspector) are left alone.
- */
-export declare function syncProjectAgents(root: string, agents: AgentSummary[]): Promise<void>;
+export declare const syncProjectAgents: (root: string, agents: AgentSummary[]) => Promise<void>;
+export declare const syncProjectChannels: (root: string, channels: ChannelSummary[]) => Promise<void>;
 /** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
 export declare function markProjectStopped(): void;
 /** All known projects, most recently started first. */

package/dist/inspector/instances.js

@@ -145,6 +145,7 @@ async function readProject(file) {
             lastStopped: rec.lastStopped,
             startCount: rec.startCount ?? 1,
             ...(Array.isArray(rec.agents) ? { agents: rec.agents } : {}),
+            ...(Array.isArray(rec.channels) ? { channels: rec.channels } : {}),
         };
     }
     catch {
@@ -164,32 +165,35 @@ export async function registerProject(root) {
             lastStarted: now,
             startCount: (prev?.startCount ?? 0) + 1,
             ...(prev?.agents ? { agents: prev.agents } : {}),
+            ...(prev?.channels ? { channels: prev.channels } : {}),
         };
         await fs.writeFile(projectFile(abs), JSON.stringify(rec, null, 2));
     }
     catch { } // best-effort, like the instance file
 }
-let syncedAgents = "";
+const synced = new Map();
 /**
- * Write the roster into the project's record. Called on every roster read
- * (the UI polls it, routines tick it), so a record only changes when the
- * roster did. Roots with no record (a CLI run in a project that never
- * started the inspector) are left alone.
+ * Write the roster (or the channel list) into the project's record. Called
+ * on every read (the UI polls it, routines tick it), so a record only
+ * changes when the list did. Roots with no record (a CLI run in a project
+ * that never started the inspector) are left alone.
  */
-export async function syncProjectAgents(root, agents) {
-    const key = `${root}\n${JSON.stringify(agents)}`;
-    if (key === syncedAgents)
+async function syncProjectList(root, key, list) {
+    const stamp = `${root}\n${JSON.stringify(list)}`;
+    if (synced.get(key) === stamp)
         return;
     try {
         const file = projectFile(root);
         const rec = await readProject(file);
         if (!rec)
             return;
-        await fs.writeFile(file, JSON.stringify({ ...rec, agents }, null, 2));
-        syncedAgents = key;
+        await fs.writeFile(file, JSON.stringify({ ...rec, [key]: list }, null, 2));
+        synced.set(key, stamp);
     }
     catch { }
 }
+export const syncProjectAgents = (root, agents) => syncProjectList(root, "agents", agents);
+export const syncProjectChannels = (root, channels) => syncProjectList(root, "channels", channels);
 /** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
 export function markProjectStopped() {
     if (!selfRoot)

package/dist/inspector/search.d.ts

@@ -1,10 +1,11 @@
 import { type AgentSummary } from "./agents.js";
+import { type ChannelSummary } from "./channels.js";
 /**
- * The ⌘K palette: every active agent in every workspace this machine
- * knows, so a user can jump to one without switching workspaces first.
- * This instance reads its own roster from disk; the others come from the
- * project registry, where each instance records its roster whenever it
- * reads it (see instances.ts). Stopped workspaces are listed too — the
+ * The ⌘K palette: every active agent and every channel in every workspace
+ * this machine knows, so a user can jump to one without switching
+ * workspaces first. This instance reads its own lists from disk; the others
+ * come from the project registry, where each instance records them
+ * whenever it reads them (see instances.ts). Stopped workspaces are listed too — the
  * palette starts them on the way to the agent.
  */
 export interface WorkspaceAgents {
@@ -18,6 +19,7 @@ export interface WorkspaceAgents {
     current: boolean;
     live: boolean;
     agents: AgentSummary[];
+    channels: ChannelSummary[];
 }
 export interface AgentSearch {
     workspaces: WorkspaceAgents[];

package/dist/inspector/search.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { resolveProject } from "../config.js";
 import { getProjectRoot } from "./context.js";
 import { listAgents, toSummary } from "./agents.js";
+import { listChannels, toChannelSummary } from "./channels.js";
 import { currentInstanceUrl, discoverWorkspaces, listProjects } from "./instances.js";
 export async function searchAgents() {
     const project = await resolveProject(getProjectRoot()).catch(() => null);
@@ -13,9 +14,10 @@ export async function searchAgents() {
         current: true,
         live: true,
         agents: (await listAgents().catch(() => [])).filter((a) => !a.archived).map(toSummary),
+        channels: (await listChannels().catch(() => [])).map(toChannelSummary),
     };
     const [workspaces, projects] = await Promise.all([discoverWorkspaces(), listProjects()]);
-    const rosters = new Map(projects.map((p) => [p.root, p.agents ?? []]));
+    const records = new Map(projects.map((p) => [p.root, p]));
     const others = workspaces
         .filter((w) => w.root && w.exists !== false)
         .map((w) => ({
@@ -25,7 +27,8 @@ export async function searchAgents() {
         root: w.root,
         current: false,
         live: w.live,
-        agents: rosters.get(w.root) ?? [],
+        agents: records.get(w.root)?.agents ?? [],
+        channels: records.get(w.root)?.channels ?? [],
     }));
     return { workspaces: [self, ...others] };
 }

package/dist/inspector/server.js

@@ -1,6 +1,7 @@
 import { existsSync, promises as fs } from "node:fs";
 import http from "node:http";
 import path from "node:path";
+import { attachmentPath, saveAttachment } from "./chat/store.js";
 import { setOutputDir, setProjectRoot, getOutputDir, getProjectRoot } from "./context.js";
 import { resolveProject } from "../config.js";
 import { listRuns, getRun, readRunFile } from "./runs.js";
@@ -9,7 +10,7 @@ import { dockerStatus, triggerRun, stopRun } from "./runner.js";
 import { clearNotifications, listNotifications, markNotificationsRead } from "./notifications.js";
 import { startDiagnosis } from "./diagnose.js";
 import { deleteChannel, getChannel, listChannels, saveChannel, channelsRoot } from "./channels.js";
-import { cancelChat, createChat, deleteChat, disposeAllBackends, getChat, listChats, postMessage, resolvePermission, setChatVibeable, subscribeChat, convertChatToChannel, dropChannelSeats, ensureChannelChat } from "./chat/sessions.js";
+import { cancelChat, createChat, forkChat, resetSession, answerElicitation, steerChat, stopChatTask, setChatConfig, listAgentSessionsFor, deleteChat, disposeAllBackends, getChat, listChats, postMessage, resolvePermission, setChatVibeable, subscribeChat, convertChatToChannel, dropChannelSeats, ensureChannelChat } from "./chat/sessions.js";
 import { bundleDetail, conceptDetail, createBundle, knowledgeIndex, putConcept, verifyFromUi, } from "./knowledge.js";
 import { deleteAgent, getAgent, listAgents, saveAgent, setAgentArchived, agentsRoot, } from "./agents.js";
 import { deleteAgentSkill, getSkill, listAgentSkills, listSkills, readSkill, saveAgentSkill, skillsRoot, } from "./skills.js";
@@ -54,6 +55,24 @@ function json(res, body, status = 200) {
     res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
     res.end(JSON.stringify(body));
 }
+/** A raw upload body (attachments), capped at `max` bytes. */
+function readRawBody(req, max) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > max) {
+                reject(new Error(`file too large (max ${Math.round(max / 1_000_000)} MB)`));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let data = "";
@@ -472,7 +491,7 @@ async function handleApi(req, res, url) {
             return json(res, { error: err.message }, 400);
         }
     }
-    // GET /api/search/agents — active agents of every reachable workspace (the ⌘K palette)
+    // GET /api/search/agents — active agents and channels of every reachable workspace (the ⌘K palette)
     if (seg.length === 3 && seg[1] === "search" && seg[2] === "agents" && method === "GET") {
         return json(res, await searchAgents());
     }
@@ -902,13 +921,25 @@ async function handleApi(req, res, url) {
                 return json(res, { error: "agent must be claude, codex, or pi" }, 400);
             }
             try {
-                return json(res, await createChat({ agent, scope }));
+                return json(res, await createChat({ agent, scope, ...(typeof body.resume === "string" && body.resume ? { resume: body.resume } : {}) }));
             }
             catch (err) {
                 return json(res, { error: err.message }, 400);
             }
         }
     }
+    // GET /api/agent-sessions?agent=claude|codex — the agent's own sessions in the project root
+    if (seg.length === 2 && seg[1] === "agent-sessions" && method === "GET") {
+        const agent = url.searchParams.get("agent") ?? "claude";
+        if (!["claude", "codex", "pi"].includes(agent))
+            return json(res, { error: "agent must be claude, codex, or pi" }, 400);
+        try {
+            return json(res, { sessions: await listAgentSessionsFor(agent) });
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 502);
+        }
+    }
     // DELETE /api/chats/:id
     if (seg.length === 3 && seg[1] === "chats" && method === "DELETE") {
         try {
@@ -968,6 +999,60 @@ async function handleApi(req, res, url) {
             return json(res, { error: err.message }, 400);
         }
     }
+    // POST /api/chats/:id/fork — a new chat continuing a copy of this one's session
+    if (seg.length === 4 && seg[1] === "chats" && seg[3] === "fork" && method === "POST") {
+        try {
+            const result = await forkChat(seg[2]);
+            return result.error ? json(res, { error: result.error }, result.status ?? 400) : json(res, result.meta);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // POST /api/chats/:id/attachments — raw file body; x-file-name names it. Returns the stored attachment.
+    if (seg.length === 4 && seg[1] === "chats" && seg[3] === "attachments" && method === "POST") {
+        try {
+            if (!(await getChat(seg[2])))
+                return json(res, { error: "not found" }, 404);
+            const data = await readRawBody(req, 25_000_000);
+            if (data.length === 0)
+                return json(res, { error: "empty file" }, 400);
+            const mimeType = (req.headers["content-type"] ?? "application/octet-stream").split(";")[0].trim();
+            const name = await saveAttachment(seg[2], decodeURIComponent(String(req.headers["x-file-name"] ?? "file")), data);
+            return json(res, { name, mimeType, size: data.length });
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
+    // GET /api/chats/:id/attachments/:name — the stored file
+    if (seg.length === 5 && seg[1] === "chats" && seg[3] === "attachments" && method === "GET") {
+        try {
+            const file = attachmentPath(seg[2], seg[4]);
+            const ext = path.extname(file).toLowerCase();
+            const data = await fs.readFile(file);
+            res.writeHead(200, {
+                "content-type": MIME[ext] ?? "application/octet-stream",
+                "content-length": data.length,
+                "cache-control": "private, max-age=86400",
+                "x-content-type-options": "nosniff",
+            });
+            return void res.end(data);
+        }
+        catch {
+            return json(res, { error: "not found" }, 404);
+        }
+    }
+    // POST /api/chats/:id/reset-session — forget the agent's session; the next message starts fresh
+    if (seg.length === 4 && seg[1] === "chats" && seg[3] === "reset-session" && method === "POST") {
+        try {
+            const result = await resetSession(seg[2]);
+            return result.error ? json(res, { error: result.error }, result.status ?? 400) : json(res, result.meta);
+        }
+        catch (err) {
+            return json(res, { error: err.message }, 400);
+        }
+    }
     // POST /api/chats/:id/{message,permission,cancel}
     if (seg.length === 4 && seg[1] === "chats" && method === "POST") {
         let body = {};
@@ -981,18 +1066,44 @@ async function handleApi(req, res, url) {
         }
         try {
             let result;
+            const attachments = Array.isArray(body.attachments)
+                ? body.attachments
+                    .filter((a) => a && typeof a.name === "string" && typeof a.mimeType === "string")
+                    .map((a) => ({ name: String(a.name), mimeType: String(a.mimeType), size: Number(a.size) || 0 }))
+                : [];
             if (seg[3] === "message") {
                 const text = String(body.text ?? "").trim();
-                if (!text)
+                if (!text && attachments.length === 0)
                     return json(res, { error: "text is required" }, 400);
                 // Channels: the poster's display name signs the message.
-                result = await postMessage(seg[2], text, { from: typeof body.from === "string" ? body.from : undefined });
+                result = await postMessage(seg[2], text || "(see attached)", { from: typeof body.from === "string" ? body.from : undefined, attachments });
             }
             else if (seg[3] === "permission") {
                 result = await resolvePermission(seg[2], String(body.requestId ?? ""), body.optionId == null ? null : String(body.optionId));
             }
             else if (seg[3] === "cancel") {
-                result = await cancelChat(seg[2]);
+                // Channels: `agent` stops one member; without it every agent in the chat.
+                result = await cancelChat(seg[2], typeof body.agent === "string" && body.agent ? body.agent : undefined);
+            }
+            else if (seg[3] === "steer") {
+                const text = String(body.text ?? "").trim();
+                if (!text && attachments.length === 0)
+                    return json(res, { error: "text is required" }, 400);
+                result = await steerChat(seg[2], text || "(see attached)", attachments);
+            }
+            else if (seg[3] === "elicitation") {
+                const action = body.action === "accept" || body.action === "decline" || body.action === "cancel" ? body.action : null;
+                if (!action)
+                    return json(res, { error: "action must be accept, decline, or cancel" }, 400);
+                const content = body.content && typeof body.content === "object" ? body.content : {};
+                result = await answerElicitation(seg[2], String(body.requestId ?? ""), action === "accept" ? { action, content } : { action });
+            }
+            else if (seg[3] === "task-stop") {
+                result = await stopChatTask(seg[2], String(body.taskId ?? ""));
+            }
+            else if (seg[3] === "config") {
+                const value = typeof body.value === "boolean" ? body.value : String(body.value ?? "");
+                result = await setChatConfig(seg[2], String(body.configId ?? ""), value);
             }
             else {
                 return json(res, { error: "not found" }, 404);