@netnodeag/kraftwerk 0.80.0 → 0.81.0

package/README.md

@@ -300,7 +300,9 @@ Optional, at the project root, and also the root marker for the walk-up. All
 fields are optional. `workflows:` sets the workflows root, `output:` the
 run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 (default `knowledge/`), and `agents:` the agent-definition root (default
-`agents/`). `repos:` turns on the [repositories](#repositories) folder.
+`agents/`). `repos:` turns on the [repositories](#repositories) folder,
+`projects:` the [projects](#projects), and `contacts:`, `places:` and
+`events:` each one of the [contacts, places and events](#contacts-places-and-events).
 `cloud: { enabled: false }` leaves the workspace out of this machine's
 record in the [kraftwerk cloud](#this-machine-in-the-kraftwerk-cloud).
 
@@ -342,7 +344,8 @@ projects (all but archived ones) and the channels of every workspace on this
 machine, grouped by workspace and running or not (a stopped one is started
 on the way), read from the workspace registry under `~/.kraftwerk/workspaces`,
 which every inspector keeps current with its roster, project and channel
-lists.
+lists — and this workspace's contacts, places and events, by title, role,
+organisation, address or date.
 
 ### Triggering from CI, cron, or webhooks
 

package/dist/cli/init.js

@@ -139,11 +139,12 @@ export async function runInit(cwd) {
         created.push(bundleRel);
     }
     // .gitignore: the output dir, the repos root (clones must never become
-    // gitlinks of the workspace repo) and .env (secrets). A missing file gets
+    // gitlinks of the workspace repo), the temp root (session scratch, which
+    // also carries a .gitignore of its own) and .env (secrets). A missing file gets
     // all in one write; an existing one only the entries it lacks.
     const gitignorePath = path.join(cwd, ".gitignore");
     const gitignore = (await readFile(gitignorePath, "utf8").catch(() => null)) ?? null;
-    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, DOTENV_FILE];
+    const entries = [`${DATA_DIR}/output/`, `${DATA_DIR}/repos/`, `${DATA_DIR}/temp/`, DOTENV_FILE];
     if (gitignore === null) {
         await writeFile(gitignorePath, entries.map((e) => `${e}\n`).join(""));
         created.push(".gitignore");

package/dist/cli/kraftwerk.js

@@ -18,6 +18,7 @@ import { registerWorkspaceCommands } from "./workspaces.js";
 import { registerRepoCommands } from "./repos.js";
 import { registerVibeableCommands } from "./vibeables.js";
 import { registerTrashCommands } from "./trash.js";
+import { registerTempCommands } from "./temp.js";
 import { registerDevicesCommands } from "./devices.js";
 import { registerDaemonCommand } from "./daemon.js";
 import { registerRemoteCommand } from "./remote.js";
@@ -49,6 +50,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
  *   kraftwerk journal <agent> [entry] an agent's memory across sessions: print it, add a line
  *   kraftwerk trash ...               what was deleted: list, restore, purge, empty
+ *   kraftwerk temp [clean]            the sessions' scratch folders (TMPDIR of every agent): list, clean
  *   kraftwerk devices ...             paired devices: list, pair one, revoke one
  *   kraftwerk daemon                  the machine's kraftwerk: every open workspace at <slug>.localhost
  *   kraftwerk cloud [on|off|status]   this machine in the kraftwerk cloud (the daemon registers it)
@@ -309,6 +311,7 @@ registerRefCommand(program);
 registerRepoCommands(program);
 registerVibeableCommands(program);
 registerTrashCommands(program);
+registerTempCommands(program);
 registerDevicesCommands(program);
 registerDaemonCommand(program);
 registerRemoteCommand(program);

package/dist/cli/temp.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerTempCommands(program: Command): void;

package/dist/cli/temp.js

@@ -0,0 +1,62 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { cleanTemp, listTemp, SWEEP_AFTER_MS } from "../core/temp.js";
+import { fmtAgo } from "./workspaces.js";
+import { initContext as prepare } from "./routines.js";
+/**
+ * `kraftwerk temp` — the sessions' scratch folders under kraftwerk-data/temp
+ * (one per chat session; TMPDIR of the agent process). Nothing in there is
+ * a deliverable: a clean deletes for good, no trash.
+ *
+ *   kraftwerk temp                          list: session, files, size, last change
+ *   kraftwerk temp clean                    remove folders idle for a week
+ *   kraftwerk temp clean --older-than <d>   … idle for <d> days
+ *   kraftwerk temp clean --all              remove every folder
+ */
+const fmtBytes = (n) => n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} KB` : n < 1024 ** 3 ? `${(n / 1024 ** 2).toFixed(1)} MB` : `${(n / 1024 ** 3).toFixed(2)} GB`;
+export function registerTempCommands(program) {
+    const temp = program.command("temp").description("The sessions' scratch folders: list, clean");
+    temp
+        .command("list", { isDefault: true })
+        .description("List the scratch folders, newest first")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const view = await listTemp();
+        if (opts.json) {
+            console.log(JSON.stringify(view, null, 2));
+            return;
+        }
+        if (view.entries.length === 0) {
+            console.log(chalk.dim("No scratch folders."));
+            console.log(chalk.dim(view.root));
+            return;
+        }
+        const table = new Table({ head: ["session", "files", "size", "last change"].map((h) => chalk.bold(h)) });
+        for (const e of view.entries)
+            table.push([chalk.cyan(e.id), String(e.files), fmtBytes(e.bytes), chalk.dim(fmtAgo(e.modifiedAt))]);
+        console.log(table.toString());
+        console.log(chalk.dim(`${view.root} — ${fmtBytes(view.bytes)} in ${view.entries.length} folder${view.entries.length === 1 ? "" : "s"}`));
+    });
+    temp
+        .command("clean")
+        .description(`Remove scratch folders idle for ${SWEEP_AFTER_MS / 86_400_000} days (for good — nothing there is a deliverable)`)
+        .option("--older-than <days>", "Remove folders idle for this many days instead")
+        .option("--all", "Remove every folder, whatever its age")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const days = opts.olderThan === undefined ? undefined : Number(opts.olderThan);
+        if (days !== undefined && (!Number.isFinite(days) || days < 0)) {
+            console.error(chalk.red(`--older-than wants a number of days, not "${opts.olderThan}"`));
+            process.exit(2);
+        }
+        const gone = await cleanTemp({ all: opts.all, ...(days === undefined ? {} : { olderThanMs: days * 86_400_000 }) });
+        const bytes = gone.reduce((n, e) => n + e.bytes, 0);
+        if (opts.json) {
+            console.log(JSON.stringify({ removed: gone.map((e) => e.id), bytes }, null, 2));
+            return;
+        }
+        console.log(`${chalk.green("✔")} removed ${gone.length} folder${gone.length === 1 ? "" : "s"} (${fmtBytes(bytes)})`);
+    });
+}

package/dist/client/routes.d.ts

@@ -136,6 +136,8 @@ export declare const ROUTES: {
     readonly "settings.save": readonly ["PUT", "/api/settings"];
     readonly "skills.get": readonly ["GET", "/api/skills/:name"];
     readonly "skills.list": readonly ["GET", "/api/skills"];
+    readonly "temp.clean": readonly ["DELETE", "/api/temp"];
+    readonly "temp.list": readonly ["GET", "/api/temp"];
     readonly "trash.empty": readonly ["DELETE", "/api/trash"];
     readonly "trash.list": readonly ["GET", "/api/trash"];
     readonly "trash.purge": readonly ["POST", "/api/trash/purge"];

package/dist/client/routes.js

@@ -137,6 +137,8 @@ export const ROUTES = {
     "settings.save": ["PUT", "/api/settings"],
     "skills.get": ["GET", "/api/skills/:name"],
     "skills.list": ["GET", "/api/skills"],
+    "temp.clean": ["DELETE", "/api/temp"],
+    "temp.list": ["GET", "/api/temp"],
     "trash.empty": ["DELETE", "/api/trash"],
     "trash.list": ["GET", "/api/trash"],
     "trash.purge": ["POST", "/api/trash/purge"],

package/dist/core/chat/acp.js

@@ -3,6 +3,7 @@ import { promises as fs } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { RequestError, } from "@agentclientprotocol/sdk";
 import { adapterEnv, airMeta, connectAcp, EXT_METHODS, EXT_NOTIFICATIONS, fileChangeReportMeta, openSession, withAdapter, } from "../../acp.js";
+import { tempEnv } from "../temp.js";
 import { unattendedMode } from "./permissions.js";
 /**
  * ACP-backed chat: spawn an adapter (claude-agent-acp / codex-acp) as a
@@ -389,7 +390,7 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
     };
     const { child, conn } = await connectAcp(agent, {
         cwd,
-        env: adapterEnv(agent, tuning),
+        env: { ...adapterEnv(agent, tuning), ...(tuning.temp ? tempEnv(tuning.temp) : {}) },
         client,
         clientName: "kraftwerk-inspector",
         elicitation: true,

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

@@ -37,6 +37,8 @@ export interface BackendTuning {
     skillDirs?: string[];
     /** claude: extra directories the session may work in (e.g. project root for run chats). */
     addDirs?: string[];
+    /** The session's scratch folder (core/temp.ts): handed to the process as TMPDIR and KRAFTWERK_TEMP. */
+    temp?: string;
     /**
      * Nobody is watching this session live (routine runs). The backend selects
      * the harness's own hands-off permission mode — the harness keeps deciding

package/dist/core/chat/context.js

@@ -12,6 +12,7 @@ import { unattendedTimeoutLabel } from "./permissions.js";
 import { getChannel } from "../channels.js";
 import { JOURNAL_FILE, journalExcerpt, readJournal } from "../journal.js";
 import { filesSummary } from "../files.js";
+import { sessionTemp, tempContext } from "../temp.js";
 /**
  * What an agent is told about where it works: the skills it may use and
  * the scope's context block (the workspace, a run, a project, a channel,
@@ -85,8 +86,8 @@ async function agentKnowledgeContext(def) {
         `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 ${def.slug}/${def.harness}\` ` +
-        `(write the markdown to a temp file first; the CLI stamps provenance and maintains index.md/log.md). ` +
+        `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor ${def.slug}/${def.harness}\` ` +
+        `(write the markdown into your temp folder 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`);
 }
@@ -132,7 +133,8 @@ export async function agentFilesContext(def) {
     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`);
+        `Only finished work and the user's own material belong in these folders — scratch, intermediate and downloaded files go to your ` +
+        `temp folder (below), never here. Delete nothing there unless asked.\n\n`);
 }
 /**
  * "## Your vibeables" block: the apps an agent builds and maintains, linked
@@ -310,7 +312,7 @@ async function baseScopeContext(scope, agent) {
             `- 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 ` +
+            `- \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.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 — ` +
@@ -349,7 +351,7 @@ async function baseScopeContext(scope, agent) {
             `## Recent runs\n${runLines || "(none)"}\n\n` +
             `## Knowledge\nOKF bundles in this project:\n${bundleLines || "(none)"}\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 kraftwerk-chat/${agent}\` ` +
+            `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor kraftwerk-chat/${agent}\` ` +
             `(stamps provenance, maintains index.md/log.md — never hand-edit those).\n\n` +
             `## Agents\n${agentLines || "(none)"}\n` +
             `These are persistent agents (defined under agents/); the user talks to them on the ` +
@@ -403,7 +405,10 @@ export async function scopeContext(meta, seat) {
         // Who, where and when: the workspace's contacts, places and events, wherever the chat works (a run discusses its own artifacts only).
         scope.kind === "run" ? Promise.resolve("") : entitiesContext().catch(() => ""),
     ]);
-    return [base, channel, project, repos, entities, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+    // Every session has a scratch folder of its own (core/temp.ts), named by its absolute path: a run chat or a
+    // vibeable session works in another folder than the workspace root. The block comes after the files blocks it refers to.
+    const temp = await sessionTemp(meta.id).catch(() => null);
+    return [base, channel, project, repos, entities, vibe, temp ? tempContext(temp.abs) : "", RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
 }
 /** The channel block a member agent gets once per process: who is here, how turns work, how to hand over. */
 async function channelContext(slug, self) {

package/dist/core/chat/pi.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { workspaceEnv } from "../env.js";
+import { tempEnv } from "../temp.js";
 const clip = (raw) => {
     const oneLine = String(raw ?? "").replace(/\s+/g, " ").trim();
     return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
@@ -24,7 +25,7 @@ export function startPiBackend(cwd, hooks, tuning = {}) {
                 const proc = spawn("pi", ["-p", "--mode", "json", "--session-id", sessionId, ...tuningArgs], {
                     cwd,
                     stdio: ["pipe", "pipe", "pipe"],
-                    env: workspaceEnv(),
+                    env: { ...workspaceEnv(), ...(tuning.temp ? tempEnv(tuning.temp) : {}) },
                 });
                 child = proc;
                 proc.stdin.write(text);

package/dist/core/chat/seats.js

@@ -9,6 +9,7 @@ import { chatHref, dismissKey, pushNotification } from "../notifications.js";
 import { writeMeta } from "./store.js";
 import { availableSkills } from "./context.js";
 import { effectiveCwd } from "./sessions.js";
+import { sessionTemp } from "../temp.js";
 import { emit, isUnattended, ownerLabel, seatAuthor } from "./state.js";
 /**
  * Starting an agent process for a seat: its harness, tuning (model,
@@ -57,6 +58,8 @@ async function backendTuning(meta, seat) {
         if (skills.length > 0)
             tuning.skillDirs = skills.map((s) => s.dir);
     }
+    // Every seat gets the chat's scratch folder as its temp dir (core/temp.ts), so nothing temporary lands in files/ or /tmp.
+    tuning.temp = (await sessionTemp(meta.id)).abs;
     return tuning;
 }
 export async function ensureBackend(state, seat) {

package/dist/core/chat/sessions.js

@@ -7,6 +7,7 @@ import { deleteAgentSession, listAgentSessions } from "./acp.js";
 import { chatHref, pushNotification } from "../notifications.js";
 import { readIdentity } from "../identity.js";
 import { moveToTrash } from "../trash.js";
+import { removeSessionTemp } from "../temp.js";
 import { attachmentPath, copyChatFiles, listChatMetas, newChatId, readMetaAt, safeChatDir, writeMeta } from "./store.js";
 import { postChannelMessage } from "./channel-turns.js";
 import { expandSkillInvocation, scopeContext } from "./context.js";
@@ -526,6 +527,8 @@ export async function deleteChat(id) {
     dropBackend(state);
     chatStates().delete(id);
     await moveToTrash("chats", id, safeChatDir(id));
+    // Scratch, not a deliverable: gone for good with the chat.
+    await removeSessionTemp(id).catch(() => { });
     return {};
 }
 /** The agents' own transcripts of a chat folder (one in the trash), deleted for good. Best effort. */

package/dist/core/files.js

@@ -312,5 +312,6 @@ export async function filesContext(scope, heading, intro) {
     return (`## ${heading}\n${intro} ${s.root}/ — ${s.count} file${s.count === 1 ? "" : "s"}` +
         (recent ? `, most recently changed:\n${recent}\n` : " (empty so far)\n") +
         `Read and write them there like any folder; put what you produce for the user in ${s.root}/deliverables/. ` +
+        `Only finished work and the material the user gave you belong here — scratch, intermediate and downloaded files go to your temp folder (see Temporary files), never into this folder. ` +
         `Files over 25 MB stay out of git automatically. Delete nothing there unless asked.`);
 }

package/dist/core/projects.js

@@ -441,7 +441,7 @@ export async function projectContext(slug, actor, opts = {}) {
             ? `## Knowledge\nOKF bundles linked to this project (markdown + YAML frontmatter under the knowledge root):\n` +
                 linkLines("knowledge", (l) => `- ${l.slug}${l.label ? ` (${l.label})` : ""}`) +
                 `\nRead with \`npx kraftwerk knowledge list <bundle>\`, \`get <bundle>/<path>\`, \`search <text>\`. ` +
-                `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file <tmp.md> --actor ${actor}\` ` +
+                `Write ONLY through \`npx kraftwerk knowledge put <bundle>/<path> --file $KRAFTWERK_TEMP/<name>.md --actor ${actor}\` ` +
                 `(stamps provenance, maintains index.md/log.md — never hand-edit those).`
             : "",
         p.repos.length > 0

package/dist/core/temp.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The temp folder: where a session's scratch work goes — intermediate
+ * results, downloads, build output, a markdown written for a CLI to read —
+ * instead of the system's temp dir or, worse, the workspace's files.
+ *
+ *   kraftwerk-data/temp/<session-id>/   one folder per chat session
+ *   <run dir>/temp/                     a workflow run's (inside its mount)
+ *
+ * Three things make it stick, so it does not depend on an agent reading a
+ * sentence: the folder is handed to every spawned agent as TMPDIR (and
+ * TMP, TEMP, KRAFTWERK_TEMP), so mktemp, Python's tempfile, Node's
+ * os.tmpdir() and the agent's own scratchpad land there by themselves; it
+ * sits inside the workspace, so writes there need no approval from the
+ * harness; and the session prompt names it next to the files folders,
+ * which say in turn that nothing temporary belongs in them.
+ *
+ * The temp root is local: a .gitignore of its own keeps everything in it
+ * out of the workspace git (and `kraftwerk init` lists it too). Nothing in
+ * it is a deliverable, so nothing goes to the trash: a chat's folder is
+ * removed with the chat, and folders nobody touched for SWEEP_AFTER_MS are
+ * swept when a session starts (at most once an hour) or on demand
+ * (`kraftwerk temp clean`, DELETE /api/temp).
+ */
+export declare const TEMP_DIR = "kraftwerk-data/temp";
+/** A folder idle this long is swept. */
+export declare const SWEEP_AFTER_MS: number;
+export interface TempEntry {
+    /** The folder name: the session's id. */
+    id: string;
+    /** Relative to the workspace root, forward slashes. */
+    path: string;
+    files: number;
+    bytes: number;
+    /** The newest change inside (the folder's own when empty). */
+    modifiedAt: string;
+}
+export interface TempView {
+    root: string;
+    entries: TempEntry[];
+    bytes: number;
+}
+/** Absolute temp root of the current workspace. */
+export declare function tempRoot(): Promise<string>;
+/** The environment that points a process at `dir` for everything temporary. */
+export declare function tempEnv(dir: string): Record<string, string>;
+/** Create a folder outside the workspace's temp root (a workflow run's) and return the env for it. */
+export declare function tempEnvFor(dir: string): Promise<Record<string, string>>;
+/**
+ * A session's own folder, created: absolute path and the path relative to
+ * the workspace root (for the prompt). Starting a session is also when
+ * folders nobody uses any more are swept, at most once an hour.
+ */
+export declare function sessionTemp(id: string): Promise<{
+    abs: string;
+    rel: string;
+    env: Record<string, string>;
+}>;
+/** Remove one session's folder for good (nothing there is a deliverable). */
+export declare function removeSessionTemp(id: string): Promise<void>;
+/** Every session folder in the temp root, newest first. */
+export declare function listTemp(): Promise<TempView>;
+/**
+ * Remove session folders: all of them, or those idle longer than
+ * `olderThanMs` (default SWEEP_AFTER_MS). `keep` names folders that stay
+ * whatever their age (the session being started). Returns what went.
+ */
+export declare function cleanTemp(opts?: {
+    all?: boolean;
+    olderThanMs?: number;
+    keep?: string[];
+}): Promise<TempEntry[]>;
+/** The "## Temporary files" block of a session's context. */
+export declare function tempContext(rel: string): string;

package/dist/core/temp.js

@@ -0,0 +1,154 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { resolveWorkspace } from "../config.js";
+import { workspaceRoot } from "./context.js";
+import { perWorkspace } from "./workspace.js";
+/**
+ * The temp folder: where a session's scratch work goes — intermediate
+ * results, downloads, build output, a markdown written for a CLI to read —
+ * instead of the system's temp dir or, worse, the workspace's files.
+ *
+ *   kraftwerk-data/temp/<session-id>/   one folder per chat session
+ *   <run dir>/temp/                     a workflow run's (inside its mount)
+ *
+ * Three things make it stick, so it does not depend on an agent reading a
+ * sentence: the folder is handed to every spawned agent as TMPDIR (and
+ * TMP, TEMP, KRAFTWERK_TEMP), so mktemp, Python's tempfile, Node's
+ * os.tmpdir() and the agent's own scratchpad land there by themselves; it
+ * sits inside the workspace, so writes there need no approval from the
+ * harness; and the session prompt names it next to the files folders,
+ * which say in turn that nothing temporary belongs in them.
+ *
+ * The temp root is local: a .gitignore of its own keeps everything in it
+ * out of the workspace git (and `kraftwerk init` lists it too). Nothing in
+ * it is a deliverable, so nothing goes to the trash: a chat's folder is
+ * removed with the chat, and folders nobody touched for SWEEP_AFTER_MS are
+ * swept when a session starts (at most once an hour) or on demand
+ * (`kraftwerk temp clean`, DELETE /api/temp).
+ */
+export const TEMP_DIR = "kraftwerk-data/temp";
+/** A folder idle this long is swept. */
+export const SWEEP_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+const SWEEP_EVERY_MS = 60 * 60 * 1000;
+/** A session id as a folder name: what newChatId() produces, nothing that could leave the root. */
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,120}$/;
+async function resolvedRoot() {
+    const ws = await resolveWorkspace(workspaceRoot()).catch(() => null);
+    return ws?.root ?? workspaceRoot();
+}
+/** Absolute temp root of the current workspace. */
+export async function tempRoot() {
+    return path.join(await resolvedRoot(), TEMP_DIR);
+}
+/** Create the root and keep it out of the workspace git: a .gitignore of its own ignores everything in it, itself included. */
+async function prepare(root) {
+    await fs.mkdir(root, { recursive: true });
+    await fs.writeFile(path.join(root, ".gitignore"), "*\n", { flag: "wx" }).catch(() => { });
+}
+/** The environment that points a process at `dir` for everything temporary. */
+export function tempEnv(dir) {
+    return { KRAFTWERK_TEMP: dir, TMPDIR: dir, TMP: dir, TEMP: dir };
+}
+/** Create a folder outside the workspace's temp root (a workflow run's) and return the env for it. */
+export async function tempEnvFor(dir) {
+    await fs.mkdir(dir, { recursive: true });
+    return tempEnv(dir);
+}
+const lastSweep = perWorkspace(() => ({ at: 0 }));
+/**
+ * A session's own folder, created: absolute path and the path relative to
+ * the workspace root (for the prompt). Starting a session is also when
+ * folders nobody uses any more are swept, at most once an hour.
+ */
+export async function sessionTemp(id) {
+    if (!ID_RE.test(id))
+        throw new Error("invalid session id");
+    const root = await tempRoot();
+    await prepare(root);
+    const abs = path.join(root, id);
+    await fs.mkdir(abs, { recursive: true });
+    const sweep = lastSweep();
+    if (Date.now() - sweep.at > SWEEP_EVERY_MS) {
+        sweep.at = Date.now();
+        void cleanTemp({ keep: [id] }).catch(() => { });
+    }
+    return { abs, rel: `${TEMP_DIR}/${id}`, env: tempEnv(abs) };
+}
+/** Remove one session's folder for good (nothing there is a deliverable). */
+export async function removeSessionTemp(id) {
+    if (!ID_RE.test(id))
+        return;
+    await fs.rm(path.join(await tempRoot(), id), { recursive: true, force: true });
+}
+/** Files, bytes and the newest mtime below a folder. */
+async function measure(dir) {
+    const st = await fs.stat(dir);
+    const out = { files: 0, bytes: 0, newest: st.mtimeMs };
+    const walk = async (d) => {
+        if (out.files > 20000)
+            return;
+        for (const k of await fs.readdir(d, { withFileTypes: true }).catch(() => [])) {
+            const abs = path.join(d, k.name);
+            if (k.isDirectory())
+                await walk(abs);
+            else if (k.isFile()) {
+                const s = await fs.stat(abs).catch(() => null);
+                if (!s)
+                    continue;
+                out.files++;
+                out.bytes += s.size;
+                if (s.mtimeMs > out.newest)
+                    out.newest = s.mtimeMs;
+            }
+        }
+    };
+    await walk(dir);
+    return out;
+}
+/** Every session folder in the temp root, newest first. */
+export async function listTemp() {
+    const root = await tempRoot();
+    const kids = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+    const entries = [];
+    for (const k of kids) {
+        if (!k.isDirectory() || k.name.startsWith("."))
+            continue;
+        const m = await measure(path.join(root, k.name)).catch(() => null);
+        if (!m)
+            continue;
+        entries.push({ id: k.name, path: `${TEMP_DIR}/${k.name}`, files: m.files, bytes: m.bytes, modifiedAt: new Date(m.newest).toISOString() });
+    }
+    entries.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+    return { root, entries, bytes: entries.reduce((n, e) => n + e.bytes, 0) };
+}
+/**
+ * Remove session folders: all of them, or those idle longer than
+ * `olderThanMs` (default SWEEP_AFTER_MS). `keep` names folders that stay
+ * whatever their age (the session being started). Returns what went.
+ */
+export async function cleanTemp(opts = {}) {
+    const view = await listTemp();
+    const cutoff = Date.now() - (opts.olderThanMs ?? SWEEP_AFTER_MS);
+    const keep = new Set(opts.keep ?? []);
+    const gone = [];
+    for (const e of view.entries) {
+        if (keep.has(e.id))
+            continue;
+        if (!opts.all && Date.parse(e.modifiedAt) > cutoff)
+            continue;
+        await fs.rm(path.join(view.root, e.id), { recursive: true, force: true });
+        gone.push(e);
+    }
+    return gone;
+}
+/** The "## Temporary files" block of a session's context. */
+export function tempContext(rel) {
+    return (`## Temporary files\n` +
+        `Your scratch folder is ${rel}/ — TMPDIR (and KRAFTWERK_TEMP) point there, so \`mktemp\`, Python's tempfile, ` +
+        `os.tmpdir() and your own scratchpad land in it by themselves. Put everything that is not a result there: ` +
+        `intermediate output, downloads, extracted archives, build output, one-off scripts, a markdown written for a CLI ` +
+        `to read. It is private to this session, kept out of git, and removed when the session is deleted or after a week ` +
+        `unused — never store anything there you or the user want to keep. The files folders named above hold only what ` +
+        `the user keeps: what you produce for them, and the material they gave you. Never create temporary or ` +
+        `intermediate files there, and never in the system's temp dir.`);
+}

package/dist/harness.d.ts

@@ -47,6 +47,8 @@ export interface AgentInvocation {
     clis?: string[];
     /** MCP servers available in this phase, keyed by server name. */
     mcpServers?: Record<string, McpServerConfig>;
+    /** Extra environment for the agent process (the run's temp folder as TMPDIR, see core/temp.ts); on top of the workspace's. */
+    env?: Record<string, string>;
     resume?: string;
     onToolUse?: (tool: string, target: string) => void;
     onText?: (text: string) => void;

package/dist/harnesses/acp.js

@@ -83,7 +83,7 @@ async function open(agent, inv, resume) {
     };
     const { child, conn } = await connectAcp(agent, {
         cwd: inv.cwd,
-        env: adapterEnv(agent, { model: inv.model, effort: inv.effort }),
+        env: { ...adapterEnv(agent, { model: inv.model, effort: inv.effort }), ...inv.env },
         client,
         clientName: "kraftwerk",
         onError: (err) => end(`could not start the ${agent} adapter: ${err.message}`),

package/dist/harnesses/claude.js

@@ -38,6 +38,7 @@ function invokeClaude(inv) {
         const child = spawn("claude", args, {
             cwd: inv.cwd,
             stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...inv.env },
         });
         child.stdin.write(inv.prompt);
         child.stdin.end();

package/dist/harnesses/codex.js

@@ -62,6 +62,7 @@ function invokeCodex(inv) {
         const child = spawn("codex", args, {
             cwd: inv.cwd,
             stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...inv.env },
         });
         child.stdin.write(prompt);
         child.stdin.end();

package/dist/harnesses/pi.js

@@ -64,6 +64,7 @@ function invokePi(inv) {
         const child = spawn("pi", args, {
             cwd: inv.cwd,
             stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...inv.env },
         });
         child.stdin.write(inv.prompt);
         child.stdin.end();

package/dist/run.d.ts

@@ -39,6 +39,13 @@ export declare class Run {
     private readonly verbose;
     private readonly maxGateRetries;
     constructor(options: RunOptions);
+    /**
+     * The run's scratch folder, <run dir>/temp, as TMPDIR for every phase
+     * (core/temp.ts): inside the run dir so a sandboxed run finds it in its
+     * mount, created when the first phase starts.
+     */
+    private temp?;
+    private tempEnv;
     trace(event: string, data?: Record<string, unknown>): Promise<void>;
     agentPhase(params: {
         name: string;