@fitchmultz/pi-subagents 0.47.0 → 0.49.0

package/docs/intercom.md

@@ -605,7 +605,7 @@ Assistant-error replies wait for broker acknowledgement during `message_end`, bo
 Historical official Pi 0.87.1 checks exposed queue visibility and prompt-preparation races. Current tests preserve exact-once receipts and input rejection/recovery on the selected host, including the genuine Pi 1.0 pre-admission window described above; they do not promise one combined provider turn. Historical results are not a current 1.0 pass. Use an explicit `async: false` wait when dependent work needs a finalized result. Native pending-call, idle-checkpoint and immediate-usage APIs are no longer supported. See [result delivery](reference.md#host-capabilities-and-result-delivery) and [local qualification](development.md#local-validation).
 
 - **Same machine only** — The core broker uses local Unix sockets, no network support. The optional [secure remote bridge](intercom-bridge.md) authenticates remote messaging through a separate loopback mTLS proxy; it does not expose the broker socket.
-- **No dedicated intercom log** — Messages are kept in Pi session history, but there is no separate intercom transcript or inbox
+- **No dedicated local intercom log** — Messages are kept in Pi session history. The optional remote bridge has its own durable mailbox and recent-transcript API; the local peer tool has no separate inbox.
 - **No attachments UI** — `file`, `snippet`, and `context` attachments are supported in the protocol, but not in the compose overlay
 - **Only connected sessions appear** — The list shows Pi sessions that have loaded `pi-intercom` and successfully registered with the broker, not every open Pi process on the machine
 - **Broker lifecycle** — The broker auto-spawns on first use and exits when idle; sessions reconnect automatically if the broker restarts

package/docs/reference.md

@@ -375,7 +375,7 @@ The files in `prompts/` document common workflows without registering additional
 
 ## Bundled intercom
 
-For a remote agent on Linux, the optional [secure remote bridge](intercom-bridge.md) provides a loopback-only mTLS HTTPS API over an SSH reverse forward. It registers a certificate-bound peer such as `grok-bot` and supports messaging and optional locally pinned, name-only starts of persistent Pi sessions on the destination machine; the private Unix broker socket remains local. The guide includes setup, remote start/sessions/stop commands, lifecycle limits, credential rotation and revocation.
+For an authenticated remote agent, the optional [secure remote bridge](intercom-bridge.md) provides a loopback-only mTLS HTTPS API carried by Tailscale TCP forwarding or an SSH reverse forward. It supports unattended messaging, durable mailboxes and wake notifications, named groups, live/saved session discovery, workspace/model-aware spawn, resume by stable ID or unique name, recent transcripts and native stop/cancel controls. The private Unix broker socket remains local. The guide explains setup, full credential authority, native host limits, safe updates, rotation and revocation.
 
 The same `pi-subagents` install registers the intercom extension and skill. `load_intercom({})` exposes the full peer tool explicitly; actionable peer inbound and recovered reply needs also expose it before use. Presence, passive breadcrumbs, routine subagent notices, and human messages answered in chat do not. Broker presence and delivery continue even with the schema hidden. Managed children get a private coordination channel back to the parent Pi session unless an explicit agent extension allowlist excludes it. See [the intercom guide](intercom.md) for direct peer messaging, keyboard UI, tool actions, configuration, and broker details.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",

package/scripts/intercom-bridge-wake-preflight.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { readBridgeFile, writeBridgeJson } from "../src/pi-intercom/bridge-files.ts";
+import { stateDirectory } from "../src/pi-intercom/bridge-storage.ts";
+import { isRecord } from "../src/shared/unknown.ts";
+
+// Run only after proving this history covers every legacy worker and stopping those workers.
+// --complete-since is the operator's coverage attestation, not something outcomes can prove.
+const { values } = parseArgs({
+  options: {
+    "state-dir": { type: "string" },
+    audit: { type: "string" },
+    "complete-since": { type: "string" },
+    "stopped-at": { type: "string" },
+    "stopped-pid": { type: "string" },
+    "unknown-attempts": { type: "string" },
+  },
+});
+try {
+  const stateDir = stateDirectory(values["state-dir"]);
+  const coveredSince = Date.parse(values["complete-since"] ?? "");
+  const stoppedAt = Date.parse(values["stopped-at"] ?? "");
+  const pid = Number(values["stopped-pid"]);
+  const unknownAttempts = Number(values["unknown-attempts"]);
+  if (
+    stateDir === undefined ||
+    values.audit === undefined ||
+    !Number.isSafeInteger(coveredSince) ||
+    !Number.isSafeInteger(stoppedAt) ||
+    coveredSince > stoppedAt - 3600000 ||
+    stoppedAt > Date.now() ||
+    !Number.isSafeInteger(pid) ||
+    pid <= 0 ||
+    values["unknown-attempts"] === undefined ||
+    !Number.isInteger(unknownAttempts) ||
+    unknownAttempts < 0 ||
+    unknownAttempts > 20
+  ) {
+    throw new Error(
+      "Require state-dir, private audit, complete-since (at least one hour before stopped-at), stopped-at, stopped-pid and unknown-attempts (0..20).",
+    );
+  }
+  try {
+    process.kill(pid, 0);
+    throw new Error("Legacy helper is still running; stop it before preflight.");
+  } catch (error) {
+    if (error.code !== "ESRCH") {
+      throw error;
+    }
+  }
+  if (
+    existsSync(join(stateDir, "wake-quota.sqlite")) ||
+    existsSync(join(stateDir, "wake-history.json"))
+  ) {
+    throw new Error("Preflight cannot replace an existing ledger/history. Preserve it.");
+  }
+  const attempts = [];
+  const outcomes = new Set(["accepted", "http_rejected", "transport_unconfirmed"]);
+  const audit = readBridgeFile(values.audit, true, 32 * 1024 * 1024).toString("utf8");
+  for (const line of audit.split("\n")) {
+    if (line.trim() === "") {
+      continue;
+    }
+    /** @type {unknown} */
+    const raw = JSON.parse(line);
+    if (!isRecord(raw) || typeof raw.timestamp !== "string") {
+      throw new Error("Invalid audit record.");
+    }
+    const entry = raw;
+    const timestamp = Date.parse(entry.timestamp);
+    if (!Number.isSafeInteger(timestamp)) {
+      throw new Error("Audit record has no valid timestamp.");
+    }
+    if (timestamp < coveredSince || timestamp > stoppedAt) {
+      continue;
+    }
+    if (entry.event === "log_overflow") {
+      throw new Error(
+        "Audit overflow prevents complete-history migration; use conservative startup.",
+      );
+    }
+    if (
+      entry.event === "wake_delivery" &&
+      typeof entry.result === "string" &&
+      outcomes.has(entry.result)
+    ) {
+      attempts.push(timestamp);
+    }
+  }
+  if (attempts.length > 10000) {
+    throw new Error("Attempt history exceeds bounded migration input.");
+  }
+  writeBridgeJson(join(stateDir, "wake-history.json"), {
+    coveredSince,
+    stoppedAt,
+    attempts,
+    unknownAttempts,
+  });
+  console.log(
+    JSON.stringify({
+      result: "prepared",
+      recordedAttempts: attempts.length,
+      unknownAttempts,
+      note: "Start the new helper against this same stateDir; never copy/reset its ledger. Coverage and unknown-attempt bounds remain operator-owned proof.",
+    }),
+  );
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/scripts/intercom-remote.mjs

@@ -4,7 +4,7 @@ import { lstatSync, readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 
 function help() {
-  console.log(`Usage: node intercom-remote.mjs <register|list|inbox|send|ask|reply|ack|start|sessions|stop> [options] [IDs...]
+  console.log(`Usage: node intercom-remote.mjs <register|list|inbox|send|ask|reply|ack|start|spawn|resume|sessions|stop|cancel|capabilities|transcript|groups|group-upsert|broadcast|group-send> [options] [IDs...]
 
 Environment (required):
   INTERCOM_BRIDGE_CA    Path to trusted bridge CA certificate
@@ -13,14 +13,30 @@ Environment (required):
   INTERCOM_BRIDGE_URL   HTTPS origin (default: https://127.0.0.1:9443)
 
 Options:
-  --to PEER            Recipient name or ID for send/ask
+  --to PEER            Recipient name, peer ID or native ID for messages/controls
   --message TEXT       Message for send/ask/reply
+  --id ID              Send only: exact message ID (default: random; no deduplication guarantee)
+  --passive            Send only: mailbox delivery without waking the recipient
   --reply-to ID        Inbound ask ID from inbox, for reply
-  --timeout-ms MS      Ask timeout (100..120000, default: 120000)
+  --timeout-ms MS      Ask: 100..120000 (default 120000); control: 100..10000 (default 3000)
   --after CURSOR       Inbox cursor from nextCursor (default: 0)
-  --limit COUNT        Inbox page size (1..256, default: 256)
+  --wait-ms MS         Inbox: wait for new mail, 0..10000 (default: 0)
+  --limit COUNT        Inbox: 1..256; sessions/transcript: 1..100
   --name NAME          Start/reuse a named idle Pi session under local policy
-  --session-id ID      Stop only a Pi session launched by this identity/helper
+  --session-id ID      Native ID for resume, stop or cancel
+  --target ID_OR_NAME  Unique target for resume, stop, cancel or transcript
+  --cwd PATH           Spawn in an existing locally approved workspace
+  --task TEXT          Submit an Intercom task after spawn/resume readiness
+  --model PROVIDER/ID  Exact spawn model; or --provider NAME with --model ID
+  --mode cancel|kill   Stop mode: owned kill observes exit; foreign kill requests shutdown
+  --live --saved       Opt into live/saved session metadata
+  --q TEXT --offset N  Catalog filter and page cursor
+  --max-bytes N        Transcript UTF-8 text budget (256..131072)
+  --cursor CURSOR      Opaque cursor from an earlier transcript page
+  --group NAME         Named group for broadcast/group-send
+  --members JSON       Group members as a JSON array of IDs/names
+  --name-pattern GLOB  Dynamic group name selector
+  --cwd-pattern GLOB   Dynamic group cwd selector (combined with name pattern)
   -h, --help           Show help
 
 Examples:
@@ -31,7 +47,10 @@ Examples:
   node intercom-remote.mjs reply --reply-to QUESTION_ID --message 'Proceed.'
   node intercom-remote.mjs ack MESSAGE_ID
   node intercom-remote.mjs start --name planner
-  node intercom-remote.mjs sessions
+  node intercom-remote.mjs spawn --name planner --cwd /project --task 'Review this project.'
+  node intercom-remote.mjs sessions --live --saved
+  node intercom-remote.mjs resume --name saved-unique-name
+  node intercom-remote.mjs transcript --target NATIVE_SESSION_ID
   node intercom-remote.mjs stop --session-id NATIVE_SESSION_ID
 
 Outputs JSON. Exit: 0 success, 1 API/TLS/transport failure, 2 invalid arguments.
@@ -39,25 +58,24 @@ No automatic retries: a lost response does not prove a message was unsent.`);
 }
 
 function allowedOptions(action) {
-  if (action === "inbox") {
-    return ["after", "limit"];
-  }
-  if (action === "start") {
-    return ["name"];
-  }
-  if (action === "stop") {
-    return ["session-id"];
-  }
-  if (action === "send") {
-    return ["to", "message"];
-  }
-  if (action === "ask") {
-    return ["to", "message", "timeout-ms"];
-  }
-  if (action === "reply") {
-    return ["reply-to", "message"];
-  }
-  return [];
+  const fields = {
+    inbox: ["after", "limit", "wait-ms"],
+    start: ["name"],
+    spawn: ["name", "cwd", "task", "provider", "model"],
+    resume: ["session-id", "name", "target", "task"],
+    stop: ["session-id", "target", "to", "mode", "timeout-ms"],
+    cancel: ["session-id", "target", "to", "timeout-ms"],
+    sessions: ["live", "saved", "q", "offset", "limit"],
+    capabilities: ["to", "target", "timeout-ms"],
+    transcript: ["to", "target", "timeout-ms", "limit", "max-bytes", "cursor"],
+    broadcast: ["message", "group"],
+    "group-send": ["message", "group"],
+    "group-upsert": ["name", "members", "name-pattern", "cwd-pattern"],
+    send: ["to", "message", "passive", "id"],
+    ask: ["to", "message", "timeout-ms"],
+    reply: ["reply-to", "message"],
+  };
+  return fields[action] ?? [];
 }
 
 function requireMessage(recipient, message) {
@@ -71,15 +89,101 @@ function requireMessage(recipient, message) {
   }
 }
 
+function sendId(id) {
+  // Match the bridge's label bounds without changing the caller's ID.
+  // oxlint-disable-next-line no-control-regex
+  const controls = /[\u0000-\u001f\u007f-\u009f]/;
+  if (id !== undefined && (id.trim() === "" || id.length > 512 || controls.test(id))) {
+    throw new Error("Invalid message ID.");
+  }
+  return id;
+}
+
+function resumeBody(options) {
+  if (["name", "session-id", "target"].filter((key) => options[key] !== undefined).length !== 1) {
+    throw new Error("Resume requires exactly one --name, --session-id or --target.");
+  }
+  return {
+    name: options.name,
+    sessionId: options["session-id"],
+    target: options.target,
+    task: options.task,
+  };
+}
+function stopBody(action, options) {
+  if (["session-id", "target", "to"].filter((key) => options[key] !== undefined).length !== 1) {
+    throw new Error("Choose exactly one --session-id, --target or --to.");
+  }
+  return {
+    target: options["session-id"] ?? options.target ?? options.to,
+    mode: action === "stop" ? options.mode : undefined,
+    timeoutMs: controlTimeout(options),
+  };
+}
 function launchBody(action, options) {
-  const value = action === "start" ? options.name : options["session-id"];
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(action === "start" ? "--name is required." : "--session-id is required.");
+  if (action === "resume") {
+    return resumeBody(options);
+  }
+  if (action === "stop" || action === "cancel") {
+    return stopBody(action, options);
+  }
+  if (typeof options.name !== "string" || options.name.trim() === "") {
+    throw new Error("--name is required.");
   }
-  return action === "start" ? { name: value } : { sessionId: value };
+  return action === "start"
+    ? { name: options.name }
+    : {
+        name: options.name,
+        cwd: options.cwd,
+        task: options.task,
+        provider: options.provider,
+        model: options.model,
+      };
+}
+function controlTimeout(options) {
+  const timeoutMs = options["timeout-ms"] === undefined ? 3000 : Number(options["timeout-ms"]);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 10000) {
+    throw new Error("Control --timeout-ms must be 100..10000.");
+  }
+  return timeoutMs;
+}
+function extraBody(action, options) {
+  if (["capabilities", "transcript"].includes(action)) {
+    if (["to", "target"].filter((key) => options[key] !== undefined).length !== 1) {
+      throw new Error("Choose exactly one --to or --target.");
+    }
+    return {
+      to: options.to ?? options.target,
+      timeoutMs: controlTimeout(options),
+      ...(action === "transcript" ? transcriptBody(options) : {}),
+    };
+  }
+  if (action === "group-upsert") {
+    return {
+      name: options.name,
+      members: options.members === undefined ? undefined : JSON.parse(options.members),
+      namePattern: options["name-pattern"],
+      cwdPattern: options["cwd-pattern"],
+    };
+  }
+  if (action === "broadcast" || action === "group-send") {
+    requireMessage(action === "group-send" ? options.group : "all", options.message);
+    return { message: options.message, group: options.group };
+  }
+}
+function transcriptBody(options) {
+  return {
+    limit: options.limit === undefined ? undefined : Number(options.limit),
+    maxBytes: options["max-bytes"] === undefined ? undefined : Number(options["max-bytes"]),
+    cursor: options.cursor,
+  };
 }
 function requestBody(action, options, ids, timeout) {
-  if (action === "start" || action === "stop") {
+  const extra = extraBody(action, options);
+  if (extra !== undefined) {
+    return extra;
+  }
+  if (["start", "spawn", "resume", "stop", "cancel"].includes(action)) {
     return launchBody(action, options);
   }
   if (["send", "ask", "reply"].includes(action)) {
@@ -91,7 +195,9 @@ function requestBody(action, options, ids, timeout) {
     return {
       to: recipient,
       message: options.message,
+      messageId: sendId(options.id),
       ...(action === "ask" ? { timeoutMs: timeout } : {}),
+      ...(options.passive === true ? { passive: true } : {}),
     };
   }
   if (action === "ack") {
@@ -128,31 +234,70 @@ function privateKey(path) {
 function inboxQuery(options) {
   const after = options.after ?? "0";
   const limit = options.limit ?? "256";
+  const waitMs = options["wait-ms"] ?? "0";
   if (
     !/^(0|[1-9]\d{0,15})$/.test(after) ||
     !Number.isSafeInteger(Number(after)) ||
     !/^[1-9]\d{0,2}$/.test(limit) ||
-    Number(limit) > 256
+    Number(limit) > 256 ||
+    !/^(0|[1-9]\d{0,3}|10000)$/.test(waitMs)
   ) {
-    throw new Error("--after must be a nonnegative safe integer cursor; --limit must be 1..256.");
+    throw new Error(
+      "--after must be a nonnegative safe integer cursor; --limit must be 1..256; --wait-ms must be 0..10000.",
+    );
+  }
+  const query = new URLSearchParams({ after, limit });
+  if (options["wait-ms"] !== undefined) {
+    query.set("waitMs", waitMs);
   }
-  return new URLSearchParams({ after, limit }).toString();
+  return query.toString();
+}
+
+function requestQuery(action, options) {
+  if (action === "inbox") {
+    return inboxQuery(options);
+  }
+  return action === "sessions"
+    ? new URLSearchParams(
+        Object.entries(options).map(([key, value]) => [key, String(value)]),
+      ).toString()
+    : "";
 }
 
 let body, action, origin, timeout, query;
 try {
   const parsed = parseArgs({
     allowPositionals: true,
+    tokens: true,
     options: {
       help: { type: "boolean", short: "h" },
       to: { type: "string" },
       message: { type: "string" },
+      id: { type: "string" },
+      passive: { type: "boolean" },
       "reply-to": { type: "string" },
       "timeout-ms": { type: "string" },
       after: { type: "string" },
+      "wait-ms": { type: "string" },
       limit: { type: "string" },
       name: { type: "string" },
       "session-id": { type: "string" },
+      cwd: { type: "string" },
+      target: { type: "string" },
+      mode: { type: "string" },
+      provider: { type: "string" },
+      model: { type: "string" },
+      task: { type: "string" },
+      live: { type: "boolean" },
+      saved: { type: "boolean" },
+      q: { type: "string" },
+      offset: { type: "string" },
+      group: { type: "string" },
+      members: { type: "string" },
+      "name-pattern": { type: "string" },
+      "cwd-pattern": { type: "string" },
+      "max-bytes": { type: "string" },
+      cursor: { type: "string" },
     },
   });
   if (parsed.values.help) {
@@ -160,6 +305,13 @@ try {
     process.exit(0);
   }
   const options = parsed.values;
+  for (const name of ["wait-ms", "id"]) {
+    if (
+      parsed.tokens.filter((token) => token.kind === "option" && token.name === name).length > 1
+    ) {
+      throw new Error(`--${name} must not be repeated.`);
+    }
+  }
   [action] = parsed.positionals;
   if (
     ![
@@ -171,8 +323,17 @@ try {
       "reply",
       "ack",
       "start",
+      "spawn",
+      "resume",
       "sessions",
       "stop",
+      "cancel",
+      "capabilities",
+      "transcript",
+      "groups",
+      "group-upsert",
+      "broadcast",
+      "group-send",
     ].includes(action)
   ) {
     throw new Error("Choose an action; use --help.");
@@ -189,7 +350,7 @@ try {
     throw new Error("--timeout-ms must be 100..120000.");
   }
   body = requestBody(action, options, parsed.positionals.slice(1), timeout);
-  query = action === "inbox" ? inboxQuery(options) : "";
+  query = requestQuery(action, options);
   origin = new URL(process.env.INTERCOM_BRIDGE_URL || "https://127.0.0.1:9443");
   if (
     origin.protocol !== "https:" ||
@@ -216,10 +377,11 @@ try {
 
 try {
   const files = tlsFiles();
-  origin.pathname = `/v1/${action}`;
+  const aliases = { "group-upsert": "groups", "group-send": "broadcast" };
+  origin.pathname = `/v1/${aliases[action] ?? action}`;
   origin.search = query;
   const payload = JSON.stringify(body);
-  const get = ["list", "inbox", "sessions"].includes(action);
+  const get = ["list", "inbox", "sessions", "groups"].includes(action);
   const result = await new Promise((resolve, reject) => {
     const req = https.request(
       origin,
@@ -263,14 +425,21 @@ try {
       () => {
         req.destroy(new Error("Bridge request deadline exceeded; delivery may be unknown."));
       },
-      action === "start" ? 90000 : (action === "ask" ? timeout : 0) + 15000,
+      ["start", "spawn", "resume", "transcript"].includes(action)
+        ? 90000
+        : (action === "ask" ? timeout : 0) + 15000,
     );
     req.once("close", () => clearTimeout(timer));
     req.once("error", reject);
     req.end(get ? undefined : payload);
   });
   console.log(JSON.stringify(result.value, null, 2));
-  if (result.status < 200 || result.status >= 300 || result.value?.ok !== true) {
+  if (
+    result.status < 200 ||
+    result.status >= 300 ||
+    result.value?.ok !== true ||
+    unsuccessful(result.value)
+  ) {
     process.exitCode = 1;
   }
 } catch (error) {
@@ -286,3 +455,9 @@ try {
   );
   process.exitCode = 1;
 }
+function unsuccessful(value) {
+  return (
+    value?.status === "partial" ||
+    ["denied", "failed", "unsupported"].includes(value?.native?.status)
+  );
+}

package/src/pi-intercom/bridge-broadcast.ts

@@ -0,0 +1,70 @@
+import { randomUUID } from "node:crypto";
+import { Fault, BroadcastFault } from "./bridge-protocol.ts";
+import type { GroupTargets } from "./bridge-groups.ts";
+import type { UnknownRecord } from "../shared/unknown.ts";
+import type { Session } from "./bridge-session.ts";
+import type { RequestContext } from "./bridge-http.ts";
+
+export async function broadcastTargets(
+  session: Readonly<Session>,
+  targets: GroupTargets,
+  message: string,
+  context: RequestContext,
+): Promise<UnknownRecord> {
+  const receipts: UnknownRecord[] = [];
+  for (const peer of targets.peers) {
+    if (context.signal.aborted) {
+      receipts.push({
+        peer: peer.id,
+        attempted: false,
+        error: {
+          code: "not_attempted",
+          message: "Broadcast stopped before sending.",
+          deliveryUnknown: false,
+        },
+      });
+      continue;
+    }
+    const id = randomUUID();
+    try {
+      // No hidden retries; sequential admission bounds broker pressure.
+      // oxlint-disable-next-line no-await-in-loop
+      const receipt = await session.send(peer.id, message, context, { messageId: id });
+      receipts.push({ peer: peer.id, attempted: true, ...receipt });
+    } catch (error) {
+      const fault =
+        error instanceof Fault
+          ? error
+          : new Fault(503, "send_unconfirmed", "Target delivery could not be confirmed.");
+      receipts.push({
+        peer: peer.id,
+        attempted: true,
+        error: {
+          code: fault.code,
+          message: fault.message,
+          ...fault.details,
+          id,
+          deliveryUnknown: fault.details.accepted !== false,
+        },
+      });
+    }
+  }
+  const failed =
+    receipts.filter((receipt) => receipt.accepted !== true).length + targets.errors.length;
+  const outcome = {
+    status: failed === 0 ? "complete" : "partial",
+    receipts,
+    errors: targets.errors,
+  };
+  // Transport closure must not erase outcomes, or disclose them after authorization is revoked.
+  session.authorize();
+  try {
+    session.guard(context.signal);
+  } catch (error) {
+    if (error instanceof Fault) {
+      throw new BroadcastFault(error, outcome);
+    }
+    throw error;
+  }
+  return outcome;
+}