negotium 0.19.2 → 0.20.1

package/dist/runtime/src/runtime/actor-topic-reach.ts

@@ -0,0 +1,85 @@
+import {
+  getTopic,
+  listSubagentChildTopicIds,
+  listSubagentTellTargetIds,
+} from "#storage/api-topics";
+import type { ActorTopicScope } from "#types";
+
+/**
+ * Rooms a turn may reach because of lineage this node itself recorded, not
+ * because a person is in them: a subagent's direct parent and the targets an
+ * ancestor granted it, and a room's own subagent workers.
+ *
+ * Lineage stands in for an assertion only when there is none — the turns that
+ * manage subagents (the spawn, the report back, the follow-up) are turns no
+ * person started, they carry no `actorTopicScope`, and cutting them off would
+ * break delegation the moment it began. A turn that *does* carry an assertion
+ * never gets lineage on top of it: the hub mirrors a subagent room with its
+ * parent's roster, so an owner of the parent is asserted as owner of the child
+ * and needs no exception, while a member who is not the owner — or a person
+ * speaking from a subagent room an ancestor granted rooms outside that
+ * person's own — must not inherit authority the hub did not assert.
+ * `canSubagentTellTarget` still applies its own rules on top (status-only,
+ * grants).
+ */
+export function subagentLineageTopicIds(currentTopicId: string | undefined): {
+  reachable: Set<string>;
+  children: Set<string>;
+} {
+  const reachable = new Set<string>();
+  const children = new Set<string>();
+  if (!currentTopicId) return { reachable, children };
+  const current = getTopic(currentTopicId);
+  if (current?.isSubagent && current.parentTopicId) {
+    reachable.add(current.parentTopicId);
+    for (const id of listSubagentTellTargetIds(currentTopicId)) reachable.add(id);
+  }
+  for (const id of listSubagentChildTopicIds(currentTopicId)) {
+    reachable.add(id);
+    children.add(id);
+  }
+  return { reachable, children };
+}
+
+/**
+ * The rooms cross-room tools may name for this turn.
+ *
+ * Off the `otium` surface the node owns membership, so nothing narrows the
+ * caller's own rooms. On `otium` the hub does, and its assertion is
+ * authoritative: with one, exactly the current room plus the asserted visible
+ * rooms are reachable — no lineage. Without one (an older hub, or a turn no
+ * person started) only the current room and its subagent lineage are
+ * reachable (fail-closed).
+ */
+export function actorReachableTopicIds(input: {
+  surface: string | undefined;
+  currentTopicId: string | undefined;
+  actorTopicScope: ActorTopicScope | undefined;
+}): ReadonlySet<string> | null {
+  if (input.surface !== "otium") return null;
+  const ids = new Set<string>();
+  if (input.currentTopicId) ids.add(input.currentTopicId);
+  if (input.actorTopicScope) {
+    for (const id of input.actorTopicScope.visibleNodeTopicIds) ids.add(id);
+    return ids;
+  }
+  for (const id of subagentLineageTopicIds(input.currentTopicId).reachable) ids.add(id);
+  return ids;
+}
+
+/**
+ * Rooms the actor may abort/restart/delete. With an assertion: exactly the
+ * rooms the hub says the actor owns (a parent's subagent workers are among
+ * them only if the hub asserted so). Without one: the current room's own
+ * subagent workers (a room controls what it delegated), nothing else. Same
+ * surface rule as {@link actorReachableTopicIds}.
+ */
+export function actorOwnedTopicIds(input: {
+  surface: string | undefined;
+  currentTopicId?: string | undefined;
+  actorTopicScope: ActorTopicScope | undefined;
+}): ReadonlySet<string> | null {
+  if (input.surface !== "otium") return null;
+  if (input.actorTopicScope) return new Set(input.actorTopicScope.ownedNodeTopicIds);
+  return subagentLineageTopicIds(input.currentTopicId).children;
+}

package/dist/runtime/src/runtime/actor-topic-scope.ts

@@ -0,0 +1,175 @@
+import type { ActorTopicScope } from "#types";
+
+/**
+ * Hard caps on a hub-supplied room assertion.
+ *
+ * The assertion is not stored and forgotten: it rides the signed per-turn MCP
+ * token, which every hosted built-in MCP server receives in the URL query
+ * (`?token=`) of an `http://127.0.0.1` request, and — with
+ * `NEGOTIUM_BUILTIN_MCP_TRANSPORT=stdio` — one base64url argv entry of the
+ * session-comm child. The transport, not the database, is the tight bound:
+ *
+ * - `Bun.serve` answers 431 once the request line is too long (Bun 1.3.14:
+ *   a 16,205-character URL is served, 16,305 is refused). These caps alone
+ *   do not bound the URL — the token carries other fields — so the whole URL
+ *   is budgeted at `MCP_URL_BUDGET_CHARS` (14 KiB) in `runtime-spec.ts`,
+ *   where the numbers live. The 8 KiB assertion below becomes 10,924
+ *   base64url characters at most; with every other runtime-token field at
+ *   its largest (the prompt itself is not in the token — only the derived
+ *   `explicitAgentSwitchTargets`, at most three agent names) the URL is
+ *   ≤ ~13.4 KB.
+ * - argv: `encodeActorTopicScopeArg` is the assertion alone, ≤ 10,924
+ *   characters, far below Linux `MAX_ARG_STRLEN` (128 KiB) for one argument
+ *   and macOS `ARG_MAX` (1 MiB) overall. The encoder re-validates before it
+ *   encodes, so an in-process caller that bypassed the gateway parser cannot
+ *   put an unbounded object into argv either.
+ *
+ * With UUID room ids (39 bytes each serialized) the byte cap admits roughly
+ * 208 ids across both lists; the per-list count cap bounds the work done on
+ * an assertion before its size is known, and the id length cap keeps a single
+ * id from being the whole budget. Raising these means moving the assertion
+ * out of the token (server-side per-turn context), not editing the numbers.
+ */
+export const ACTOR_TOPIC_SCOPE_LIMITS = Object.freeze({
+  /** Ids per list, counted before de-duplication. */
+  maxIdsPerList: 200,
+  /** Characters per id, after trimming. */
+  maxIdLength: 128,
+  /** UTF-8 bytes of the normalized assertion as JSON. */
+  maxSerializedBytes: 8 * 1024,
+});
+
+const SCOPE_KEYS = ["visibleNodeTopicIds", "ownedNodeTopicIds"] as const;
+
+export type ActorTopicScopeValidation =
+  | { ok: true; scope: ActorTopicScope | undefined }
+  | { ok: false; error: string };
+
+function idList(value: unknown, name: string): string[] | string {
+  if (!Array.isArray(value)) return `${name} must be an array of topic ids`;
+  if (value.length > ACTOR_TOPIC_SCOPE_LIMITS.maxIdsPerList) {
+    return `${name} has ${value.length} ids; at most ${ACTOR_TOPIC_SCOPE_LIMITS.maxIdsPerList} are allowed`;
+  }
+  const ids = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") return `${name} must contain only strings`;
+    const id = item.trim();
+    if (!id) return `${name} must not contain empty ids`;
+    if (id.length > ACTOR_TOPIC_SCOPE_LIMITS.maxIdLength) {
+      return `${name} contains an id longer than ${ACTOR_TOPIC_SCOPE_LIMITS.maxIdLength} characters`;
+    }
+    ids.add(id);
+  }
+  return [...ids];
+}
+
+/**
+ * Validate a hub-supplied room assertion and say why it failed.
+ *
+ * `undefined` in means `undefined` out (no assertion, fail-closed downstream);
+ * anything else must be exactly `{ visibleNodeTopicIds, ownedNodeTopicIds }`
+ * — a plain object with those two own keys and nothing else (so a stray
+ * `__proto__` or `constructor` key is a rejection, not a property), each a
+ * list of non-empty strings within {@link ACTOR_TOPIC_SCOPE_LIMITS} — or it is
+ * rejected, so a malformed assertion can never be read as "everything".
+ */
+export function validateActorTopicScope(value: unknown): ActorTopicScopeValidation {
+  if (value === undefined) return { ok: true, scope: undefined };
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {
+      ok: false,
+      error:
+        "actorTopicScope must be { visibleNodeTopicIds: string[], ownedNodeTopicIds: string[] }",
+    };
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    return { ok: false, error: "actorTopicScope must be a plain object" };
+  }
+  const keys = Object.keys(value);
+  const unknown = keys.filter((key) => !(SCOPE_KEYS as readonly string[]).includes(key));
+  if (unknown.length || keys.length !== SCOPE_KEYS.length) {
+    return {
+      ok: false,
+      error: unknown.length
+        ? `actorTopicScope has unexpected key(s): ${unknown.join(", ")}`
+        : "actorTopicScope must have both visibleNodeTopicIds and ownedNodeTopicIds",
+    };
+  }
+  const record = value as Record<string, unknown>;
+  const visible = idList(record.visibleNodeTopicIds, "actorTopicScope.visibleNodeTopicIds");
+  if (typeof visible === "string") return { ok: false, error: visible };
+  const owned = idList(record.ownedNodeTopicIds, "actorTopicScope.ownedNodeTopicIds");
+  if (typeof owned === "string") return { ok: false, error: owned };
+  const scope: ActorTopicScope = { visibleNodeTopicIds: visible, ownedNodeTopicIds: owned };
+  const bytes = Buffer.byteLength(JSON.stringify(scope), "utf-8");
+  if (bytes > ACTOR_TOPIC_SCOPE_LIMITS.maxSerializedBytes) {
+    return {
+      ok: false,
+      error: `actorTopicScope is ${bytes} bytes serialized; at most ${ACTOR_TOPIC_SCOPE_LIMITS.maxSerializedBytes} are allowed`,
+    };
+  }
+  return { ok: true, scope };
+}
+
+/**
+ * Validate a hub-supplied room assertion.
+ *
+ * `undefined` in means `undefined` out (no assertion, fail-closed downstream);
+ * anything else must pass {@link validateActorTopicScope} or it is rejected
+ * with `null`. Every path an assertion can enter by — the gateway body, the
+ * signed MCP tokens, the stdio argv — goes through this one parser, so the
+ * limits cannot drift between them.
+ */
+export function parseActorTopicScope(value: unknown): ActorTopicScope | undefined | null {
+  const validated = validateActorTopicScope(value);
+  return validated.ok ? validated.scope : null;
+}
+
+export function isActorTopicScope(value: unknown): value is ActorTopicScope {
+  return parseActorTopicScope(value) != null;
+}
+
+/**
+ * Read a validated assertion out of a persisted or signed context. Anything
+ * that does not validate collapses to "no assertion" rather than throwing, so
+ * a stale row cannot break a turn — it only narrows it to what a turn without
+ * an assertion reaches: the current room plus its own subagent lineage.
+ */
+export function actorTopicScopeFrom(value: unknown): ActorTopicScope | undefined {
+  return parseActorTopicScope(value) ?? undefined;
+}
+
+/**
+ * The strictest assertion two requests agree on: an id is kept only when both
+ * assert it, and a request without an assertion leaves the result without one
+ * (fail-closed). Used when several pending requests of one actor fold into a
+ * single turn, so the merged turn never reaches a room one of them could not.
+ */
+export function intersectActorTopicScopes(
+  scopes: ReadonlyArray<ActorTopicScope | undefined>,
+): ActorTopicScope | undefined {
+  if (scopes.length === 0 || scopes.some((scope) => scope === undefined)) return undefined;
+  const [first, ...rest] = scopes as ActorTopicScope[];
+  const keep = (key: keyof ActorTopicScope) =>
+    first[key].filter((id) => rest.every((scope) => scope[key].includes(id)));
+  return {
+    visibleNodeTopicIds: keep("visibleNodeTopicIds"),
+    ownedNodeTopicIds: keep("ownedNodeTopicIds"),
+  };
+}
+
+/**
+ * Argv-safe encoding for the stdio session-comm server (`--actor-topic-scope=`).
+ * Bounded by {@link ACTOR_TOPIC_SCOPE_LIMITS}: 8,192 bytes of JSON become at
+ * most 10,924 base64url characters, see there. The input is put through
+ * {@link validateActorTopicScope} first and an invalid or oversized assertion
+ * throws — it is never truncated (which would narrow the turn silently) nor
+ * passed on (which would let a typed in-process caller overflow argv).
+ */
+export function encodeActorTopicScopeArg(scope: ActorTopicScope): string {
+  const validated = validateActorTopicScope(scope);
+  if (!validated.ok) throw new Error(validated.error);
+  if (!validated.scope) throw new Error("actorTopicScope is required");
+  return Buffer.from(JSON.stringify(validated.scope), "utf-8").toString("base64url");
+}

package/dist/runtime/src/runtime/ask-callbacks.ts

@@ -9,7 +9,12 @@
  * (the ask/tell REST routes stayed in the host).
  */
 
-import { deliverPeerReply, type RemoteReplyRoute } from "#mcp/session-comm/peer-forward";
+import {
+  deliverPeerReply,
+  isHubRemoteReplyRoute,
+  parseHubRemoteReplyRoute,
+  type RemoteReplyRoute,
+} from "#mcp/session-comm/peer-forward";
 import { db } from "#storage/forum-db";
 import { PENDING_ASK_TTL_MS, type PendingAskUserId } from "#storage/session-asks";
 import { registerStorageSchemaInitializer } from "#storage/storage-host";
@@ -31,6 +36,13 @@ registerStorageSchemaInitializer((database) => {
       created_at INTEGER NOT NULL
     )
   `);
+  // Hub-routed asks keep their whole route here; the legacy columns are
+  // blank for them. Added after the table existed, so guarded.
+  try {
+    database.exec("ALTER TABLE remote_ask_callbacks ADD COLUMN route_json TEXT");
+  } catch {
+    // Column already present.
+  }
 });
 
 interface PendingAskIdentity {
@@ -65,25 +77,29 @@ const MAX_ASK_AGE_MS = PENDING_ASK_TTL_MS;
 export function registerAskCallback(entry: AskPending): void {
   pendingAsks.set(entry.targetQueryId, entry);
   if (entry.remoteReply) {
+    const route = entry.remoteReply;
+    const hub = isHubRemoteReplyRoute(route);
     db.query(
       `INSERT INTO remote_ask_callbacks
-       (target_query_id, request_id, node_name, node_cell_id, topic_id, user_id, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)
+       (target_query_id, request_id, node_name, node_cell_id, topic_id, user_id, created_at, route_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
        ON CONFLICT(target_query_id) DO UPDATE SET
          request_id = excluded.request_id,
          node_name = excluded.node_name,
          node_cell_id = excluded.node_cell_id,
          topic_id = excluded.topic_id,
          user_id = excluded.user_id,
-         created_at = excluded.created_at`,
+         created_at = excluded.created_at,
+         route_json = excluded.route_json`,
     ).run(
       entry.targetQueryId,
-      entry.remoteReply.requestId,
-      entry.remoteReply.nodeName,
-      entry.remoteReply.nodeCellId,
-      entry.remoteReply.topicId,
-      entry.remoteReply.userId,
+      route.requestId,
+      route.nodeName,
+      hub ? "" : route.nodeCellId,
+      route.topicId,
+      hub ? "" : route.userId,
       entry.createdAt,
+      hub ? JSON.stringify(route) : null,
     );
   }
 }
@@ -99,10 +115,23 @@ export function resolveAskCallback(queryId: string): AskPending | null {
     entry.timedOut = true;
   }
   pendingAsks.delete(queryId);
-  db.query("DELETE FROM remote_ask_callbacks WHERE target_query_id = ?").run(queryId);
+  // A hub-routed callback keeps its durable row until the answer is in the
+  // reply outbox: `deliverHubRemoteReply` deletes it in the same transaction
+  // as the outbox insert, so a crash between resolve and enqueue still leaves
+  // the row for the startup pass to fail explicitly instead of losing both.
+  if (!entry.remoteReply || !isHubRemoteReplyRoute(entry.remoteReply)) {
+    db.query("DELETE FROM remote_ask_callbacks WHERE target_query_id = ?").run(queryId);
+  }
   return entry;
 }
 
+/** The hub-routed answer is durably queued: the callback row has served its purpose. */
+export function deleteHubRemoteAskCallbackRow(requestId: string): void {
+  db.query("DELETE FROM remote_ask_callbacks WHERE request_id = ? AND route_json IS NOT NULL").run(
+    requestId,
+  );
+}
+
 /** Clean up stale asks that outlived their TTL (periodic, lightweight). */
 export function purgeStaleAsks(now: number = Date.now()): void {
   for (const [id, entry] of pendingAsks) {
@@ -130,28 +159,52 @@ interface DurableRemoteAskCallbackRow {
   node_cell_id: string;
   topic_id: string;
   user_id: string;
+  route_json: string | null;
+}
+
+function durableRoute(row: DurableRemoteAskCallbackRow): RemoteReplyRoute | null {
+  if (row.route_json) {
+    try {
+      return parseHubRemoteReplyRoute(JSON.parse(row.route_json));
+    } catch {
+      return null;
+    }
+  }
+  return {
+    nodeName: row.node_name,
+    nodeCellId: row.node_cell_id,
+    topicId: row.topic_id,
+    userId: row.user_id,
+    requestId: row.request_id,
+  };
 }
 
 /** Fail remote asks whose target turn was interrupted by the previous process.
- *  Call once during startup after the peer session bridge is registered. */
-export async function failInterruptedRemoteAskCallbacks(): Promise<number> {
+ *  Call once during startup after the peer session bridge is registered.
+ *  `routes: "hub"` limits the pass to hub-routed asks, which need no adapter
+ *  bridge and are therefore failed by the node itself at startup. */
+export async function failInterruptedRemoteAskCallbacks(
+  options: { routes?: "all" | "hub" } = {},
+): Promise<number> {
   const rows = db
     .query(
-      `SELECT target_query_id, request_id, node_name, node_cell_id, topic_id, user_id
+      `SELECT target_query_id, request_id, node_name, node_cell_id, topic_id, user_id, route_json
        FROM remote_ask_callbacks
        ORDER BY created_at ASC`,
     )
     .all() as DurableRemoteAskCallbackRow[];
   let failed = 0;
   for (const row of rows) {
+    const route = durableRoute(row);
+    if (!route) {
+      db.query("DELETE FROM remote_ask_callbacks WHERE target_query_id = ?").run(
+        row.target_query_id,
+      );
+      continue;
+    }
+    if (options.routes === "hub" && !isHubRemoteReplyRoute(route)) continue;
     const delivered = await deliverPeerReply(
-      {
-        nodeName: row.node_name,
-        nodeCellId: row.node_cell_id,
-        topicId: row.topic_id,
-        userId: row.user_id,
-        requestId: row.request_id,
-      },
+      route,
       "peer",
       "The remote worker restarted before this ask completed. Please retry the request.",
       "error",

package/dist/runtime/src/runtime/bashrs-completions.ts

@@ -20,6 +20,7 @@
 
 import {
   closeSync,
+  existsSync,
   openSync,
   readdirSync,
   readFileSync,
@@ -236,6 +237,11 @@ export async function flushBashrsCompletions(): Promise<void> {
       continue;
     }
 
+    // Another consumer of the same spill dir (a node and an embedding host can
+    // both hold leadership, each under its own lease store) may have finished
+    // this job between our read and now. Nothing left to deliver.
+    if (!existsSync(resultPath)) continue;
+
     try {
       // The stable bash_id is carried through so at-least-once delivery on
       // either side — this watcher crashing before the rename, or the sink's
@@ -246,7 +252,19 @@ export async function flushBashrsCompletions(): Promise<void> {
         bashId: result.bash_id,
         message: buildMessage(dir, result),
       });
-      renameSync(resultPath, marker);
+      try {
+        renameSync(resultPath, marker);
+      } catch (renameErr) {
+        // ENOENT here means a concurrent consumer already marked the job
+        // delivered (the sink collapses the duplicate by bash_id). That is the
+        // success state, not a failure to retry.
+        if ((renameErr as NodeJS.ErrnoException).code !== "ENOENT") throw renameErr;
+        logger.debug(
+          { bashId: result.bash_id },
+          "bashrs-completions: already delivered by another consumer",
+        );
+        continue;
+      }
       logger.info(
         { bashId: result.bash_id, userId: parsed.userId, topicId: parsed.topicId },
         "bashrs-completions: delivered",

package/dist/runtime/src/runtime/gateway-capabilities.ts

@@ -0,0 +1,22 @@
+/**
+ * Extra `GET /health` capability strings contributed by whatever is loaded
+ * alongside the node — an adapter that forwards a new gateway route over its
+ * relay, for instance. The core route list is fixed in `control.ts`; this
+ * registry lets a host advertise a capability only when the piece that makes
+ * it true is actually present, so a hub can tell "the node supports it" from
+ * "the node *and* its relay support it".
+ */
+const registered = new Set<string>();
+
+export function registerRuntimeGatewayCapability(name: string): () => void {
+  const capability = name.trim();
+  if (!capability) throw new Error("capability name is required");
+  registered.add(capability);
+  return () => {
+    registered.delete(capability);
+  };
+}
+
+export function listRuntimeGatewayCapabilities(): string[] {
+  return [...registered].sort();
+}