@staix/agent-hub 0.21.0 → 0.23.0

package/src/hub/bus.ts

@@ -1,4 +1,4 @@
-import { appendNote, DIGEST, frame, HUB, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
+import { remoteEnvelope, appendNote, DIGEST, frame, HUB, isInvocationKind, keepNotes, MAX_HOP, mergePrefaces, newEnvelope, noteLine, parseMarker, quoteNotes, replyAudience, uniqueMemoryLines, type Envelope, type EnvelopeOpts, type PeerId, type PeerState, type Priority } from "./envelope.ts";
 import type { PeerAdapter, DeliveryReceipt } from "./peers.ts";
 import type { DoingKind } from "./peer-doing.ts";
 import type { QueuePressure } from "./queue-backpressure.ts";
@@ -41,6 +41,11 @@ export interface BusOptions {
   /** How long a status envelope may wait for company before it is delivered on its own. */
   batchMs: number;
   queueCap: number;
+  /** Accepted live operational settings; read only at the next matching delivery/note operation. */
+  maxAttempts?: () => number;
+  digestMax?: () => number;
+  pullBudgetBytes?: () => number;
+  notesKept?: () => number;
   /** Optional: rewrite a delivery before it goes out (M6 digest condensation). Must return its input on any failure. */
   condense?: (envs: Envelope[]) => Promise<Envelope[]>;
   journal?: DeliveryJournal;
@@ -118,7 +123,7 @@ function resolveTo(to: PeerId[], originals: Envelope[] | undefined): PeerId[] {
 }
 
 const SEEN_CAP = 2048;
-const MAX_ATTEMPTS = 3;
+export const MAX_ATTEMPTS = 3;
 // ponytail: provenance is capped at 2048 ids/peer, 4096 peers, 100000 ids total and 256 KiB per snapshot.
 // Omitted metadata means unknown age only; use a measured per-envelope store if larger queues need provenance.
 const QUEUE_TIME_CAP = 2048, QUEUE_TIME_PEERS_CAP = 4096, QUEUE_TIME_TOTAL_CAP = 100_000, QUEUE_TIME_SNAPSHOT_BYTES = 256 * 1024;
@@ -127,11 +132,11 @@ const remoteId = (id: string): boolean => id.includes("@");
 const remoteFingerprint = (value: unknown): value is string => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
 // ponytail: one digest carries at most ten originals; larger supervision windows split into bounded deliveries.
 // Revisit this ceiling after measuring native supervision cost, rather than bypassing the delivery limit.
-const DIGEST_MAX = 10;
+export const DIGEST_MAX = 10;
 // #713: a pull-only peer reads between steps, often minutes apart, so one pull drains its queue up to this many bytes of rendered text instead of ten items.
 // Bounded, not unbounded: a queue larger than the budget takes more than one pull, and the reply says how many are still waiting. Push peers keep DIGEST_MAX.
-const PULL_BUDGET_BYTES = 64 * 1024;
-const NOTES_KEPT = 10;
+export const PULL_BUDGET_BYTES = 64 * 1024;
+export const NOTES_KEPT = 10;
 
 /**
  * N-peer fan-out. Never delivers back to `from`, caps hops, dedupes by id. Each peer has one queue,
@@ -177,6 +182,41 @@ export class Bus {
    * and is never corrected once the queue empties (measured: status.json kept `queued 4` on an empty queue).
    */
   onQueues?: () => void;
+  /**
+   * #445 C2: a peer's answer to a delivery, offered BEFORE anything is built from it. The host returns true when the answer belongs to an invocation it
+   * took over: the bus then publishes nothing, stores nothing, emits no event and lets no tap, queue, digest or memory path see it. `answers` is what the
+   * peer was handed (the request is in it, never condensed), so a reply that answers an invocation is found by identity, not by addressing.
+   */
+  onAnswer?: (peer: PeerId, text: string, answers: readonly Envelope[]) => boolean;
+  /** Host ledger authority; absent or unknown never permits invocation replay. */
+  canRetryInvocation?: (id: string) => boolean;
+  onInvocationUncertain?: (id: string) => void;
+  /** Validated transport receipts, ids only; application admission is not a capability result. */
+  onInvocationReceipt?: (id: string, state: "completed" | "failed_safe" | "needs_review") => void;
+  hasInvocationTurn(peer: PeerId): boolean { return this.invocationTurnOpen(peer); }
+  private readonly invocationDeliveries = new Map<string, string>();
+
+  releaseInvocation(id: string): void { this.invocationDeliveries.delete(id); }
+  invocationUncertain(id: string): boolean {
+    const delivery = this.invocationDeliveries.get(id), row = delivery && this.journal?.get(delivery);
+    return !!row && (row.state === "needs_review" || ["dispatching", "accepted"].includes(row.state) && !this.activeDeliveries.has(row.id));
+  }
+
+  /** Hold the existing delivery rather than cancelling native work or replaying an uncertain effect. */
+  holdInvocation(id: string, reason: string, target?: PeerId): void {
+    const delivery = this.invocationDeliveries.get(id), row = delivery && this.journal?.get(delivery);
+    if (!row || !this.journal) {
+      this.storageError = "uncertain invocation delivery evidence unavailable; inspect the invocation ledger before recovery";
+      if (target) this.recoveryHeldPeers.add(target);
+      this.onQueues?.();
+      return;
+    }
+    this.journal.transition(row.id, "needs_review", reason);
+    this.activeDeliveries.delete(row.id);
+    this.recoveryHeldPeers.add(row.peer);
+    this.onQueues?.();
+  }
+
   /** Actual transport admission, using originals even when a digest was condensed. Never an enqueue metric. */
   onDelivered?: (peer: PeerId, originals: Envelope[]) => void;
   /** Before deliver's synchronous busy transition, with originals rather than a condensed digest. */
@@ -208,6 +248,7 @@ export class Bus {
       if (state.revision > 0 && bus && bus.schemaVersion === 1) this.loadSnapshot(bus);
       for (const id of state.manualPaused) { this.manualPaused.add(id); this.paused.add(id); }
       for (const row of this.journal.list()) {
+        for (const env of row.originals) if (env.kind === "invocation") this.invocationDeliveries.set(env.id, row.id);
         if (row.state === "needs_review" || row.state === "dispatching" || row.state === "accepted") this.recoveryHeldPeers.add(row.peer);
       }
     }
@@ -243,6 +284,17 @@ export class Bus {
     this.opts.doing?.(peer.id, "reset"); // a new adapter never shows what the one it replaces was doing
     peer.onMessage = (text, opts) => {
       if (!this.isRostered(peer.id)) return `off roster: ${peer.id}`;
+      // #445 C2: an answer to an invocation is found by what the peer was handed, never by how the answer is addressed, so a headless agent whose final answer is
+      // normally shared with every peer cannot leak it. It is the invocation's answer when it names the request itself (an adapter may report its delivery complete before
+      // it answers, so the receipt cannot decide), or when it names nothing while that invocation's own delivery is still the peer's open turn. Once that turn has ended,
+      // `lastDelivery` still holds the request until the next delivery replaces it, and a later message from the peer is an ordinary message: it must be published.
+      const handed = this.lastDelivery.get(peer.id)?.out ?? [];
+      const named = opts?.inReplyTo?.id !== undefined && handed.some((e) => e.id === opts.inReplyTo!.id); // an invocation is delivered alone, so the only envelope in `handed` to name is its request (or the preface that rode with it)
+      if (this.onAnswer && handed.some((e) => e.kind === "invocation") && (named || opts?.inReplyTo?.id === undefined && this.invocationTurnOpen(peer.id))) {
+        let taken = false;
+        try { taken = this.onAnswer(peer.id, text, handed) === true; } catch { taken = true; } // a throwing host never turns a callee's answer into a broadcast
+        if (taken) return;
+      }
       const { priority, body } = parseMarker(text);
       if (!body) return;
       // What the peer was handed differs from what it stands for once a delivery was condensed; both the audience
@@ -311,6 +363,9 @@ export class Bus {
             this.deliveryReceipt(peer.id, { id: deliveryId, state: "needs_review", reason: "adapter reported delivery failure without safe-failure evidence" });
           }
         }
+      } else if (envs.some(env => env.kind === "invocation")) {
+        this.recoveryHeldPeers.add(peer.id);
+        for (const env of envs) if (env.kind === "invocation") this.onInvocationUncertain?.(env.id);
       } else this.failed(peer.id, same ? last.originals : envs, undefined, failure?.quota === true);
     };
     peer.onState = () => {
@@ -490,6 +545,7 @@ export class Bus {
       }
     }
     this.loadSnapshot(snapshot);
+    if (this.journal) for (const row of this.journal.list()) for (const env of row.originals) if (env.kind === "invocation") this.invocationDeliveries.set(env.id, row.id);
     this.persist();
   }
 
@@ -557,6 +613,7 @@ export class Bus {
     if (this.closed || this.recoveryHeld || this.storageError || peer === "user" || peer === HUB) return refuse();
     const row = this.queueShow(id);
     if (!row || row.peer !== peer || row.state !== "needs_review" || !this.journal || this.journal.retryEvidence(peer, row.originals) !== "unused") return refuse();
+    if (row.originals.some(env => env.kind === "invocation")) return refuse();
     this.resolveDelivery(id, row.revision, "retry", "recipient requested one uncertain redelivery", `peer:${peer}`);
   }
 
@@ -671,6 +728,7 @@ export class Bus {
       const last = this.lastDelivery.get(peer);
       if (before && last && last.out.length === before.out.length && last.out.every((env, index) => env.id === before.out[index]!.id)) this.lastDelivery.delete(peer);
       this.refreshRecoveryHold(peer);
+      for (const env of before?.originals ?? []) if (isInvocationKind(env)) this.onInvocationReceipt?.(env.id, "failed_safe");
       this.onQueues?.();
       void this.drain(peer);
       return;
@@ -689,7 +747,11 @@ export class Bus {
     if (state === "completed") { this.failureStreak.delete(peer); this.lastFailure.delete(peer); }
     if (state === "completed" || state === "failed" || state === "needs_review") this.activeDeliveries.delete(id);
     if (state === "completed" || state === "failed") { this.refreshRecoveryHold(peer); void this.drain(peer); }
-    if (state === "needs_review") this.recoveryHeldPeers.add(peer);
+    if (receipt.state === "completed" || receipt.state === "needs_review") for (const env of before?.originals ?? []) if (isInvocationKind(env)) this.onInvocationReceipt?.(env.id, receipt.state);
+    if (state === "needs_review") {
+      this.recoveryHeldPeers.add(peer);
+      for (const env of before?.originals ?? []) if (env.kind === "invocation") this.onInvocationUncertain?.(env.id);
+    }
     this.onQueues?.();
   }
 
@@ -797,7 +859,7 @@ export class Bus {
   note(id: PeerId, line: string): void {
     if (remoteId(id)) return;
     const existing = this.prefaces.get(id);
-    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
+    this.prefaces.set(id, existing ? { ...existing, body: keepNotes(uniqueMemoryLines(appendNote(existing.body, line)), this.opts.notesKept?.() ?? NOTES_KEPT) } : newEnvelope(HUB, uniqueMemoryLines(line), { to: [id], kind: "presence" }));
     this.persist();
   }
 
@@ -805,7 +867,7 @@ export class Bus {
   private restorePreface(id: PeerId, env: Envelope): void {
     if (remoteId(id)) return;
     const now = this.prefaces.get(id);
-    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), NOTES_KEPT) });
+    this.prefaces.set(id, !now ? { ...env, body: uniqueMemoryLines(env.body) } : now.id === env.id ? { ...now, body: uniqueMemoryLines(now.body) } : { ...env, body: keepNotes(mergePrefaces(env.body, now.body), this.opts.notesKept?.() ?? NOTES_KEPT) });
   }
 
   /**
@@ -1016,7 +1078,7 @@ export class Bus {
       try { for (const id of targets) {
         const peer = this.peers.get(id);
         if (!peer) { this.enqueue(id, env); continue; }
-        if (!this.journal && !this.held(id) && env.priority === "important" && !remoteId(id) && peer.steer && this.stateOf(id) === "busy") {
+        if (!this.journal && !this.held(id) && env.priority === "important" && !remoteId(id) && peer.steer && this.stateOf(id) === "busy" && !this.invocationTurnOpen(id)) {
           // Not queued while the steer is in flight, or an idle transition would deliver it a second time.
           this.steering++;
           const deliveryId = crypto.randomUUID();
@@ -1036,7 +1098,7 @@ export class Bus {
         if (!this.flushingHub) this.onQueues?.();
         for (const id of targets) {
           const peer = this.peers.get(id);
-          if (!this.held(id) && env.priority === "important" && !remoteId(id) && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env);
+          if (!this.held(id) && env.priority === "important" && !remoteId(id) && peer?.steer && this.stateOf(id) === "busy") void this.steerQueued(id, env); // steerQueued itself refuses to join an invocation's turn
           else void this.drain(id);
         }
       }
@@ -1080,6 +1142,20 @@ export class Bus {
     return this.seen.get(id) ?? this.deferredHub.get(id);
   }
 
+  /**
+   * #445 C2: whether the peer's current turn is one that holds an invocation request. With a journal that is a delivery of the peer's own that has not reached a
+   * terminal receipt and whose payload holds the request (the receipt paths delete it from `activeDeliveries`); without one it is the peer being busy, which is the
+   * best the bus can know (the daemon always has a journal). A steer is never sent into such a turn (the two steer sites and `steerQueued` ask this first): an adapter answers the highest-hop envelope of
+   * everything its turn holds, and a steered one would become what the answer names instead of the request.
+   */
+  private invocationTurnOpen(peer: PeerId): boolean {
+    if (!this.journal) return this.stateOf(peer) === "busy" && (this.lastDelivery.get(peer)?.out ?? []).some((e) => e.kind === "invocation");
+    for (const [deliveryId, owner] of this.activeDeliveries) {
+      if (owner === peer && this.journal.get(deliveryId)?.out.some((e) => e.kind === "invocation")) return true;
+    }
+    return false;
+  }
+
   /** The envelopes most recently handed to a peer, used to distinguish a received request from an unread queue. */
   lastDeliveredTo(peer: PeerId): Envelope[] {
     return this.lastDelivery.get(peer)?.out ?? [];
@@ -1305,6 +1381,8 @@ export class Bus {
     const peer = this.peers.get(id);
     const queue = this.queues.get(id);
     if (!this.journal || !peer?.steer || !queue || this.storageError) return;
+    // #445 C2: an invocation's turn answers the request alone. Joining it with a steer would change what its answer names, so the envelope waits in the queue for the next delivery.
+    if (this.invocationTurnOpen(id)) { void this.drain(id); return; }
     const index = queue.findIndex((item) => item.id === env.id);
     if (index < 0) return;
     this.steering++;
@@ -1326,6 +1404,9 @@ export class Bus {
   }
 
   /** Holds on a peer's queue, for a drain and a pull alike: off roster, recovery, an uncertain delivery, a pause (console, budget, conductor). */
+  /** #445 C2: whether a delivery to this peer would wait on a hold (roster, recovery, pause or a lifecycle fence). */
+  isHeld(id: PeerId): boolean { return this.held(id); }
+
   private held(id: PeerId): boolean {
     return !this.isRostered(id) || this.recoveryHeld || this.recoveryHeldPeers.has(id) || this.paused.has(id) || this.opts.deliveryHeld?.(id) === true;
   }
@@ -1445,6 +1526,7 @@ export class Bus {
           this.activeDeliveries.set(deliveryId, id);
         } else this.remember(out);
         this.lastDelivery.set(id, { out, originals: delivery });
+        for (const env of delivery) if (env.kind === "invocation") this.invocationDeliveries.set(env.id, deliveryId);
         if (remoteId(id)) this.remoteTransport.set(deliveryId, { peer: id, originals: delivery });
         this.preparing.delete(id); // from here on the transport/journal owns settlement
         try {
@@ -1458,7 +1540,10 @@ export class Bus {
           else { await peer.deliver(out); this.delivered(id, delivery); }
         } catch {
           if (this.journal) this.uncertain(id, deliveryId, "adapter delivery outcome is uncertain");
-          else this.failed(id, delivery);
+          else if (delivery.some(env => env.kind === "invocation")) {
+            this.recoveryHeldPeers.add(id);
+            for (const env of delivery) if (env.kind === "invocation") this.onInvocationUncertain?.(env.id);
+          } else this.failed(id, delivery);
           break;
         } finally { this.remoteTransport.delete(deliveryId); }
       }
@@ -1505,13 +1590,16 @@ export class Bus {
    * An envelope that already failed once goes alone, so a poison one cannot take a digest down with it.
    */
   private take(id: PeerId, queue: Envelope[], remove = true): Envelope[] {
+    const digestMax = this.opts.digestMax?.() ?? DIGEST_MAX;
     const ordered = [...queue.filter((e) => e.priority === "important"), ...queue.filter((e) => e.priority !== "important")];
     const batch: Envelope[] = [];
     for (const env of ordered) {
       const failedBefore = this.attempts.has(`${id}:${env.id}`);
       if (failedBefore && batch.length) break;
+      // #445 C2: an invocation or its result goes alone, so the reply to the turn answers exactly one of them.
+      if (isInvocationKind(env) && batch.length) break;
       batch.push(env);
-      if (failedBefore || remoteId(id) || batch.length === DIGEST_MAX) break;
+      if (failedBefore || remoteId(id) || batch.length === digestMax || isInvocationKind(env)) break;
     }
     if (remove) for (const env of batch) queue.splice(queue.indexOf(env), 1);
     return batch;
@@ -1523,15 +1611,17 @@ export class Bus {
    * envelope cannot stall the queue. An envelope that already failed once still goes alone, as in `take`.
    */
   private takeBudget(id: PeerId, queue: Envelope[]): Envelope[] {
+    const pullBudgetBytes = this.opts.pullBudgetBytes?.() ?? PULL_BUDGET_BYTES;
     const batch: Envelope[] = [];
     let bytes = 0;
     for (const env of queue) {
       const failedBefore = this.attempts.has(`${id}:${env.id}`);
       if (failedBefore && batch.length) break;
       const size = Buffer.byteLength(frame(env)) + 2;
-      if (batch.length && bytes + size > PULL_BUDGET_BYTES) break;
+      if (batch.length && bytes + size > pullBudgetBytes) break;
+      if (isInvocationKind(env) && batch.length) break; // #445 C2: alone, as in `take`
       batch.push(env); bytes += size;
-      if (failedBefore) break;
+      if (failedBefore || isInvocationKind(env)) break;
     }
     for (const env of batch) queue.splice(queue.indexOf(env), 1);
     return batch;
@@ -1555,11 +1645,12 @@ export class Bus {
   }
 
   private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail", quota = false): void {
+    const maxAttempts = this.opts.maxAttempts?.() ?? MAX_ATTEMPTS;
     if (!this.journal) this.deliveryFailed(id);
     // A quota refusal ran no work. The budget pause fences retries until reset; it is not a poison attempt.
     const quotaPaused = quota && this.paused.has(id);
     this.lastFailure.set(id, reason.replace(/\s+/g, " ").slice(0, 300));
-    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
+    if (!quotaPaused && envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= maxAttempts)) {
       this.failureStreak.set(id, (this.failureStreak.get(id) ?? 0) + 1);
     }
     const keep = envs.filter((env) => {
@@ -1568,10 +1659,19 @@ export class Bus {
         this.restorePreface(id, env); // rides again on the next delivery, without counting as a failed envelope
         return false;
       }
+      if (env.kind === "invocation") {
+        const key = `${id}:${env.id}`, n = (this.attempts.get(key) ?? 0) + 1;
+        let read = false;
+        try { read = this.canRetryInvocation?.(env.id) === true; } catch { /* Unknown refuses replay. */ }
+        if (read && n < 2) { this.attempts.set(key, n); return true; }
+        this.attempts.delete(key);
+        this.emit({ t: "undeliverable", env, peer: id, reason: "invocation safe delivery refusal; no further automatic retry" });
+        return false;
+      }
       if (quotaPaused) return true;
       const key = `${id}:${env.id}`;
       const n = (this.attempts.get(key) ?? 0) + 1;
-      if (n < MAX_ATTEMPTS) return this.attempts.set(key, n);
+      if (n < maxAttempts) return this.attempts.set(key, n);
       this.attempts.delete(key);
       this.emit({ t: "undeliverable", env, peer: id, reason: this.lastFailure.get(id) });
       return false;
@@ -1584,7 +1684,7 @@ export class Bus {
 
   private emit(e: BusEvent): void {
     if (this.flushingHub) { this.deferredEvents.push(e); return; }
-    if ("env" in e && (remoteId(e.env.from) || e.env.to?.some(remoteId) || ("peer" in e && remoteId(e.peer)))) {
+    if ("env" in e && (remoteEnvelope(e.env) || e.env.to?.some(remoteId) || ("peer" in e && remoteId(e.peer)))) {
       const { refs: _, ...env } = e.env;
       e = { ...e, env: { ...env, body: "[remote room message withheld]", ...(env.to ? { to: env.to.filter(id => /^[a-z][a-z0-9-]{0,31}$/.test(id) || !!parseRemotePeerId(id)) } : {}) }, ...("reason" in e ? { reason: "remote room delivery" } : {}) };
     }

package/src/hub/capabilities.ts

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import { sanitize } from "./envelope.ts";
+
+/**
+ * #445 C1: what an agent can offer another, and what a person has agreed to share. Pure: no I/O, no clock, no process. The hub never calls any of these capabilities itself (C2 sends a request to the
+ * owner's own session); this module only decides what is LISTED.
+ *
+ * Authority: nothing is shared unless the person wrote it, in `invocation.share` of `.agenthub/config.local.json`, keyed by the exact peer id and the capability id and pinned by the capability's digest.
+ * Everything that comes from an agent (names, descriptions, schemas, the publisher's side-effect declaration) is untrusted text and only ever narrows what is shown.
+ */
+
+export const SIDE_EFFECTS = ["read", "write", "external", "destructive"] as const;
+export type SideEffect = (typeof SIDE_EFFECTS)[number];
+export const CAPABILITY_KINDS = ["command", "skill", "mcp_tool"] as const;
+export const CAPABILITY_SOURCES = ["acp", "codex-skills", "published"] as const;
+export const CAPABILITY_INVOKES = ["native", "prompt"] as const;
+
+export const NAME_RE = /^[A-Za-z0-9_.:-]{1,64}$/;
+export const DESCRIPTION_MAX = 300;
+/** A listing is bounded: no source can make the hub hold or show an unbounded manifest. */
+export const MAX_CAPABILITIES = 128;
+const MAX_SCHEMA_PROPERTIES = 16;
+const MAX_SCHEMA_ENUM = 32;
+const MAX_ENUM_VALUE = 64;
+const MAX_PUBLISH_BYTES = 64 * 1024;
+
+export interface FlatSchema {
+  type: "object";
+  properties: Record<string, { type: "string" | "number" | "boolean"; enum?: string[]; description?: string }>;
+  required?: string[];
+  additionalProperties: false;
+}
+export interface Capability {
+  id: string;
+  kind: (typeof CAPABILITY_KINDS)[number];
+  name: string;
+  description: string;
+  inputSchema?: FlatSchema;
+  /** The publisher's declared class; absent when its source names none (every native listing). */
+  sideEffect?: SideEffect;
+  source: (typeof CAPABILITY_SOURCES)[number];
+  invoke: (typeof CAPABILITY_INVOKES)[number];
+  digest: string;
+}
+export interface CapabilityManifest { capabilities: Capability[]; observedAt: number }
+
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const CONTROL_CHARS = "[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f\\u2028\\u2029\\u202a-\\u202e\\u2066-\\u2069]";
+/** Two regexes on purpose: the global one replaces, the plain one tests (a global regex keeps lastIndex between test calls and would miss the second of two strings). */
+const CONTROL = new RegExp(CONTROL_CHARS, "g"), HAS_CONTROL = new RegExp(CONTROL_CHARS);
+
+/** Canonical JSON: sorted keys at every depth, so equal values digest equally whatever order a source wrote them in. */
+export function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (object(value)) return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * The digest pins what a person agreed to: the identity of the capability, what it takes, the declared class, where it came from and how it is run. The description is NOT in it: it is capped untrusted text
+ * a source may reword freely, so rewording must not unlist an entry, while a changed schema, class, source or invoke form must.
+ */
+export function capabilityDigest(c: Pick<Capability, "kind" | "name" | "inputSchema" | "sideEffect" | "source" | "invoke">): string {
+  return `sha256:${createHash("sha256").update(canonical({ kind: c.kind, name: c.name, inputSchema: c.inputSchema ?? null, sideEffect: c.sideEffect ?? null, source: c.source, invoke: c.invoke })).digest("hex")}`;
+}
+
+/** Agent text shown to another model: control and bidirectional characters out, header forgery quoted, whitespace collapsed, cut by code point. */
+export function cleanDescription(raw: unknown): string {
+  const text = typeof raw === "string" ? raw : "";
+  return Array.from(sanitize(text.replace(CONTROL, " ")).replace(/\s+/g, " ").trim()).slice(0, DESCRIPTION_MAX).join("");
+}
+
+/** A flat object of strings, numbers, booleans and string enums, nothing nested, nothing extra. Anything else is not a schema this hub will carry. */
+export function flatSchema(raw: unknown): FlatSchema | undefined {
+  if (!object(raw) || raw.type !== "object" || raw.additionalProperties !== false || !object(raw.properties)) return undefined;
+  const names = Object.keys(raw.properties);
+  if (names.length === 0 || names.length > MAX_SCHEMA_PROPERTIES) return undefined;
+  const properties: FlatSchema["properties"] = {};
+  for (const name of names) {
+    const prop = raw.properties[name];
+    if (!NAME_RE.test(name) || !object(prop) || !["string", "number", "boolean"].includes(prop.type as string)) return undefined;
+    const extra = Object.keys(prop).filter(key => !["type", "enum", "description"].includes(key));
+    if (extra.length) return undefined;
+    const out: FlatSchema["properties"][string] = { type: prop.type as "string" | "number" | "boolean" };
+    if (prop.enum !== undefined) {
+      if (prop.type !== "string" || !Array.isArray(prop.enum) || prop.enum.length === 0 || prop.enum.length > MAX_SCHEMA_ENUM
+        || !prop.enum.every(value => typeof value === "string" && value.length >= 1 && value.length <= MAX_ENUM_VALUE && !HAS_CONTROL.test(value))) return undefined;
+      out.enum = [...prop.enum] as string[];
+    }
+    if (prop.description !== undefined) out.description = cleanDescription(prop.description);
+    properties[name] = out;
+  }
+  let required: string[] | undefined;
+  if (raw.required !== undefined) {
+    if (!Array.isArray(raw.required) || !raw.required.every(name => typeof name === "string" && Object.hasOwn(properties, name))) return undefined;
+    required = [...new Set(raw.required as string[])];
+  }
+  return { type: "object", properties, ...(required?.length ? { required } : {}), additionalProperties: false };
+}
+
+/** A class a side wrote: absent stays absent (it contributes nothing, O6), but a value that is not one of the four reads as the most dangerous one. */
+export function declaredClass(raw: unknown): SideEffect | undefined {
+  if (raw === undefined) return undefined;
+  return typeof raw === "string" && (SIDE_EFFECTS as readonly string[]).includes(raw) ? raw as SideEffect : "destructive";
+}
+const RANK: Record<SideEffect, number> = { read: 0, write: 1, external: 2, destructive: 3 };
+/** The higher of the publisher's declaration and the person's class (owner decision O1): neither side can make a capability look safer than the other said. */
+export function effectiveClass(declared: SideEffect | undefined, person: unknown): SideEffect {
+  const chosen = declaredClass(person);
+  if (declared === undefined) return chosen ?? "destructive"; // O6: only when neither side names a class
+  if (chosen === undefined) return declared;
+  return RANK[chosen] >= RANK[declared] ? chosen : declared;
+}
+
+export interface Candidate { kind: unknown; name: unknown; description?: unknown; inputSchema?: unknown; sideEffect?: unknown; source: Capability["source"]; invoke: Capability["invoke"] }
+/** One capability from one source, made safe, or undefined when it is not a capability this hub will carry. The id is derived, never taken from the source. */
+export function buildCapability(candidate: Candidate): Capability | undefined {
+  if (!(CAPABILITY_KINDS as readonly unknown[]).includes(candidate.kind) || typeof candidate.name !== "string" || !NAME_RE.test(candidate.name)) return undefined;
+  let inputSchema: FlatSchema | undefined;
+  if (candidate.inputSchema !== undefined) { inputSchema = flatSchema(candidate.inputSchema); if (!inputSchema) return undefined; }
+  const kind = candidate.kind as Capability["kind"], sideEffect = declaredClass(candidate.sideEffect);
+  const base = { kind, name: candidate.name, ...(inputSchema ? { inputSchema } : {}), ...(sideEffect ? { sideEffect } : {}), source: candidate.source, invoke: candidate.invoke };
+  return { id: `${kind}:${candidate.name}`, ...base, description: cleanDescription(candidate.description), digest: capabilityDigest(base) };
+}
+
+/** A manifest from a source's raw list: invalid entries are dropped one by one, duplicates by id keep the first, and the whole is bounded. */
+export function buildManifest(raw: readonly Candidate[], observedAt: number): CapabilityManifest {
+  const seen = new Set<string>(), capabilities: Capability[] = [];
+  for (const candidate of raw) {
+    const built = buildCapability(candidate);
+    if (!built || seen.has(built.id)) continue;
+    seen.add(built.id); capabilities.push(built);
+    if (capabilities.length >= MAX_CAPABILITIES) break;
+  }
+  return { capabilities, observedAt };
+}
+
+export class PublishRefusal extends Error {}
+/**
+ * `hub_capabilities_publish`: the source for a session whose capabilities the hub cannot read natively. Every field is checked, an unknown field is a refusal, nothing is stored on a refusal, and the invoke
+ * form is forced to `prompt`: a publisher cannot claim a native path the hub never verified.
+ */
+export function validatePublished(raw: unknown, observedAt: number): CapabilityManifest {
+  if (!object(raw) || Object.keys(raw).some(key => key !== "capabilities") || !Array.isArray(raw.capabilities)) throw new PublishRefusal("capabilities must be an array");
+  if (raw.capabilities.length === 0) throw new PublishRefusal("capabilities must not be empty (publish a list, or nothing)");
+  if (raw.capabilities.length > MAX_CAPABILITIES) throw new PublishRefusal(`at most ${MAX_CAPABILITIES} capabilities`);
+  if (JSON.stringify(raw.capabilities).length > MAX_PUBLISH_BYTES) throw new PublishRefusal("the list is too large");
+  const seen = new Set<string>(), candidates: Candidate[] = [];
+  raw.capabilities.forEach((entry, index) => {
+    const at = `capabilities[${index}]`;
+    if (!object(entry)) throw new PublishRefusal(`${at} must be an object`);
+    const extra = Object.keys(entry).filter(key => !["kind", "name", "description", "inputSchema", "sideEffect"].includes(key));
+    if (extra.length) throw new PublishRefusal(`${at}: unknown field ${JSON.stringify(extra[0])}`);
+    if (!(CAPABILITY_KINDS as readonly unknown[]).includes(entry.kind)) throw new PublishRefusal(`${at}.kind must be one of ${CAPABILITY_KINDS.join(", ")}`);
+    if (typeof entry.name !== "string" || !NAME_RE.test(entry.name)) throw new PublishRefusal(`${at}.name must match ${NAME_RE}`);
+    if (typeof entry.description !== "string") throw new PublishRefusal(`${at}.description must be text`);
+    if (entry.sideEffect === undefined || !(SIDE_EFFECTS as readonly unknown[]).includes(entry.sideEffect)) throw new PublishRefusal(`${at}.sideEffect must be one of ${SIDE_EFFECTS.join(", ")}`);
+    if (entry.inputSchema !== undefined && !flatSchema(entry.inputSchema)) throw new PublishRefusal(`${at}.inputSchema must be a flat object of string, number, boolean or string enum properties with additionalProperties false`);
+    const id = `${entry.kind}:${entry.name}`;
+    if (seen.has(id)) throw new PublishRefusal(`${at}: ${id} is listed twice`);
+    seen.add(id);
+    candidates.push({ kind: entry.kind, name: entry.name, description: entry.description, inputSchema: entry.inputSchema, sideEffect: entry.sideEffect, source: "published", invoke: "prompt" });
+  });
+  return buildManifest(candidates, observedAt);
+}
+
+export interface ShareEntry { digest: string; class?: SideEffect }
+export type ShareConfig = Record<string, Record<string, ShareEntry>>;
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+/** `invocation.share` as written by a person: malformed entries are dropped and say nothing is shared for them; it is never an error that stops the hub. */
+export function readShare(raw: unknown): ShareConfig {
+  const out: ShareConfig = {};
+  if (!object(raw)) return out;
+  for (const [peer, entries] of Object.entries(raw)) {
+    const address = /^[a-z][a-z0-9-]{0,31}(?:@[a-z][a-z0-9-]{0,31})?$/.exec(peer);
+    if (!object(entries) || address?.[0] !== peer || peer.includes("@") && ["hub", "digest"].includes(peer.split("@")[0]!)) continue;
+    const kept: Record<string, ShareEntry> = {};
+    for (const [id, entry] of Object.entries(entries)) {
+      if (!/^(command|skill|mcp_tool):[A-Za-z0-9_.:-]{1,64}$/.test(id) || !object(entry) || typeof entry.digest !== "string" || !DIGEST_RE.test(entry.digest)) continue;
+      const cls = entry.class === undefined ? undefined : (SIDE_EFFECTS as readonly unknown[]).includes(entry.class) ? entry.class as SideEffect : null;
+      if (cls === null || peer.includes("@") && cls !== "read") continue;
+      kept[id] = { digest: entry.digest, ...(cls ? { class: cls } : {}) };
+    }
+    if (Object.keys(kept).length) out[peer] = kept;
+  }
+  return out;
+}
+
+export interface Listed { id: string; kind: Capability["kind"]; name: string; description: string; inputSchema?: FlatSchema; class: SideEffect; invoke: Capability["invoke"]; source: Capability["source"]; digest: string }
+/**
+ * What `peer` offers: the capabilities of its manifest that the person listed BY THIS PEER ID and whose digest still matches. A digest change drops the entry until the person pins the new one, and a peer id
+ * never reads another peer's entries (an instance `codex-2` does not inherit `codex`). With no share, or no manifest, the answer is nothing.
+ */
+export function listedCapabilities(peer: string, manifest: CapabilityManifest | undefined, share: ShareConfig): Listed[] {
+  const entries = Object.hasOwn(share, peer) ? share[peer] : undefined;
+  if (!manifest || !entries) return [];
+  const out: Listed[] = [];
+  for (const cap of manifest.capabilities) {
+    const entry = Object.hasOwn(entries, cap.id) ? entries[cap.id] : undefined;
+    if (!entry || entry.digest !== cap.digest) continue;
+    out.push({ id: cap.id, kind: cap.kind, name: cap.name, description: cap.description, ...(cap.inputSchema ? { inputSchema: cap.inputSchema } : {}), class: effectiveClass(cap.sideEffect, entry.class), invoke: cap.invoke, source: cap.source, digest: cap.digest });
+  }
+  return out;
+}
+
+export type ShareState = "listed" | "unshared" | "digest-changed";
+/** For the person's `ahub capabilities`: every manifest entry, whether the person shares it, and the class that would apply. */
+export function shareView(peer: string, manifest: CapabilityManifest | undefined, share: ShareConfig): Array<{ id: string; kind: Capability["kind"]; name: string; description: string; source: Capability["source"]; invoke: Capability["invoke"]; digest: string; state: ShareState; class: SideEffect }> {
+  const entries = Object.hasOwn(share, peer) ? share[peer] : undefined;
+  return (manifest?.capabilities ?? []).map(cap => {
+    const entry = entries && Object.hasOwn(entries, cap.id) ? entries[cap.id] : undefined;
+    const state: ShareState = !entry ? "unshared" : entry.digest === cap.digest ? "listed" : "digest-changed";
+    return { id: cap.id, kind: cap.kind, name: cap.name, description: cap.description, source: cap.source, invoke: cap.invoke, digest: cap.digest, state, class: effectiveClass(cap.sideEffect, entry?.class) };
+  });
+}

package/src/hub/config-apply.ts

@@ -194,7 +194,11 @@ const schema: Record<string, Check> = {
   conductor: block({ feed: words(["own", "all", "off"]), approval_wait_s: number(0, 2_147_483_647 / 1000) }),
   budget: block({ gate: number(0, 1), stale_min: timerMinutes, poll_min: timerMinutes, checkpoint_timeout_s: timerSeconds, kimi_tokens_5h: number(0), wait_max_min: number(0) }),
   context: block({ gate: number(0, 1), stale_min: timerMinutes, max_assignment_used: number(0, 1) }),
-  inference: block({ enabled: bool, digest_min_items: number(1, 100_000, true), digest_min_chars: number(1, 10_000_000, true), triage: bool }),
+  bus: block({ max_attempts: operationalNumberCheck("bus.max_attempts"), digest_max: operationalNumberCheck("bus.digest_max"), pull_budget_bytes: operationalNumberCheck("bus.pull_budget_bytes"), notes_kept: operationalNumberCheck("bus.notes_kept"), terminal_history_limit: operationalNumberCheck("bus.terminal_history_limit") }),
+  adapter_timing: block({ acp_tool_ceiling_min: operationalNumberCheck("adapter_timing.acp_tool_ceiling_min"), acp_activity_batch_ms: operationalNumberCheck("adapter_timing.acp_activity_batch_ms"), jcode_steer_timeout_s: operationalNumberCheck("adapter_timing.jcode_steer_timeout_s") }),
+  model_relay: block({ cooldown_failures: operationalNumberCheck("model_relay.cooldown_failures"), cooldown_s: operationalNumberCheck("model_relay.cooldown_s"), cooldown_cap_s: operationalNumberCheck("model_relay.cooldown_cap_s"), terminal_history_limit: operationalNumberCheck("model_relay.terminal_history_limit") }),
+  console: block({ poll_ms: operationalNumberCheck("console.poll_ms"), notice_ms: operationalNumberCheck("console.notice_ms"), history_limit: operationalNumberCheck("console.history_limit"), pending_stream_limit: operationalNumberCheck("console.pending_stream_limit"), attention_limit: operationalNumberCheck("console.attention_limit") }),
+  inference: block({ enabled: bool, digest_min_items: operationalNumberCheck("inference.digest_min_items"), digest_min_chars: operationalNumberCheck("inference.digest_min_chars"), triage: bool, backoff_min: operationalNumberCheck("inference.backoff_min") }),
   omniroute: block({ urls: strings, api_key_file: text, access_hosts: strings, cf_client_id_file: text, cf_client_secret_file: text }),
   mlx: block({ enabled: bool, provider: words(["legacy", "ollama"]), host: text, runtimeDir: text, modelPath: text, bin: text, port: number(1, 65535, true), model: text, sourceModel: text,
     contextWindow: number(1), maxInputTokens: number(1), maxTokens: number(1), maxConcurrency: number(1, 1024, true) }),
@@ -213,8 +217,8 @@ const schema: Record<string, Check> = {
   peers: (v, k) => { map(block({ start_mode: words(["tui", "headless"]) }), START_MODE_PEERS)(v, k); peerStartConfig(v); },
   terminal: (v, k) => { block({ open: strings })(v, k); terminalTemplate(object(v, k).open); },
   limits: block({ sender_per_min: number(0), pair_per_min: number(0), important_per_hour: number(0), repeat_window_s: number(0) }),
-  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true), pool: v => { reviewerPoolConfig({ pool: v }, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS); }, rerotate: bool, same_family: words(["fallback", "never"]) }), recovery: block({ auto_resume_after_crash: bool }),
-  capabilities: map(strings), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
+  review: block({ adaptive: bool, min_reviews: number(1, Number.MAX_SAFE_INTEGER, true), pool: v => { reviewerPoolConfig({ pool: v }, DEFAULT_REVIEW_POOL, REVIEW_POOL_KINDS); }, rerotate: bool, same_family: words(["fallback", "never"]) }), recovery: block({ auto_resume_after_crash: bool, reconnect_wait_s: operationalNumberCheck("recovery.reconnect_wait_s"), unmanaged_reconnect_wait_s: operationalNumberCheck("recovery.unmanaged_reconnect_wait_s"), control_timeout_s: operationalNumberCheck("recovery.control_timeout_s"), shutdown_wait_s: operationalNumberCheck("recovery.shutdown_wait_s"), terminal_idle_wait_s: operationalNumberCheck("recovery.terminal_idle_wait_s") }),
+  capabilities: map(strings), invocation: block({ share: map(map(() => {})), timeout_s: number(10, 86_400, true) }), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
 };
 export const SCHEMA_KEYS: readonly string[] = Object.freeze(Object.keys(schema));
 export function validateRawConfig(raw: unknown, declarations?: InstancesConfig, context?: ProjectAdapterCatalog, inertModuleRoster = false): asserts raw is Record<string, unknown> {
@@ -255,7 +259,7 @@ const restart: Record<string, string> = {
   profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
   text_projection: "Converter and cache ownership are bound at startup", corpus: "The corpus index is bound to its roots at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
 };
-const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet"]);
+const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "pet"]);
 const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
 /** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
 export function configApply(key: string, scopes: readonly ConfigIdentityScope[] = []): ApplyRule {

package/src/hub/config-trust.ts

@@ -33,6 +33,7 @@ export const MACHINE_LOCAL = [
   "folder_triggers", // #512c: entries make the hub read a folder and propose a task per new file; a committed config may not point the hub at a folder on someone else's machine
   "schedules", // #512: entries make the hub propose tasks on a timer; a committed config may not create work on someone else's machine
   "corpus.paths", // #510: folders the hub reads as evidence; a committed config may not point the hub at a folder on someone else's machine
+  "invocation", // #445 C1: what another agent may be offered from this machine's agents (a digest-pinned allowlist); a committed config may not share a person's agents' commands with someone else's peers
 ] as const;
 /** Legacy exported field list stays compatible; new policies use the complete list below. */
 export const ALL_MACHINE_LOCAL = [...MACHINE_LOCAL, "rooms", "tasks.queue_backpressure", "context.max_assignment_used", "action_policy", "protect_instruction_files", "qwen_cmd", "jcode_cmd", "jcode_home", "jcode_provider_profile", "adapters", "adapter_modules", "text_projection", "instances"] as const;