@staix/agent-hub 0.21.0 → 0.23.0

package/src/hub/deferred-hub.ts

@@ -1,4 +1,4 @@
-import { HUB, MAX_HOP, type Envelope } from "./envelope.ts";
+import { HUB, KINDS, MAX_HOP, type Envelope } from "./envelope.ts";
 
 /** ponytail: cap recovery at 2048 unpublished hub originals; replace with a paged durable outbox if measured recovery workloads exceed it. */
 export const MAX_DEFERRED_HUB = 2048;
@@ -22,7 +22,7 @@ export function validateDeferredEnvelope(value: unknown, name: string): Envelope
       typeof env.body !== "string" || env.body.length > 1_000_000 ||
       !Number.isSafeInteger(env.hop) || (env.hop as number) < 0 || (env.hop as number) > MAX_HOP ||
       !Number.isSafeInteger(env.ts) || (env.ts as number) < 0 ||
-      !["chat", "task", "review", "status", "budget", "presence"].includes(env.kind as string) ||
+      !(KINDS as readonly string[]).includes(env.kind as string) ||
       !["important", "status", "fyi"].includes(env.priority as string) ||
       (!Array.isArray(env.to) || env.to.length > 256 || !env.to.every(peer => text(peer, 256))) ||
       (env.private !== undefined && typeof env.private !== "boolean"))

package/src/hub/delivery-hints.ts

@@ -1,4 +1,4 @@
-import { sanitize, type Kind } from "./envelope.ts";
+import { KINDS, sanitize, type Kind } from "./envelope.ts";
 
 export const DELIVERY_RETRY_WARNING = sanitize("Hub redelivery warning: An earlier attempt of this delivery is uncertain; check for its effects before acting.");
 export interface HeldDeliveryHints {
@@ -18,7 +18,7 @@ export function heldDeliveryHints(rows: readonly HeldDeliveryHints["rows"][numbe
 export function renderHeldHint(value: unknown, now = Date.now(), recipientRetry = true): string {
   if (!value || typeof value !== "object" || Array.isArray(value)) return "";
   const held = value as HeldDeliveryHints;
-  const kinds = new Set(["chat", "task", "review", "status", "budget", "presence"]);
+  const kinds = new Set<string>(KINDS);
   try {
     if (!Number.isSafeInteger(held.count) || held.count < 1 || !Array.isArray(held.rows) || held.rows.length > 32 || held.rows.length > held.count || typeof held.truncated !== "boolean" || Buffer.byteLength(JSON.stringify(held), "utf8") > 4096) return "";
     if (held.rows.some(row => !row || typeof row !== "object" || typeof row.id !== "string" || !row.id.length || row.id.length > 256 || !Number.isFinite(row.createdAt) || !Array.isArray(row.senders) || !Array.isArray(row.kinds) || row.senders.some(sender => typeof sender !== "string" || sender.length > 256) || row.kinds.some(kind => !kinds.has(kind)))) return "";

package/src/hub/delivery-journal.ts

@@ -3,7 +3,7 @@ import { dirname } from "node:path";
 import { Database } from "bun:sqlite";
 import type { BusSnapshot } from "./bus.ts";
 import type { QueuePressure } from "./queue-backpressure.ts";
-import { HUB, USER, type Envelope, type Kind } from "./envelope.ts";
+import { HUB, KINDS, USER, type Envelope, type Kind } from "./envelope.ts";
 import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
@@ -20,8 +20,8 @@ export type JournalDeliveryState =
   | "discarded";
 export type JournalResolution = "completed" | "retry" | "discard";
 export const MAX_ENVELOPE_BODY = 1_000_000;
+export const TERMINAL_CAP = 2048;
 const SCHEMA_VERSION = 1,
-  TERMINAL_CAP = 2048,
   MAX_ROWS = 100_000,
   MAX_JSON = 20 * 1024 * 1024;
 const STATES = new Set<JournalDeliveryState>([
@@ -56,6 +56,8 @@ export interface DeliveryJournalOptions {
   projectId: string;
   instanceId: string;
   operationId?: string;
+  /** Accepted live history target; only terminal mutations apply it, other pruning keeps the legacy cap. */
+  terminalHistoryLimit?: () => number;
 }
 export interface JournalSnapshot {
   schemaVersion: number;
@@ -118,9 +120,7 @@ function validateEnvelope(value: unknown, name: string, seen = false): Envelope
   if (typeof e.body !== "string" || e.body.length > MAX_ENVELOPE_BODY) fail(`${name}.body is invalid`);
   integer(e.ts, `${name}.ts`);
   if (
-    !new Set(["chat", "task", "review", "status", "budget", "presence"]).has(
-      e.kind as string,
-    )
+    !(KINDS as readonly string[]).includes(e.kind as string)
   )
     fail(`${name}.kind is invalid`);
   if (!new Set(["important", "status", "fyi"]).has(e.priority as string))
@@ -271,13 +271,16 @@ export class DeliveryJournal {
   private closed = false;
   private queueMetadataTracking = false;
   private queueMetadataInvalidated = false;
+  private pruningDeferred = 0;
   private readonly operationId?: string;
+  private readonly terminalHistoryLimit?: () => number;
   constructor(options: DeliveryJournalOptions) {
     this.file = options.file;
     this.projectRoot = text(options.projectRoot, "projectRoot", 4096);
     this.projectId = text(options.projectId, "projectId", 256);
     this.instanceId = text(options.instanceId, "instanceId", 256);
     this.operationId = options.operationId;
+    this.terminalHistoryLimit = options.terminalHistoryLimit;
     mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
     this.db = new Database(options.file, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
@@ -704,53 +707,56 @@ export class DeliveryJournal {
       updatedAt: delivery.createdAt,
     });
     return this.queueMetadataTransaction(trackQueuePressure, () => {
-      const evidence = this.retryEvidence(delivery.peer, delivery.originals);
-      if (evidence === "used") {
-        // Inheritance commits with the handoff, before safe failure or pruning can erase a grouped parent.
-        this.recordRetryEvidence(delivery.peer, delivery.originals, delivery.id, this.retryWarning(delivery.peer, delivery.originals));
-        delivery = { ...delivery, attempt: Math.max(1, delivery.attempt ?? 0) };
-      } else if (evidence === "unknown") this.markRetryUnknown([{ ...delivery, revision: 0, updatedAt: delivery.createdAt }], {});
-      const ids = new Set(delivery.originals.map((env) => env.id)), immutableIds = new Set(retryOriginals(delivery.originals).map(env => env.id));
-      for (const row of this.list(delivery.peer)) {
-        if (row.state !== "queued" || !row.originals.some((env) => ids.has(env.id))) continue;
-        this.transition(row.id, "discarded", `grouped into delivery ${delivery.id}`);
-        if (retryOriginals(row.originals).some(env => immutableIds.has(env.id))) {
-          delivery = { ...delivery, previousId: delivery.previousId ?? row.id };
-          if ((row.attempt ?? 0) > 0) delivery = { ...delivery, attempt: Math.max(delivery.attempt ?? 0, row.attempt!) };
+      // Grouped parents are not linked until the handoff INSERT.
+      return this.withPruningDeferred(() => {
+        const evidence = this.retryEvidence(delivery.peer, delivery.originals);
+        if (evidence === "used") {
+          // Inheritance commits with the handoff, before safe failure or pruning can erase a grouped parent.
+          this.recordRetryEvidence(delivery.peer, delivery.originals, delivery.id, this.retryWarning(delivery.peer, delivery.originals));
+          delivery = { ...delivery, attempt: Math.max(1, delivery.attempt ?? 0) };
+        } else if (evidence === "unknown") this.markRetryUnknown([{ ...delivery, revision: 0, updatedAt: delivery.createdAt }], {});
+        const ids = new Set(delivery.originals.map((env) => env.id)), immutableIds = new Set(retryOriginals(delivery.originals).map(env => env.id));
+        for (const row of this.list(delivery.peer)) {
+          if (row.state !== "queued" || !row.originals.some((env) => ids.has(env.id))) continue;
+          this.transition(row.id, "discarded", `grouped into delivery ${delivery.id}`);
+          if (retryOriginals(row.originals).some(env => immutableIds.has(env.id))) {
+            delivery = { ...delivery, previousId: delivery.previousId ?? row.id };
+            if ((row.attempt ?? 0) > 0) delivery = { ...delivery, attempt: Math.max(delivery.attempt ?? 0, row.attempt!) };
+          }
         }
-      }
-      const revision = this.bump();
-      const now = Date.now();
-      this.db
-        .query(
-          "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
-        )
-        .run(
-          JSON.stringify(bus),
-          JSON.stringify(bus.manualPaused ?? []),
-          this.projectId,
-        );
-      this.writeQueueMetadata(bus, revision, trackQueuePressure);
-      this.db
-        .query(
-          "INSERT INTO deliveries (id, project_id, peer, state, revision, created_at, updated_at, originals, out_json, reason, attempt, previous_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-        )
-        .run(
-          delivery.id,
-          this.projectId,
-          delivery.peer,
-          delivery.state,
-          revision,
-          delivery.createdAt,
-          now,
-          JSON.stringify(delivery.originals),
-          JSON.stringify(delivery.out),
-          delivery.reason ?? null,
-          delivery.attempt ?? null,
-          delivery.previousId ?? null,
-        );
-      this.harden();
-      return { ...delivery, revision, updatedAt: now };
+        const revision = this.bump();
+        const now = Date.now();
+        this.db
+          .query(
+            "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
+          )
+          .run(
+            JSON.stringify(bus),
+            JSON.stringify(bus.manualPaused ?? []),
+            this.projectId,
+          );
+        this.writeQueueMetadata(bus, revision, trackQueuePressure);
+        this.db
+          .query(
+            "INSERT INTO deliveries (id, project_id, peer, state, revision, created_at, updated_at, originals, out_json, reason, attempt, previous_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+          )
+          .run(
+            delivery.id,
+            this.projectId,
+            delivery.peer,
+            delivery.state,
+            revision,
+            delivery.createdAt,
+            now,
+            JSON.stringify(delivery.originals),
+            JSON.stringify(delivery.out),
+            delivery.reason ?? null,
+            delivery.attempt ?? null,
+            delivery.previousId ?? null,
+          );
+        this.harden();
+        return { ...delivery, revision, updatedAt: now };
+      });
     });
   }
   createDelivery(
@@ -785,7 +791,7 @@ export class DeliveryJournal {
           input.attempt ?? null,
           input.previousId ?? null,
         );
-      this.pruneTerminal();
+      this.pruneTerminal(input.state, input.id);
       return { ...input, revision, updatedAt };
     })();
   }
@@ -802,9 +808,14 @@ export class DeliveryJournal {
     return this.db.transaction((): JournalDelivery => {
       const row = this.get(deliveryId);
       if (!row || row.peer !== peer || !["dispatching", "accepted"].includes(row.state)) throw new Error("delivery is not active for this peer");
-      const completed = this.transition(deliveryId, "completed", reason, row.revision);
-      const put = this.db.query("INSERT OR IGNORE INTO task_offer_reads (project_id,peer,envelope_id,delivery_id,source,offer_revision) VALUES (?,?,?,?,?,?)");
-      for (const env of row.originals) if (env.from === HUB && env.kind === "task" && Number.isSafeInteger(env.refs?.taskOffer) && env.refs!.taskOffer! >= 1) put.run(this.projectId, peer, env.id, deliveryId, source, env.refs!.taskOffer!);
+      const completed = this.withPruningDeferred(() => {
+        const result = this.transition(deliveryId, "completed", reason, row.revision);
+        const put = this.db.query("INSERT OR IGNORE INTO task_offer_reads (project_id,peer,envelope_id,delivery_id,source,offer_revision) VALUES (?,?,?,?,?,?)");
+        for (const env of row.originals) if (env.from === HUB && env.kind === "task" && Number.isSafeInteger(env.refs?.taskOffer) && env.refs!.taskOffer! >= 1) put.run(this.projectId, peer, env.id, deliveryId, source, env.refs!.taskOffer!);
+        return result;
+      });
+      // Proof is now durable in this transaction, and the return receipt is captured.
+      this.pruneTerminal("completed", "");
       return completed;
     })();
   }
@@ -834,7 +845,7 @@ export class DeliveryJournal {
           "UPDATE deliveries SET state = ?, revision = ?, updated_at = ?, reason = ? WHERE id = ? AND project_id = ?",
         )
         .run(state, revision, Date.now(), reason ?? null, id, this.projectId);
-      this.pruneTerminal();
+      this.pruneTerminal(state, id);
       return this.get(id)!;
     })();
   }
@@ -1023,7 +1034,7 @@ export class DeliveryJournal {
           JSON.stringify(retryOriginals(current.originals).map(env => env.id)),
         );
       if (action === "retry") this.recordRetryEvidence(current.peer, current.originals, id, actor === `peer:${current.peer}`);
-      this.pruneTerminal();
+      this.pruneTerminal(result.state, result.id);
       return result;
     })();
   }
@@ -1031,7 +1042,15 @@ export class DeliveryJournal {
     const row = this.db.query("SELECT action,reason,observed_revision,actor FROM resolution_history WHERE project_id=? AND delivery_id=? ORDER BY id DESC LIMIT 1").get(this.projectId, id) as { action: JournalResolution; reason: string; observed_revision: number; actor: string } | null;
     return row ? { action: row.action, reason: row.reason, observedRevision: row.observed_revision, actor: row.actor } : undefined;
   }
-  private pruneTerminal(): void {
+  private withPruningDeferred<T>(body: () => T): T {
+    this.pruningDeferred++;
+    try { return body(); } finally { this.pruningDeferred--; }
+  }
+  private pruneTerminal(state: JournalDeliveryState, currentId: string): void {
+    if (this.pruningDeferred) return;
+    const terminal = state === "completed" || state === "discarded" || state === "failed";
+    const terminalCap = terminal ? this.terminalHistoryLimit?.() ?? TERMINAL_CAP : TERMINAL_CAP;
+    // Never delete the receipt this mutation/resolve is still using, at any target.
     const count = Number(
       (
         this.db
@@ -1041,12 +1060,12 @@ export class DeliveryJournal {
           .get(this.projectId) as { n: number }
       ).n,
     );
-    if (count <= TERMINAL_CAP) return;
+    if (count <= terminalCap) return;
     this.db
       .query(
-        "DELETE FROM deliveries WHERE id IN (SELECT d.id FROM deliveries d WHERE d.project_id = ? AND d.state IN ('completed','discarded','failed') AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id) ORDER BY d.updated_at, d.id LIMIT ?)",
+        "DELETE FROM deliveries WHERE id IN (SELECT d.id FROM deliveries d WHERE d.project_id = ? AND d.state IN ('completed','discarded','failed') AND d.id != ? AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id) ORDER BY d.updated_at, d.id LIMIT ?)",
       )
-      .run(this.projectId, count - TERMINAL_CAP);
+      .run(this.projectId, currentId, count - terminalCap);
   }
   importSnapshot(snapshot: JournalSnapshot, operationId: string, trackQueuePressure = false): boolean {
     this.ensureOpen();

package/src/hub/envelope.ts

@@ -3,7 +3,9 @@ import { randomUUID } from "node:crypto";
 export type PeerId = string;
 export type PeerState = "idle" | "busy" | "paused" | "offline";
 export type Priority = "important" | "status" | "fyi";
-export type Kind = "chat" | "task" | "review" | "status" | "budget" | "presence";
+/** Every envelope kind, once: the journal, the restart reader, the deferred-notice check and the held-delivery hints all read this list. `invocation` and `invocation_result` are #445 C2. */
+export const KINDS = ["chat", "task", "review", "status", "budget", "presence", "invocation", "invocation_result"] as const;
+export type Kind = (typeof KINDS)[number];
 
 export interface Envelope {
   id: string;
@@ -14,7 +16,7 @@ export interface Envelope {
   kind: Kind;
   priority: Priority;
   body: string; // agent conclusions only, never tool noise
-  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[] };
+  refs?: { repo?: string; branch?: string; commit?: string; paths?: string[]; task?: string; reviewRevision?: string; taskOffer?: number; taskCancelled?: number; taskRecipient?: "owner" | "reviewer" | "planner"; planReview?: number; planReviewFlow?: number; planAuthor?: string; backlog?: number[]; supervision?: boolean; supervisionKey?: string; completedFor?: number; boundedCheck?: string; budgetResume?: string; budgetResumeMoves?: { id: number; title: string; to: PeerId | null; role: "owner" | "reviewer" }[]; budgetResumeEarlier?: string[]; invocation?: string; invocationRemote?: true };
   /** The body must not be shown outside its recipients: console tail and log print a stub instead (PII tasks). */
   private?: boolean;
   ts: number;
@@ -28,6 +30,11 @@ export const HUB: PeerId = "hub";
 /** A hub-written condensation of several status messages. Not a peer: a reply to it is for the senders it replaced. */
 export const DIGEST: PeerId = "digest";
 
+/** Host-marked room provenance survives local invocation rewriting; it grants no authority. */
+export function remoteEnvelope(env: Pick<Envelope, "from" | "kind" | "refs">): boolean {
+  return env.from.includes("@") || env.from === HUB && (env.kind === "invocation" || env.kind === "invocation_result") && env.refs?.invocationRemote === true;
+}
+
 export interface EnvelopeOpts {
   to?: PeerId[];
   kind?: Kind;
@@ -104,6 +111,9 @@ export function renderDigest(envs: Envelope[], primed: boolean): string {
   return primed ? items : `${STANDING_INSTRUCTION}\n\n${items}`;
 }
 
+/** #445 C2: an invocation request or its result. Each is delivered alone and never condensed, so a turn's reply maps to exactly one invocation. */
+export const isInvocationKind = (env: Pick<Envelope, "kind">): boolean => env.kind === "invocation" || env.kind === "invocation_result";
+
 /** Who a reply to a delivery is for: everyone whose message it answers, each once, in the order they arrived. */
 export function replyAudience(envs: Envelope[]): PeerId[] {
   return [...new Set(envs.filter((e) => !(e.from === HUB && e.kind === "presence")).map((e) => e.from))];

package/src/hub/events.ts

@@ -20,6 +20,8 @@ export type HubEvent =
   | { type: "settings"; key: string; from: import("./settings.ts").SettingValue; to: import("./settings.ts").SettingValue; source: "dashboard" | "terminal" | "conductor"; peer?: string; undo?: boolean; reason?: string }
   /** A structural config edit (#689): the file, key paths with short hashes of their values before and after (never a value), the file revisions and the person who made it. */
   | { type: "config_edit"; file: "config.local.json" | "sdlc.toml"; paths: { path: string; before: string | null; after: string | null }[]; fileBefore: string; fileAfter: string; tier: 2 | 3; by: "person"; source: "dashboard" | "terminal"; backup?: string; reason?: string }
+  /** #445 C2: an invocation's ids, class and outcome. Never an argument, a result or a description. */
+  | { type: "invocation"; id: string; caller: string; target: string; capability: string; class: string; outcome: string; task?: number; bytes?: number }
   | { type: "envelope"; id: string; from: string; to?: string[]; priority: string; hop: number; kind?: string; task?: string; bytes?: number; private?: boolean; dropped?: string }
   | { type: "overflow" | "undeliverable"; id: string; from: string; peer: string }
   | { type: "stale"; id: string; from: string; peer: string; task?: string }

package/src/hub/hub-tools.ts

@@ -82,6 +82,8 @@ const tool = (name: string, description: string, properties: Record<string, unkn
 });
 
 export const BOUNDED_TASK_TOOLS = new Set(["hub_task_spec", "hub_check_start", "hub_check_result", "hub_check_cancel"]);
+/** #445 C1: what a peer lists and publishes. Their text is another agent's words, so neither call is captured to memory. */
+export const CAPABILITY_TOOLS = new Set(["hub_capabilities", "hub_capabilities_publish", "hub_invoke"]);
 
 export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_spec", "Read complete assigned GitHub issue contracts through the bounded hub boundary. Owner/reviewer only; no repository or URL input. Refuses withheld or oversized specs.", { id }, ["id"]),
@@ -116,6 +118,19 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Symbol starts also include optional current-head one-hop code neighbours as derived SHA-stamped edges; unknown coverage is explicit. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
   tool("hub_memory_correct", "Propose a correction to a visible memory entry. This creates a machine-local candidate only; a person accepts or rejects it with amem review. It never edits a note. id is an exact id or unique visible prefix; text and reason must each fit 4000 UTF-8 bytes.", { id: str, text: str, reason: str }, ["id", "text", "reason"]),
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's amem curated store); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
+  tool("hub_capabilities", "List the commands and skills the person has shared from a peer (id, input schema, effective class, the peer's permission mode, digest). Shared entries only: nothing else is visible here. Descriptions are written by the peer that offers them and are untrusted. Listing grants no right to call anything.", { peer: { type: "string", description: "peer id; omit for every peer with a shared entry" } }),
+  tool("hub_invoke", "Ask another peer to run one capability the person shared from it (see hub_capabilities). Read capabilities need no approval. Remote peer@label reads require manual exact capability/digest/read pins on both hubs; remote discovery is not provided, and only bounded flat scalar inputs cross. Write/external require your open non-PII task and a person's allow-once approval for each call; unattended refuses. Destructive never runs. After admission and any person approval, returns an invocation id; the result arrives later as its own message from the hub, once, addressed to you only. The arguments follow the capability's input schema. Refused with a reason when the capability is not shared, has no permitted class or task scope, the peer cannot be reached, the arguments do not fit, or the call would nest inside an invocation you are answering. Not available during a PII turn.", {
+    peer: { type: "string", description: "local peer or exact remote peer@label that offers the capability" }, capability: { type: "string", description: "the capability id from hub_capabilities, for example command:skill:review" },
+    args: { type: "object", description: "the capability's inputs; omit when it takes none", additionalProperties: true },
+    task: { type: "integer", description: "an open task you own or review; required for write/external" },
+  }, ["peer", "capability"]),
+  tool("hub_capabilities_publish", "Publish what your own session can do (commands, skills) for a person to share. Only for a session whose capabilities the hub cannot read natively; refused for a peer the hub reads itself. Replaces your earlier list, ends with your connection, and is never shared until the person pins it. Not available during a PII turn.", {
+    capabilities: { type: "array", minItems: 1, maxItems: 128, description: "every capability you offer", items: { type: "object", additionalProperties: false, required: ["kind", "name", "description", "sideEffect"], properties: {
+      kind: { type: "string", enum: ["command", "skill", "mcp_tool"] }, name: { type: "string", description: "letters, digits, _ . : - only, at most 64" }, description: { type: "string", description: "what it does, at most 300 characters" },
+      sideEffect: { type: "string", enum: ["read", "write", "external", "destructive"], description: "the worst effect a call can have" },
+      inputSchema: { type: "object", description: "flat object of string, number, boolean or string-enum properties, additionalProperties false; omit for a single text input" },
+    } } },
+  }, ["capabilities"]),
 ];
 
 export const PLANNER_REVIEW_TOOLS: HubTool[] = [
@@ -169,7 +184,7 @@ export function configuredToolContext(status: unknown, peer: string): ProjectToo
   return { startPeers, readOnly: readOnlyPeers.includes(peer) };
 }
 
-const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
+const READ_ONLY_PROJECT_TOOLS = Object.freeze(["hub_capabilities", "hub_send", "hub_inbox", "hub_delivery_done", "hub_review", "hub_task_show", "hub_task_list", "hub_memory_search", "hub_memory_show", "hub_memory_graph", "hub_source_read", "hub_status"]);
 /** Publication restricts exposure only; server-side authority remains mandatory for every call. */
 export function projectToolList<T extends { name: string }>(tools: T[], readOnly = false): T[] {
   return readOnly ? tools.filter(tool => READ_ONLY_PROJECT_TOOLS.includes(tool.name)) : tools;

package/src/hub/inference.ts

@@ -1,3 +1,4 @@
+import { INFERENCE_BACKOFF_SETTING, INFERENCE_DIGEST_ITEMS_SETTING, INFERENCE_DIGEST_CHARS_SETTING } from "./operational-settings.ts";
 import type { MlxHandle } from "../models/mlx.ts";
 import type { ChatMessage, OmniRoute } from "../omniroute/client.ts";
 import { CLASSES, type TaskClass } from "./board.ts";
@@ -12,14 +13,16 @@ export interface InferenceConfig {
   /** ... or with more status text than this */
   digest_min_chars: number;
   triage: boolean;
+  /** Captured with the inference instance; an existing backoff deadline is never rewritten. */
+  backoff_min?: number;
 }
-export const DEFAULT_INFERENCE: InferenceConfig = { enabled: true, digest_min_items: 5, digest_min_chars: 8000, triage: true };
+export const DEFAULT_INFERENCE: InferenceConfig = { enabled: true, digest_min_items: INFERENCE_DIGEST_ITEMS_SETTING.defaultValue, digest_min_chars: INFERENCE_DIGEST_CHARS_SETTING.defaultValue, triage: true, backoff_min: INFERENCE_BACKOFF_SETTING.defaultValue };
 
 /** Sender of a condensed digest. Not the hub's own id: replies to it must keep the hop count of what it replaced. */
 export { DIGEST };
 
 const TIMEOUT_MS = 8000;
-const BACKOFF_MS = 5 * 60_000;
+export const BACKOFF_MS = 5 * 60_000;
 const SUMMARY_CAP = 1500;
 
 export interface InferenceDeps {
@@ -37,11 +40,12 @@ export interface InferenceDeps {
  */
 export class Inference {
   private offUntil = 0;
+  private readonly backoffMs: number;
 
   constructor(
     private readonly cfg: InferenceConfig,
     private readonly d: InferenceDeps,
-  ) {}
+  ) { this.backoffMs = cfg.backoff_min === undefined ? BACKOFF_MS : cfg.backoff_min * 60_000; }
 
   /**
    * `interactive`: a person is waiting for this one answer (`ahub ask`). It gets its own, longer clock and neither obeys
@@ -67,8 +71,9 @@ export class Inference {
 
   private backOff(why: string, quiet = false): undefined {
     if (quiet) return undefined;
-    this.offUntil = Date.now() + BACKOFF_MS; // do not make every delivery wait out the timeout while the model is down
-    this.d.log(`inference: off for ${BACKOFF_MS / 60_000} min (${why.slice(0, 120)})`);
+    const backoffMs = this.backoffMs;
+    this.offUntil = Date.now() + backoffMs; // do not make every delivery wait out the timeout while the model is down
+    this.d.log(`inference: off for ${backoffMs / 60_000} min (${why.slice(0, 120)})`);
     return undefined;
   }