@kybernesis/create 0.20.0 → 0.21.0

package/dist/add.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { bold, dim, green, red, run, yellow } from "./util.js";
+import { addBuzz } from "./buzz.js";
 import { CHANNEL_KINDS, arcanaMemorySlotTs, channelPlan } from "./templates.js";
 /**
  * `kyb add channel <kind>` — put another surface on an agent that already exists.
@@ -21,10 +22,15 @@ import { CHANNEL_KINDS, arcanaMemorySlotTs, channelPlan } from "./templates.js";
 export async function add(what, rest) {
     if (what === "memory")
         return addMemory();
+    // Buzz is a bridge and a key, not a channel file; "add channel buzz" is what
+    // the provisioner and people naturally type, so both spellings land here.
+    if (what === "buzz" || (what === "channel" && rest.find((a) => !a.startsWith("-")) === "buzz"))
+        return addBuzz();
     if (what !== "channel") {
         console.error(red(`kyb add: don't know how to add "${what ?? ""}".`));
         console.log(dim(`  kyb add channel <${CHANNEL_KINDS.filter((k) => k !== "none").join("|")}>`));
         console.log(dim(`  kyb add memory   ${dim("— an eve 0.49 memory slot backed by Arcana (recall before every turn)")}`));
+        console.log(dim(`  kyb add buzz     ${dim("— the agent's own Buzz identity, tools and bridge, ready for its owner's community")}`));
         process.exitCode = 1;
         return;
     }

package/dist/buzz.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `kyb add buzz` — get an agent ready for its owner's Buzz community.
+ *
+ * @remarks
+ * Buzz is not a channel file. The agent is a member of the community with its
+ * own key, a separate bridge process hears mentions and answers as the person
+ * who spoke, and an extension gives the agent the rest of the workspace. Every
+ * one of those used to be a manual step on the host, so ticking Buzz on a build
+ * did nothing at all.
+ *
+ * This does everything that does not depend on the customer: the package, the
+ * extension mount, the agent's own key, the Buzz CLI and the bridge's unit. The
+ * unit is left switched off, because the one thing only the customer can give
+ * is which community it lives in. That arrives later through the owner's
+ * Channels page (manage's `buzz.join`), which writes the relay, publishes the
+ * agent's profile and starts the bridge.
+ */
+export declare const BUZZ_PACKAGE = "@kybernesis/buzz@^0.10.2";
+export declare const BUZZ_EXTENSION_MOUNT: string;
+/** Where the agent's Buzz key lives: inside the agent, so the bridge and the agent read the same file. */
+export declare function buzzKeyPath(appDir: string): string;
+export declare function buzzBridgeUnitName(agent: string): string;
+/** The bridge's systemd unit. Pure, so the test pins what every host gets. */
+export declare function buzzBridgeUnit(input: {
+    agent: string;
+    user: string;
+    appDir: string;
+}): string;
+export declare function addBuzz(cwd?: string): void;

package/dist/buzz.js

@@ -0,0 +1,154 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { upsertEnv } from "./envfile.js";
+import { bold, capture, dim, green, red, run, yellow } from "./util.js";
+/**
+ * `kyb add buzz` — get an agent ready for its owner's Buzz community.
+ *
+ * @remarks
+ * Buzz is not a channel file. The agent is a member of the community with its
+ * own key, a separate bridge process hears mentions and answers as the person
+ * who spoke, and an extension gives the agent the rest of the workspace. Every
+ * one of those used to be a manual step on the host, so ticking Buzz on a build
+ * did nothing at all.
+ *
+ * This does everything that does not depend on the customer: the package, the
+ * extension mount, the agent's own key, the Buzz CLI and the bridge's unit. The
+ * unit is left switched off, because the one thing only the customer can give
+ * is which community it lives in. That arrives later through the owner's
+ * Channels page (manage's `buzz.join`), which writes the relay, publishes the
+ * agent's profile and starts the bridge.
+ */
+export const BUZZ_PACKAGE = "@kybernesis/buzz@^0.10.2";
+export const BUZZ_EXTENSION_MOUNT = `// The agent's hands in Buzz: projects, issues, pull requests, patches, repos,\n` +
+    `// long-form notes, channel canvases, workflows, the feed, media — everything the\n` +
+    `// workspace has beyond talking, which the bridge alone does not provide.\n` +
+    `//\n` +
+    `// Actions are signed with THIS AGENT's key and appear under its name.\n` +
+    `export { default } from "@kybernesis/buzz/extension";\n`;
+/** Where the agent's Buzz key lives: inside the agent, so the bridge and the agent read the same file. */
+export function buzzKeyPath(appDir) {
+    return join(appDir, ".buzz", "agent-key.json");
+}
+export function buzzBridgeUnitName(agent) {
+    return `${agent}-buzz-bridge`;
+}
+/** The bridge's systemd unit. Pure, so the test pins what every host gets. */
+export function buzzBridgeUnit(input) {
+    const { agent, user, appDir } = input;
+    return `# Managed by @kybernesis/create (kyb add buzz). Switched on from the owner's Channels page.
+[Unit]
+Description=${agent} Buzz bridge
+After=network-online.target ${agent}-agent.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+WorkingDirectory=${appDir}
+# The relay, the key and the agent credential all come from .env.local, the
+# same file the agent reads, so they can never disagree.
+ExecStart=/bin/bash -lc 'set -a && . ./.env.local && set +a && exec npx kybernesis-buzz run'
+Restart=always
+RestartSec=10
+# The bridge publishes "offline" on the way out; this gives it time to.
+KillSignal=SIGTERM
+TimeoutStopSec=10
+StartLimitBurst=5
+StartLimitIntervalSec=300
+StandardOutput=append:${appDir}/buzz-bridge.log
+StandardError=append:${appDir}/buzz-bridge.log
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+export function addBuzz(cwd = resolve(process.cwd())) {
+    if (!existsSync(join(cwd, "package.json")) || !existsSync(join(cwd, "agent"))) {
+        console.error(red("kyb add buzz: run this inside an agent directory."));
+        process.exitCode = 1;
+        return;
+    }
+    if (!existsSync(join(cwd, "scripts/eve-server.sh"))) {
+        console.error(red("kyb add buzz: Buzz runs a bridge beside the agent, so it needs a host of its own (an exe VM or a server). This agent deploys to Vercel."));
+        process.exitCode = 1;
+        return;
+    }
+    const agent = agentNameOf(cwd);
+    console.log(bold("kyb add buzz"));
+    console.log(dim(`  agent: ${agent}`));
+    const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+    if (!pkg.dependencies?.["@kybernesis/buzz"]) {
+        run("npm", ["install", BUZZ_PACKAGE, "--no-audit", "--no-fund"], { cwd });
+    }
+    const mount = join(cwd, "agent/extensions/buzz.ts");
+    if (!existsSync(mount)) {
+        mkdirSync(join(cwd, "agent/extensions"), { recursive: true });
+        writeFileSync(mount, BUZZ_EXTENSION_MOUNT);
+        console.log(green("  + agent/extensions/buzz.ts"));
+    }
+    // One key for the bridge and the agent's tools. An existing BUZZ_KEYFILE is
+    // kept: replacing a key is a new member the community never invited.
+    const envPath = join(cwd, ".env.local");
+    const env = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+    const existing = env.match(/^BUZZ_KEYFILE\s*=\s*"?([^"\n]+)"?/m)?.[1]?.trim();
+    const keyFile = existing || buzzKeyPath(cwd);
+    if (!existing)
+        upsertEnv(cwd, { BUZZ_KEYFILE: keyFile });
+    mkdirSync(join(keyFile, ".."), { recursive: true });
+    ignore(cwd, ".buzz/");
+    const init = capture("npx", ["kybernesis-buzz", "init"], cwd, { BUZZ_KEYFILE: keyFile });
+    const npub = init?.match(/npub1[02-9ac-hj-np-z]+/)?.[0];
+    if (!npub) {
+        console.error(red("  Could not create the agent's Buzz identity (npx kybernesis-buzz init)."));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(green(`  + Buzz identity ${npub}`));
+    // The CLI is what the agent acts through; no binary is published, so it is
+    // built once in a container. Without docker the agent can still talk.
+    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, timeoutMs: 15 * 60_000 });
+            console.log(ok ? green("  + Buzz CLI (.buzz/bin/buzz)") : yellow("  ! the Buzz CLI did not build; run: npx kybernesis-buzz install-cli"));
+        }
+        else {
+            console.log(yellow("  ! no docker here, so the Buzz CLI was not built; the agent can talk in Buzz but not act in it."));
+        }
+    }
+    const unitName = buzzBridgeUnitName(agent);
+    const dir = mkdtempSync(join(tmpdir(), "kyb-buzz-"));
+    try {
+        const file = join(dir, `${unitName}.service`);
+        writeFileSync(file, buzzBridgeUnit({ agent, user: userInfo().username, appDir: cwd }));
+        const installed = run("sudo", ["-n", "install", "-m", "644", file, `/etc/systemd/system/${unitName}.service`], { allowFail: true, quiet: true }) &&
+            run("sudo", ["-n", "systemctl", "daemon-reload"], { allowFail: true, quiet: true });
+        console.log(installed
+            ? green(`  + ${unitName}.service (off until the owner connects a community)`)
+            : yellow(`  ! could not install ${unitName}.service without a password; the owner's Connect step will need it`));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    console.log(bold("\n  Next:"));
+    console.log(`    · The owner connects it from the Channels page: their community's address, then an admin adds ${npub} as a member.`);
+}
+function agentNameOf(dir) {
+    const env = join(dir, ".env.local");
+    if (existsSync(env)) {
+        const hit = readFileSync(env, "utf8").match(/^KYBERNESIS_AGENT\s*=\s*"?([^"\n]+)"?/m);
+        if (hit?.[1])
+            return hit[1].trim();
+    }
+    return basename(dir);
+}
+function ignore(dir, entry) {
+    const path = join(dir, ".gitignore");
+    const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+    if (current.split("\n").some((line) => line.trim() === entry))
+        return;
+    writeFileSync(path, `${current.replace(/\n*$/, "\n")}${entry}\n`);
+}

package/dist/cli.js

@@ -233,6 +233,7 @@ ${dim("  npm i -g @kybernesis/create@latest")}
       --yes             ${dim("no prompts; take flags and defaults")}
   ${bold("kyb add channel <kind>")}
       ${dim("slack|imessage|telegram|discord|web — writes the channel, deps and env")}
+  ${bold("kyb add buzz")}        ${dim("the agent's own Buzz identity, tools and bridge (connected from the Channels page)")}
   ${bold("kyb add memory")}      ${dim("eve 0.49 memory slot backed by Arcana: recall before every turn")}
   ${bold("kyb doctor")}          preflight checks (keys, issuer, envs, discovery)
   ${bold("kyb skills")}          install/refresh the FDE skill suite for Claude Code

package/dist/upgrade.js

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { upsertEnv } from "./envfile.js";
+import { BUZZ_EXTENSION_MOUNT } from "./buzz.js";
 import { reconcileHostArtifact } from "./host-artifacts.js";
 import { assessPeerTree, staleRangeWarning } from "./peer-tree.js";
 import { dockerPruneCronArtifact } from "./docker-prune-cron.js";
@@ -101,18 +102,7 @@ function repairBuzzSetup(cwd, deps) {
     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";
-`);
+        writeFileSync(mount, BUZZ_EXTENSION_MOUNT);
         done.push("mounted the Buzz extension (agent/extensions/buzz.ts)");
     }
     /**
@@ -124,7 +114,10 @@ function repairBuzzSetup(cwd, deps) {
      */
     const envPath = join(cwd, ".env.local");
     const env = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
-    if (!/^BUZZ_RELAY=/m.test(env)) {
+    // An agent set up by `kyb add buzz` has no relay until its owner connects a
+    // community from the Channels page; that is waiting, not broken.
+    const awaitingOwner = /^BUZZ_KEYFILE=/m.test(env) && capture("sh", ["-c", "grep -l 'kyb add buzz' /etc/systemd/system/*buzz-bridge.service 2>/dev/null"]);
+    if (!/^BUZZ_RELAY=/m.test(env) && !awaitingOwner) {
         const unit = capture("sh", [
             "-c",
             "grep -ohE 'BUZZ_(RELAY|KEYFILE)=[^ \"]+' /etc/systemd/system/*buzz-bridge.service 2>/dev/null | head -2",

package/package.json

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