@kybernesis/buzz 0.10.2 → 0.12.0

package/README.md

@@ -55,13 +55,20 @@ 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.
+An agent shows the name and picture its owner set in the app or KYBER Studio, and where the
+owner has not chosen, what its `.agent` name says (display name, description, picture and
+NIP-05 handle). The bridge reads the owner's choice from the control plane
+(`GET /api/agent/profile`, with the agent's credential) and the name's public profile document
+(`https://<name>.agentid.dev/.well-known/agent-profile.json`) when it starts and every fifteen
+minutes, and writes the profile only in communities whose copy differs. The control plane holds
+the picture as a small image, so it is uploaded to a community's own media store once per change
+and that address is used everywhere. A new picture or name reaches every community without a
+command on the host. The `.agent` name comes from `ARP_AGENT_DID`, or from
+`.eve/arp-identity.json` in the agent's directory.
+
+`kybernesis-buzz profile --sync` does the same once, on demand: the owner's Sync profile button
+runs it through `@kybernesis/manage` (`buzz.profile`). `kybernesis-buzz profile --from-agentid`
+still takes the profile from the name alone.
 
 ## Configuration
 
@@ -73,7 +80,7 @@ directory. `kybernesis-buzz profile --from-agentid` does the same once, on deman
 | `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) |
+| `BUZZ_PROFILE_SYNC_MS` | How often the profile is re-checked against the name and picture its owner set and its `.agent` name (default `900000`, fifteen minutes; `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/cli.js

@@ -6,6 +6,7 @@ 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";
+import { resolveFace, syncProfile } from "./face.js";
 /**
  * Setup and operation for an agent that lives in a workspace.
  *
@@ -60,6 +61,27 @@ function identityDid() {
         return null;
     }
 }
+/** One line per community, in the shape the Channels page reads back. */
+function printOutcomes(outcomes) {
+    for (const { relay, outcome, detail } of outcomes) {
+        if (outcome === "updated")
+            console.log(`  ✓ ${relay}${detail ? ` — ${detail}` : ""}`);
+        else if (outcome === "unchanged")
+            console.log(`  ✓ ${relay} — already up to date`);
+        else if (outcome === "not-member")
+            console.log(`  · ${relay} — not a member yet, so nothing to be known as there`);
+        else
+            console.log(`  ✕ ${relay} — ${detail}`);
+    }
+}
+/** Where the face comes from: the control plane when this host has a credential, and the `.agent` name. */
+function faceSources(name) {
+    return {
+        name,
+        issuer: process.env.KYBERNESIS_ISSUER ?? "https://agent.kybernesis.ai",
+        ...(process.env.KYBERNESIS_AGENT_CREDENTIAL ? { credential: process.env.KYBERNESIS_AGENT_CREDENTIAL } : {}),
+    };
+}
 /**
  * Say who this agent is, in every community it belongs to.
  *
@@ -79,6 +101,25 @@ async function setProfile() {
         console.log();
         return;
     }
+    // The face its owner chose (the control plane), over its `.agent` name: what the bridge
+    // keeps in step on its own, run now. The Sync profile button in the app runs this.
+    if (process.argv.includes("--sync")) {
+        const did = identityDid();
+        const name = did ? nameFromDid(did) : null;
+        let outcomes;
+        try {
+            const face = await resolveFace(faceSources(name));
+            outcomes = await syncProfile({ face, relays: urls, key });
+        }
+        catch (error) {
+            console.error(`\n  ${error.message}\n`);
+            process.exit(1);
+        }
+        printOutcomes(outcomes);
+        const reached = outcomes.filter((o) => o.outcome === "updated" || o.outcome === "unchanged").length;
+        console.log(reached > 0 ? `\n  ${key.npub.slice(0, 20)}… now looks the way its owner set it.\n` : "\n  Nothing published — invite this key to a community first.\n");
+        return;
+    }
     // AgentID: the agent's `.agent` name is the source of truth for how it
     // presents itself. `--from-agentid` reads the name's public profile document
     // and publishes it as this key's kind-0 — name, description, picture and
@@ -103,16 +144,7 @@ async function setProfile() {
             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}`);
-        }
+        printOutcomes(outcomes);
         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;
@@ -120,6 +152,7 @@ async function setProfile() {
     const name = flag("name");
     if (!name) {
         console.error("usage: kybernesis-buzz profile --name <name> [--about …] [--picture <file|url>]");
+        console.error("   or: kybernesis-buzz profile --sync");
         console.error("   or: kybernesis-buzz profile --from-agentid [<name>.agent]");
         console.error("   or: kybernesis-buzz profile --copy-from <wss://…>");
         process.exit(1);
@@ -199,20 +232,23 @@ 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.
+    // How the agent presents itself follows the face its owner chose (name and picture, from the
+    // control plane), with its `.agent` name filling the gaps: checked on start and then every
+    // BUZZ_PROFILE_SYNC_MS (default fifteen minutes, 0 turns it off), and written only where a
+    // community's copy differs. A new picture or name 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 every = Number(process.env.BUZZ_PROFILE_SYNC_MS ?? 15 * 60 * 1000);
     const timers = [];
-    if (name && every > 0) {
+    const sources = faceSources(name);
+    if ((name || sources.credential) && every > 0) {
         const log = (message) => console.log(new Date().toISOString().slice(11, 19), message);
-        const sync = () => syncProfileFromName({ name, relays: relayList(), key: loadKey(KEY_FILE) })
+        const sync = () => resolveFace(sources)
+            .then((face) => syncProfile({ face, 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`);
+                    log(`profile: ${relay} updated${detail ? ` (${detail})` : ""}`);
                 if (outcome === "failed")
                     log(`profile: ${relay} not updated — ${detail}`);
             }
@@ -384,8 +420,9 @@ 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)
+    BUZZ_PROFILE_SYNC_MS           how often the profile is re-checked against the name and
+                                   picture its owner set (default 900000ms, fifteen
+                                   minutes; 0 turns it off)
     KYBERNESIS_ISSUER              the control plane
     KYBERNESIS_AGENT_CREDENTIAL    this agent's credential
 `);

package/dist/extension/_manifest.json

@@ -1,10 +1,10 @@
 {
   "kind": "eve-extension",
   "formatVersion": 2,
-  "builtWithEve": "0.68.0",
+  "builtWithEve": "0.81.1",
   "requires": {
     "extension": 1,
-    "tool": 59,
+    "tool": 93,
     "instructions": 2
   }
 }

package/dist/face.d.ts

@@ -0,0 +1,78 @@
+import type { AgentKey } from "./keys.js";
+import * as profile from "./profile.js";
+import type { Profile } from "./profile.js";
+import { type SyncOutcome } from "./agentid.js";
+/**
+ * The agent's face in every community: the name and picture its owner chose.
+ *
+ * @remarks
+ * The owner sets them in the app or KYBER Studio, and the control plane holds them. Before
+ * this, a community only ever saw what was published when the agent joined (its bare
+ * registered name) or what its `.agent` name said, so a new picture or name chosen by the
+ * owner never reached Buzz, and a name sync put the old one back. Now the owner's choice wins
+ * field by field and the `.agent` name fills the gaps, the same order every client draws.
+ *
+ * The control plane keeps the picture as a small data URL; a profile can only carry an
+ * address. So the picture is uploaded to a community's own media store, addressed by the hash
+ * of its bytes, and a community whose copy already points at that hash is left alone.
+ */
+export type Face = {
+    /** The handle: lowercase, no spaces. */
+    handle: string;
+    /** Null when nobody has chosen one: the community keeps what it has. */
+    displayName: string | null;
+    /** A data URL, an https address, or null to leave the picture as it is. */
+    picture: string | null;
+    about: string | null;
+    nip05: string | null;
+};
+type ControlPlaneFace = {
+    agent: string;
+    displayName: string | null;
+    picture: string | null;
+    about: string | null;
+    nip05: string | null;
+};
+/** GET /api/agent/profile: the calling agent's own face, as its owner set it. */
+export declare function fetchControlPlaneFace(options: {
+    issuer: string;
+    credential: string;
+    fetch?: typeof fetch;
+}): Promise<ControlPlaneFace>;
+/**
+ * What the agent should look like: the owner's choices over its `.agent` name.
+ *
+ * @remarks
+ * Either source may be missing (an older control plane, an agent with no name); only both
+ * missing is an error. The `.agent` name is read even when the control plane answers, because
+ * the control plane only folds it in once the name lists the agent back as verified, and an
+ * agent that has always taken its picture from its name should keep doing so.
+ */
+export declare function resolveFace(options: {
+    /** The `.agent` name, when this agent has one. */
+    name: string | null;
+    issuer?: string;
+    credential?: string;
+    fetch?: typeof fetch;
+}): Promise<Face>;
+/** The profile fields the face decides, given where its picture now lives. */
+export declare function profileFromFace(face: Face, pictureUrl: string | null): Profile;
+/**
+ * Bring this agent's profile in every community in line with its face.
+ *
+ * @remarks
+ * Each community is read first; only one whose copy differs is written, so running this on a
+ * timer costs one read per community when nothing has changed. A picture is uploaded at most
+ * once per change, to the first community that takes it, and that address is used everywhere,
+ * the way `kybernesis-buzz profile --picture` always has. Fields the face does not decide are
+ * kept. A community that refuses or cannot be reached is reported, not fatal.
+ */
+export declare function syncProfile(options: {
+    face: Face;
+    relays: readonly string[];
+    key: AgentKey;
+    read?: typeof profile.read;
+    write?: typeof profile.write;
+    upload?: typeof profile.uploadImage;
+}): Promise<SyncOutcome[]>;
+export {};

package/dist/face.js

@@ -0,0 +1,148 @@
+import * as profile from "./profile.js";
+import { fetchNameProfile } from "./agentid.js";
+/** GET /api/agent/profile: the calling agent's own face, as its owner set it. */
+export async function fetchControlPlaneFace(options) {
+    const url = `${options.issuer.replace(/\/+$/, "")}/api/agent/profile`;
+    const res = await (options.fetch ?? fetch)(url, {
+        headers: { authorization: `Bearer ${options.credential}`, accept: "application/json" },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok)
+        throw new Error(`the control plane did not give this agent's profile (${res.status} from ${url})`);
+    return (await res.json());
+}
+function handleOf(name) {
+    return name.trim().toLowerCase().replace(/\s+/g, "-");
+}
+/**
+ * What the agent should look like: the owner's choices over its `.agent` name.
+ *
+ * @remarks
+ * Either source may be missing (an older control plane, an agent with no name); only both
+ * missing is an error. The `.agent` name is read even when the control plane answers, because
+ * the control plane only folds it in once the name lists the agent back as verified, and an
+ * agent that has always taken its picture from its name should keep doing so.
+ */
+export async function resolveFace(options) {
+    let owner = null;
+    let ownerError = null;
+    if (options.issuer && options.credential) {
+        try {
+            owner = await fetchControlPlaneFace({ issuer: options.issuer, credential: options.credential, fetch: options.fetch });
+        }
+        catch (error) {
+            ownerError = error;
+        }
+    }
+    let named = null;
+    let nameError = null;
+    if (options.name) {
+        try {
+            named = await fetchNameProfile(options.name, options.fetch);
+        }
+        catch (error) {
+            nameError = error;
+        }
+    }
+    if (!owner && !named) {
+        throw ownerError ?? nameError ?? new Error("Nothing says who this agent is: no control plane credential and no .agent name.");
+    }
+    return {
+        handle: options.name ?? handleOf(owner.agent),
+        displayName: owner?.displayName ?? named?.name ?? null,
+        picture: owner?.picture ?? named?.picture ?? null,
+        about: owner?.about ?? (named?.description || null),
+        nip05: owner?.nip05 ?? named?.nip05 ?? null,
+    };
+}
+/** A picture held as a data URL, decoded and stripped the way an upload will be. */
+async function pictureBytes(dataUrl) {
+    const match = /^data:(image\/[a-z0-9.+-]+);base64,(.+)$/i.exec(dataUrl);
+    if (!match)
+        return null;
+    const mediaType = match[1].toLowerCase();
+    const bytes = new Uint8Array(Buffer.from(match[2], "base64"));
+    const { createHash } = await import("node:crypto");
+    const sha256 = createHash("sha256").update(profile.stripMetadata(bytes, mediaType)).digest("hex");
+    return { bytes, mediaType, sha256 };
+}
+/** The profile fields the face decides, given where its picture now lives. */
+export function profileFromFace(face, pictureUrl) {
+    return {
+        name: face.handle,
+        ...(face.displayName ? { display_name: face.displayName } : {}),
+        ...(face.about ? { about: face.about } : {}),
+        ...(pictureUrl ? { picture: pictureUrl } : {}),
+        ...(face.nip05 ? { nip05: face.nip05 } : {}),
+        bot: true,
+    };
+}
+/**
+ * Bring this agent's profile in every community in line with its face.
+ *
+ * @remarks
+ * Each community is read first; only one whose copy differs is written, so running this on a
+ * timer costs one read per community when nothing has changed. A picture is uploaded at most
+ * once per change, to the first community that takes it, and that address is used everywhere,
+ * the way `kybernesis-buzz profile --picture` always has. Fields the face does not decide are
+ * kept. A community that refuses or cannot be reached is reported, not fatal.
+ */
+export async function syncProfile(options) {
+    const read = options.read ?? profile.read;
+    const write = options.write ?? profile.write;
+    const upload = options.upload ?? profile.uploadImage;
+    const { face, key } = options;
+    const current = new Map();
+    const outcomes = new Map();
+    for (const relay of options.relays) {
+        try {
+            current.set(relay, await read(relay, key));
+        }
+        catch (error) {
+            const why = error.message;
+            outcomes.set(relay, { relay, outcome: why.includes("not a relay member") ? "not-member" : "failed", detail: why });
+        }
+    }
+    // Where the picture lives. Null leaves each community's picture as it is.
+    let pictureUrl = null;
+    let pictureProblem = null;
+    if (face.picture && /^https:\/\//.test(face.picture)) {
+        pictureUrl = face.picture;
+    }
+    else if (face.picture) {
+        const picture = await pictureBytes(face.picture);
+        if (!picture) {
+            pictureProblem = "the picture is not an image this can send";
+        }
+        else {
+            pictureUrl = [...current.values()].map((p) => p?.picture).find((url) => url?.includes(picture.sha256)) ?? null;
+            for (const relay of current.keys()) {
+                if (pictureUrl)
+                    break;
+                try {
+                    pictureUrl = await upload(relay, key, picture.bytes, picture.mediaType);
+                }
+                catch (error) {
+                    pictureProblem = error.message;
+                }
+            }
+        }
+    }
+    const wanted = profileFromFace(face, pictureUrl);
+    for (const [relay, existing] of current) {
+        const matches = existing && Object.keys(wanted).every((field) => existing[field] === wanted[field]);
+        if (matches) {
+            outcomes.set(relay, { relay, outcome: "unchanged" });
+            continue;
+        }
+        try {
+            await write(relay, key, { ...(existing ?? {}), ...wanted });
+            outcomes.set(relay, { relay, outcome: "updated", ...(pictureProblem ? { detail: `picture not sent: ${pictureProblem}` } : {}) });
+        }
+        catch (error) {
+            const why = error.message;
+            outcomes.set(relay, { relay, outcome: why.includes("not a relay member") ? "not-member" : "failed", detail: why });
+        }
+    }
+    return options.relays.map((relay) => outcomes.get(relay));
+}

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export { BuzzRelay, type NostrEvent, type PresenceStatus, type RelayOptions, KIN
 export { asHexPubkey, loadKey, loadOrCreateKey, npubEncode, type AgentKey } from "./keys.js";
 export * as profile from "./profile.js";
 export type { Profile } from "./profile.js";
+export { fetchControlPlaneFace, profileFromFace, resolveFace, syncProfile, type Face } from "./face.js";
 export { readSurfaceManifest, surfaceWriter, surfacesDir, type SurfaceManifest } from "./surface.js";

package/dist/index.js

@@ -2,4 +2,5 @@ export { buzzBridge } from "./bridge.js";
 export { BuzzRelay, KIND_MESSAGE, KIND_REACTION, KIND_PRESENCE, KIND_TYPING, KIND_DM_OPEN, } from "./relay.js";
 export { asHexPubkey, loadKey, loadOrCreateKey, npubEncode } from "./keys.js";
 export * as profile from "./profile.js";
+export { fetchControlPlaneFace, profileFromFace, resolveFace, syncProfile } from "./face.js";
 export { readSurfaceManifest, surfaceWriter, surfacesDir } from "./surface.js";

package/dist/turn.js

@@ -196,6 +196,15 @@ async function drainUnread(stream, timeouts) {
     }
 }
 const isTurnBoundary = (type) => type === "session.waiting" || type === "session.completed" || type === "session.failed";
+/**
+ * eve ≥0.69 no longer ends a turn at a question or sign-in from inside a tool:
+ * it emits `turn.waiting` with `on: "input"` and holds the turn open, and the
+ * answer resumes that same turn. For the bridge that is where this send stops,
+ * as `session.waiting` did before, with the questions to relay. eve's own
+ * `result()` stops at the same event. `on: "tasks"` is not a stop: delegated
+ * work is running and the reply is still to come.
+ */
+const isHeldForInput = (event) => event.type === "turn.waiting" && event.data?.on === "input";
 async function collectResponse(response, watchdog, phase, streamIndex, continueStream, log = () => { }) {
     let message = "";
     let status = "completed";
@@ -242,7 +251,7 @@ async function collectResponse(response, watchdog, phase, streamIndex, continueS
         else if (event.type === "input.requested") {
             inputRequests.push(...event.data.requests);
         }
-        else if (event.type === "session.waiting") {
+        else if (event.type === "session.waiting" || isHeldForInput(event)) {
             status = "waiting";
         }
         else if (event.type === "session.failed") {
@@ -251,11 +260,12 @@ async function collectResponse(response, watchdog, phase, streamIndex, continueS
         else if (event.type === "session.completed") {
             status = "completed";
         }
-        if (isTurnBoundary(event.type) && !staleBoundaryFirst) {
+        const ends = isTurnBoundary(event.type) || isHeldForInput(event);
+        if (ends && !staleBoundaryFirst) {
             endedAtOwnBoundary = true;
             return true;
         }
-        if (isTurnBoundary(event.type) && staleBoundaryFirst && sawTurnStart) {
+        if (ends && staleBoundaryFirst && sawTurnStart) {
             endedAtOwnBoundary = true;
             return true;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/buzz",
-  "version": "0.10.2",
+  "version": "0.12.0",
   "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",
@@ -44,17 +44,17 @@
     "test": "node --test \"test/**/*.test.mjs\""
   },
   "dependencies": {
-    "@kybernesis/enterprise": "^0.9.0",
+    "@kybernesis/enterprise": "^0.10.0",
     "nostr-tools": "^2.10.0",
     "zod": "^4"
   },
   "devDependencies": {
     "@types/node": "24.x",
-    "eve": "0.68.0",
+    "eve": "0.81.1",
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "eve": ">=0.68.0 <0.69.0"
+    "eve": ">=0.81.1 <0.82.0"
   },
   "engines": {
     "node": ">=20"
@@ -69,5 +69,8 @@
       "source": "./extension",
       "dist": "./dist/extension"
     }
+  },
+  "publishConfig": {
+    "tag": "eve-0.81"
   }
 }