@netnodeag/kraftwerk 0.57.3 → 0.58.0

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

@@ -2,6 +2,23 @@ import type { Attachment, ChatAgentId, ChatMeta, ChatScope, ElicitationAnswer, S
 import { type Channel } from "../channels.js";
 /** Server shutdown: no agent subprocess may outlive the inspector. */
 export declare function disposeAllBackends(): void;
+/**
+ * "## Your journal" block: the recent part of agents/<slug>/journal.md and
+ * how to add to it. This is what makes the agent the same colleague from
+ * one session to the next.
+ */
+export declare function agentJournalContext(def: {
+    slug: string;
+    harness: ChatAgentId;
+}): Promise<string>;
+/**
+ * "## Files" block for an agent: the workspace's files and the folders in
+ * it linked to the agent. An agent owns no files; in a project it works
+ * with the project's (the project block says where).
+ */
+export declare function agentFilesContext(def: {
+    files?: string[];
+}): Promise<string>;
 /**
  * "## Your vibeables" block: the apps an agent builds and maintains, linked
  * in agent.yml like knowledge. Empty when nothing is linked. When the
@@ -36,6 +53,34 @@ export declare function createChat(opts: {
 }): Promise<ChatMeta>;
 /** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
 export declare function chatAwaitingApproval(id: string): boolean;
+/** A request in a chat that waits for a human: an approval or a question, with the seat (agent) that raised it. */
+export interface WaitingRequest {
+    requestId: string;
+    kind: "approval" | "question";
+    title: string;
+    since: string;
+    meta: ChatMeta;
+    /** The seat that asked: MAIN in an ordinary chat, the agent slug in a channel. */
+    seat: string;
+}
+/** Every request waiting for a human, across the chats in memory. */
+export declare function waitingRequests(): WaitingRequest[];
+/** One chat an agent is in right now: mid-turn, or waiting on a human. */
+export interface AgentActivity {
+    chatId: string;
+    title: string;
+    since?: string;
+}
+/**
+ * Live work per agent slug, from the chats in memory: where its seat is
+ * mid-turn (working) and where it raised a permission request or a
+ * question nobody answered yet (waiting). Agent sessions and channel seats
+ * alike; plain and project chats have no agent and are left out.
+ */
+export declare function agentActivity(): Map<string, {
+    working: AgentActivity[];
+    waiting: AgentActivity[];
+}>;
 export declare function listChats(): Promise<Array<ChatMeta & {
     busy: boolean;
     awaitingApproval: boolean;
@@ -132,10 +177,16 @@ export declare function listAgentSessionsFor(agent: ChatAgentId): Promise<Array<
 export declare function resolvePermission(id: string, requestId: string, optionId: string | null): Promise<{
     error?: string;
 }>;
-/** Delete a chat: kill its backend, drop the live state, remove its folder. */
+/**
+ * Delete a chat: kill its backend, drop the live state, move its folder to
+ * the trash. The agents' own transcripts stay until it is deleted from the
+ * trash (purgeChatTranscripts), so a restored chat can resume.
+ */
 export declare function deleteChat(id: string): Promise<{
     error?: string;
 }>;
+/** The agents' own transcripts of a chat folder (one in the trash), deleted for good. Best effort. */
+export declare function purgeChatTranscripts(dir: string): Promise<void>;
 /**
  * Interrupt the agent's turn — in a channel, one agent's (`agent` = its
  * slug) or every agent's. Whatever the agent was waiting on from a human

package/dist/inspector/chat/sessions.js

@@ -14,7 +14,10 @@ import { startPiBackend } from "./pi.js";
 import { UNATTENDED_PERMISSION_TIMEOUT_MS, declineOption, unattendedTimeoutLabel } from "./permissions.js";
 import { chatHref, dismissKey, pushNotification } from "../notifications.js";
 import { getChannel, mentionTargets } from "../channels.js";
-import { appendEvent, attachmentPath, copyChatFiles, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
+import { moveToTrash } from "../trash.js";
+import { JOURNAL_FILE, journalExcerpt, readJournal } from "../journal.js";
+import { filesSummary } from "../files.js";
+import { appendEvent, attachmentPath, copyChatFiles, listChatMetas, newChatId, readEvents, readMeta, readMetaAt, safeChatDir, writeMeta, } from "./store.js";
 const MAIN = "main";
 const states = new Map();
 const newSeat = (key, harness) => ({
@@ -55,6 +58,28 @@ function chatLabel(meta) {
         return meta.title;
     return meta.scope.kind === "agent" ? meta.scope.slug : "chat";
 }
+/**
+ * Whose a chat is, owner first, for a notification: "📁 Relaunch · 🦊 Lisa",
+ * "🦊 Lisa", "#launch · 🐻 Max", "Ralv · <chat title>". The project or
+ * agent comes before the chat because that is where you go.
+ */
+async function ownerLabel(meta, seatKey) {
+    const agentName = async (slug) => {
+        const a = await getAgent(slug).catch(() => null);
+        return a ? `${a.emoji ? `${a.emoji} ` : ""}${a.name}` : slug;
+    };
+    const projectName = async (slug) => `📁 ${(await getProject(slug).catch(() => null))?.title ?? slug}`;
+    const { scope } = meta;
+    if (scope.kind === "agent")
+        return agentName(scope.slug);
+    if (scope.kind === "project")
+        return projectName(scope.slug);
+    if (scope.kind === "channel") {
+        const parts = [meta.project ? await projectName(meta.project) : `#${scope.slug}`, await agentName(seatKey)];
+        return parts.join(" · ");
+    }
+    return `Ralv${meta.title ? ` · ${meta.title}` : ""}`;
+}
 /** Text of the agent's final message (or last error) after `afterSeq`, for a notification body. */
 function lastEventText(state, afterSeq, type) {
     const parts = [];
@@ -133,6 +158,7 @@ async function loadState(id) {
         pendingPermissions: new Map(),
         pendingElicitations: new Map(),
         pendingSeat: new Map(),
+        pendingInfo: new Map(),
         writeChain: Promise.resolve(),
     };
     // Two racing loads: keep whichever registered first.
@@ -290,6 +316,50 @@ async function agentKnowledgeContext(def) {
         `Never hand-edit index.md or log.md, and never add \`verified\` yourself — verification is the human's ` +
         `click in the UI.\n\n`);
 }
+/**
+ * "## Your journal" block: the recent part of agents/<slug>/journal.md and
+ * how to add to it. This is what makes the agent the same colleague from
+ * one session to the next.
+ */
+export async function agentJournalContext(def) {
+    const { text, truncated } = journalExcerpt(await readJournal(def.slug).catch(() => ""));
+    return (`## Your journal
+Your own notes from earlier sessions, newest first (agents/${def.slug}/${JOURNAL_FILE}). ` +
+        `They are your memory between sessions: build on them, keep what you promised, and check facts that may have changed since.
+
+` +
+        (text ? `${text}
+` : `(empty: nothing recorded yet)
+`) +
+        (truncated ? `(older days are in the file; read it when you need them)
+` : "") +
+        `
+Add to it when something should outlive this session, one line each:
+` +
+        `  npx kraftwerk journal ${def.slug} "<one line>" --kind learned|decided|promised|done
+` +
+        `learned: a durable fact about the user, the work or the workspace. decided: a decision and its reason. ` +
+        `promised: something you said you would do. done: a promise kept or a piece of work finished. ` +
+        `Write a few lines at the end of a session that changed something, not a transcript; no secrets. ` +
+        `Never edit ${JOURNAL_FILE} by hand.
+
+`);
+}
+/**
+ * "## Files" block for an agent: the workspace's files and the folders in
+ * it linked to the agent. An agent owns no files; in a project it works
+ * with the project's (the project block says where).
+ */
+export async function agentFilesContext(def) {
+    const ws = await filesSummary("workspace").catch(() => null);
+    if (!ws)
+        return "";
+    const linked = (def.files ?? []).map((f) => `- ${ws.root}/${f}/`).join("\n");
+    return (`## Files\nThe workspace's shared files (any format: brand assets, templates, contracts, …) are in ${ws.root}/ (${ws.count} file${ws.count === 1 ? "" : "s"}). ` +
+        (linked ? `The folders that are part of your job:\n${linked}\n` : "") +
+        `Work you do for a project belongs in that project's files folder, not here. What you produce in a direct session goes to ${ws.root}/inbox/. ` +
+        `Delete nothing there unless asked.\n\n`);
+}
 /**
  * "## Your vibeables" block: the apps an agent builds and maintains, linked
  * in agent.yml like knowledge. Empty when nothing is linked. When the
@@ -425,6 +495,8 @@ async function baseScopeContext(scope, agent) {
                 : "") +
             (await agentKnowledgeContext(def)) +
             (await agentVibeablesContext(def)) +
+            (await agentJournalContext(def)) +
+            (await agentFilesContext(def)) +
             `The working directory is the project root. Stay within your role; if a request is clearly outside it, ` +
             `say so and suggest which agent or tool fits better.` +
             (scope.routine
@@ -508,6 +580,7 @@ async function baseScopeContext(scope, agent) {
             `## Agents\n${agentLines || "(none)"}\n` +
             `These are persistent agents (defined under agents/); the user talks to them on the ` +
             `Agents screen. Point the user there when a request clearly belongs to one of them.\n\n` +
+            (await agentFilesContext({})) +
             `Answer questions about workflows and runs by reading the files above. Do not modify run outputs unless asked.`);
     }
     if (scope.kind === "run") {
@@ -645,23 +718,32 @@ async function ensureBackend(state, seat) {
                 const notifyKey = `approval:${state.meta.id}:${requestId}`;
                 let deadline;
                 state.pendingSeat.set(requestId, seat.key);
+                state.pendingInfo.set(requestId, { kind: "approval", title, since: new Date().toISOString() });
                 state.pendingPermissions.set(requestId, (optionId) => {
                     if (deadline)
                         clearTimeout(deadline);
                     state.pendingPermissions.delete(requestId);
                     state.pendingSeat.delete(requestId);
+                    state.pendingInfo.delete(requestId);
                     emit(state, { type: "permission_resolved", requestId, optionId }, me);
                     void dismissKey(notifyKey);
                     resolve(optionId);
                 });
                 emit(state, { type: "permission_request", requestId, title, options }, me);
                 // The bell: a question is waiting. Answered -> the item goes away again.
-                void pushNotification({
-                    kind: "approval",
-                    key: notifyKey,
-                    title: `${chatLabel(state.meta)}${me?.kind === "agent" ? ` · @${me.slug}` : ""} needs approval`,
-                    body: title,
-                    href: chatHref(state.meta),
+                // The owner lookup is async: answered meanwhile, there is nothing to notify about (and a late item is taken back).
+                void ownerLabel(state.meta, seat.key).then(async (who) => {
+                    if (!state.pendingInfo.has(requestId))
+                        return;
+                    await pushNotification({
+                        kind: "approval",
+                        key: notifyKey,
+                        title: `${who} needs approval`,
+                        body: title,
+                        href: `${chatHref(state.meta)}?focus=${encodeURIComponent(requestId)}`,
+                    });
+                    if (!state.pendingInfo.has(requestId))
+                        await dismissKey(notifyKey);
                 });
                 if (isUnattended(state.meta.scope)) {
                     deadline = setTimeout(() => {
@@ -688,22 +770,31 @@ async function ensureBackend(state, seat) {
                 const notifyKey = `question:${state.meta.id}:${requestId}`;
                 let deadline;
                 state.pendingSeat.set(requestId, seat.key);
+                state.pendingInfo.set(requestId, { kind: "question", title: message, since: new Date().toISOString() });
                 state.pendingElicitations.set(requestId, (answer) => {
                     if (deadline)
                         clearTimeout(deadline);
                     state.pendingElicitations.delete(requestId);
                     state.pendingSeat.delete(requestId);
+                    state.pendingInfo.delete(requestId);
                     emit(state, { type: "elicitation_resolved", requestId, ...answer }, me);
                     void dismissKey(notifyKey);
                     resolve(answer);
                 });
                 emit(state, { type: "elicitation_request", requestId, message, fields }, me);
-                void pushNotification({
-                    kind: "approval",
-                    key: notifyKey,
-                    title: `${chatLabel(state.meta)}${me?.kind === "agent" ? ` · @${me.slug}` : ""} has a question`,
-                    body: message,
-                    href: chatHref(state.meta),
+                // The owner lookup is async: answered meanwhile, there is nothing to notify about (and a late item is taken back).
+                void ownerLabel(state.meta, seat.key).then(async (who) => {
+                    if (!state.pendingInfo.has(requestId))
+                        return;
+                    await pushNotification({
+                        kind: "approval",
+                        key: notifyKey,
+                        title: `${who} has a question`,
+                        body: message,
+                        href: `${chatHref(state.meta)}?focus=${encodeURIComponent(requestId)}`,
+                    });
+                    if (!state.pendingInfo.has(requestId))
+                        await dismissKey(notifyKey);
                 });
                 if (isUnattended(state.meta.scope)) {
                     deadline = setTimeout(() => {
@@ -775,13 +866,48 @@ export async function createChat(opts) {
         pendingPermissions: new Map(),
         pendingElicitations: new Map(),
         pendingSeat: new Map(),
+        pendingInfo: new Map(),
         writeChain: Promise.resolve(),
     });
     return meta;
 }
 /** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
 export function chatAwaitingApproval(id) {
-    return (states.get(id)?.pendingPermissions.size ?? 0) > 0;
+    return (states.get(id)?.pendingInfo.size ?? 0) > 0;
+}
+/** Every request waiting for a human, across the chats in memory. */
+export function waitingRequests() {
+    const out = [];
+    for (const state of states.values()) {
+        for (const [requestId, info] of state.pendingInfo) {
+            out.push({ requestId, ...info, meta: state.meta, seat: state.pendingSeat.get(requestId) ?? MAIN });
+        }
+    }
+    return out;
+}
+/**
+ * Live work per agent slug, from the chats in memory: where its seat is
+ * mid-turn (working) and where it raised a permission request or a
+ * question nobody answered yet (waiting). Agent sessions and channel seats
+ * alike; plain and project chats have no agent and are left out.
+ */
+export function agentActivity() {
+    const out = new Map();
+    const of = (slug) => out.get(slug) ?? out.set(slug, { working: [], waiting: [] }).get(slug);
+    for (const state of states.values()) {
+        const { meta } = state;
+        for (const seat of state.seats.values()) {
+            const slug = meta.scope.kind === "agent" ? meta.scope.slug : meta.scope.kind === "channel" ? seat.key : undefined;
+            if (!slug)
+                continue;
+            const item = { chatId: meta.id, title: meta.title };
+            if (seat.busy)
+                of(slug).working.push({ ...item, ...(seat.busySince ? { since: seat.busySince } : {}) });
+            if ([...state.pendingSeat.values()].includes(seat.key))
+                of(slug).waiting.push(item);
+        }
+    }
+    return out;
 }
 export async function listChats() {
     const metas = await listChatMetas();
@@ -810,6 +936,7 @@ export async function postMessage(id, text, opts = {}) {
     if (seat.busy)
         return { error: "agent is still working — wait for the turn to finish" };
     seat.busy = true;
+    seat.busySince = new Date().toISOString();
     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);
@@ -841,7 +968,7 @@ export async function postMessage(id, text, opts = {}) {
                 const failed = state.events.some((e) => e.seq > turnStart && (e.type === "error" || (e.type === "failure" && e.severity === "error")));
                 void pushNotification({
                     kind: failed ? "routine_failed" : "routine_done",
-                    title: `${chatLabel(state.meta)} ${failed ? "ended with an error" : "finished"}`,
+                    title: `${await ownerLabel(state.meta, MAIN)} · ${chatLabel(state.meta)} ${failed ? "ended with an error" : "finished"}`,
                     body: failed ? lastEventText(state, turnStart, "error") : lastEventText(state, turnStart, "text"),
                     href: chatHref(state.meta),
                     ...(failed ? { diagnose: routineRef(state.meta) } : {}),
@@ -853,7 +980,7 @@ export async function postMessage(id, text, opts = {}) {
             if (isUnattended(state.meta.scope)) {
                 void pushNotification({
                     kind: "routine_failed",
-                    title: `${chatLabel(state.meta)} failed`,
+                    title: `${await ownerLabel(state.meta, MAIN)} · ${chatLabel(state.meta)} failed`,
                     body: err.message,
                     href: chatHref(state.meta),
                     diagnose: routineRef(state.meta),
@@ -950,6 +1077,7 @@ function seatTextSince(state, afterSeq, slug) {
 }
 async function runSeatTurn(state, channel, seat, hops) {
     seat.busy = true;
+    seat.busySince = new Date().toISOString();
     const me = { kind: "agent", slug: seat.key };
     const start = emit(state, { type: "turn_start" }, me).seq;
     try {
@@ -1270,7 +1398,11 @@ export async function resolvePermission(id, requestId, optionId) {
     resolve(optionId);
     return {};
 }
-/** Delete a chat: kill its backend, drop the live state, remove its folder. */
+/**
+ * Delete a chat: kill its backend, drop the live state, move its folder to
+ * the trash. The agents' own transcripts stay until it is deleted from the
+ * trash (purgeChatTranscripts), so a restored chat can resume.
+ */
 export async function deleteChat(id) {
     const state = await loadState(id);
     if (!state)
@@ -1281,18 +1413,19 @@ export async function deleteChat(id) {
         resolve({ action: "cancel" });
     dropBackend(state);
     states.delete(id);
-    await fs.rm(safeChatDir(id), { recursive: true, force: true });
-    // The agent's own transcripts go with the chat (best effort, in the background).
-    const cwd = await effectiveCwd(state.meta);
-    for (const [seatKey, sessionId] of Object.entries(state.meta.sessions ?? {})) {
-        void (async () => {
-            const harness = seatKey === MAIN ? state.meta.agent : (await getAgent(seatKey).catch(() => null))?.harness;
-            if (harness && harness !== "pi")
-                await deleteAgentSession(harness, cwd, sessionId);
-        })().catch(() => { });
-    }
+    await moveToTrash("chats", id, safeChatDir(id));
     return {};
 }
+/** The agents' own transcripts of a chat folder (one in the trash), deleted for good. Best effort. */
+export async function purgeChatTranscripts(dir) {
+    const meta = await readMetaAt(dir);
+    const cwd = await effectiveCwd(meta);
+    for (const [seatKey, sessionId] of Object.entries(meta.sessions ?? {})) {
+        const harness = seatKey === MAIN ? meta.agent : (await getAgent(seatKey).catch(() => null))?.harness;
+        if (harness && harness !== "pi")
+            await deleteAgentSession(harness, cwd, sessionId).catch(() => { });
+    }
+}
 /**
  * Interrupt the agent's turn — in a channel, one agent's (`agent` = its
  * slug) or every agent's. Whatever the agent was waiting on from a human

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

@@ -3,6 +3,8 @@ 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>;
+/** meta.json of a chat folder wherever it is (also one in the trash); throws when unreadable. */
+export declare function readMetaAt(dir: string): Promise<ChatMeta>;
 /** Where a chat keeps the files dropped into it. */
 export declare function attachmentsDir(id: string): string;
 /** A stored attachment's path; rejects names that could leave the folder. */

package/dist/inspector/chat/store.js

@@ -26,12 +26,16 @@ export async function writeMeta(meta) {
 }
 export async function readMeta(id) {
     try {
-        return upgradeMeta(JSON.parse(await fs.readFile(path.join(safeChatDir(id), "meta.json"), "utf8")));
+        return await readMetaAt(safeChatDir(id));
     }
     catch {
         return null;
     }
 }
+/** meta.json of a chat folder wherever it is (also one in the trash); throws when unreadable. */
+export async function readMetaAt(dir) {
+    return upgradeMeta(JSON.parse(await fs.readFile(path.join(dir, "meta.json"), "utf8")));
+}
 /**
  * Chats written before 0.36 scoped agent sessions as
  * { kind: "team", member } — read them as { kind: "agent", slug } so the

package/dist/inspector/files.d.ts

@@ -0,0 +1,87 @@
+import type { Readable } from "node:stream";
+/**
+ * Files: the material of the work, any format, as plain folders. Two
+ * owners, by how long a file lives:
+ *
+ *   kraftwerk-data/files/                    workspace files: shared, outlive any project
+ *   kraftwerk-data/projects/<slug>/files/    a project's files: briefing, drafts, deliverables
+ *
+ * Agents own none (they link folders; see agentFilesContext). Being plain
+ * folders, agents read and write them like any directory, the workspace
+ * git keeps their history, and a delete goes to the trash. Files over
+ * LOCAL_OVER_BYTES stay out of git: listed in the root's own .gitignore,
+ * shown as "local only". Knowledge is separate: a file becomes evidence in
+ * a bundle's references/ through "learn from this" (later).
+ */
+export declare const WORKSPACE_FILES_DIR = "kraftwerk-data/files";
+export declare const PROJECT_FILES_DIR = "files";
+/** Bigger files stay local: kept out of the workspace git. */
+export declare const LOCAL_OVER_BYTES: number;
+/** Upload cap: a guard against a runaway request, not a policy. */
+export declare const MAX_UPLOAD_BYTES: number;
+/** "workspace" or "project:<slug>". */
+export type FilesScope = string;
+export interface FileEntry {
+    name: string;
+    /** Path inside the scope's root, forward slashes. */
+    path: string;
+    type: "dir" | "file";
+    size?: number;
+    modifiedAt: string;
+    /** dirs: files below it (recursive, capped). */
+    count?: number;
+    mime?: string;
+    /** Over the size limit: kept out of git. */
+    local?: boolean;
+}
+export interface FilesListing {
+    scope: FilesScope;
+    label: string;
+    /** The folder, inside the root ("" = the root). */
+    path: string;
+    /** The root relative to the workspace, for the agent and the UI. */
+    root: string;
+    entries: FileEntry[];
+}
+export interface FilesScopeInfo {
+    scope: FilesScope;
+    label: string;
+    root: string;
+    count: number;
+    status?: string;
+}
+export declare const mimeOf: (name: string) => string;
+/** The root folder of a scope, its display label, and the root relative to the workspace. */
+export declare function scopeRoot(scope: FilesScope): Promise<{
+    abs: string;
+    rel: string;
+    label: string;
+    workspace: string;
+}>;
+export declare function listScopes(): Promise<FilesScopeInfo[]>;
+export declare function listFiles(scope: FilesScope, rel?: string): Promise<FilesListing>;
+/** A file to stream to the browser. */
+export declare function openFile(scope: FilesScope, rel: string): Promise<{
+    stream: Readable;
+    size: number;
+    mime: string;
+    name: string;
+}>;
+/** Stream an upload into a folder; a name already taken gets " (2)". */
+export declare function saveUpload(scope: FilesScope, dirRel: string, name: string, body: Readable): Promise<FileEntry>;
+export declare function makeFolder(scope: FilesScope, rel: string): Promise<FileEntry>;
+/** Rename or move inside the scope. Refused when the target exists. */
+export declare function moveFile(scope: FilesScope, fromRel: string, toRel: string): Promise<void>;
+/** Move a file or folder to the trash (trash/files/<workspace | projects/slug>/<path>). */
+export declare function deleteFile(scope: FilesScope, rel: string): Promise<void>;
+/** "files/ (23 files; recent: designs/home-v3.png 2026-10-05, …)" — where the files are, not every file. */
+export declare function filesSummary(scope: FilesScope, recent?: number): Promise<{
+    root: string;
+    count: number;
+    recent: {
+        path: string;
+        at: string;
+    }[];
+} | null>;
+/** The "## Files" block of a session's context: the folder to use, what is in it lately. */
+export declare function filesContext(scope: FilesScope, heading: string, intro: string): Promise<string>;