@staix/agent-hub 0.22.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";
@@ -182,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. */
@@ -213,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);
       }
     }
@@ -248,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
@@ -316,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 = () => {
@@ -495,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();
   }
 
@@ -562,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}`);
   }
 
@@ -676,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;
@@ -694,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?.();
   }
 
@@ -1021,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();
@@ -1041,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);
         }
       }
@@ -1085,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 ?? [];
@@ -1310,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++;
@@ -1331,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;
   }
@@ -1450,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 {
@@ -1463,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); }
       }
@@ -1516,8 +1596,10 @@ export class Bus {
     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 === digestMax) 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;
@@ -1537,8 +1619,9 @@ export class Bus {
       if (failedBefore && batch.length) break;
       const size = Buffer.byteLength(frame(env)) + 2;
       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;
@@ -1576,6 +1659,15 @@ 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;
@@ -1592,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

@@ -195,7 +195,10 @@ const schema: Record<string, Check> = {
   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) }),
   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") }),
-  inference: block({ enabled: bool, digest_min_items: number(1, 100_000, true), digest_min_chars: number(1, 10_000_000, true), triage: bool }),
+  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) }),
@@ -215,7 +218,7 @@ const schema: Record<string, Check> = {
   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, 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), coordination: words(["advisory", "turn-free"]), experiments: block({ stale_notices: words(["drop", "deliver"]) }),
+  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> {
@@ -256,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;

package/src/hub/control-client.ts

@@ -9,7 +9,7 @@ export function stateDirFor(cwd: string): string {
 
 /** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). 16 = a Claude session without channel evidence: hello `channel: false` and `inbox` (issue #205). The plugin is installed apart from the daemon, so they can drift. */
 export const PROTOCOL = 16;
-export const DAEMON_FEATURES = ["conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
+export const DAEMON_FEATURES = ["conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, PROTOCOL] as const;
 
@@ -86,15 +86,25 @@ export function readControl(stateDir: string): ControlDescriptor | undefined {
 
 const instancePins = new Map<string, { instanceId: string }>();
 
+/** Maximum supported 3600 s approval plus admission/transport margin; applies to every hub_invoke client path. */
+export const INVOCATION_CONTROL_TIMEOUT_MS = 3_665_000;
+export function controlRequestTimeout(msg: Record<string, unknown>, requested = 30_000): number {
+  return msg.t === "task" && msg.op === "hub_invoke" && requested !== 0
+    ? Math.max(Number.isFinite(requested) ? requested : 0, INVOCATION_CONTROL_TIMEOUT_MS) : requested;
+}
+
+
 /** One authenticated control connection. `request` correlates replies by `rid`; everything else goes to `onPush`. */
 export class ControlClient {
   features: readonly string[] = [];
   private welcomeInstanceId?: string;
   /** Identity from the authenticated welcome, never the unauthenticated descriptor alone. */
   get instanceId(): string | undefined { return this.welcomeInstanceId; }
-  get isOpen(): boolean { return this.ws.readyState === WebSocket.OPEN; }
+  get isOpen(): boolean { return !this.closing && this.ws.readyState === WebSocket.OPEN; }
   private nextRid = 1;
   private readonly pending = new Map<number, (msg: any) => void>();
+  private readonly invocations = new Set<number>();
+  private closing = false;
   onPush: (msg: any) => void = () => {};
   /** `code`/`reason`: what the hub closed with, e.g. 4000 when another client attached as the same peer. */
   onClose: (code: number, reason: string) => void = () => {};
@@ -179,13 +189,32 @@ export class ControlClient {
   }
 
   /** `timeoutMs`: for calls a person waits on. The hub has its own budget; this one only makes sure the CLI never hangs. */
-  request(msg: Record<string, unknown>, timeoutMs = 30_000): Promise<any> {
-    if (this.ws.readyState !== WebSocket.OPEN) return Promise.resolve({ ok: false, error: "hub connection is not open" });
+  request(msg: Record<string, unknown>, timeoutMs = 30_000, signal?: AbortSignal): Promise<any> {
+    if (this.ws.readyState !== WebSocket.OPEN || this.closing && msg.t !== "request_cancel") return Promise.resolve({ ok: false, error: "hub connection is not open" });
+    const invocation = msg.t === "task" && msg.op === "hub_invoke";
+    timeoutMs = controlRequestTimeout(msg, timeoutMs);
+    if (signal?.aborted) return Promise.resolve({ ok: false, error: "hub request cancelled before sending" });
     const rid = this.nextRid++;
     return new Promise((resolve) => {
-      const timer = timeoutMs ? setTimeout(() => (this.pending.delete(rid), resolve({ ok: false, error: `no answer from the hub within ${Math.round(timeoutMs / 1000)} s` })), timeoutMs) : undefined;
-      this.pending.set(rid, (reply) => (clearTimeout(timer), resolve(reply)));
-      this.ws.send(JSON.stringify({ ...msg, rid }));
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const done = (reply: any) => {
+        this.pending.delete(rid); this.invocations.delete(rid); clearTimeout(timer); signal?.removeEventListener("abort", aborted); resolve(reply);
+      };
+      const abandon = (error: string) => {
+        if (!this.pending.has(rid)) return;
+        if (invocation && this.ws.readyState === WebSocket.OPEN) {
+          try { this.ws.send(JSON.stringify({ t: "request_cancel", request: rid })); } catch { /* Socket close also withdraws admission. */ }
+        }
+        done({ ok: false, error: invocation ? `${error}; invocation admission unconfirmed, inspect before retrying` : error });
+      };
+      const aborted = () => abandon("hub request cancelled");
+      this.pending.set(rid, done);
+      if (invocation) this.invocations.add(rid);
+      signal?.addEventListener("abort", aborted, { once: true });
+      if (signal?.aborted) { aborted(); return; }
+      timer = timeoutMs ? setTimeout(() => abandon(`no answer from the hub within ${Math.round(timeoutMs / 1000)} s`), timeoutMs) : undefined;
+      try { this.ws.send(JSON.stringify({ ...msg, rid })); }
+      catch { abandon("hub request could not be sent"); }
     });
   }
 
@@ -194,6 +223,10 @@ export class ControlClient {
   }
 
   close(): void {
-    this.ws.close();
+    if (this.closing) return;
+    this.closing = true;
+    if (!this.invocations.size || this.ws.readyState !== WebSocket.OPEN) { this.ws.close(); return; }
+    // Withdraw admissions before reporting a graceful close to callers. An abrupt transport loss is fenced by the daemon close handler.
+    void Promise.allSettled([...this.invocations].map(request => this.request({ t: "request_cancel", request }, 3000))).finally(() => this.ws.close());
   }
 }