@kybernesis/buzz 0.10.0 → 0.10.2

package/README.md

@@ -53,6 +53,16 @@ BUZZ_RELAY="wss://one.communities.buzz.xyz,wss://two.communities.buzz.xyz"
 Conversations never mix: a channel belongs to exactly one community, and
 sessions are keyed by channel.
 
+## Who it says it is
+
+An agent connected to a `.agent` name takes its profile from the name: display name,
+description, picture and NIP-05 handle. The bridge reads the name's public profile document
+(`https://<name>.agentid.dev/.well-known/agent-profile.json`) when it starts and every six
+hours, and writes the profile only in communities whose copy differs. A new picture, a new
+description, or the name's address moving reaches every community without a command on the
+host. The name comes from `ARP_AGENT_DID`, or from `.eve/arp-identity.json` in the agent's
+directory. `kybernesis-buzz profile --from-agentid` does the same once, on demand.
+
 ## Configuration
 
 | Variable | Meaning |
@@ -63,6 +73,8 @@ sessions are keyed by channel.
 | `BUZZ_SESSIONS_FILE` | Channel-to-session continuity store (default beside the key file; an existing legacy `.buzz-sessions.json` is reused) |
 | `BUZZ_AGENT_SILENCE_TIMEOUT_MS` | Maximum silence before the agent acknowledges a request: unread drain, send and create acknowledgement (default `300000`, five minutes). This is where a genuine stall shows: no run is ever created. |
 | `BUZZ_AGENT_WORK_TIMEOUT_MS` | Ceiling on silence once the response stream is open (default `3600000`, sixty minutes). The stream is quiet while the agent works, a long tool call or a delegated subagent produces nothing until it returns, so this is a ceiling on work, not a stall detector. |
+| `BUZZ_PROFILE_SYNC_MS` | How often the profile is re-checked against the agent's `.agent` name (default `21600000`, six hours; `0` turns it off) |
+| `AGENTID_MIRROR_SUFFIX` | Where names serve their public documents (default `.agentid.dev`); for staging only |
 | `KYBERNESIS_ISSUER` | The control plane |
 | `KYBERNESIS_AGENT_CREDENTIAL` | This agent's credential |
 

package/dist/agentid.d.ts

@@ -0,0 +1,54 @@
+import type { AgentKey } from "./keys.js";
+import * as profile from "./profile.js";
+import type { Profile } from "./profile.js";
+/**
+ * An agent's `.agent` name is the source of truth for how it presents itself.
+ *
+ * @remarks
+ * The name's public profile document carries the name, description, picture and NIP-05
+ * handle. The bridge keeps each community's copy of the profile in step with it, so a change
+ * made on the name — a new picture, a new description, or the name's address moving — reaches
+ * every community without anyone running a command on the agent's host. A one-off copy is
+ * exactly what went stale when the addresses moved: the profile kept pointing at a picture URL
+ * that no longer existed.
+ */
+/** Where names serve their public documents: `<name>.agentid.dev`. */
+export declare const DEFAULT_MIRROR_SUFFIX = ".agentid.dev";
+export type NameProfile = {
+    name: string;
+    description: string;
+    picture: string | null;
+    nip05: string | null;
+};
+/** `did:web:kyber.agent`, `kyber.agent` or `kyber` → `kyber`. Anything else is not a `.agent` name. */
+export declare function nameFromDid(did: string): string | null;
+/** The name's public profile document. `AGENTID_MIRROR_SUFFIX` overrides the host, for staging. */
+export declare function profileDocumentUrl(name: string, suffix?: string): string;
+export declare function fetchNameProfile(name: string, fetchImpl?: typeof fetch): Promise<NameProfile>;
+/** The profile fields the name decides. */
+export declare function profileFromName(name: string, doc: NameProfile): Profile;
+/** Whether a community's copy already says everything the name says. */
+export declare function matchesName(current: Profile | null, wanted: Profile): boolean;
+export type SyncOutcome = {
+    relay: string;
+    outcome: "unchanged" | "updated" | "not-member" | "failed";
+    detail?: string;
+};
+/**
+ * Bring this agent's profile in every community in line with its name.
+ *
+ * @remarks
+ * Only communities whose copy differs are written, so running this on every start and on a
+ * timer costs one read per community when nothing has changed. Fields the name does not
+ * decide are left as they are. Throws only when the name's document cannot be read; a
+ * community that refuses or is unreachable is reported, not fatal, because membership is per
+ * community and being in one and not another is the ordinary case.
+ */
+export declare function syncProfileFromName(options: {
+    name: string;
+    relays: readonly string[];
+    key: AgentKey;
+    fetch?: typeof fetch;
+    read?: typeof profile.read;
+    write?: typeof profile.write;
+}): Promise<SyncOutcome[]>;

package/dist/agentid.js

@@ -0,0 +1,81 @@
+import * as profile from "./profile.js";
+/**
+ * An agent's `.agent` name is the source of truth for how it presents itself.
+ *
+ * @remarks
+ * The name's public profile document carries the name, description, picture and NIP-05
+ * handle. The bridge keeps each community's copy of the profile in step with it, so a change
+ * made on the name — a new picture, a new description, or the name's address moving — reaches
+ * every community without anyone running a command on the agent's host. A one-off copy is
+ * exactly what went stale when the addresses moved: the profile kept pointing at a picture URL
+ * that no longer existed.
+ */
+/** Where names serve their public documents: `<name>.agentid.dev`. */
+export const DEFAULT_MIRROR_SUFFIX = ".agentid.dev";
+/** `did:web:kyber.agent`, `kyber.agent` or `kyber` → `kyber`. Anything else is not a `.agent` name. */
+export function nameFromDid(did) {
+    const match = /^(?:did:web:)?([a-z0-9-]+)(?:\.agent)?$/i.exec(did.trim());
+    return match?.[1] ? match[1].toLowerCase() : null;
+}
+/** The name's public profile document. `AGENTID_MIRROR_SUFFIX` overrides the host, for staging. */
+export function profileDocumentUrl(name, suffix = process.env.AGENTID_MIRROR_SUFFIX ?? DEFAULT_MIRROR_SUFFIX) {
+    return `https://${name}${suffix.startsWith(".") ? suffix : `.${suffix}`}/.well-known/agent-profile.json`;
+}
+export async function fetchNameProfile(name, fetchImpl = fetch) {
+    const url = profileDocumentUrl(name);
+    const res = await fetchImpl(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+    if (!res.ok)
+        throw new Error(`${name}.agent has no profile document yet (${res.status} from ${url})`);
+    const doc = (await res.json());
+    return { name: doc.name ?? name, description: doc.description ?? "", picture: doc.picture ?? null, nip05: doc.nip05 ?? null };
+}
+/** The profile fields the name decides. */
+export function profileFromName(name, doc) {
+    return {
+        name,
+        display_name: doc.name,
+        ...(doc.description ? { about: doc.description } : {}),
+        ...(doc.picture ? { picture: doc.picture } : {}),
+        ...(doc.nip05 ? { nip05: doc.nip05 } : {}),
+        bot: true,
+    };
+}
+/** Whether a community's copy already says everything the name says. */
+export function matchesName(current, wanted) {
+    if (!current)
+        return false;
+    return Object.keys(wanted).every((field) => current[field] === wanted[field]);
+}
+/**
+ * Bring this agent's profile in every community in line with its name.
+ *
+ * @remarks
+ * Only communities whose copy differs are written, so running this on every start and on a
+ * timer costs one read per community when nothing has changed. Fields the name does not
+ * decide are left as they are. Throws only when the name's document cannot be read; a
+ * community that refuses or is unreachable is reported, not fatal, because membership is per
+ * community and being in one and not another is the ordinary case.
+ */
+export async function syncProfileFromName(options) {
+    const doc = await fetchNameProfile(options.name, options.fetch);
+    const wanted = profileFromName(options.name, doc);
+    const read = options.read ?? profile.read;
+    const write = options.write ?? profile.write;
+    const outcomes = [];
+    for (const relay of options.relays) {
+        try {
+            const current = await read(relay, options.key);
+            if (matchesName(current, wanted)) {
+                outcomes.push({ relay, outcome: "unchanged" });
+                continue;
+            }
+            await write(relay, options.key, { ...(current ?? {}), ...wanted });
+            outcomes.push({ relay, outcome: "updated" });
+        }
+        catch (error) {
+            const why = error.message;
+            outcomes.push({ relay, outcome: why.includes("not a relay member") ? "not-member" : "failed", detail: why });
+        }
+    }
+    return outcomes;
+}

package/dist/cli.js

@@ -5,6 +5,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { buzzBridge } from "./bridge.js";
 import { asHexPubkey, loadKey, loadOrCreateKey, npubEncode } from "./keys.js";
 import * as profile from "./profile.js";
+import { nameFromDid, syncProfileFromName } from "./agentid.js";
 /**
  * Setup and operation for an agent that lives in a workspace.
  *
@@ -44,8 +45,10 @@ function flag(name) {
     const at = process.argv.indexOf(`--${name}`);
     return at === -1 ? undefined : process.argv[at + 1];
 }
-/** The `.agent` identity this directory's agent was connected to, if any. */
-function identityDidFromFile() {
+/** The `.agent` identity this agent was connected to, if any: `ARP_AGENT_DID`, else the directory's identity file. */
+function identityDid() {
+    if (process.env.ARP_AGENT_DID?.startsWith("did:web:"))
+        return process.env.ARP_AGENT_DID;
     const file = process.env.ARP_IDENTITY_FILE ?? join(process.cwd(), ".eve", "arp-identity.json");
     if (!existsSync(file))
         return null;
@@ -57,18 +60,6 @@ function identityDidFromFile() {
         return null;
     }
 }
-/** The name's public profile document, served from the name's own address. */
-async function fetchAgentIdProfile(sld) {
-    const suffix = process.env.AGENTID_MIRROR_SUFFIX ?? ".agent.arp.run";
-    const url = `https://${sld}${suffix.startsWith(".") ? suffix : `.${suffix}`}/.well-known/agent-profile.json`;
-    const res = await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
-    if (!res.ok) {
-        console.error(`\n  ${sld}.agent has no profile document yet (${res.status} from ${url}).\n`);
-        process.exit(1);
-    }
-    const doc = (await res.json());
-    return { name: doc.name ?? sld, description: doc.description ?? "", picture: doc.picture ?? null, nip05: doc.nip05 ?? null };
-}
 /**
  * Say who this agent is, in every community it belongs to.
  *
@@ -94,34 +85,36 @@ async function setProfile() {
     // the NIP-05 handle that nostr clients verify against the name itself. The
     // Buzz key never leaves this host; ARP Cloud only publishes the document.
     if (process.argv.includes("--from-agentid")) {
-        const did = flag("from-agentid") && !flag("from-agentid").startsWith("--") ? flag("from-agentid") : identityDidFromFile();
+        const did = flag("from-agentid") && !flag("from-agentid").startsWith("--") ? flag("from-agentid") : identityDid();
         if (!did) {
             console.error("\n  Which name? kybernesis-buzz profile --from-agentid <name>.agent\n  (or run it from the agent's directory, where .eve/arp-identity.json says who it is)\n");
             process.exit(1);
         }
-        const sld = did.replace(/^did:web:/, "").replace(/\.agent$/, "").toLowerCase();
-        const doc = await fetchAgentIdProfile(sld);
-        const wanted = {
-            name: sld,
-            display_name: doc.name,
-            ...(doc.description ? { about: doc.description } : {}),
-            ...(doc.picture ? { picture: doc.picture } : {}),
-            ...(doc.nip05 ? { nip05: doc.nip05 } : {}),
-            bot: true,
-        };
-        let published = 0;
-        for (const url of urls) {
-            try {
-                await profile.write(url, key, wanted);
-                console.log(`  ✓ ${url}`);
-                published += 1;
-            }
-            catch (error) {
-                const why = error.message;
-                console.log(why.includes("not a relay member") ? `  · ${url} — not a member yet, so nothing to be known as there` : `  ✕ ${url} — ${why}`);
-            }
+        const name = nameFromDid(did);
+        if (!name) {
+            console.error(`\n  ${did} is not a .agent name.\n`);
+            process.exit(1);
         }
-        console.log(published > 0 ? `\n  ${doc.name} (${sld}.agent) is ${key.npub.slice(0, 20)}… — profile taken from the name.\n` : "\n  Nothing published — invite this key to a community first.\n");
+        let outcomes;
+        try {
+            outcomes = await syncProfileFromName({ name, relays: urls, key });
+        }
+        catch (error) {
+            console.error(`\n  ${error.message}\n`);
+            process.exit(1);
+        }
+        for (const { relay, outcome, detail } of outcomes) {
+            if (outcome === "updated")
+                console.log(`  ✓ ${relay}`);
+            else if (outcome === "unchanged")
+                console.log(`  ✓ ${relay} — already matches the name`);
+            else if (outcome === "not-member")
+                console.log(`  · ${relay} — not a member yet, so nothing to be known as there`);
+            else
+                console.log(`  ✕ ${relay} — ${detail}`);
+        }
+        const reached = outcomes.filter((o) => o.outcome === "updated" || o.outcome === "unchanged").length;
+        console.log(reached > 0 ? `\n  ${name}.agent is ${key.npub.slice(0, 20)}… — profile taken from the name.\n` : "\n  Nothing published — invite this key to a community first.\n");
         return;
     }
     const name = flag("name");
@@ -206,8 +199,34 @@ function run() {
             ? { agentSilenceTimeoutMs: Number(process.env.BUZZ_AGENT_SILENCE_TIMEOUT_MS) }
             : {}),
     });
+    // How the agent presents itself follows its `.agent` name: checked on start and then every
+    // BUZZ_PROFILE_SYNC_MS (default six hours, 0 turns it off), and written only where a
+    // community's copy differs. A new picture or a moved address needs no command on this host.
+    const did = identityDid();
+    const name = did ? nameFromDid(did) : null;
+    const every = Number(process.env.BUZZ_PROFILE_SYNC_MS ?? 6 * 60 * 60 * 1000);
+    const timers = [];
+    if (name && every > 0) {
+        const log = (message) => console.log(new Date().toISOString().slice(11, 19), message);
+        const sync = () => syncProfileFromName({ name, relays: relayList(), key: loadKey(KEY_FILE) })
+            .then((outcomes) => {
+            for (const { relay, outcome, detail } of outcomes) {
+                if (outcome === "updated")
+                    log(`profile: ${relay} updated from ${name}.agent`);
+                if (outcome === "failed")
+                    log(`profile: ${relay} not updated — ${detail}`);
+            }
+        })
+            .catch((error) => log(`profile: ${error.message}`));
+        // A moment after start, so the bridge's own connections come first.
+        timers.push(setTimeout(sync, 5_000), setInterval(sync, every));
+        for (const timer of timers)
+            timer.unref();
+    }
     for (const signal of ["SIGINT", "SIGTERM"]) {
         process.on(signal, () => {
+            for (const timer of timers)
+                clearTimeout(timer);
             bridge.stop();
             setTimeout(() => process.exit(0), 400);
         });
@@ -365,6 +384,8 @@ else {
     BUZZ_SESSIONS_FILE             channel-to-session continuity store
     BUZZ_AGENT_SILENCE_TIMEOUT_MS   maximum silence before a turn is acknowledged (default 300000ms)
     BUZZ_AGENT_WORK_TIMEOUT_MS      ceiling on a turn once acknowledged (default 3600000ms)
+    BUZZ_PROFILE_SYNC_MS           how often the profile is re-checked against the .agent name
+                                   (default 21600000ms, six hours; 0 turns it off)
     KYBERNESIS_ISSUER              the control plane
     KYBERNESIS_AGENT_CREDENTIAL    this agent's credential
 `);

package/dist/turn.d.ts

@@ -82,8 +82,17 @@ export declare function silentTurnReply(failures: readonly TurnFailure[]): strin
 export declare function describeSilentTurn(failures: readonly TurnFailure[]): string;
 /** Convert one inbound Buzz message into an eve-compatible turn. */
 export declare function composeMessage(text: string, attachments: MediaRef[], fetchAttachment: (ref: MediaRef) => Promise<FetchedMedia>, log?: (message: string) => void): Promise<TurnMessage>;
+/**
+ * How long reading the backlog of a conversation on record may take before the
+ * conversation is treated as gone. An idle session's unread events arrive in
+ * well under a second; a session whose durable run died under a runtime
+ * upgrade never finishes. On 2026-10-05 a Buzz channel's stored run had failed
+ * replay after the eve 0.68 cutover, and every message in that channel sat at
+ * "typing" with nothing reaching the agent, for as long as anyone waited.
+ */
+export declare const DEFAULT_UNREAD_DRAIN_TIMEOUT_MS = 20000;
 /** Continue a channel's existing conversation, replacing it only when it is explicitly stale. */
-export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void, agentSilenceTimeoutMs?: number, agentWorkTimeoutMs?: number): Promise<TurnOutcome>;
+export declare function answerTurn(client: Client, sessions: SessionStore, channel: string, message: TurnMessage, community: string, log?: (message: string) => void, agentSilenceTimeoutMs?: number, agentWorkTimeoutMs?: number, unreadDrainTimeoutMs?: number): Promise<TurnOutcome>;
 /** What the room is told when eve refuses the turn itself. */
 /**
  * The two answers from eve that mean the stored session cannot carry another

package/dist/turn.js

@@ -313,12 +313,23 @@ async function sendExisting(responsePromise, streamIndex, timeouts, continueStre
         watchdog.dispose();
     }
 }
+/**
+ * How long reading the backlog of a conversation on record may take before the
+ * conversation is treated as gone. An idle session's unread events arrive in
+ * well under a second; a session whose durable run died under a runtime
+ * upgrade never finishes. On 2026-10-05 a Buzz channel's stored run had failed
+ * replay after the eve 0.68 cutover, and every message in that channel sat at
+ * "typing" with nothing reaching the agent, for as long as anyone waited.
+ */
+export const DEFAULT_UNREAD_DRAIN_TIMEOUT_MS = 20_000;
 /** Continue a channel's existing conversation, replacing it only when it is explicitly stale. */
-export async function answerTurn(client, sessions, channel, message, community, log = () => { }, agentSilenceTimeoutMs = DEFAULT_AGENT_SILENCE_TIMEOUT_MS, agentWorkTimeoutMs = DEFAULT_AGENT_WORK_TIMEOUT_MS) {
+export async function answerTurn(client, sessions, channel, message, community, log = () => { }, agentSilenceTimeoutMs = DEFAULT_AGENT_SILENCE_TIMEOUT_MS, agentWorkTimeoutMs = DEFAULT_AGENT_WORK_TIMEOUT_MS, unreadDrainTimeoutMs = DEFAULT_UNREAD_DRAIN_TIMEOUT_MS) {
     const intervalMs = {
         silenceMs: validateAgentSilenceTimeoutMs(agentSilenceTimeoutMs),
         workMs: validateAgentSilenceTimeoutMs(agentWorkTimeoutMs),
     };
+    // Never longer than the silence bound, so a caller that tightened silence tightened this too.
+    const drainMs = Math.min(validateAgentSilenceTimeoutMs(unreadDrainTimeoutMs), intervalMs.silenceMs);
     const existing = sessions.get(community, channel);
     if (existing) {
         try {
@@ -330,8 +341,24 @@ export async function answerTurn(client, sessions, channel, message, community,
              * `send()` opens its response stream at the position the handle already
              * holds and stops at the FIRST turn boundary it meets. Draining first
              * repairs any cursor that was left behind by a prior disconnected reader.
+             * Bounded on its own, tightly: this read is of a backlog, not of work.
+             * A backlog that does not finish is not proof of anything by itself —
+             * the run behind it may be dead (eve 0.68 cutover, 2026-10-05: a stored
+             * run that failed replay streamed nothing, and the channel sat at
+             * "typing" for good) or the transport may be having a moment. So the
+             * stall is logged and the send goes ahead: the agent's answer to the
+             * send decides. 404 / "no longer active" replaces the session below; a
+             * real reply continues it; a transport failure preserves it.
              */
-            const unread = await drainUnread((signal) => session.stream({ follow: false, startIndex: existing.streamIndex, signal }), intervalMs);
+            let unread = 0;
+            try {
+                unread = await drainUnread((signal) => session.stream({ follow: false, startIndex: existing.streamIndex, signal }), { silenceMs: drainMs, workMs: drainMs });
+            }
+            catch (error) {
+                if (!(error instanceof AgentSilenceTimeoutError))
+                    throw error;
+                log(`backlog of ${channel.slice(0, 8)} (${existing.id}) did not finish reading in ${drainMs}ms; asking the agent directly`);
+            }
             if (unread > 0) {
                 log(`caught up on ${unread} unread event(s) in ${channel.slice(0, 8)} before answering`);
             }

package/package.json

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