@netnodeag/kraftwerk 0.79.0 → 0.81.0

package/dist/core/refs.js

@@ -0,0 +1,143 @@
+import { listAgents } from "./agents.js";
+import { CONTACTS, EVENTS, listEntities, PLACES } from "./entities.js";
+import { knowledgeIndex } from "./knowledge.js";
+import { listProjects } from "./projects.js";
+import { listRepos } from "./repos.js";
+import { listVibeables } from "./vibeables.js";
+import { listWorkflows } from "./workflows.js";
+/**
+ * The reference registry: everything in a workspace that can be pointed
+ * at by name — knowledge bundles, vibeables, repositories, workflows,
+ * agents, projects, contacts, places and events. Each kind registers only
+ * a lookup (its storage and routes stay where they are); one resolver then
+ * serves every place a reference appears: a project's link lists, an
+ * event's place and contacts, a `contact:anna-meier` token in text, the
+ * ⌘K palette and the context an agent starts with.
+ *
+ * A reference is `<token>:<slug>` — the kind's singular token (contact,
+ * place, event, project, agent, workflow, repo, vibeable, knowledge) and
+ * the target's slug. Only registered tokens match, so `https:` and the
+ * like never do. A target that does not exist is reported (found: false),
+ * never an error — the same rule project links have always followed.
+ */
+export const REF_KIND_NAMES = ["knowledge", "vibeables", "repos", "workflows", "agents", "projects", "contacts", "places", "events"];
+/** A list that fails to read is an empty list: a reference into it is "not found", never an error. */
+const safe = async (p, fallback) => p.catch(() => fallback);
+export const REF_KINDS = [
+    {
+        kind: "knowledge",
+        token: "knowledge",
+        noun: "knowledge bundle",
+        list: async () => (await safe(knowledgeIndex(), { bundles: [] })).bundles.map((b) => ({ slug: b.name, label: `${b.concepts} concepts`, href: `/knowledge/${b.name}` })),
+    },
+    {
+        kind: "vibeables",
+        token: "vibeable",
+        noun: "vibeable",
+        list: async () => (await safe(listVibeables(), { vibeables: [] })).vibeables.map((v) => ({ slug: v.slug, label: v.dev ? "dev" : "static", href: `/vibeables/${v.slug}` })),
+    },
+    {
+        kind: "repos",
+        token: "repo",
+        noun: "repository",
+        list: async () => (await safe(listRepos(), { repos: [] })).repos.map((r) => ({ slug: r.slug, label: r.branch ?? "", href: `/repos/${r.slug}` })),
+    },
+    {
+        kind: "workflows",
+        token: "workflow",
+        noun: "workflow",
+        list: async () => (await safe(listWorkflows(), { workflows: [] })).workflows.map((w) => ({ slug: w.slug, label: w.description ?? w.name ?? "", href: `/workflows/${w.slug}` })),
+    },
+    {
+        kind: "agents",
+        token: "agent",
+        noun: "agent",
+        list: async () => (await safe(listAgents(), []))
+            .filter((a) => !a.archived)
+            .map((a) => ({ slug: a.slug, label: `${a.emoji} ${a.name}`, href: `/agents/${a.slug}` })),
+    },
+    {
+        kind: "projects",
+        token: "project",
+        noun: "project",
+        list: async () => (await safe(listProjects(), { projects: [] })).projects.map((p) => ({ slug: p.slug, label: p.title, href: `/projects/${p.slug}` })),
+    },
+    {
+        kind: "contacts",
+        token: "contact",
+        noun: "contact",
+        list: async () => (await safe(listEntities(CONTACTS), { items: [] })).items.map((c) => ({ slug: c.slug, label: CONTACTS.describe(c), href: `/contacts/${c.slug}` })),
+    },
+    {
+        kind: "places",
+        token: "place",
+        noun: "place",
+        list: async () => (await safe(listEntities(PLACES), { items: [] })).items.map((p) => ({ slug: p.slug, label: PLACES.describe(p), href: `/places/${p.slug}` })),
+    },
+    {
+        kind: "events",
+        token: "event",
+        noun: "event",
+        list: async () => (await safe(listEntities(EVENTS), { items: [] })).items.map((e) => ({ slug: e.slug, label: EVENTS.describe(e), href: `/events/${e.slug}` })),
+    },
+];
+const byKind = new Map(REF_KINDS.map((d) => [d.kind, d]));
+const byToken = new Map(REF_KINDS.map((d) => [d.token, d]));
+/** The kind registered under a plural name or a token; undefined for anything else. */
+export const refKind = (name) => byKind.get(name) ?? byToken.get(name);
+/** The link states of some slugs against one list of targets. */
+const states = (slugs, targets) => slugs.map((slug) => {
+    const t = targets.find((x) => x.slug === slug);
+    return t ? { slug, found: true, ...(t.label ? { label: t.label } : {}) } : { slug, found: false };
+});
+/** Which of the slugs exist right now, per kind. Kinds without slugs are not listed at all. */
+export async function resolveRefs(byKind) {
+    const out = {};
+    await Promise.all(Object.keys(byKind).map(async (kind) => {
+        const slugs = byKind[kind];
+        const def = refKind(kind);
+        out[kind] = !def || slugs.length === 0 ? [] : states(slugs, await def.list());
+    }));
+    return out;
+}
+const SLUG = "[a-z0-9][a-z0-9-]{0,48}";
+/** A `token:slug` reference in text: a registered token, a colon, a slug — not inside a word, a path or a URL. */
+export const REF_TOKEN_RE = new RegExp(`(?<![\\w/:.@-])(${REF_KINDS.map((d) => d.token).join("|")}):(${SLUG})(?![\\w-])`, "g");
+/** Every distinct reference in a text, in order of appearance. */
+export function findRefs(text) {
+    const seen = new Set();
+    const out = [];
+    for (const m of text.matchAll(REF_TOKEN_RE)) {
+        const token = m[0];
+        if (seen.has(token))
+            continue;
+        seen.add(token);
+        out.push({ token, kind: byToken.get(m[1]).kind, slug: m[2] });
+    }
+    return out;
+}
+/** Parse one reference ("contact:anna-meier"); null when it is not one. */
+export function parseRef(text) {
+    const m = new RegExp(`^(${REF_KINDS.map((d) => d.token).join("|")}|${REF_KIND_NAMES.join("|")}):(${SLUG})$`).exec(text.trim());
+    if (!m)
+        return null;
+    const def = refKind(m[1]);
+    return { token: `${def.token}:${m[2]}`, kind: def.kind, slug: m[2] };
+}
+/** Resolve references: each with whether its target exists and where it opens. */
+export async function resolveTokens(refs) {
+    const kinds = [...new Set(refs.map((r) => r.kind))];
+    const lists = new Map(await Promise.all(kinds.map(async (k) => [k, await refKind(k).list()])));
+    return refs.map((r) => {
+        const def = refKind(r.kind);
+        const t = lists.get(r.kind).find((x) => x.slug === r.slug);
+        return { kind: r.kind, token: `${def.token}:${r.slug}`, slug: r.slug, found: !!t, ...(t?.label ? { label: t.label } : {}), href: t?.href ?? `/${r.kind}/${r.slug}` };
+    });
+}
+/** Resolve one reference written as text; null when the text is not a reference. */
+export async function resolveRef(text) {
+    const ref = parseRef(text);
+    if (!ref)
+        return null;
+    return (await resolveTokens([ref]))[0];
+}

package/dist/core/search.d.ts

@@ -25,6 +25,16 @@ export interface WorkspaceAgents {
     channels: ChannelSummary[];
     /** Projects that are not archived; empty when the feature is off. */
     projects: ProjectHit[];
+    /** Contacts, places and events of this instance (the registry does not carry them); empty for other workspaces and while the features are off. */
+    entities: EntityHit[];
+}
+/** What the palette needs of a contact, place or event. */
+export interface EntityHit {
+    kind: "contacts" | "places" | "events";
+    slug: string;
+    title: string;
+    /** The rest of its one-line description (role and org, address, date). */
+    detail?: string;
 }
 export interface AgentSearch {
     workspaces: WorkspaceAgents[];

package/dist/core/search.js

@@ -4,7 +4,17 @@ import { workspaceRoot } from "./context.js";
 import { listAgents, toSummary } from "./agents.js";
 import { listChannels, toChannelSummary } from "./channels.js";
 import { currentInstanceUrl, discoverWorkspaces, listWorkspaceRecords } from "./instances.js";
+import { CONTACTS, EVENTS, listEntities, PLACES } from "./entities.js";
 import { listProjects, toProjectHit } from "./projects.js";
+async function entityHits(def) {
+    const view = await listEntities(def).catch(() => ({ items: [] }));
+    return view.items
+        .filter((e) => !e.configError)
+        .map((e) => {
+        const detail = def.detail(e);
+        return { kind: def.kind, slug: e.slug, title: e.title, ...(detail ? { detail } : {}) };
+    });
+}
 export async function searchAgents() {
     const project = await resolveWorkspace(workspaceRoot()).catch(() => null);
     const self = {
@@ -17,6 +27,7 @@ export async function searchAgents() {
         agents: (await listAgents().catch(() => [])).filter((a) => !a.archived).map(toSummary),
         channels: (await listChannels().catch(() => [])).map(toChannelSummary),
         projects: (await listProjects().catch(() => ({ projects: [] }))).projects.filter((p) => p.status !== "archived").map(toProjectHit),
+        entities: (await Promise.all([CONTACTS, PLACES, EVENTS].map(entityHits))).flat(),
     };
     const [workspaces, known] = await Promise.all([discoverWorkspaces(), listWorkspaceRecords()]);
     const records = new Map(known.map((p) => [p.root, p]));
@@ -33,6 +44,7 @@ export async function searchAgents() {
         agents: records.get(w.root)?.agents ?? [],
         channels: records.get(w.root)?.channels ?? [],
         projects: records.get(w.root)?.projects ?? [],
+        entities: [],
     }));
     return { workspaces: [self, ...others] };
 }

package/dist/core/settings.d.ts

@@ -32,6 +32,10 @@ export interface SaveSettingsInput {
     vibeables?: ReposSettingsInput;
     /** Omitted = untouched. Same shape and rules as repos. */
     projects?: ReposSettingsInput;
+    /** Omitted = untouched. Same shape and rules as repos. */
+    contacts?: ReposSettingsInput;
+    places?: ReposSettingsInput;
+    events?: ReposSettingsInput;
 }
 export interface ReposSettingsInput {
     enabled: boolean;

package/dist/core/settings.js

@@ -1,7 +1,8 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "yaml";
-import { ignoreEntryFor, PROJECTS_DEFAULT_ROOT, REPOS_DEFAULT_ROOT, resolveWorkspace, VIBEABLES_DEFAULT_ROOT, isSafeGitName } from "../config.js";
+import { ENTITY_KINDS, entityDefaultRoot, ignoreEntryFor, PROJECTS_DEFAULT_ROOT, REPOS_DEFAULT_ROOT, resolveWorkspace, VIBEABLES_DEFAULT_ROOT, isSafeGitName } from "../config.js";
+import { ensureEntitiesRoot } from "./entities.js";
 import { ensureProjectsRoot } from "./projects.js";
 import { disposeAllDevs, ensureVibeablesRoot } from "./vibeables.js";
 import { workspaceRoot } from "./context.js";
@@ -76,8 +77,15 @@ function cleanGit(value) {
         return null;
     return { enabled: false, ...out };
 }
-const ROOT_DEFAULTS = { repos: REPOS_DEFAULT_ROOT, vibeables: VIBEABLES_DEFAULT_ROOT, projects: PROJECTS_DEFAULT_ROOT };
-/** The repos, vibeables or projects block to write; null when the feature is off and nothing else is set. */
+const ROOT_DEFAULTS = {
+    repos: REPOS_DEFAULT_ROOT,
+    vibeables: VIBEABLES_DEFAULT_ROOT,
+    projects: PROJECTS_DEFAULT_ROOT,
+    contacts: entityDefaultRoot("contacts"),
+    places: entityDefaultRoot("places"),
+    events: entityDefaultRoot("events"),
+};
+/** The repos, vibeables, projects, contacts, places or events block to write; null when the feature is off and nothing else is set. */
 function cleanRootBlock(block, value, projectRoot) {
     if (typeof value !== "object" || value === null)
         throw new Error(`${block} must be an object`);
@@ -163,6 +171,16 @@ export async function saveSettings(input) {
         else
             doc.set("projects", projects);
     }
+    for (const kind of ENTITY_KINDS) {
+        const given = input[kind];
+        if (given === undefined)
+            continue;
+        const block = cleanRootBlock(kind, given, project.root);
+        if (block === null)
+            doc.delete(kind);
+        else
+            doc.set(kind, block);
+    }
     await fs.writeFile(configPath, doc.toString());
     // Turning repositories on prepares the folder so the first clone and the
     // workspace git both find it in the right state.
@@ -172,5 +190,8 @@ export async function saveSettings(input) {
         await ensureVibeablesRoot().catch(() => { });
     if (input.projects?.enabled)
         await ensureProjectsRoot().catch(() => { });
+    for (const kind of ENTITY_KINDS)
+        if (input[kind]?.enabled)
+            await ensureEntitiesRoot(kind).catch(() => { });
     return getSettings();
 }

package/dist/core/slug.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one slug rule for folders and files kraftwerk names after a title:
+ * lowercase letters, digits and dashes, at most 49 characters, starting
+ * with a letter or digit. Projects, contacts, places and events share it,
+ * so a `kind:slug` reference has one shape everywhere.
+ */
+export declare const SLUG_RE: RegExp;
+/** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
+export declare function slugify(title: string, max?: number): string;

package/dist/core/slug.js

@@ -0,0 +1,18 @@
+/**
+ * The one slug rule for folders and files kraftwerk names after a title:
+ * lowercase letters, digits and dashes, at most 49 characters, starting
+ * with a letter or digit. Projects, contacts, places and events share it,
+ * so a `kind:slug` reference has one shape everywhere.
+ */
+export const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
+/** Derive a slug from a title: "Relaunch netnode.ch" -> "relaunch-netnode-ch". */
+export function slugify(title, max = 48) {
+    return title
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, max)
+        .replace(/-+$/, "");
+}

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/core/trash.d.ts

@@ -8,7 +8,7 @@
  */
 export declare const TRASH_DIR = "kraftwerk-data/trash";
 /** What can be in the trash; also the folder under trash/ it lands in. */
-export type TrashKind = "agents" | "agent-skills" | "projects" | "workflows" | "knowledge" | "vibeables" | "channels" | "repos" | "chats" | "runs" | "files";
+export type TrashKind = "agents" | "agent-skills" | "projects" | "contacts" | "places" | "events" | "workflows" | "knowledge" | "vibeables" | "channels" | "repos" | "chats" | "runs" | "files";
 export interface TrashEntry {
     /** Path inside the trash, forward slashes — the entry's handle. */
     id: string;

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;

package/dist/run.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { harnessFor } from "./harnesses/registry.js";
 import { correctionPrompt, parseEnvelope } from "./envelope.js";
 import { fmtDuration, phaseStatsLine, summaryTable } from "./stats.js";
+import { tempEnvFor } from "./core/temp.js";
 export class Run {
     /** Session per harness AND protocol: a CLI session id means nothing to the ACP adapter and vice versa. */
     sessions = new Map();
@@ -19,6 +20,15 @@ export class Run {
         this.verbose = options.verbose ?? false;
         this.maxGateRetries = options.maxGateRetries ?? 2;
     }
+    /**
+     * 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.
+     */
+    temp;
+    tempEnv() {
+        return (this.temp ??= tempEnvFor(path.join(this.runDir, "temp")));
+    }
     async trace(event, data = {}) {
         await appendFile(path.join(this.runDir, "trace.jsonl"), JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + "\n");
     }
@@ -78,6 +88,7 @@ export class Run {
                 tools: agent.tools,
                 clis: cliEntries.map(([name]) => name),
                 mcpServers: agent.mcp,
+                env: await this.tempEnv(),
                 resume: this.sessions.get(sessionKey),
                 onToolUse: (tool, target) => {
                     console.log(`  ⚙ ${tool} ${target}`.trimEnd());
@@ -160,10 +171,11 @@ export class Run {
         console.log(`\n▸ Phase "${params.name}" — script (bash)`);
         await this.trace("phase_start", { phase: params.name, kind: "script" });
         const started = Date.now();
+        const temp = await this.tempEnv();
         const result = await new Promise((resolve, reject) => {
             const child = spawn("bash", ["-c", params.script], {
                 cwd: this.runDir,
-                env: { ...process.env, RUN_DIR: this.runDir, PHASE: params.name, ...params.env },
+                env: { ...process.env, ...temp, RUN_DIR: this.runDir, PHASE: params.name, ...params.env },
             });
             let stdout = "";
             let stderr = "";

package/dist/server/api/devices.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { log } from "../../core/log.js";
 import { createPairCode, listDevices, redeemPairCode, revokeDevice, setDevicePush } from "../../core/devices.js";
 import { networkUrls } from "../bind.js";
 import { currentHub } from "../hub-context.js";
@@ -108,7 +109,7 @@ export const deviceRoutes = [
         const { enabled, url } = await c.body();
         const s = await setRelay(enabled, url);
         const hub = currentHub();
-        const status = hub.daemon ? await applyRelay(hub.port, await getPkgVersion(), (l) => console.log(l)) : relayStatus();
+        const status = hub.daemon ? await applyRelay(hub.port, await getPkgVersion(), (level, l) => log(level, "relay", l)) : relayStatus();
         return { enabled: s.enabled, url: s.url, fingerprint: keyFingerprint(s.publicKey), daemon: hub.daemon === true, ...status };
     }),
     route({ name: "devices.revoke", method: "DELETE", path: "/api/devices/:id", summary: "unpair a device: its token stops working at once", access: "local" }, async (c) => (await revokeDevice(c.params.id)) ? { ok: true } : fail(404, "no such device")),