@kybernesis/create 0.8.1 → 0.9.0

package/dist/cli.js

@@ -60,7 +60,50 @@ function initOptions(rest) {
         yes: rest.includes('--yes') || rest.includes('-y'),
     };
 }
+/** What each command is for, in one line, as a person would ask for it. */
+const COMMANDS = {
+    init: "Scaffold a new agent: governed, remembering, multiplayer, self-testing.",
+    doctor: "Check this machine and this project before an engagement.",
+    arcana: "Set the memory workspaces and keys this agent uses.",
+    skills: "Install the FDE skill suite (--global for every project).",
+    credential: "Write the agent credential onto a host (--local to stay here).",
+    register: "Register this agent with the control plane (--name, --url).",
+    deploy: "Deploy this agent to its host (--no-env to leave the env file alone).",
+    upgrade: "Bring @kybernesis packages and eve to the certified versions (--skip-eval).",
+    version: "Print the version of this tool.",
+};
+/**
+ * Print help instead of doing anything.
+ *
+ * Given a command, describe that command; otherwise list them. Either way this
+ * function's only effect is output — which is the entire point of it existing.
+ */
+function usage(command) {
+    if (command && COMMANDS[command]) {
+        console.log(`\n  ${bold(`kyb ${command}`)} — ${COMMANDS[command]}\n`);
+        return;
+    }
+    console.log(`\n  ${bold("kyb")} ${dim(VERSION)} — the Kybernesis agent CLI\n`);
+    for (const [name, description] of Object.entries(COMMANDS)) {
+        console.log(`  ${bold(name.padEnd(12))}${description}`);
+    }
+    console.log(`\n  ${dim("kyb <command> --help for one command.")}\n`);
+}
 const [, , command, ...rest] = process.argv;
+/**
+ * `--help` asks what a command does. It must never be the thing that does it.
+ *
+ * Checked before dispatch rather than inside each command, because "the flag
+ * was ignored" is not a failure anyone verifies per command — and the one time
+ * it mattered, `kyb upgrade --help` ran a real upgrade against a live agent's
+ * dependencies. Nothing broke, which is the wrong kind of luck: the same
+ * mistake on a command that writes credentials or deploys would not have been
+ * survivable.
+ */
+if (rest.includes("--help") || rest.includes("-h")) {
+    usage(command);
+    process.exit(0);
+}
 switch (command) {
     case "init":
         await init(rest.find((a) => !a.startsWith("-")), initOptions(rest));

package/dist/upgrade.js

@@ -1,14 +1,25 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { EVE_VERSION, bold, capture, dim, green, red, run, yellow } from "./util.js";
-const PACKAGES = [
-    "@kybernesis/arcana",
-    "@kybernesis/enterprise",
-    "@kybernesis/multiplayer",
-    "@kybernesis/engineer",
-    "@kybernesis/dispatch",
-    "@kybernesis/evals",
-];
+/**
+ * Which packages to upgrade: every `@kybernesis/*` this agent depends on.
+ *
+ * @remarks
+ * This was a fixed list of six, written when there were six. Four more shipped
+ * afterwards — connectors, local, manage and exe — and an agent using them was
+ * told "everything is at latest certified versions" while holding versions from
+ * months earlier. A hardcoded list does not fail loudly when it falls behind;
+ * it just quietly stops covering things, and the command that reports it is the
+ * same one that is wrong.
+ *
+ * Reading the manifest cannot fall behind. A package added tomorrow is covered
+ * by an upgrade run today.
+ */
+function kybernesisPackages(deps) {
+    return Object.keys(deps)
+        .filter((name) => name.startsWith("@kybernesis/"))
+        .sort();
+}
 function versionLt(a, b) {
     const pa = a.split(".").map(Number);
     const pb = b.split(".").map(Number);
@@ -52,13 +63,15 @@ export async function upgrade(skipEval) {
     console.log(bold("\nkyb upgrade — checking @kybernesis/* and eve against npm\n"));
     warnIfStale();
     const toUpgrade = [];
-    for (const name of PACKAGES) {
+    const unresolved = [];
+    for (const name of kybernesisPackages(deps)) {
         if (!deps[name])
             continue;
         const installed = capture("node", ["-p", `require('${name}/package.json').version`], cwd)?.trim();
         const latest = capture("npm", ["view", name, "version"])?.trim();
         if (!installed || !latest) {
             console.log(`  ${yellow("!")} ${name}: could not resolve versions`);
+            unresolved.push(name);
             continue;
         }
         if (installed === latest)
@@ -91,6 +104,16 @@ export async function upgrade(skipEval) {
             console.log(dim(`    note: eve@${eveLatest} exists upstream; ${EVE_VERSION} is the newest Kybernesis-certified version.`));
         }
     }
+    if (toUpgrade.length === 0 && unresolved.length > 0) {
+        // Saying everything is current, having just failed to check several
+        // packages, is the worst available answer: it is the sentence someone
+        // repeats to a client. Usually the dependencies are simply not installed
+        // here, which is worth naming rather than hiding behind a green tick.
+        console.log(`\n${yellow(`Checked what could be read. ${unresolved.length} package(s) could not be ` +
+            `resolved, so this is not a clean bill of health.`)}\n` +
+            `  ${dim("Usually: dependencies are not installed here. Run npm install, then kyb upgrade.")}\n`);
+        return;
+    }
     if (toUpgrade.length === 0) {
         console.log(`\n${green("Everything is at latest certified versions.")}\n`);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.8.1",
+  "version": "0.9.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/control-plane/SKILL.md

@@ -24,9 +24,33 @@ credentials; 403 `agent_not_granted` = valid user, no grant for THIS agent.
 
 Register the agent under Agents (runtime: ▲ eve + deployment URL — the row
 shows a health probe). Grant users under their profile (grants resolve at
-MINT time). Users page also links/revokes chat identities (Slack ↔ user).
+MINT time). Users page also links/revokes chat identities (platform id ↔ user) — the
+manual/bulk path; see "Chat identity" below for the self-service one.
 Sign-in for humans is RFC 8628 device flow (user code, e.g. ABCD-EFGH).
 
+## Chat identity (how a room full of people becomes people)
+
+`POST /api/agent/identity` — the door a channel bridge knocks on. Agent
+authenticates with its OWN credential (`KYBERNESIS_AGENT_CREDENTIAL`), passes
+`{provider, externalId}`, gets back `{token, bundle}` minted FOR THAT PERSON.
+Client side is `channelIdentity()` in `@kybernesis/enterprise`.
+
+- **Unlinked → 404 `{error:"not_linked", link}`**, not an error to show: the
+  bridge delivers that link to the sender **privately** on the platform they
+  used. Delivery IS the proof of control — a link posted in a room lets anyone
+  in that room claim to be that person. Single-use, 15 min, org-scoped.
+- The person claims it at `/link/<code>`: they sign in as themselves, confirm,
+  and `external_identity` is written. **They must already be a user in the org**
+  (invited or SSO) or the link dead-ends at the sign-in wall — this is the
+  most likely "it didn't work" report.
+- Linked but ungranted → 403 `agent_not_granted`; the bridge tells them so.
+  Refusals are NOT cached, so granting takes effect on their next message.
+- Tokens are 5 min here (`CHANNEL_IDENTITY_TTL_SECONDS`), not the 1h default:
+  a bridge re-mints per turn, so revocation lands in minutes and the host holds
+  nothing durable for anybody.
+
+Order is free: link-then-grant and grant-then-link both work.
+
 ## Timing semantics (the support-ticket section)
 
 Token TTL defaults to 1h — that IS the revocation SLA for already-minted
@@ -42,6 +66,12 @@ appetite and tell them the number.
 4. Revoke the grant → old token still works until TTL; re-mint refused.
 5. Suspend the user → mint refused immediately; restore → mint works.
 
+For an agent on a chat surface, the same check has a channel form, verified
+against production 2026-08-20: unlinked sender → gets a link privately (and
+nothing in the room); claims it → next message answers as them (the bridge log
+names their EMAIL, not their platform id); ungranted → "no access yet"; grant →
+works on the next message.
+
 This exact sequence was verified against production 2026-08-05. The demo
 moment for clients is step 3→4 — access appearing and disappearing from the
 admin screen.

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

@@ -222,7 +222,9 @@ table below live.
   (Photon), Telegram, Discord, Teams, SMS/phone (Twilio), GitHub, Linear, and
   a web chat — the agent can live on several at once (§4.3c has the table and
   install commands). Slack gets the richest treatment (our multiplayer group
-  semantics); the rest are 1:1 surfaces today. Pick with the client, then ask
+  semantics); Buzz gets the strongest identity story (§4.3c — the agent is a
+  workspace MEMBER and every turn runs as the person who sent it); the rest are
+  1:1 surfaces today. Pick with the client, then ask
   the Slack questions below only if Slack made the list.
 
 ### 2.3a Slack specifics
@@ -706,6 +708,7 @@ re-teaching the agent. What ships:
 | GitHub @mentions, PR review | GitHub | `eve add channel/github` |
 | Linear issue delegation | Linear | `eve add channel/linear-agent` |
 | Web app / browser chat | eve HTTP + `useEveAgent` | built-in (route auth via enterprise) |
+| **Buzz** (agent as a workspace member) | our `@kybernesis/buzz` (§4.3c) | not an eve channel — a bridge process beside the agent |
 
 Every channel's doc page (`node_modules/eve/docs/channels/<name>.mdx`) carries
 its **complete** setup: the file to write, the env vars, the webhook/app
@@ -756,6 +759,48 @@ other surfaces are stock channels, excellent for 1:1; and each surface has its
 own provider terms and data flow — sensitive-data review (§2.5) is per
 channel, not per agent.
 
+#### Buzz — the agent as a workspace member
+
+Buzz is not an eve channel and does not go in `agent/channels/`. The agent joins
+the workspace as a **member** with its own key, and a small bridge process runs
+beside it. That shape buys the thing no other surface has today: every message is
+signed by its sender, so each turn runs as **that person** — their memory, their
+connections, their grants — instead of the whole room sharing one identity.
+
+**What you do (the client never touches a terminal):**
+
+```bash
+eve add @kybernesis/buzz          # deps + the workspace-behaviour instructions
+npx kybernesis-buzz init          # prints the npub to invite — do NOT regenerate later
+```
+
+Give that npub to a workspace admin to invite. Then set `BUZZ_RELAY` (the
+workspace relay, `wss://…`), `KYBERNESIS_ISSUER` and `KYBERNESIS_AGENT_CREDENTIAL`,
+and run it as a service:
+
+```bash
+npx kybernesis-buzz service /tmp/agent-buzz.service   # writes a systemd unit
+sudo mv /tmp/agent-buzz.service /etc/systemd/system/ && sudo systemctl enable --now agent-buzz
+npx kybernesis-buzz run                               # or, to watch it in the foreground
+```
+
+**What the client's people do:** tag the agent → get a sign-in link **by direct
+message** → click it, sign in, confirm. Done, once, per person. Their admin's
+only job is in the control plane: the person must be a **user in the org first**
+(invited or SSO), and must hold a grant on this agent unless its access tier is
+`org`/`public`. Link-then-grant and grant-then-link both work, and a grant takes
+effect on their next message.
+
+**Failure modes worth knowing before a client sees them:**
+
+- A stranger with no control-plane account gets a link that dead-ends at the
+  sign-in wall. The bridge cannot know in advance whether an unknown key belongs
+  to anyone, so this is by design — but say it out loud during setup.
+- The key file IS the agent. Losing it means being invited again as a stranger
+  with no history; back it up with the rest of the agent's secrets.
+- A bridge that is not running looks like an agent that is offline and ignoring
+  people, not like an error. The unit above is not optional.
+
 ### 4.3d Connections — wire the client's actual systems
 
 A connection turns an external system into tools the model can call. Rule one:

package/skills/kybernesis-packages/SKILL.md

@@ -1,10 +1,10 @@
 ---
-description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), dispatch (agent-to-agent), connectors (Gmail/Calendar/remote MCP), local (the user's own machine), manage (Studio→agent), exe (off-Vercel hosting), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
+description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), buzz (workspace member), engineer (build+ship), dispatch (agent-to-agent), connectors (Gmail/Calendar/remote MCP), local (the user's own machine), manage (Studio→agent), exe (off-Vercel hosting), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
 ---
 
 # The Kybernesis packages
 
-Eleven packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
+Twelve packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
 `KybernesisAI/platform`. Registry: `https://registry.kybernesis.ai`
 (`eve registry add @kybernesis=https://registry.kybernesis.ai/r/{name}.json`,
 then `eve add @kybernesis/<item>`). Each covers one axis:
@@ -20,7 +20,11 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   extension). `kybernesisAuth()` admits only control-plane IdentitySessions
   WITH a grant for this agent (`authorization: Bearer` + `x-kybernesis-bundle`
   headers; 401 no-creds, 403 agent_not_granted). Lazy JWKS — compiles without
-  KYBERNESIS_ISSUER. See the `control-plane` skill.
+  KYBERNESIS_ISSUER. Also `channelIdentity({ issuer, credential })` — resolves a
+  chat sender (provider + platform id) to a session minted FOR THAT PERSON, per
+  turn, so a bridge never holds durable credentials for anybody. THROWS when the
+  control plane is unreachable rather than refusing: a 500 read as "not allowed"
+  locks a whole room out over a deploy. See the `control-plane` skill.
 - **multiplayer** — Slack conversation mechanics. `multiplayerSlackChannel()`
   from `/slack` subpath: thread = shared session with per-speaker verified
   identity, no-re-mention continuation, dual surface (verified
@@ -82,6 +86,18 @@ then `eve add @kybernesis/<item>`). Each covers one axis:
   same shape as eve's `experimental_chatgpt()`), `hostPreflight()`, Photon
   iMessage credentials, and a `/preview` tool. Subpaths: `/slack`, `/photon`,
   `/sandbox`, `/preview`. See the `self-hosting` skill.
+- **buzz** — the agent as a MEMBER of a Buzz workspace (not a bot bolted on).
+  `buzzBridge()` + a `kybernesis-buzz` CLI (`init` prints the key to invite ·
+  `run` · `service` writes a systemd unit · `id` converts npub↔hex). Each turn
+  runs as the sender, resolved via `channelIdentity`; an unknown sender is sent
+  a sign-in link **privately** — holding it is what proves control of the
+  account, so a link posted in a room lets anyone there claim to be that person.
+  Publishes presence (20001, 60s heartbeat), typing (20002, every 3s) and 👀
+  (kind 7). Wire gotchas: reactions and dm-open go over HTTP with NIP-98 auth,
+  NOT the socket (a socket reaction is accepted and then never appears), and
+  command acks come back as `response:{…}` — parse without stripping that prefix
+  and a working call reads as a failure.
+
 - **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing, engineer?,
   safety? })` = smoke + 5 memory + 1 safety (quoted content is data, on by
   default) + routing per dept + optional engineer pair (vision loop, push-to-main