@kybernesis/create 0.12.3 → 0.13.1

package/dist/doctor.js

@@ -275,6 +275,53 @@ export async function doctor() {
         else {
             add("fail", `self-hosted: ${shortQueueTimeouts.join(" and ")} left at the 30s default`, "one queue delivery holds a connection open for the entire turn, so any turn slower than the timeout is redelivered and its steps re-run — the agent answers the same question twice, with two different answers, and nothing reports an error. Set both to 900000 in .env.local and restart the server");
         }
+        /**
+         * Disk, on a host whose runtime does not clean up after itself.
+         *
+         * eve builds a sandbox template per session configuration and keeps every
+         * one, and leaves session containers running long after their turn ended.
+         * The result is gigabytes a day on a working agent, and the failure it
+         * eventually produces looks like anything except a full disk.
+         */
+        if (capture("sh", ["-c", "command -v docker >/dev/null && echo yes"])?.trim() === "yes") {
+            const job = capture("sh", ["-c", "test -x /etc/cron.daily/kyb-docker-prune && echo yes"])?.trim();
+            const percent = Number(capture("sh", ["-c", "df / | awk 'NR==2{print $5}' | tr -d '%'"])?.trim() ?? 0);
+            if (job !== "yes") {
+                add("warn", "no daily docker reclaim on this host", "sandbox images and abandoned session containers accumulate by the gigabyte; `kyb upgrade` installs /etc/cron.daily/kyb-docker-prune");
+            }
+            else if (percent >= 80) {
+                add("fail", `disk ${percent}% full despite the reclaim job`, "run it now: sudo /etc/cron.daily/kyb-docker-prune, and check what else is on this host");
+            }
+            else {
+                add("pass", `daily docker reclaim installed (disk ${percent}% used)`);
+            }
+        }
+        /**
+         * Instructions that name a tool the agent does not have.
+         *
+         * `deliver` mounts with the engineer layer, which is mounted on the builder
+         * subagent — so an agent whose ROOT is told to hand over files (by its own
+         * instructions, or by our playbook, which says to) promises a file it
+         * cannot send. It cannot see the mismatch either: it writes the contents to
+         * a memory note, or apologises without a cause, and the delivery
+         * infrastructure passes every check while nobody can receive anything.
+         */
+        const rootDeliver = existsSync(join(cwd, "agent/tools/deliver.ts"));
+        const instructionsMentionDeliver = (() => {
+            try {
+                const dir = join(cwd, "agent/instructions");
+                return readdirSync(dir).some((file) => readFileSync(join(dir, file), "utf8").includes("deliver"));
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (instructionsMentionDeliver && !rootDeliver) {
+            add("fail", "instructions tell this agent to deliver files, but the root has no deliver tool", 'add agent/tools/deliver.ts: export { deliver as default } from "@kybernesis/engineer/tools" — the engineer layer mounts it on the builder subagent only');
+        }
+        else if (rootDeliver) {
+            add("pass", "the agent that talks to people can also hand them a file");
+        }
         // The exe VM sandbox backend needs a credential that cannot be scoped.
         // Surface the blast radius here, where it is still cheap to change course.
         const sandboxFile = join(cwd, "agent/sandbox/sandbox.ts");
@@ -350,7 +397,11 @@ export async function doctor() {
             add("fail", "engineer subagent has NO sandbox of its own", "subagents do not inherit the root sandbox — add agent/subagents/builder/sandbox/sandbox.ts or the vision loop cannot run");
         }
         if (existsSync(join(builderDir, "extensions/engineer.ts"))) {
-            add("pass", "engineer mounted locally on the subagent (root keeps no shell)");
+            // Not "the root keeps no shell": every eve agent has a sandbox with bash,
+            // read_file, write_file, glob and grep. What the local mount withholds is
+            // the build loop and any shell ON THE HOST. This sentence is one people
+            // reason about security boundaries from, so it says the true thing.
+            add("pass", "engineer mounted locally on the subagent (root gets no host shell, no build loop)");
         }
         else {
             add("warn", "engineer extension not mounted on the subagent", "agent/subagents/builder/extensions/engineer.ts");

package/dist/templates.js

@@ -513,18 +513,39 @@ export default defineAgent({
     "Builds and runs software: scaffolds projects, writes code, installs dependencies, runs builds and dev servers, and visually verifies rendered pages. Use when the user asks for something to be BUILT, prototyped, deployed, or fixed in code — not for questions, planning, or scheduling.",
   model: ${JSON.stringify(model)},
 });
+`,
+        },
+        {
+            path: "agent/tools/deliver.ts",
+            content: `// Handing a file to the person you are talking to.
+//
+// The engineer layer mounts on \`builder\`, so building stays there — but
+// DELIVERING is not building. It reads one file from this agent's own sandbox
+// and copies it to storage, runs no commands and writes nothing back, and the
+// agent that needs it is the one talking to the user.
+//
+// Without this the root is told (by its instructions, and by our own playbook)
+// to deliver files and has no such tool. It cannot detect the mismatch, so it
+// promises a file and then quietly puts the contents somewhere nobody can
+// reach — a memory note, or an apology with no cause given.
+export { deliver as default } from "@kybernesis/engineer/tools";
 `,
         },
         {
             path: "agent/subagents/builder/extensions/engineer.ts",
             content: `// Engineer layer mounted LOCALLY on this subagent (eve >=0.30): screenshot,
 // deliver, and the trade-school skills belong to \`builder\` alone, so the root
-// agent has no shell.
+// gets no shell ON THE HOST and none of the build loop.
+//
+// Not "the root has no shell" — every eve agent has a sandbox with bash,
+// read_file, write_file, glob and grep, and this app builds two templates
+// (root and builder). The root's shell is its own container. The distinction
+// that matters is host access, and the old wording blurred exactly the line
+// people read this comment to understand.
 //
 // The root DOES get a browser and GitHub tools — the engineer layer installs
 // extension/agent-browser and extension/github-tools at the root, deliberately,
 // because reading a page is not the same blast radius as running a command.
-// This comment used to claim otherwise, which is worse than saying nothing.
 export { default } from "@kybernesis/engineer";
 `,
         },

package/dist/upgrade.js

@@ -179,14 +179,63 @@ function repairBuzzSetup(cwd, deps) {
         console.log(`    ${dim("Takes effect after the next build and restart.")}\n`);
     }
 }
+/**
+ * Keep the agent host from filling up with what the runtime leaves behind.
+ *
+ * @remarks
+ * eve builds a sandbox template image per session configuration and never
+ * collects the old ones, and it leaves session CONTAINERS running — a turn that
+ * took four minutes can still own a container, and its writable layer, eight
+ * days later. Forty stale images accumulated on one agent in a week; another
+ * reached 94% full and began failing in ways that looked like anything but a
+ * disk problem. Every self-hosted agent hits this; it is a property of the
+ * runtime, not of any one deployment.
+ *
+ * Installed rather than documented, and DAILY rather than weekly, because the
+ * accumulation is measured in gigabytes per day on an agent doing real work.
+ * The first version of this ran weekly and was already too slow.
+ */
+function repairDockerPrune(cwd, deps) {
+    if (!deps["@kybernesis/exe"])
+        return;
+    if (capture("sh", ["-c", "command -v docker >/dev/null && echo yes"])?.trim() !== "yes")
+        return;
+    const installed = capture("sh", ["-c", "test -x /etc/cron.daily/kyb-docker-prune && echo yes"]);
+    if (installed?.trim() === "yes")
+        return;
+    const source = join(cwd, "node_modules/@kybernesis/exe/scripts/docker-prune.sh");
+    if (!existsSync(source))
+        return;
+    // `sudo -n`: this runs inside an upgrade, and an upgrade that stops to ask
+    // for a password in the middle of an unattended run is worse than one that
+    // says what it could not do.
+    const ok = run("sh", [
+        "-c",
+        // The weekly predecessor is removed in the same breath: two jobs pruning
+        // the same host is not twice as safe, it is one more thing to reason
+        // about when something unexpected disappears.
+        `sudo -n cp ${JSON.stringify(source)} /etc/cron.daily/kyb-docker-prune && ` +
+            `sudo -n chmod 755 /etc/cron.daily/kyb-docker-prune && ` +
+            `sudo -n rm -f /etc/cron.weekly/docker-prune`,
+    ], { cwd, allowFail: true, quiet: true });
+    if (ok) {
+        console.log(`  ${green("+")} installed the daily docker reclaim (/etc/cron.daily/kyb-docker-prune)`);
+        console.log(`    ${dim("eve leaves sandbox images and running session containers behind; this collects them.")}\n`);
+    }
+    else {
+        console.log(`  ${yellow("!")} could not install the docker reclaim job (needs sudo). Without it this host ` +
+            `fills with stale sandbox images. Run:\n` +
+            `    ${dim("sudo cp node_modules/@kybernesis/exe/scripts/docker-prune.sh /etc/cron.daily/kyb-docker-prune && sudo chmod 755 /etc/cron.daily/kyb-docker-prune")}`);
+    }
+}
 export async function upgrade(skipEval) {
     const cwd = process.cwd();
     const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     warnIfStale();
+    // Env-only, so it is safe before anything is installed.
     repairLocalQueueTimeouts(cwd, deps);
-    repairBuzzSetup(cwd, deps);
     const toUpgrade = [];
     const unresolved = [];
     for (const name of kybernesisPackages(deps)) {
@@ -241,10 +290,25 @@ export async function upgrade(skipEval) {
     }
     if (toUpgrade.length === 0) {
         console.log(`\n${green("Everything is at latest certified versions.")}\n`);
+        // Still repair: being on the right versions is not the same as being set
+        // up. An agent can sit at latest for weeks with a capability switched off.
+        repairBuzzSetup(cwd, deps);
+        repairDockerPrune(cwd, deps);
         return;
     }
     console.log(bold(`\nInstalling: ${toUpgrade.join(", ")}\n`));
     run("npm", ["install", ...toUpgrade], { cwd });
+    /**
+     * Repairs run AFTER the install, not before.
+     *
+     * Both of these copy files out of packages that the install has just put
+     * there — a proxy script, a cron job, a CLI. Running them first meant looking
+     * for a file the older installed version did not ship: the repair found
+     * nothing, said nothing, and only worked on the NEXT upgrade. Which is a
+     * bug that hides itself, because by then it looks like it always worked.
+     */
+    repairBuzzSetup(cwd, deps);
+    repairDockerPrune(cwd, deps);
     run("npm", ["run", "typecheck"], { cwd });
     if (eveChanged) {
         // A framework bump must also pass discovery/compile, not just types.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.12.3",
+  "version": "0.13.1",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",

package/skills/fde-engagement/references/playbook.md

@@ -2052,9 +2052,23 @@ tool. Reads went from unreliable to deterministic with about sixty lines.
 ### 11.6 The engineer layer, self-hosted
 
 `--engineer` scaffolds a **builder subagent** that owns the build capability, so
-the root agent never gets a shell. It comes with the full production loop —
-workshop sandbox, Playwright, screenshots, visual verification, delivery — not a
-reduced version of the Vercel one.
+the root agent gets **no shell on the host and no build loop**. It comes with the
+full production loop — workshop sandbox, Playwright, screenshots, visual
+verification, delivery — not a reduced version of the Vercel one.
+
+> Say it that way rather than "the root never gets a shell". Every eve agent has
+> a sandbox with `bash`, `read_file`, `write_file`, `glob` and `grep`, and an
+> `--engineer` app builds two templates. The root's shell is its own container.
+> The line that matters is host access, and the shorter phrasing blurs exactly
+> the boundary people quote this passage to explain.
+
+**Delivery belongs to the root as well.** The engineer layer mounts on `builder`,
+but the agent that talks to people is the one asked for files — and delivering
+reads one file and copies it, which is not the blast radius that justified
+keeping the build loop away from the root. `kyb init --engineer` now scaffolds
+`agent/tools/deliver.ts` for exactly this. An agent instructed to hand over files
+without that mount cannot tell it is missing: it writes the contents to a memory
+note and reports success.
 
 - **Subagents own their sandbox; they do NOT inherit the root's.** A builder
   without its own `sandbox/sandbox.ts` gets a bare template and every screenshot