@kybernesis/create 0.12.0 → 0.12.3

package/dist/doctor.js

@@ -367,9 +367,23 @@ export async function doctor() {
         }
     }
     // ── eve discovery + local port ─────────────────────────────────────────
-    const info = capture("npx", ["eve", "info"], cwd);
-    if (info === null)
-        add("fail", "eve info failed", "run npx eve info for details");
+    /**
+     * Discovery, run with the environment the SERVER runs with.
+     *
+     * `eve info` compiles the agent, and an agent that reads a variable at module
+     * scope — a model id, a required credential — throws without it. eve does not
+     * load .env.local itself, so running this with a bare environment reported a
+     * healthy agent as a failed discovery, on a host where the service starts it
+     * correctly every time. That red is the one thing a person is told must be
+     * green before going further, so it stopped a deployment that was fine.
+     *
+     * `env` here is the same merged view every other check reads: .env.local
+     * underneath, the real environment on top.
+     */
+    const info = capture("npx", ["eve", "info"], cwd, env);
+    if (info === null) {
+        add("fail", "eve info failed", "run: set -a && . ./.env.local && set +a && npx eve info — the agent's own error is in that output");
+    }
     else {
         const diag = /Diagnostics\s+(\d+) errors?, (\d+) warnings?/.exec(info);
         if (diag && diag[1] === "0")

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/dist/util.d.ts

@@ -11,7 +11,7 @@ export declare function run(command: string, args: string[], options?: {
     allowFail?: boolean;
     quiet?: boolean;
 }): boolean;
-export declare function capture(command: string, args: string[], cwd?: string): string | null;
+export declare function capture(command: string, args: string[], cwd?: string, extraEnv?: Record<string, string>): string | null;
 export declare function ask(question: string, fallback: string): Promise<string>;
 export declare function closePrompts(): void;
 /** Parse KEY="value" / KEY=value lines from an env file's contents. */

package/dist/util.js

@@ -24,8 +24,12 @@ export function run(command, args, options) {
     }
     return ok;
 }
-export function capture(command, args, cwd) {
-    const result = spawnSync(command, args, { cwd, encoding: "utf8", env: process.env });
+export function capture(command, args, cwd, extraEnv) {
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: "utf8",
+        env: extraEnv ? { ...process.env, ...extraEnv } : process.env,
+    });
     return result.status === 0 ? result.stdout : null;
 }
 let rl = null;

package/package.json

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