@netnodeag/kraftwerk 0.36.0 → 0.37.1

package/README.md

@@ -180,7 +180,7 @@ 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/`).
+`agents/`). `repos:` turns on the [repositories](#repositories) folder.
 
 `switcher:` links other kraftwerk workspaces from the inspector header. The
 workspace name becomes a dropdown listing them:
@@ -296,6 +296,44 @@ the model via ACP session options and the thinking budget via
 are created and edited in the UI, or by editing the files, since the
 definition is read fresh for each new session.
 
+### Repositories
+
+Turn on `repos:` in `kraftwerk.yml` (or the checkbox in settings) and the
+workspace gets one folder for the git repositories its agents work on:
+
+```yaml
+repos:
+  root: kraftwerk-data/repos   # default: repos/ — git-ignored, never synced
+```
+
+The folder is the registry. Whatever has a `.git` directly under the root is
+a repository, whether the "repositories" screen cloned it, `kraftwerk repos
+add <url>` did, or an agent ran `git clone` there. Every entry is read live
+from git: origin, branch, head, uncommitted changes, ahead/behind. The
+screen clones by url, fetches and fast-forwards clean clones, and removes
+them (refusing while they hold unpushed or uncommitted work). Cloning uses
+your own git credentials and never prompts, so a private remote has to work
+from a terminal first.
+
+Every agent, and the inspector assistant, gets the list as context: where
+the root is, what is cloned, and how to add more with the CLI. So "look at
+the widgets repo" works as soon as it is cloned, and "clone
+github:org/widgets and look at it" works before.
+
+```bash
+kraftwerk repos                                  # name, branch, head, state
+kraftwerk repos add github:org/widgets           # or any https / ssh url
+kraftwerk repos add <url> --name tools --branch dev
+kraftwerk repos add <url> --depth 1              # shallow clone of a large repository
+kraftwerk repos update widgets                   # fetch, fast-forward when clean
+kraftwerk repos remove widgets [--force]
+```
+
+`GET /api/repos` returns the same list for automation. The root must be a
+folder inside the project (never the project itself): it is excluded from the
+workspace git sync, the first clone adds it to `.gitignore`, and `kraftwerk
+doctor` warns when git does not ignore it.
+
 ### Skills in chat
 
 Chats, both general ones and agent sessions, can use skills. These are

package/dist/cli/doctor.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { isDir, resolveProject } from "../config.js";
+import { ignoreEntryFor, isDir, reposRootFor, resolveProject } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
 const ICONS = {
@@ -106,6 +106,23 @@ export async function runDoctor(cwd) {
             }
         }
     }
+    // Repositories: the clones root must stay out of the workspace git. git
+    // itself decides — that covers worktrees (.git is a file), a workspace
+    // nested in a larger repo, a .gitignore at the toplevel, global excludes.
+    const reposRoot = reposRootFor(project);
+    if (reposRoot) {
+        const entry = ignoreEntryFor(project.root, reposRoot) ?? path.relative(project.root, reposRoot);
+        const label = `repos: ${path.relative(cwd, reposRoot) || "."}`;
+        const check = spawnSync("git", ["check-ignore", "-q", "--", reposRoot], { cwd: project.root, encoding: "utf8" });
+        if (check.error)
+            report("info", label, "git not found — cannot check .gitignore");
+        else if (check.status === 0)
+            report("ok", label, "git-ignored");
+        else if (check.status === 1)
+            report("warn", label, `${entry}/ is not git-ignored — clones would show up as untracked gitlinks; add it to .gitignore`);
+        else
+            report("ok", label, "not inside a git repository");
+    }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {
         report("warn", "no workflows root", "expected src/workflows/ or workflows/ — `kraftwerk init` scaffolds one");

package/dist/cli/init.js

@@ -1,7 +1,7 @@
 import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { CONFIG_SCHEMA_URL, SCHEMA_URL } from "../config.js";
+import { CONFIG_SCHEMA_URL, gitignoreHas, SCHEMA_URL } from "../config.js";
 import { initBundle, writeConcept } from "../okf.js";
 /**
  * `kraftwerk init` — make any repository a kraftwerk consumer in one
@@ -22,6 +22,8 @@ output: ${DATA_DIR}/output         # where run artifacts land (git-ignored)
 knowledge: ${DATA_DIR}/knowledge   # OKF knowledge bundles
 agents: ${DATA_DIR}/agents         # agent definitions
 skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packages)
+# repos:                          # git repositories the agents work on (uncomment both lines to enable)
+#   root: ${DATA_DIR}/repos       # clones land here (git-ignored); a bare \`repos:\` uses repos/ instead
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello
@@ -124,20 +126,25 @@ export async function runInit(cwd) {
         await writeConcept(knowledgeRoot, DEMO_BUNDLE, "playbooks/refunds", DEMO_CONCEPT, "kraftwerk-init");
         created.push(bundleRel);
     }
-    // .gitignore: append the output dir if it's not covered yet.
-    const outputEntry = `${DATA_DIR}/output`;
+    // .gitignore: the output dir and the repos root (clones must never become
+    // gitlinks of the workspace repo). A missing file gets both 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`];
     if (gitignore === null) {
-        await writeFile(gitignorePath, `${outputEntry}/\n`);
+        await writeFile(gitignorePath, entries.map((e) => `${e}/\n`).join(""));
         created.push(".gitignore");
     }
-    else if (!gitignore.split("\n").some((l) => l.trim().replace(/\/$/, "") === outputEntry)) {
-        await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${outputEntry}/\n`);
-        created.push(`.gitignore (${outputEntry}/ added)`);
-    }
     else {
-        skipped.push(".gitignore");
+        const missing = entries.filter((e) => !gitignoreHas(gitignore, e));
+        if (missing.length === 0) {
+            skipped.push(".gitignore");
+        }
+        else {
+            await appendFile(gitignorePath, `${gitignore.endsWith("\n") ? "" : "\n"}${missing.map((e) => `${e}/\n`).join("")}`);
+            created.push(`.gitignore (${missing.map((e) => `${e}/`).join(", ")} added)`);
+        }
     }
     for (const f of created)
         console.log(`${chalk.green("✔")} ${f}`);

package/dist/cli/kraftwerk.js

@@ -13,6 +13,7 @@ import { runDoctor } from "./doctor.js";
 import { runInit } from "./init.js";
 import { registerKnowledgeCommands } from "./knowledge.js";
 import { registerProjectCommands } from "./projects.js";
+import { registerRepoCommands } from "./repos.js";
 import { registerRoutineCommands } from "./routines.js";
 import { listRuns, showRun } from "./runs.js";
 import { runUi } from "./ui.js";
@@ -27,6 +28,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk routines ...            per-agent scheduled prompts (list/add/remove/enable/run)
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk projects ...            known projects on this machine (list/start/forget)
+ *   kraftwerk repos ...               repositories the agents work on (list/add/update/remove)
  *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
  *   kraftwerk validate [paths...]     validate without executing
  *
@@ -259,6 +261,7 @@ runs
 registerKnowledgeCommands(program);
 registerRoutineCommands(program);
 registerProjectCommands(program);
+registerRepoCommands(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/projects.d.ts

@@ -1,2 +1,16 @@
 import type { Command } from "commander";
+/**
+ * `kraftwerk projects` — every project that ever ran the inspector on this
+ * machine (~/.kraftwerk/projects), joined with what is running right now.
+ * The answer to "where did I start that UI, and how do I get it back":
+ *
+ *   kraftwerk projects                 list: name, root, running/stopped
+ *   kraftwerk projects start <ref>     relaunch `kraftwerk ui` in that root, detached
+ *   kraftwerk projects stop <ref>      SIGTERM a running UI (also ones started in a terminal)
+ *   kraftwerk projects forget <ref>    drop the record (the folder stays)
+ *
+ * <ref> is a project name, the root's folder name, the root path, or a
+ * port / localhost:port for running instances that recorded no root.
+ */
+export declare const fmtAgo: (iso?: string) => string;
 export declare function registerProjectCommands(program: Command): void;

package/dist/cli/projects.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import chalk from "chalk";
+import { absolutePath } from "../config.js";
 import Table from "cli-table3";
 import { discoverWorkspaces, forgetProject, startProject, stopProject, tildify, } from "../inspector/instances.js";
 /**
@@ -15,7 +16,7 @@ import { discoverWorkspaces, forgetProject, startProject, stopProject, tildify,
  * <ref> is a project name, the root's folder name, the root path, or a
  * port / localhost:port for running instances that recorded no root.
  */
-const fmtAgo = (iso) => {
+export const fmtAgo = (iso) => {
     if (!iso)
         return "—";
     const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
@@ -43,7 +44,7 @@ const status = (e) => {
 /** Match a ref against known workspaces; `needRoot` excludes rootless live instances (start/forget need a root). */
 async function resolveRef(ref, needRoot = true) {
     const all = (await discoverWorkspaces()).filter((e) => e.root || !needRoot);
-    const abs = path.resolve(ref);
+    const abs = absolutePath(ref);
     const port = /^\d+$/.test(ref) ? `http://localhost:${ref}` : `http://${ref.replace(/^https?:\/\//, "")}`;
     const hits = all.filter((e) => e.root === abs ||
         e.root === ref ||

package/dist/cli/repos.d.ts

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

package/dist/cli/repos.js

@@ -0,0 +1,115 @@
+import chalk from "chalk";
+import Table from "cli-table3";
+import { addRepo, listRepos, removeRepo, updateRepo } from "../inspector/repos.js";
+import { fmtAgo } from "./projects.js";
+import { initContext as prepare } from "./routines.js";
+/**
+ * `kraftwerk repos` — the git repositories the agents work on, kept under
+ * the project's repos root (`repos.root` in kraftwerk.yml). The same module
+ * the inspector uses, so a clone made here shows up on the repositories
+ * screen and in every agent's context at once:
+ *
+ *   kraftwerk repos                        list: name, branch, head, state
+ *   kraftwerk repos add <url> [--name x] [--branch b] [--depth n]
+ *   kraftwerk repos update <name>          fetch, fast-forward when clean
+ *   kraftwerk repos remove <name> [--force]
+ */
+const die = (msg) => {
+    console.error(chalk.red(msg));
+    process.exit(1);
+};
+export function registerRepoCommands(program) {
+    const repos = program
+        .command("repos")
+        .description("Repositories the agents work on: list, clone one into the repos root, update, remove");
+    repos
+        .command("list", { isDefault: true })
+        .description("List the clones under the repos root with branch, head and state")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await prepare();
+        const view = await listRepos();
+        if (opts.json) {
+            console.log(JSON.stringify(view, null, 2));
+            return;
+        }
+        if (!view.enabled)
+            die(view.error ?? "repositories are off");
+        if (view.repos.length === 0) {
+            console.log(chalk.dim(`No repositories under ${view.root} yet — \`kraftwerk repos add <url>\` clones one.`));
+            return;
+        }
+        const table = new Table({
+            head: ["name", "branch", "head", "state", "url"].map((h) => chalk.bold(h)),
+            wordWrap: true,
+            colWidths: [22, 16, 30, 18, 40],
+        });
+        for (const r of view.repos) {
+            const state = r.error
+                ? chalk.red(r.error)
+                : [
+                    r.dirty ? chalk.yellow(`${r.dirty} changed`) : "",
+                    r.ahead ? chalk.green(`${r.ahead}↑`) : "",
+                    r.behind ? chalk.cyan(`${r.behind}↓`) : "",
+                ]
+                    .filter(Boolean)
+                    .join(" ") || chalk.dim("clean");
+            table.push([
+                chalk.cyan(r.slug),
+                r.branch ?? "—",
+                r.head ? `${r.head} ${chalk.dim(r.subject ?? "")}\n${chalk.dim(fmtAgo(r.committedAt))}` : "—",
+                state,
+                r.url ?? chalk.dim("(no origin)"),
+            ]);
+        }
+        console.log(table.toString());
+        console.log(chalk.dim(view.root ?? ""));
+    });
+    repos
+        .command("add")
+        .description("Clone a repository into the repos root")
+        .argument("<url>", "git url, or github:org/repo")
+        .option("--name <name>", "Folder name under the root (default: last url segment)")
+        .option("--branch <branch>", "Branch to check out")
+        .option("--depth <n>", "Shallow clone with n commits of history (large repositories)")
+        .option("--json", "Print the new entry as JSON")
+        .action(async (url, opts) => {
+        await prepare();
+        try {
+            const depth = opts.depth === undefined ? undefined : Number(opts.depth);
+            const repo = await addRepo({ url, name: opts.name, branch: opts.branch, depth });
+            if (opts.json)
+                console.log(JSON.stringify(repo, null, 2));
+            else
+                console.log(`${chalk.green("✔")} ${chalk.cyan(repo.slug)} → ${repo.path}${repo.branch ? chalk.dim(` (${repo.branch})`) : ""}`);
+        }
+        catch (err) {
+            die(err.message);
+        }
+    });
+    repos
+        .command("update")
+        .description("Fetch a repository and fast-forward it when it is clean")
+        .argument("<name>", "Folder name under the root")
+        .action(async (name) => {
+        await prepare();
+        const r = await updateRepo(name).catch((err) => ({ ok: false, error: err.message, repo: undefined }));
+        if (!r.ok)
+            die(r.error ?? "update failed");
+        const repo = r.repo;
+        const tail = r.error ? chalk.yellow(` — ${r.error}`) : "";
+        console.log(`${chalk.green("✔")} ${chalk.cyan(name)} at ${repo.head} ${chalk.dim(repo.subject ?? "")}${tail}`);
+    });
+    repos
+        .command("remove")
+        .description("Delete a clone from the repos root (refused while it holds unpushed or uncommitted work)")
+        .argument("<name>", "Folder name under the root")
+        .option("--force", "Delete even with local changes")
+        .action(async (name, opts) => {
+        await prepare();
+        const r = await removeRepo(name, !!opts.force).catch((err) => ({ ok: false, error: err.message }));
+        if (!r.ok)
+            die(r.error ?? "remove failed");
+        console.log(`${chalk.green("✔")} removed ${chalk.cyan(name)}`);
+    });
+}

package/dist/cli/routines.d.ts

@@ -1,2 +1,12 @@
 import type { Command } from "commander";
+/**
+ * `kraftwerk routines` — CLI surface over per-agent scheduled prompts
+ * (agents/<slug>/routines.yml). Definition CRUD works directly on the
+ * files; `run` fires through the running inspector server, because the
+ * session (chat) and the scheduler live there.
+ */
+/** Point the inspector context at this project so agent/routine paths resolve. */
+export declare function initContext(): Promise<{
+    port: number;
+}>;
 export declare function registerRoutineCommands(program: Command): void;

package/dist/cli/routines.js

@@ -12,7 +12,7 @@ import { getAgent, listAgents } from "../inspector/agents.js";
  * session (chat) and the scheduler live there.
  */
 /** Point the inspector context at this project so agent/routine paths resolve. */
-async function initContext() {
+export async function initContext() {
     const project = await resolveProject(process.cwd());
     setProjectRoot(project.root);
     setOutputDir(project.outputDir);

package/dist/cli/ui.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, spawnSync } from "node:child_process";
 import chalk from "chalk";
-import { resolveProject } from "../config.js";
+import { absolutePath, resolveProject } from "../config.js";
 import { selfCommand } from "../inspector/self-command.js";
 import { RESTART_EXIT_CODE, startInspector } from "../inspector/server.js";
 /**
@@ -52,7 +52,7 @@ export async function runUi(cwd, opts) {
         return superviseUi(opts);
     const staticDir = ensureBuilt();
     const project = await resolveProject(cwd);
-    const outputDir = opts.output ? path.resolve(cwd, opts.output) : project.outputDir;
+    const outputDir = opts.output ? absolutePath(opts.output, cwd) : project.outputDir;
     // Port precedence: --port flag > kraftwerk.yml `port` > 1981.
     const port = opts.port ? Number(opts.port) : (project.config.port ?? 1981);
     await startInspector({ outputDir, staticDir, port, projectRoot: project.root });

package/dist/config.d.ts

@@ -25,6 +25,8 @@
  *     remote: origin
  *     interval: 300            # seconds between background fetches
  *     autosync: pull           # off | pull
+ *   repos:                     # git repositories the agents work on (absent = off, bare key = on)
+ *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -49,6 +51,29 @@ export interface GitConfig {
     /** off = fetch only. pull = also fast-forward when behind and clean. Default: pull. */
     autosync?: "off" | "pull";
 }
+/**
+ * Repositories: git clones the agents work on, kept under one root inside
+ * the project so every agent finds them at a known path. The root is never
+ * synced by the workspace git and should be git-ignored.
+ */
+export interface ReposConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /** Where clones land, relative to the project root. Default: repos */
+    root?: string;
+}
+/** Where clones land when `repos.root` is not set. */
+export declare const REPOS_DEFAULT_ROOT = "repos";
+/**
+ * Absolute repos root when the feature is on, undefined otherwise. The one
+ * place that reads the block, so the sync exclude, the doctor check, the
+ * settings save and the module itself cannot disagree.
+ */
+export declare function reposRootFor(project: Project): string | undefined;
+/** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
+export declare function ignoreEntryFor(projectRoot: string, dir: string): string | undefined;
+/** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
+export declare function gitignoreHas(text: string, entry: string): boolean;
 /** One entry of the workspace switcher: another kraftwerk instance to link to. */
 export interface SwitcherEntry {
     /** Display name of the other workspace. */
@@ -79,6 +104,8 @@ export interface ProjectConfig {
     switcher?: SwitcherEntry[];
     /** Workspace git sync. Absent = off. */
     git?: GitConfig;
+    /** Repositories the agents work on. Absent = off. */
+    repos?: ReposConfig;
 }
 export interface Project {
     /** Absolute project root the CLI operates on. */
@@ -93,6 +120,14 @@ export interface Project {
     outputDir: string;
 }
 /** True when the path exists and is a directory. */
+/**
+ * A user-supplied path as an absolute one: a leading `~` is the home
+ * directory (shells expand it, JSON bodies and quoted args do not), then
+ * path.resolve. Every path that gets stored or compared — registry roots,
+ * `--output`, project refs — goes through here so nothing ever persists
+ * `~/…` or `<cwd>/~/…`.
+ */
+export declare function absolutePath(p: string, from?: string): string;
 export declare const isDir: (p: string) => Promise<boolean>;
 /**
  * Resolve the project for a cwd: walk up until a kraftwerk.yml or a

package/dist/config.js

@@ -1,4 +1,5 @@
 import { readFile, stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { parse } from "yaml";
 /**
@@ -28,6 +29,8 @@ import { parse } from "yaml";
  *     remote: origin
  *     interval: 300            # seconds between background fetches
  *     autosync: pull           # off | pull
+ *   repos:                     # git repositories the agents work on (absent = off, bare key = on)
+ *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -35,8 +38,44 @@ export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk
 export const CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/kraftwerk.schema.json";
 export const CONFIG_FILENAMES = ["kraftwerk.yml", "kraftwerk.yaml"];
 const WORKFLOW_ROOT_CANDIDATES = ["src/workflows", "workflows"];
+/** Where clones land when `repos.root` is not set. */
+export const REPOS_DEFAULT_ROOT = "repos";
+/**
+ * Absolute repos root when the feature is on, undefined otherwise. The one
+ * place that reads the block, so the sync exclude, the doctor check, the
+ * settings save and the module itself cannot disagree.
+ */
+export function reposRootFor(project) {
+    const r = project.config.repos;
+    if (!r || r.enabled === false)
+        return undefined;
+    return path.resolve(project.root, r.root ?? REPOS_DEFAULT_ROOT);
+}
+/** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
+export function ignoreEntryFor(projectRoot, dir) {
+    const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
+    if (!rel || rel === "." || rel.startsWith(".."))
+        return undefined;
+    return rel;
+}
+/** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
+export function gitignoreHas(text, entry) {
+    return text.split("\n").some((l) => l.trim().replace(/^\//, "").replace(/\/$/, "") === entry);
+}
 const exists = async (p) => !!(await stat(p).catch(() => null));
 /** True when the path exists and is a directory. */
+/**
+ * A user-supplied path as an absolute one: a leading `~` is the home
+ * directory (shells expand it, JSON bodies and quoted args do not), then
+ * path.resolve. Every path that gets stored or compared — registry roots,
+ * `--output`, project refs — goes through here so nothing ever persists
+ * `~/…` or `<cwd>/~/…`.
+ */
+export function absolutePath(p, from = process.cwd()) {
+    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\"))
+        p = path.join(os.homedir(), p.slice(1));
+    return path.resolve(from, p);
+}
 export const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
 async function findConfigFile(dir) {
     for (const name of CONFIG_FILENAMES) {
@@ -87,7 +126,7 @@ export async function resolveProject(cwd) {
     const root = gitFallback ?? start;
     return { root, config: {}, outputDir: path.join(root, "output") };
 }
-const KNOWN_KEYS = ["name", "icon", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git"];
+const KNOWN_KEYS = ["name", "icon", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -123,6 +162,11 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateGit(configPath, config[key]);
         }
+        else if (key === "repos") {
+            if (config[key] === null)
+                config[key] = {};
+            validateRepos(configPath, config[key]);
+        }
         else if (typeof config[key] !== "string") {
             throw new Error(`${path.basename(configPath)}: ${key} must be a string`);
         }
@@ -182,3 +226,26 @@ function validateGit(configPath, value) {
         throw new Error(`${file}: git.autosync must be "off" or "pull"`);
     }
 }
+function validateRepos(configPath, value) {
+    const file = path.basename(configPath);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${file}: repos must be a mapping (enabled, root)`);
+    }
+    const r = value;
+    for (const key of Object.keys(r)) {
+        if (!["enabled", "root"].includes(key)) {
+            throw new Error(`${file}: repos.${key} is unknown (allowed: enabled, root)`);
+        }
+    }
+    if (r.enabled !== undefined && typeof r.enabled !== "boolean") {
+        throw new Error(`${file}: repos.enabled must be true or false`);
+    }
+    if (r.root !== undefined && (typeof r.root !== "string" || !r.root.trim())) {
+        throw new Error(`${file}: repos.root must be a non-empty string`);
+    }
+    // The root is what `repos remove --force` deletes under, so it must never
+    // be the project itself or anything outside it.
+    if (typeof r.root === "string" && !ignoreEntryFor(path.dirname(configPath), r.root.trim())) {
+        throw new Error(`${file}: repos.root must be a directory inside the project (not ".", ".." or an absolute path outside it)`);
+    }
+}

package/dist/inspector/chat/sessions.js

@@ -6,6 +6,7 @@ import { getRun, listRuns, safeRunDir } from "../runs.js";
 import { listSkills, readSkill } from "../skills.js";
 import { listWorkflows } from "../workflows.js";
 import { getAgent, listAgents } from "../agents.js";
+import { listRepos } from "../repos.js";
 import { startAcpBackend } from "./acp.js";
 import { startPiBackend } from "./pi.js";
 import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
@@ -144,6 +145,29 @@ 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`);
 }
+/**
+ * "## Repositories" block: the clones under the repos root, when the
+ * feature is on. Empty when it is off, so agents in a workspace without
+ * it never hear about it.
+ */
+async function reposContext() {
+    const view = await listRepos().catch(() => null);
+    if (!view?.enabled || !view.root)
+        return "";
+    const lines = view.repos
+        .map((r) => {
+        const state = r.error ? `unreadable: ${r.error}` : [r.dirty ? `${r.dirty} uncommitted` : "clean", r.ahead ? `${r.ahead} ahead` : "", r.behind ? `${r.behind} behind` : ""].filter(Boolean).join(", ");
+        return `- ${r.slug} — ${r.path}${r.url ? ` (${r.url})` : ""}${r.branch ? `, branch ${r.branch}` : ""}${r.head ? ` @ ${r.head}` : ""}, ${state}`;
+    })
+        .join("\n");
+    return (`## Repositories\nGit repositories this workspace works on live under ${view.root} (one clone per folder). ` +
+        `When the user names one of them, work inside its folder: read its README and structure first, keep commits on a ` +
+        `branch unless told otherwise, and never push or force-push without asking.\n${lines || "(none cloned yet)"}\n\n` +
+        `Clone a new one with \`npx kraftwerk repos add <url> [--name <folder>] [--branch <b>] [--depth <n>]\` so it lands in ` +
+        `that root (\`--depth 1\` for a large repository; a plain \`git clone\` into that folder works too); ` +
+        `\`npx kraftwerk repos\` lists them, \`update <name>\` fetches and fast-forwards a clean clone, \`remove <name>\` ` +
+        `deletes one. A repository the user mentions that is not listed is not cloned yet — offer to add it.`);
+}
 /** Base context per scope; scopeContext() appends the shared skills block. */
 async function baseScopeContext(scope, agent) {
     if (scope.kind === "agent") {
@@ -278,11 +302,14 @@ const RENDERING_BLOCK = `## Chat rendering\n` +
     `Prefer these relative /api/... URLs over file paths when showing results: they render directly ` +
     `in this chat and keep working wherever the inspector is reachable.`;
 async function scopeContext(scope, agent) {
-    const [base, skills] = await Promise.all([
+    // The repositories block reads every clone from git, so it runs alongside
+    // the rest instead of adding its spawns to the first prompt's latency.
+    const [base, repos, skills] = await Promise.all([
         baseScopeContext(scope, agent),
+        scope.kind === "agent" || scope.kind === "kraftwerk" ? reposContext() : Promise.resolve(""),
         availableSkills(scope),
     ]);
-    return [base, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+    return [base, repos, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
 }
 /* ---------- backend lifecycle ---------- */
 /** Agent sessions carry the agent's model/effort; resolved live so edits apply to new backends. */

package/dist/inspector/git.d.ts

@@ -40,6 +40,20 @@ export interface GitDiff {
     /** The diff was cut at MAX_DIFF; the rest is available in a terminal. */
     truncated?: boolean;
 }
+export interface GitResult {
+    ok: boolean;
+    /** Exit status, or null when git never ran (spawn error) or was killed. */
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export declare const NET_TIMEOUT = 60000;
+export declare function git(args: string[], cwd: string, timeoutMs?: number, env?: NodeJS.ProcessEnv): Promise<GitResult>;
+export declare function sshCommandFor(repoRoot: string): Promise<string>;
+/** A git call that may touch the network: longer timeout, non-interactive ssh. */
+export declare function gitNet(args: string[], repoRoot: string): Promise<GitResult>;
+/** Repo root for a directory, or null when it is not inside a git repo. */
+export declare function repoRootFor(dir: string): Promise<string | null>;
 /**
  * Everything the git screen renders. Each call shells out to git a handful
  * of times, and the nav badge polls it from every open tab, so results are