@kybernesis/buzz 0.5.0 → 0.6.2

package/dist/_chunks/find-B2f5dymb.mjs

@@ -0,0 +1,108 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { existsSync, readFileSync } from "node:fs";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+import { finalizeEvent, getPublicKey } from "nostr-tools/pure";
+import { createHash, randomUUID } from "node:crypto";
+const KIND_HTTP_AUTH = 27235;
+async function queryRelay(relayHttpUrl, secretKey, filters) {
+	const url = `${relayHttpUrl.replace(/\/$/, "")}/query`;
+	const body = JSON.stringify(filters);
+	const auth = finalizeEvent({
+		kind: KIND_HTTP_AUTH,
+		created_at: Math.floor(Date.now() / 1e3),
+		tags: [
+			["u", url],
+			["method", "POST"],
+			["nonce", randomUUID()],
+			["payload", createHash("sha256").update(body).digest("hex")]
+		],
+		content: ""
+	}, secretKey);
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			authorization: `Nostr ${Buffer.from(JSON.stringify(auth)).toString("base64")}`,
+			"content-type": "application/json"
+		},
+		body
+	});
+	const text = await response.text();
+	if (!response.ok) throw new Error(`relay ${response.status}: ${text.slice(0, 300)}`);
+	return {
+		events: JSON.parse(text),
+		status: response.status,
+		bytes: text.length
+	};
+}
+const KINDS = {
+	project: 30621,
+	repo: 30617,
+	issue: 1621,
+	patch: 1617,
+	message: 9,
+	note: 30023,
+	profile: 0
+};
+var find_default = defineTool({
+	description: "Find what exists in the Buzz workspace, across everyone — projects, repos, issues, patches, notes, profiles. Use this for questions like \"what projects exist here?\", which the buzz CLI's list commands CANNOT answer: those are scoped to this agent's own items and will report none when the workspace is full of other people's. Give a `type` (project, repo, issue, patch, note, message, profile) or raw `kinds`.",
+	inputSchema: z.object({
+		type: z.enum([
+			"project",
+			"repo",
+			"issue",
+			"patch",
+			"note",
+			"message",
+			"profile"
+		]).optional().describe("What to look for. Omit only if passing raw kinds."),
+		kinds: z.array(z.number()).optional().describe("Raw Nostr kind numbers, for anything not named above."),
+		authors: z.array(z.string()).optional().describe("Restrict to these author pubkeys (64-char hex). Omit for everyone in the workspace."),
+		limit: z.number().optional().describe("How many at most. Defaults to 50."),
+		community: z.string().optional().describe("Which workspace, when this agent belongs to more than one. Any distinctive part of its address.")
+	}),
+	async execute({ type, kinds, authors, limit, community }) {
+		const keyFile = process.env.BUZZ_KEYFILE ?? ".buzz-key.json";
+		if (!existsSync(keyFile)) return `No Buzz identity at ${keyFile}: this agent has no standing in the workspace yet.`;
+		const configured = (process.env.BUZZ_RELAY_HTTP ?? process.env.BUZZ_RELAY ?? "").split(",").map((entry) => entry.trim().replace(/^ws/, "http")).filter(Boolean);
+		if (configured.length === 0) return "No Buzz relay configured (BUZZ_RELAY).";
+		let relay;
+		if (community) {
+			const matches = configured.filter((entry) => entry.includes(community));
+			if (matches.length !== 1) return `"${community}" does not pick out exactly one of: ${configured.join(", ")}`;
+			relay = matches[0];
+		} else if (configured.length > 1) return `This agent belongs to more than one workspace — say which: ${configured.join(", ")}`;
+		else relay = configured[0];
+		const wanted = (kinds?.length ? kinds : void 0) ?? (type ? [KINDS[type]] : void 0);
+		const by = authors?.length ? authors : void 0;
+		if (!wanted) return "Say what to look for: a `type`, or raw `kinds`.";
+		const stored = JSON.parse(readFileSync(keyFile, "utf8"));
+		const asWhom = getPublicKey(Uint8Array.from(stored.secretKey));
+		try {
+			const filter = {
+				kinds: wanted,
+				...by ? { authors: by } : {},
+				limit: limit ?? 50
+			};
+			const { events, status, bytes } = await queryRelay(relay, Uint8Array.from(stored.secretKey), [filter]);
+			if (events.length === 0) return `Nothing in ${relay} matching ${JSON.stringify(filter)} (searched as ${asWhom.slice(0, 8)}…, relay answered ${status}).`;
+			return JSON.stringify(events.map((event) => ({
+				id: event.id,
+				author: event.pubkey,
+				created: new Date(event.created_at * 1e3).toISOString(),
+				name: event.tags.find((tag) => tag[0] === "name")?.[1],
+				slug: event.tags.find((tag) => tag[0] === "d")?.[1],
+				subject: event.tags.find((tag) => tag[0] === "subject")?.[1],
+				content: event.content?.slice(0, 400)
+			})), null, 1);
+		} catch (error) {
+			return `Could not read the workspace: ${error.message}`;
+		}
+	}
+});
+export { find_default as t };

package/dist/bridge.js

@@ -1,4 +1,5 @@
 import { channelIdentity } from "@kybernesis/enterprise";
+import { speakerCredentials } from "./credentials.js";
 import { Client } from "eve/client";
 import { BuzzRelay } from "./relay.js";
 import { loadKey, npubEncode } from "./keys.js";
@@ -50,14 +51,33 @@ export function buzzBridge(options) {
     const sessions = new Map();
     /** Who has already been sent a link, so a room full of strangers is not a room full of spam. */
     const invited = new Map();
-    const clientFor = (token, bundle) => 
-    // `host`, not `baseUrl`: a wrong key is ignored rather than rejected, and the client then
-    // builds a nonsense URL — an error about a malformed URL rather than about a mistyped option.
-    new Client({
-        host: options.agentUrl,
-        auth: { bearer: token },
-        headers: bundle ? { "x-kybernesis-bundle": bundle } : {},
-    });
+    /**
+     * A client whose credentials are resolved per request, not captured once.
+     *
+     * The identity token a turn starts with lives about five minutes. That was
+     * invisible while turns ended early — and became a failure the moment they
+     * were allowed to run to completion: a turn doing real work for six minutes
+     * reconnected its stream with the token it began with, the agent answered
+     * "Authorization is required for this route", and the reply was lost after
+     * all the work had been done. In a channel that reads as the agent typing
+     * for five minutes and then saying nothing.
+     *
+     * Resolving per request costs nothing in the normal case — the resolver
+     * caches and re-mints only near expiry — and it keeps the property the short
+     * lifetime exists for: a person whose access is revoked mid-turn stops being
+     * able to act on the next request rather than at the end of the turn.
+     */
+    const credentialsFor = speakerCredentials((externalId) => identity.resolve(PROVIDER, externalId, npubEncode(externalId)));
+    const clientFor = (pubkey) => {
+        const credentials = credentialsFor(pubkey);
+        // `host`, not `baseUrl`: a wrong key is ignored rather than rejected, and the client then
+        // builds a nonsense URL — an error about a malformed URL rather than about a mistyped option.
+        return new Client({
+            host: options.agentUrl,
+            auth: { bearer: credentials.bearer },
+            headers: credentials.headers,
+        });
+    };
     /**
      * One turn at a time per channel.
      *
@@ -73,9 +93,20 @@ export function buzzBridge(options) {
         inFlight.set(channel, queued.catch(() => { }));
         return queued;
     }
-    async function ask(channel, text, token, bundle) {
-        // Built per turn, for the person whose turn it is.
-        const client = clientFor(token, bundle);
+    /**
+     * Where this conversation is happening, handed to the agent with the turn.
+     *
+     * An agent in two communities was asked "what projects exist in this relay?"
+     * and could not know which relay "this" was — so it reached for a
+     * human-in-the-loop question, which parks a turn until somebody answers it.
+     * In a channel nobody does, so the turn never finished and the room got
+     * nothing. The bridge knew the answer the whole time: it is the connection
+     * the message arrived on.
+     */
+    async function ask(channel, text, pubkey, community) {
+        // Built per turn, for the person whose turn it is — and kept current for as
+        // long as that turn runs.
+        const client = clientFor(pubkey);
         const existing = sessions.get(channel);
         if (existing) {
             try {
@@ -107,7 +138,7 @@ export function buzzBridge(options) {
                 if (unread > 0) {
                     log(`caught up on ${unread} unread event(s) in ${channel.slice(0, 8)} before answering`);
                 }
-                const response = await session.send(text);
+                const response = await session.send(text, { clientContext: { buzzCommunity: community, buzzChannel: channel } });
                 const result = await response.result();
                 // Where this turn left the conversation, so the next one starts after it.
                 sessions.set(channel, { id: existing.id, streamIndex: session.state.streamIndex });
@@ -120,7 +151,10 @@ export function buzzBridge(options) {
                 sessions.delete(channel);
             }
         }
-        const created = await client.sessions.create({ message: text });
+        const created = await client.sessions.create({
+            message: text,
+            clientContext: { buzzCommunity: community, buzzChannel: channel },
+        });
         const message = (await created.response.result()).message ?? "";
         sessions.set(channel, {
             id: created.session.state.sessionId,
@@ -212,7 +246,7 @@ export function buzzBridge(options) {
         void relay.react(event.id, SEEN);
         const stopTyping = relay.typingIn(channel);
         try {
-            const reply = await serialize(channel, () => ask(channel, text, speaker.token, speaker.bundle));
+            const reply = await serialize(channel, () => ask(channel, text, event.pubkey, from));
             if (!reply) {
                 /**
                  * Silence is the worst answer available.

package/dist/cli.js

@@ -183,6 +183,73 @@ WantedBy=multi-user.target
     }
     process.stdout.write(unit);
 }
+/**
+ * Put the Buzz CLI on this host, so the agent can act in the workspace.
+ *
+ * @remarks
+ * The bridge gives an agent a voice; the CLI is how Buzz expects an agent to
+ * DO anything — projects, issues, pull requests, notes, canvases. Its own
+ * README is explicit: the harness prompts the agent, "and the agent replies
+ * using the Buzz CLI".
+ *
+ * There is no published binary — the project releases desktop apps only — so
+ * this builds one, from a pinned revision, in a container, and puts it where
+ * the tool looks. That is a script's job and not a person's: the alternative
+ * is a client being walked through a git checkout and a Rust toolchain, which
+ * is not an answer anyone should give a customer.
+ *
+ * `BUZZ_CLI_URL` short-circuits the build for hosts that have no Docker: point
+ * it at a binary built once for the same platform.
+ */
+async function installCli() {
+    const { execFileSync } = await import("node:child_process");
+    const { chmodSync, existsSync, mkdirSync } = await import("node:fs");
+    const { dirname, resolve } = await import("node:path");
+    const target = resolve(process.env.BUZZ_CLI_PATH ?? ".buzz/bin/buzz");
+    mkdirSync(dirname(target), { recursive: true });
+    const url = process.env.BUZZ_CLI_URL;
+    if (url) {
+        console.log(`  downloading ${url}`);
+        const response = await fetch(url);
+        if (!response.ok)
+            throw new Error(`could not download the CLI (HTTP ${response.status})`);
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(target, Buffer.from(await response.arrayBuffer()));
+        chmodSync(target, 0o755);
+        console.log(`  ✓ ${target}`);
+        return;
+    }
+    try {
+        execFileSync("docker", ["--version"], { stdio: "ignore" });
+    }
+    catch {
+        throw new Error("no docker on this host, and no BUZZ_CLI_URL set. Build the CLI once elsewhere for this " +
+            "platform and point BUZZ_CLI_URL at it, or install docker.");
+    }
+    // Pinned. A CLI that changes under a fleet on an unrelated restart is a
+    // fleet whose behaviour changed for reasons nobody can reconstruct.
+    const source = resolve(process.env.BUZZ_CLI_SRC ?? ".buzz/src");
+    if (!existsSync(source)) {
+        console.log("  fetching the CLI source (once)…");
+        execFileSync("git", ["clone", "--depth", "1", "https://github.com/block/buzz.git", source], {
+            stdio: "inherit",
+        });
+    }
+    console.log("  building — a few minutes the first time, then cached…");
+    execFileSync("docker", [
+        "run", "--rm",
+        "-v", `${source}:/src`,
+        "-w", "/src",
+        "rust:1-slim",
+        "sh", "-c",
+        "apt-get update -qq && apt-get install -y -qq pkg-config libssl-dev >/dev/null 2>&1; cargo build --release -p buzz-cli",
+    ], { stdio: "inherit" });
+    const { copyFileSync } = await import("node:fs");
+    copyFileSync(`${source}/target/release/buzz`, target);
+    chmodSync(target, 0o755);
+    console.log(`\n  ✓ ${target}`);
+    console.log("    The agent finds it there automatically; set BUZZ_CLI_PATH to move it.");
+}
 const command = process.argv[2];
 if (command === "profile") {
     setProfile().catch((error) => {
@@ -196,6 +263,12 @@ else if (command === "run")
     run();
 else if (command === "service")
     service();
+else if (command === "install-cli") {
+    installCli().catch((error) => {
+        console.error(`\n  ${error.message}\n`);
+        process.exit(1);
+    });
+}
 else if (command === "id") {
     const hex = asHexPubkey(process.argv[3]);
     if (!hex) {
@@ -209,7 +282,7 @@ else {
     console.log(`
   kybernesis-buzz — put an agent in a workspace
 
-    init              create or show this agent's identity, and what to invite
+    init              create or show this agent's identity, and what to invite\n    install-cli       install the Buzz CLI, so the agent can act as well as talk
     profile           say who this agent is, in every community it belongs to
     run               run the bridge
     service [path]    print (or write) a systemd unit for it

package/dist/credentials.d.ts

@@ -0,0 +1,25 @@
+import type { SpeakerResolution } from "@kybernesis/enterprise";
+/** What the eve client needs to authenticate one person's turn. */
+export interface SpeakerCredentials {
+    /** Bearer resolver — called by the client before every HTTP request. */
+    bearer: () => Promise<string>;
+    /** Header resolver, for the same reason and on the same schedule. */
+    headers: () => Promise<Readonly<Record<string, string>>>;
+}
+/**
+ * Credentials for a turn, resolved per request rather than captured once.
+ *
+ * @remarks
+ * An identity token lives about five minutes. That was invisible while turns
+ * ended early, and became a failure the moment they ran to completion: a turn
+ * doing six minutes of real work reconnected its stream with the token it began
+ * with, the agent answered "Authorization is required for this route", and the
+ * reply was lost after every tool call had already succeeded. In a channel that
+ * reads as the agent typing for five minutes and then saying nothing at all.
+ *
+ * Resolving per request costs nothing in the normal case, because the resolver
+ * caches and re-mints only near expiry. It also preserves the property the
+ * short lifetime exists for: access withdrawn mid-turn stops the next request
+ * rather than being noticed after the work is done.
+ */
+export declare function speakerCredentials(resolve: (externalId: string) => Promise<SpeakerResolution>): (externalId: string) => SpeakerCredentials;

package/dist/credentials.js

@@ -0,0 +1,36 @@
+/**
+ * Credentials for a turn, resolved per request rather than captured once.
+ *
+ * @remarks
+ * An identity token lives about five minutes. That was invisible while turns
+ * ended early, and became a failure the moment they ran to completion: a turn
+ * doing six minutes of real work reconnected its stream with the token it began
+ * with, the agent answered "Authorization is required for this route", and the
+ * reply was lost after every tool call had already succeeded. In a channel that
+ * reads as the agent typing for five minutes and then saying nothing at all.
+ *
+ * Resolving per request costs nothing in the normal case, because the resolver
+ * caches and re-mints only near expiry. It also preserves the property the
+ * short lifetime exists for: access withdrawn mid-turn stops the next request
+ * rather than being noticed after the work is done.
+ */
+export function speakerCredentials(resolve) {
+    return (externalId) => {
+        const current = async () => {
+            const speaker = await resolve(externalId);
+            if (!speaker.linked) {
+                // Failing here is the point: the alternative is finishing a turn with a
+                // credential the control plane has already withdrawn.
+                throw new Error(`no longer authorized (${speaker.reason})`);
+            }
+            return { token: speaker.token, bundle: speaker.bundle };
+        };
+        return {
+            bearer: async () => (await current()).token,
+            headers: async () => {
+                const { bundle } = await current();
+                return bundle ? { "x-kybernesis-bundle": bundle } : {};
+            },
+        };
+    };
+}

package/dist/extension/_manifest.json

@@ -0,0 +1,10 @@
+{
+  "kind": "eve-extension",
+  "formatVersion": 1,
+  "builtWithEve": "0.38.3",
+  "requires": {
+    "extension": 1,
+    "tool": 13,
+    "instructions": 2
+  }
+}

package/dist/extension/extension.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The agent's hands in Buzz.
+ *
+ * The bridge in this package gives an agent a voice — it hears mentions and
+ * answers as the person who asked. This gives it everything else the platform
+ * has: projects, issues, pull requests, patches, repositories, long-form notes,
+ * channel canvases, workflows, the activity feed, media.
+ *
+ * Buzz's own design says an agent acts through its CLI — the harness prompts
+ * the agent, "and the agent replies using the Buzz CLI". We replaced the
+ * harness half to get governed per-person identity, and for a while shipped
+ * only that half: agents could talk in a workspace and do nothing in it, and
+ * would say Projects did not exist because nothing had told them otherwise.
+ */
+declare const _default: import("eve/extension").NoConfigExtensionHandle;
+export default _default;

package/dist/extension/extension.mjs

@@ -0,0 +1,9 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { defineExtension } from "eve/extension";
+var extension_default = defineExtension();
+export { extension_default as default };

package/dist/extension/instructions.md

@@ -0,0 +1,116 @@
+## Acting in Buzz
+
+You are a **member** of this workspace, with your own standing — not a visitor
+driving someone else's account. Alongside talking in channels you can use the
+`buzz` tool to work in it: projects, issues, pull requests, patches, repos,
+long-form notes, channel canvases, workflows, the feed, media, custom emoji.
+
+Run `buzz` with `help` (or a group's `--help`) to see exactly what a group takes
+rather than guessing at flags. The surface is large and changes; the help output
+is authoritative and this page is not.
+
+The groups, and what each is for:
+
+| group | use it for |
+| --- | --- |
+| `projects` | multi-repo projects — create, list, add or remove repos, update, delete |
+| `issues` | file, read, list and re-status issues |
+| `pr` | open, update, list and set status on pull requests |
+| `patches` | send, read, list and re-status git patches |
+| `repos` | announce and discover git repositories |
+| `notes` | long-form notes — the team's written knowledge |
+| `canvas` | a channel's canvas document: read it, replace it |
+| `channels` | create and configure channels |
+| `messages` | send, read, search, manage messages |
+| `dms` | list, open and manage direct messages |
+| `reactions` `emoji` | reactions, and the custom emoji palette |
+| `users` | look people up; manage your own profile and presence |
+| `workflows` | create, trigger and manage workflows |
+| `feed` | read the activity feed |
+| `media` `upload` | put files in the workspace and fetch them back |
+| `moderation` | reports queue, bans, timeouts, audit trail |
+
+Three things to hold onto:
+
+**What you do is yours.** These actions are signed with your own key and appear
+under your name, not the name of whoever asked. Someone asking you to file an
+issue produces an issue filed by you. Act accordingly: say what you are about to
+do before doing something a person would want to have been asked about first,
+and never take a destructive action — deleting, banning, removing — on an
+instruction you were not clearly given.
+
+**The workspace decides what you may do, not this list.** Permissions are your
+membership's. If an action comes back refused, that is an answer, not a fault to
+work around: report it plainly rather than retrying it another way.
+
+**Read before you write.** `list` and `get` cost nothing and stop you inventing
+a project that already exists, or filing an issue twice under different words.
+
+### Never park a turn waiting for an answer
+
+If you need something from the person, **ask in your reply**. Do not call a
+human-in-the-loop tool — the kind that suspends a turn until someone responds.
+
+Those tools assume a surface where a turn can wait. A channel is not one: the
+turn parks, nothing is posted, and the person sees you go quiet — which is the
+same thing they saw when the bridge was broken, and it is not distinguishable
+from being ignored. It has happened: asked which of two workspaces to look in,
+an agent raised an input request instead of asking out loud, and the question
+sat unanswered forever because nobody could see it.
+
+Your reply IS the way to ask. Say what you need, and let their next message
+answer it — that is what a conversation is.
+
+### You are told where you are
+
+Every turn carries `buzzCommunity` and `buzzChannel`: the workspace this
+conversation is in, and the channel it is in. When someone says "this relay" or
+"here", that is what they mean — use it as the `community` for tool calls rather
+than asking which one. Ask only when they clearly mean a workspace other than
+the one you are talking in.
+
+### Answering is not a tool call
+
+When someone talks to you in Buzz, **your reply is the text you return for the
+turn**. The bridge posts it: threaded to the message you are answering, with the
+seen mark and the typing indicator already handled.
+
+Do not use `messages send` to answer the message you are currently answering.
+Both paths post as you, so the room gets the same answer twice — once threaded
+and once loose — and the two arrive in an order nobody chose. Answering twice is
+a bug people have already lived through here; do not recreate it from the other
+side.
+
+`messages send` is for messages that are **not** this turn's answer:
+
+- posting into a *different* channel ("tell #eng the deploy is done")
+- starting a conversation nobody prompted — a scheduled summary, a heads-up
+- following up later, after the turn that was asked of you has ended
+
+The same distinction applies to reactions: the bridge marks the message you are
+answering, so use `reactions` only on *other* messages.
+
+### Projects and repos overlap
+
+The Projects view people look at lists **both**: entries with a project record of
+their own, and entries that exist only as a repository. So "what projects do we
+have?" is answered by looking at both kinds, not just projects — answering with
+one of them is how you tell someone an item they are looking at right now does
+not exist.
+
+Say which is which when it matters ("three, though one is a repo without a
+project record"), and never correct someone's own vocabulary at the cost of
+answering their question.
+
+### Which workspace
+
+If this agent belongs to more than one community, every command must say which
+one — pass `community` with any distinctive part of its address. There is no
+default: a project created in the wrong company's workspace is not a mistake
+that can be taken back.
+
+### When it is not installed
+
+If the tool says the CLI is missing, say so plainly and stop. It is one command
+on the host (`kybernesis-buzz install-cli`) and it is not something to work
+around by posting a message asking someone else to do the task.

package/dist/extension/tools/buzz.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("eve/tools").ToolDefinition<{
+    args: string[];
+    community?: string | undefined;
+}, string> & {
+    execute(input: {
+        args: string[];
+        community?: string | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<string>;
+};
+export default _default;

package/dist/extension/tools/buzz.mjs

@@ -0,0 +1,56 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+const run = promisify(execFile);
+function secretKeyHex(keyFile) {
+	const stored = JSON.parse(readFileSync(keyFile, "utf8"));
+	return Buffer.from(Uint8Array.from(stored.secretKey)).toString("hex");
+}
+var buzz_default = defineTool({
+	description: "Act in the Buzz workspace: projects, issues, pull requests, patches, repos, long-form notes, channel canvases, workflows, the activity feed, media, emoji, moderation. Pass the command as a list of arguments, e.g. [\"projects\",\"list\"] or [\"issues\",\"create\",\"--repo\",\"acme/api\",\"--title\",\"Login fails on Safari\"]. Use [\"help\"] or [\"<group>\",\"--help\"] to see what a group takes instead of guessing at flags. Actions are signed as THIS AGENT and appear under its name. Do NOT use it to answer the message you are currently answering — returning your reply for the turn does that, threaded and marked; sending as well posts the same answer twice. Use messages/dms only for a DIFFERENT channel, an unprompted message, or a later follow-up.",
+	inputSchema: z.object({
+		args: z.array(z.string()).min(1).describe("The command as separate arguments, without the leading \"buzz\". Example: [\"projects\",\"get\",\"--slug\",\"atlas\"]."),
+		community: z.string().optional().describe("Which workspace to act in, when this agent belongs to more than one. Any distinctive part of its address is enough. Omit it when there is only one.")
+	}),
+	async execute({ args, community }) {
+		const local = ".buzz/bin/buzz";
+		const binary = process.env.BUZZ_CLI_PATH ?? (existsSync(local) ? resolve(local) : "buzz");
+		const keyFile = process.env.BUZZ_KEYFILE ?? ".buzz-key.json";
+		const configured = (process.env.BUZZ_RELAY_HTTP ?? process.env.BUZZ_RELAY ?? "").split(",").map((entry) => entry.trim().replace(/^ws/, "http")).filter(Boolean);
+		if (configured.length === 0) return "No Buzz relay configured: set BUZZ_RELAY (the bridge's websocket URL) or BUZZ_RELAY_HTTP.";
+		let relay;
+		if (community) {
+			const matches = configured.filter((entry) => entry.includes(community));
+			if (matches.length !== 1) return `"${community}" ${matches.length === 0 ? "matches none of" : "matches more than one of"} this agent's workspaces: ${configured.join(", ")}`;
+			relay = matches[0];
+		} else if (configured.length > 1) return `This agent belongs to more than one workspace, so say which one to act in: ${configured.join(", ")}. Pass it as "community".`;
+		else relay = configured[0];
+		if (!existsSync(keyFile)) return `No Buzz identity at ${keyFile}. This agent has no standing in the workspace until \`kybernesis-buzz init\` has run on this host.`;
+		try {
+			const { stdout } = await run(binary, args, {
+				env: {
+					...process.env,
+					BUZZ_RELAY_URL: relay,
+					BUZZ_PRIVATE_KEY: secretKeyHex(keyFile)
+				},
+				timeout: 12e4,
+				maxBuffer: 4194304
+			});
+			return stdout.trim() || "(no output)";
+		} catch (error) {
+			const failure = error;
+			if (failure.code === "ENOENT") return `The Buzz CLI is not installed on this host (looked for "${binary}"). Install it with \`kybernesis-buzz install-cli\`, or set BUZZ_CLI_PATH to where it lives.`;
+			return (failure.stderr ?? failure.message ?? "").trim() || "The Buzz CLI failed without saying why.";
+		}
+	}
+});
+export { buzz_default as default };

package/dist/extension/tools/find.d.ts

@@ -0,0 +1,16 @@
+declare const _default: import("eve/tools").ToolDefinition<{
+    type?: "issue" | "message" | "note" | "patch" | "profile" | "project" | "repo" | undefined;
+    kinds?: number[] | undefined;
+    authors?: string[] | undefined;
+    limit?: number | undefined;
+    community?: string | undefined;
+}, string> & {
+    execute(input: {
+        type?: "issue" | "message" | "note" | "patch" | "profile" | "project" | "repo" | undefined;
+        kinds?: number[] | undefined;
+        authors?: string[] | undefined;
+        limit?: number | undefined;
+        community?: string | undefined;
+    }, ctx: import("eve/tools").ToolContext): Promise<string>;
+};
+export default _default;

package/dist/extension/tools/find.mjs

@@ -0,0 +1,8 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import { t as find_default } from "../../_chunks/find-B2f5dymb.mjs";
+export { find_default as default };

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import extension_default from "./extension/extension.mjs";
+export { extension_default as buzz, extension_default as default };

package/dist/query.d.ts

@@ -0,0 +1,22 @@
+import { type NostrEvent } from "./relay.js";
+/**
+ * Read the whole workspace, not just your own corner of it.
+ *
+ * @remarks
+ * The Buzz CLI's list commands are owner-scoped — `--owner` defaults to the
+ * current identity — which is right for "my repos" and wrong for the question
+ * people actually ask an agent: *what projects exist here?* Asked that in a
+ * workspace holding three, an agent answered "none", because it had listed its
+ * own and had none. It was not broken and it was not lying; it had been given a
+ * tool that could only see one author and no way to know that mattered.
+ *
+ * There is no CLI command for the general case, but the relay has the endpoint
+ * the CLI itself uses: `POST /query`, NIP-98 signed, taking an array of Nostr
+ * filters. That is one request away from every kind the platform stores —
+ * projects, repos, issues, patches, notes — across everyone in the workspace.
+ */
+export declare function queryRelay(relayHttpUrl: string, secretKey: Uint8Array, filters: readonly Record<string, unknown>[]): Promise<{
+    events: NostrEvent[];
+    status: number;
+    bytes: number;
+}>;

package/dist/query.js

@@ -0,0 +1,63 @@
+import { createHash, randomUUID } from "node:crypto";
+import { finalizeEvent } from "nostr-tools/pure";
+import { KIND_HTTP_AUTH } from "./relay.js";
+/**
+ * Read the whole workspace, not just your own corner of it.
+ *
+ * @remarks
+ * The Buzz CLI's list commands are owner-scoped — `--owner` defaults to the
+ * current identity — which is right for "my repos" and wrong for the question
+ * people actually ask an agent: *what projects exist here?* Asked that in a
+ * workspace holding three, an agent answered "none", because it had listed its
+ * own and had none. It was not broken and it was not lying; it had been given a
+ * tool that could only see one author and no way to know that mattered.
+ *
+ * There is no CLI command for the general case, but the relay has the endpoint
+ * the CLI itself uses: `POST /query`, NIP-98 signed, taking an array of Nostr
+ * filters. That is one request away from every kind the platform stores —
+ * projects, repos, issues, patches, notes — across everyone in the workspace.
+ */
+export async function queryRelay(relayHttpUrl, secretKey, filters) {
+    const url = `${relayHttpUrl.replace(/\/$/, "")}/query`;
+    const body = JSON.stringify(filters);
+    // Signed exactly as the socket path signs: the signature binds the body, so a
+    // filter cannot be swapped in transit.
+    const auth = finalizeEvent({
+        kind: KIND_HTTP_AUTH,
+        created_at: Math.floor(Date.now() / 1000),
+        tags: [
+            ["u", url],
+            ["method", "POST"],
+            // A nonce, because the relay rejects a repeated auth event as a replay.
+            // Without it two identical requests — the same query twice, the same
+            // reaction twice — sign byte-identically and the second is refused. The
+            // refusal does not always look like one either: a duplicated read came
+            // back as an empty list, so an agent reported an empty workspace instead
+            // of a rejected request.
+            ["nonce", randomUUID()],
+            ["payload", createHash("sha256").update(body).digest("hex")],
+        ],
+        content: "",
+    }, secretKey);
+    // Bound to this module deliberately: eve's runtime replaces the global fetch
+    // in the deployed server, and a request that goes through a different client
+    // than the one that signed it can arrive unauthenticated — which this relay
+    // answers with an empty list rather than a refusal, so it reads as "nothing
+    // here" instead of "you are not who you said you were".
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            authorization: `Nostr ${Buffer.from(JSON.stringify(auth)).toString("base64")}`,
+            "content-type": "application/json",
+        },
+        body,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`relay ${response.status}: ${text.slice(0, 300)}`);
+    }
+    // The status and size travel with the answer because an empty list and a
+    // rejected request look identical to a caller that only sees the events, and
+    // this relay answers some refusals with 200 and an empty array.
+    return { events: JSON.parse(text), status: response.status, bytes: text.length };
+}

package/dist/relay.js

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { finalizeEvent } from "nostr-tools/pure";
 /**
  * The workspace protocol, as far as a member needs it.
@@ -235,6 +235,13 @@ export class BuzzRelay {
             tags: [
                 ["u", url],
                 ["method", "POST"],
+                // A nonce, because the relay rejects a repeated auth event as a replay.
+                // Without it two identical requests — the same query twice, the same
+                // reaction twice — sign byte-identically and the second is refused. The
+                // refusal does not always look like one either: a duplicated read came
+                // back as an empty list, so an agent reported an empty workspace instead
+                // of a rejected request.
+                ["nonce", randomUUID()],
                 ["payload", createHash("sha256").update(body).digest("hex")],
             ],
             content: "",

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+// Generated by eve. Do not edit by hand.
+
+export { default as buzz } from "../extension/tools/buzz.js";
+export { default as find } from "../extension/tools/find.js";

package/dist/tools/index.mjs

@@ -0,0 +1,9 @@
+import { fileURLToPath as __eveFileURLToPath } from "node:url";
+import { dirname as __eveDirname } from "node:path";
+import { createRequire as __eveCreateRequire } from "node:module";
+const __filename = __eveFileURLToPath(import.meta.url);
+__eveDirname(__filename);
+__eveCreateRequire(import.meta.url);
+import buzz_default from "../extension/tools/buzz.mjs";
+import { t as find_default } from "../_chunks/find-B2f5dymb.mjs";
+export { buzz_default as buzz, find_default as find };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "description": "Put an eve agent in a Buzz workspace as a member: per-speaker verified identity resolved through the control plane, self-service identity linking, presence, typing and seen signals.",
   "license": "Apache-2.0",
   "type": "module",
@@ -24,20 +24,29 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "default": "./dist/index.mjs"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./tools": {
+      "types": "./dist/tools/index.d.ts",
+      "default": "./dist/tools/index.mjs"
+    },
+    "./extension": {
+      "types": "./dist/extension/extension.d.ts",
+      "default": "./dist/extension/extension.mjs"
+    }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepack": "tsc -p tsconfig.build.json",
+    "build": "eve extension build && tsc -p tsconfig.build.json",
+    "prepack": "eve extension build && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "node ../../scripts/prepublish.mjs",
     "test": "node --test \"test/**/*.test.mjs\""
   },
   "dependencies": {
     "@kybernesis/enterprise": "^0.7.0",
-    "nostr-tools": "^2.10.0"
+    "nostr-tools": "^2.10.0",
+    "zod": "^4"
   },
   "devDependencies": {
     "@types/node": "24.x",
@@ -54,5 +63,11 @@
     "type": "git",
     "url": "https://github.com/KybernesisAI/platform.git",
     "directory": "packages/buzz"
+  },
+  "eve": {
+    "extension": {
+      "source": "./extension",
+      "dist": "./dist/extension"
+    }
   }
 }