@kybernesis/create 0.8.2 → 0.10.0

package/dist/cli.js

@@ -19,6 +19,7 @@ import { bold, dim, red } from "./util.js";
 import { init } from "./init.js";
 import { doctor } from "./doctor.js";
 import { upgrade } from "./upgrade.js";
+import { tui } from "./tui.js";
 import { installSkills } from "./skills.js";
 import { deploy } from "./deploy.js";
 import { register } from "./register.js";
@@ -70,6 +71,7 @@ const COMMANDS = {
     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).",
+    tui: "Talk to your agents in the terminal.",
     version: "Print the version of this tool.",
 };
 /**
@@ -132,6 +134,9 @@ switch (command) {
     case "deploy":
         await deploy({ host: flag(rest, "host"), noEnv: rest.includes("--no-env") });
         break;
+    case "tui":
+        tui(rest);
+        break;
     case "upgrade":
         await upgrade(rest.includes("--skip-eval"));
         break;

package/dist/tui.d.ts

@@ -0,0 +1 @@
+export declare function tui(args: string[]): void;

package/dist/tui.js

@@ -0,0 +1,48 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { bold, dim, yellow } from "./util.js";
+/**
+ * Hand the terminal to the TUI.
+ *
+ * @remarks
+ * The TUI is a compiled binary rather than part of this package, so this
+ * command's whole job is finding it and getting out of the way. `stdio:
+ * "inherit"` is the load-bearing part: a full-screen app needs the real
+ * terminal, not a pipe, and anything that buffers its output turns it into
+ * garbage on the way through.
+ *
+ * The search order is deliberate. PATH first, so a version someone installed
+ * on purpose wins; then the two places it actually lands — cargo's bin, and a
+ * checkout's release build — because "command not found" is a useless answer
+ * when the binary is sitting in one of two well-known directories.
+ */
+const BINARY = "kyb-tui";
+function candidates() {
+    const onPath = (process.env.PATH ?? "")
+        .split(delimiter)
+        .filter(Boolean)
+        .map((dir) => join(dir, BINARY));
+    return [
+        ...onPath,
+        join(homedir(), ".cargo", "bin", BINARY),
+        join(homedir(), "kyb-tui", "target", "release", BINARY),
+    ];
+}
+export function tui(args) {
+    const binary = candidates().find((path) => existsSync(path));
+    if (!binary) {
+        console.log(`\n  ${yellow("The terminal app is not installed on this machine.")}\n`);
+        console.log(`  ${bold("cargo install --path .")}  ${dim("from the kyb-tui checkout")}\n`);
+        process.exit(1);
+    }
+    const result = spawnSync(binary, args, { stdio: "inherit" });
+    // Exit with what it exited with: a wrapper that always reports success makes
+    // the thing it wraps untestable from a script.
+    if (result.error) {
+        console.error(`\n  Could not start the terminal app: ${result.error.message}\n`);
+        process.exit(1);
+    }
+    process.exit(result.status ?? 0);
+}

package/package.json

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