@kybernesis/create 0.12.1 → 0.13.0

package/dist/doctor.js

@@ -275,6 +275,32 @@ 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");
         }
+        /**
+         * 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 +376,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

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { upsertEnv } from "./envfile.js";
 import { EVE_VERSION, bold, capture, dim, green, red, run, yellow } from "./util.js";
@@ -87,6 +87,98 @@ function repairLocalQueueTimeouts(cwd, deps) {
         `    ${dim("slower than 30s was redelivered and its steps re-run — the agent answered twice.")}\n` +
         `    ${dim("Takes effect on the next server restart.")}\n`);
 }
+/**
+ * Finish a Buzz install that a version bump alone leaves half-done.
+ *
+ * @remarks
+ * A capability that arrives in a package but needs four manual steps to switch
+ * on has not really shipped. That is what happened here: `kyb upgrade` moved an
+ * agent to a version whose whole point was acting in a workspace, and the agent
+ * went on being unable to, because the extension was not mounted, the process
+ * had none of the environment the bridge had, and the CLI was not on the host.
+ * Everything looked upgraded and nothing was different.
+ *
+ * The person who hit it was an engineer with a terminal, and it still took a
+ * hand-written prompt to sort out. A client would not have got there at all —
+ * they would have concluded the feature did not work.
+ *
+ * So each of those is repaired here, from what the host can already tell us:
+ * the bridge's own service file holds the relay and the identity, and the rest
+ * is a file and a binary.
+ */
+function repairBuzzSetup(cwd, deps) {
+    if (!deps["@kybernesis/buzz"])
+        return;
+    const done = [];
+    // 1. The extension mount. Without it the tools do not exist, and nothing says so.
+    const mount = join(cwd, "agent/extensions/buzz.ts");
+    if (!existsSync(mount)) {
+        mkdirSync(join(cwd, "agent/extensions"), { recursive: true });
+        writeFileSync(mount, `// The agent's hands in Buzz: projects, issues, pull requests, patches, repos,
+` +
+            `// long-form notes, channel canvases, workflows, the feed, media — everything the
+` +
+            `// workspace has beyond talking, which the bridge alone does not provide.
+` +
+            `//
+` +
+            `// Actions are signed with THIS AGENT's key and appear under its name.
+` +
+            `export { default } from "@kybernesis/buzz/extension";
+`);
+        done.push("mounted the Buzz extension (agent/extensions/buzz.ts)");
+    }
+    /**
+     * 2. The environment. The bridge runs with the relay and the key; the AGENT
+     * process runs with neither, because nothing ever needed it to until the
+     * tools existed. Read from the service file rather than asked for, because
+     * the answer is already on the host and a person retyping it will eventually
+     * mistype it.
+     */
+    const envPath = join(cwd, ".env.local");
+    const env = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+    if (!/^BUZZ_RELAY=/m.test(env)) {
+        const unit = capture("sh", [
+            "-c",
+            "grep -ohE 'BUZZ_(RELAY|KEYFILE)=[^ \"]+' /etc/systemd/system/*buzz-bridge.service 2>/dev/null | head -2",
+        ]);
+        const values = {};
+        for (const line of (unit ?? "").split("\n")) {
+            const [name, ...rest] = line.trim().split("=");
+            if (name && rest.length)
+                values[name] = rest.join("=").replace(/^"|"$/g, "");
+        }
+        if (values.BUZZ_RELAY) {
+            upsertEnv(cwd, {
+                BUZZ_RELAY: values.BUZZ_RELAY,
+                ...(values.BUZZ_KEYFILE ? { BUZZ_KEYFILE: values.BUZZ_KEYFILE } : {}),
+            });
+            done.push("gave the agent process the relay and identity its bridge already had");
+        }
+        else {
+            console.log(`  ${yellow("!")} Buzz tools need BUZZ_RELAY and BUZZ_KEYFILE in .env.local — the same ` +
+                `values the bridge service uses. Could not read them from this host.`);
+        }
+    }
+    // 3. The CLI itself. Built once, in a container, because no binary is published.
+    if (!existsSync(join(cwd, ".buzz/bin/buzz"))) {
+        const hasDocker = capture("sh", ["-c", "command -v docker >/dev/null && echo yes"])?.trim() === "yes";
+        if (hasDocker) {
+            console.log(dim("  building the Buzz CLI for this host (first time only, a few minutes) …"));
+            const ok = run("npx", ["kybernesis-buzz", "install-cli"], { cwd, allowFail: true, quiet: true });
+            done.push(ok ? "installed the Buzz CLI (.buzz/bin/buzz)" : "could NOT install the Buzz CLI — run: npx kybernesis-buzz install-cli");
+        }
+        else {
+            console.log(`  ${yellow("!")} No docker here, so the Buzz CLI cannot be built. Without it the agent ` +
+                `can read the workspace but not act in it. Install docker, or set BUZZ_CLI_URL to a ` +
+                `binary built for this platform, then: npx kybernesis-buzz install-cli`);
+        }
+    }
+    if (done.length > 0) {
+        console.log(`  ${green("+")} Buzz: ${done.join("; ")}`);
+        console.log(`    ${dim("Takes effect after the next build and restart.")}\n`);
+    }
+}
 export async function upgrade(skipEval) {
     const cwd = process.cwd();
     const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
@@ -94,6 +186,7 @@ export async function upgrade(skipEval) {
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     warnIfStale();
     repairLocalQueueTimeouts(cwd, deps);
+    repairBuzzSetup(cwd, deps);
     const toUpgrade = [];
     const unresolved = [];
     for (const name of kybernesisPackages(deps)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "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

@@ -178,9 +178,12 @@ something. Chase them a week out — an unprovisioned Vercel team on Day 1 costs
 - [ ] **Confirm who at ACME is the Slack workspace admin.** Creating the Slack connector
       requires someone who can approve a Slack app install. If that person is on holiday
       your Day 2 is Slack-less.
-- [ ] **Read the reference implementation.** `~/kyber` is our own production agent and
-      the canonical example of everything in Phase 4. Skim `agent/agent.ts`,
-      `agent/instructions/`, `agent/subagents/finance/`, and `evals/`.
+- [ ] **Know the shape you are aiming for** before writing any of it: one
+      `agent/agent.ts` that picks a model and mounts extensions, instructions
+      split into identity and per-surface, one subagent per department that owns
+      its own tools and skills, and an `evals/` suite that gates the deploy.
+      Every later phase adds to that skeleton; building it in a different shape
+      is what makes the eval suite and the routing evals fight you.
 - [ ] **Confirm package versions you will pin.** As of 2026-08-06:
       `@kybernesis/arcana@0.1.1`, `@kybernesis/enterprise@0.1.2`,
       `@kybernesis/multiplayer@0.1.0`, `@kybernesis/evals@0.2.1`,
@@ -436,9 +439,9 @@ What to know when choosing:
   principal). Prefer `session.started` over per-turn switching: prompt caches
   are per model, and every switch re-ingests the conversation at uncached
   prices. Resolver failures degrade to the fallback, never fail the turn.
-- Kyber runs `anthropic/claude-opus-4.8` via the gateway; our eval judges are
-  configured separately in `evals/evals.config.ts` and must **never** be the
-  model under test.
+- Whatever the agent runs, eval judges are configured separately in
+  `evals/evals.config.ts` and must **never** be the model under test — a model
+  grading its own output measures agreement, not correctness.
 
 ### 4.1 Install `@kybernesis/enterprise` (governance) — do this FIRST
 
@@ -532,16 +535,11 @@ npx eve add @kybernesis/multiplayer
 This writes `agent/channels/slack.ts` and `agent/instructions/multiplayer.md`, and
 declares the `SLACK_CONNECTOR_UID` env var.
 
-> **Status as of 2026-08-05:** the registry item is **live** (`eve add` resolves and
-> writes both files), and the package is dogfooded in `~/kyber` — but
-> `@kybernesis/multiplayer@0.1.0` is **not yet published to npm**, so the dependency
-> install step will fail until it is. Check first:
+> Published and installable — `eve add` resolves the registry item and writes both
+> files. Confirm what you are pinning before you promise a version to a client:
 > ```bash
-> npm view @kybernesis/multiplayer version   # E404 means the publish hasn't landed
+> npm view @kybernesis/multiplayer version
 > ```
-> If it 404s, install from the workspace checkout at `~/kyber/packages/multiplayer` (or
-> vendor the two files by hand — they are shown below and in
-> `agent/instructions/multiplayer.md`) and revisit once the publish lands.
 
 The whole Slack integration is one file:
 
@@ -968,7 +966,7 @@ token minted per edge; the callee URL comes from the registry (discovery), env
 var still wins. THE DEMO: revoke the edge in the admin → the caller is refused
 (edge_not_granted) within 5 minutes, no redeploy; re-grant → restored. Run it
 for the client — it's the whole governance story in one minute. Full lifecycle
-proven live 2026-08-07 (kyber ↔ eve-gtm). Budget note: the deployed agent and
+proven live 2026-08-07 between two governed agents. Budget note: the deployed agent and
 local eval runs share the project's AI Gateway budget — size it for both.
 
 ### 4.4 Author the agent's identity and instructions
@@ -982,8 +980,7 @@ surface.ts example below). Keep always-on instructions to identity, tone, and
 standing rules; procedures belong in skills (§4.3e) — the model loads those on
 demand instead of paying for them every turn.
 
-Crib the structure from `~/kyber/agent/instructions/identity.md`, which has
-three sections worth copying:
+Give `agent/instructions/identity.md` three sections:
 
 1. **Identity** — who the agent is, and *how to write for Slack*: short paragraphs,
    bullets, no headings unless the answer is genuinely long. Slack is a chat surface, not
@@ -996,9 +993,9 @@ three sections worth copying:
    asks for something personal in a channel.
 
 For per-session context, `defineDynamic` on `session.started` lets you inject
-surface-specific instructions. `~/kyber/agent/instructions/surface.ts` is a working
-example: it greets a DM session by the caller's verified name and reminds a channel
-session that everything it posts is public.
+surface-specific instructions — greeting a DM session by the caller's verified
+name, and reminding a channel session that everything it posts is public. The
+same agent should not talk to a room the way it talks to one person.
 
 **Author these with Claude Code (§4.0), and judge drafts by test, not by
 reading** — paste the discovery notes, have it draft identity.md and the
@@ -1077,7 +1074,7 @@ export default defineAgent({
    workspace })` mount with that department's scoped key) and only that
    subagent gets the connection + skills + instructions. This is the default
    pattern now. The plain-connection alternative below still works (it's what
-   pre-0.30 required, and what you'll find in older kyber subagents) when you
+   pre-0.30 required, and what you'll find in subagents written before it) when you
    want the connection without the shipped skills:
 
    ```ts
@@ -1107,9 +1104,9 @@ export default defineAgent({
 
 `agent/schedules/*.ts` for anything recurring — a Monday pipeline summary, a Friday
 financial report. **Schedules live on the root agent only**; a scheduled root turn
-delegates to the subagent that owns the work. `~/kyber/agent/schedules/friday-financials.ts`
-is the working example: it fires Friday 02:00 UTC, delegates to `finance`, and DMs the
-result to a configured Slack user. Note that DMing a user from a schedule needs the
+delegates to the subagent that owns the work. A worked example: fire at 02:00 UTC
+on Friday, delegate to a `finance` subagent, and DM the result to a configured
+Slack user. Note that DMing a user from a schedule needs the
 `im:write` scope on the Slack connector — add it during Phase 5 or the first run fails
 silently at the last step.
 
@@ -1147,8 +1144,8 @@ rate, delegation mix, p50/p95 duration.
 userId by default, so PostHog sees one anonymous actor named after the service. To
 attribute turns to the verified speaker, add a sibling hook that stamps the
 per-message-authenticated principal via evlog's `useLogger` — on `step.started`, not
-`turn.started`, so evlog's turn state exists regardless of hook ordering (crib
-`~/kyber/agent/hooks/attribution.ts`). Then a one-time $identify per person maps ids
+`turn.started`, so evlog's turn state exists regardless of hook ordering. Then a
+one-time $identify per person maps ids
 to names. Per-employee telemetry must be a deliberate, disclosed choice at a client.
 
 ### 4.7 Environment variables
@@ -1931,8 +1928,8 @@ conversation — it changes the shape of the deal.
 
 **Grok, on a SuperGrok or X Premium+ subscription.** Same arrangement, without
 the broker: xAI's Grok Build CLI does a device login and writes a credential
-that is a valid bearer for `https://api.x.ai/v1`. Proven in production on Sid —
-twelve evals, twenty-nine gates, green on the subscription.
+that is a valid bearer for `https://api.x.ai/v1`. Proven in production on a
+self-hosted agent — twelve evals, twenty-nine gates, green on the subscription.
 
 ```bash
 # on the host, as the unix user the agent runs as
@@ -1962,8 +1959,8 @@ Three things to know before you promise it to a client:
   host for a week, it is an open question, and it would present to the client as
   the agent breaking for no reason.
 
-**The model will lie about which model it is.** Sid, running Grok, stated it was
-"Claude Opus 4.6, Anthropic" and attributed it to an instruction that exists
+**The model will lie about which model it is.** A self-hosted agent running Grok
+stated it was "Claude Opus 4.6, Anthropic" and attributed it to an instruction that exists
 nowhere in its context. Verify from the host — the configured model id and the
 credential in use — never by asking the agent. Expect a client to ask it in a
 demo, and have the real answer ready.
@@ -2055,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