@fitchmultz/pi-subagents 0.48.0 → 0.49.1

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

@@ -9,9 +9,20 @@ import { transcriptOptions, type TranscriptOptions } from "./transcript.ts";
 
 export type MessagingOperation =
   | { readonly route: "GET /v1/list" | "POST /v1/register" }
-  | { readonly route: "GET /v1/inbox"; readonly after: number; readonly limit: number }
+  | {
+      readonly route: "GET /v1/inbox";
+      readonly after: number;
+      readonly limit: number;
+      readonly waitMs: number;
+    }
   | { readonly route: "POST /v1/ack"; readonly ids: readonly string[] }
-  | { readonly route: "POST /v1/send"; readonly to: string; readonly message: string }
+  | {
+      readonly route: "POST /v1/send";
+      readonly to: string;
+      readonly message: string;
+      readonly passive?: boolean;
+      readonly messageId?: string;
+    }
   | {
       readonly route: "POST /v1/ask";
       readonly to: string;
@@ -73,7 +84,7 @@ const fields = {
   "GET /v1/inbox": [],
   "POST /v1/register": [],
   "POST /v1/ack": ["ids"],
-  "POST /v1/send": ["to", "message"],
+  "POST /v1/send": ["to", "message", "passive", "messageId"],
   "POST /v1/ask": ["to", "message", "timeoutMs"],
   "POST /v1/reply": ["replyTo", "message"],
   "POST /v1/start": ["name"],
@@ -134,22 +145,29 @@ function queryFor(req: IncomingMessage, allowed: readonly string[]): URLSearchPa
   return query;
 }
 function inboxQuery(req: IncomingMessage): Extract<Operation, { readonly route: "GET /v1/inbox" }> {
-  const query = queryFor(req, ["after", "limit"]);
+  const query = queryFor(req, ["after", "limit", "waitMs"]);
   const after = query.get("after") ?? "0";
   const limit = query.get("limit") ?? String(INBOX_COUNT);
+  const waitMs = query.get("waitMs") ?? "0";
   if (
     !/^(0|[1-9]\d{0,15})$/.test(after) ||
     !Number.isSafeInteger(Number(after)) ||
     !/^[1-9]\d{0,2}$/.test(limit) ||
-    Number(limit) > INBOX_COUNT
+    Number(limit) > INBOX_COUNT ||
+    !/^(0|[1-9]\d{0,3}|10000)$/.test(waitMs)
   ) {
     throw new Fault(
       400,
       "invalid_input",
-      "after must be a nonnegative safe integer cursor; limit must be 1..256.",
+      "after must be a nonnegative safe integer cursor; limit must be 1..256; waitMs must be 0..10000.",
     );
   }
-  return { route: "GET /v1/inbox", after: Number(after), limit: Number(limit) };
+  return {
+    route: "GET /v1/inbox",
+    after: Number(after),
+    limit: Number(limit),
+    waitMs: Number(waitMs),
+  };
 }
 function pageNumber(value: string | null, fallback: number, min: number, max: number): number {
   const number = value === null ? fallback : Number(value);
@@ -288,7 +306,7 @@ function messagingOperation(
       }
       return { route, ids: [...new Set(input.ids.map((id) => label(id, "message ID")))] };
     case "POST /v1/send":
-      return { route, message: text(input.message), to: label(input.to, "to").trim() };
+      return send(input);
     case "POST /v1/ask":
       return {
         route,
@@ -305,6 +323,18 @@ function messagingOperation(
       return nativeControl(route, input);
   }
 }
+function send(input: Readonly<Record<string, unknown>>): MessagingOperation {
+  if (input.passive !== undefined && typeof input.passive !== "boolean") {
+    throw new Fault(400, "invalid_input", "passive must be a boolean.");
+  }
+  return {
+    route: "POST /v1/send",
+    message: text(input.message),
+    to: label(input.to, "to").trim(),
+    passive: input.passive,
+    messageId: input.messageId === undefined ? undefined : label(input.messageId, "message ID"),
+  };
+}
 export async function operationFor(
   req: IncomingMessage,
   route: Route,

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

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 import { IntercomClient } from "./broker/client.ts";
 import { resolveSessionProjectId } from "./session-targets.ts";
 import type { Message, SendResult, SessionInfo } from "./types.ts";
@@ -18,14 +19,13 @@ const IDLE_TIMEOUT = 5 * 60 * 1000;
 const SEND_TIMEOUT = 8000;
 const LIST_TIMEOUT = 5000;
 
-interface SendOptions {
+interface SendOptions extends Pick<Message, "replyTo" | "expectsReply" | "delivery"> {
   readonly messageId?: string;
-  readonly replyTo?: string;
-  readonly expectsReply?: boolean;
 }
 export interface SessionOwner {
   readonly stateDir?: string;
   readonly notifications?: boolean;
+  readonly mailboxChanged?: () => void;
   readonly allowed: (identity: Identity) => boolean;
   readonly lost: (fp: string, count?: number) => void;
   readonly retired: (fp: string, generation: string) => void;
@@ -43,6 +43,7 @@ export class Session {
   });
   private readonly requests = new Set<AbortController>();
   private readonly inbox: Mailbox;
+  private inboxChanged = new AbortController();
   private readonly replying = new Set<string>();
   private pending?: WaitingAsk;
   private readonly controls = new ControlReplies();
@@ -76,9 +77,7 @@ export class Session {
   }
 
   guard(signal?: AbortSignal): void {
-    if (signal) {
-      cancelled(signal);
-    }
+    signal?.throwIfAborted();
     if (this.closed) {
       throw this.closeReason;
     }
@@ -267,12 +266,22 @@ export class Session {
       );
       return;
     }
-    if (result === "lost" || (result === "duplicate" && !this.inbox.persistent)) {
-      this.owner.lost(this.identity.fingerprint256);
+    if (result !== "duplicate" || !this.inbox.persistent) {
+      if (result !== "stored") {
+        this.owner.lost(this.identity.fingerprint256);
+      }
+      this.inboxChanged.abort();
+      this.inboxChanged = new AbortController();
     }
-    this.recordReceive(from.id, message.id, result);
+    log(result === "lost" ? "inbox_overflow" : "received", {
+      ...this.fields(),
+      peer: from.id,
+      messageId: message.id,
+      result: result === "lost" && this.inbox.persistent ? "storage_failed" : result,
+    });
     if (result !== "lost") {
       this.resolveReply(from, message);
+      this.owner.mailboxChanged?.();
     }
     this.presence();
   }
@@ -284,18 +293,6 @@ export class Session {
     pending.resolve({ from, message });
     return true;
   }
-  private recordReceive(
-    peer: string,
-    messageId: string,
-    result: "stored" | "duplicate" | "lost",
-  ): void {
-    log(result === "lost" ? "inbox_overflow" : "received", {
-      ...this.fields(),
-      peer,
-      messageId,
-      result: result === "lost" && this.inbox.persistent ? "storage_failed" : result,
-    });
-  }
   private presence(): void {
     if (this.closed) {
       return;
@@ -393,22 +390,6 @@ export class Session {
     const waiting = new WaitingAsk();
     this.pending = waiting;
     const { signal } = context;
-    const abort = () => {
-      try {
-        cancelled(signal);
-      } catch (error) {
-        waiting.reject(
-          error instanceof Error
-            ? error
-            : new Fault(
-                499,
-                "client_aborted",
-                "HTTP client disconnected; delivery may be unknown.",
-              ),
-        );
-      }
-    };
-    signal.addEventListener("abort", abort, { once: true });
     try {
       await this.connect(signal);
       const peer = await this.target(operation.to, signal);
@@ -424,16 +405,39 @@ export class Session {
       return { ...waiting.receipt, replied: true, reply: answer };
     } finally {
       waiting.clear();
-      signal.removeEventListener("abort", abort);
-      if (this.pending === waiting) {
-        this.pending = undefined;
-      }
+      this.pending = undefined;
     }
   }
-  private ack(ids: readonly string[]): UnknownRecord {
-    const result = this.inbox.ack(ids);
-    this.presence();
-    return result;
+  private async readInbox(
+    operation: Extract<Operation, { readonly route: "GET /v1/inbox" }>,
+    context: RequestContext,
+  ): Promise<UnknownRecord> {
+    const read = (): ReturnType<Mailbox["page"]> & UnknownRecord => ({
+      ...this.inbox.page(operation.after, operation.limit),
+      ...this.inbox.status(this.owner.losses(this.identity.fingerprint256)),
+    });
+    const deadline = performance.now() + operation.waitMs;
+    const losses = read().lostMessages;
+    for (;;) {
+      // Subscribe to the post-commit signal before rereading the authoritative cursor page.
+      const signal = AbortSignal.any([this.inboxChanged.signal, context.signal]);
+      const page = read();
+      const remaining = deadline - performance.now();
+      if (page.messages.length > 0 || page.lostMessages !== losses || remaining <= 0) {
+        return page;
+      }
+      log("inbox_wait", { ...this.fields(), requestId: context.requestId, after: operation.after });
+      try {
+        // A nonmatching commit must rearm the same cursor, not start parallel readers.
+        // oxlint-disable-next-line no-await-in-loop
+        await delay(remaining, undefined, { signal });
+      } catch (error) {
+        if (!signal.aborted) {
+          throw error;
+        }
+      }
+      this.guard(context.signal);
+    }
   }
   private async answer(
     replyTo: string,
@@ -461,6 +465,7 @@ export class Session {
       }
       const data = { ...(await this.send(peer, message, context, { replyTo })) };
       this.inbox.remove(replyTo);
+      this.owner.mailboxChanged?.();
       this.presence();
       return data;
     } finally {
@@ -478,32 +483,30 @@ export class Session {
         await this.connect(context.signal);
       }
       if (operation.route === "POST /v1/ack") {
-        return this.ack(operation.ids);
+        const result = this.inbox.ack(operation.ids);
+        this.owner.mailboxChanged?.();
+        this.presence();
+        return result;
       }
-      return {
-        ...this.inbox.page(operation.after, operation.limit),
-        ...this.inbox.status(this.owner.losses(this.identity.fingerprint256)),
-      };
+      return this.readInbox(operation, context);
     }
     await this.connect(context.signal);
     switch (operation.route) {
       case "POST /v1/register":
         return { sessionId: this.client.sessionId, name: this.identity.name };
-      case "GET /v1/list": {
-        const sessions = await this.peers(context.signal);
+      case "GET /v1/list":
         return {
           sessionId: this.client.sessionId,
-          sessions: bridgeSessionList(sessions),
+          sessions: bridgeSessionList(await this.peers(context.signal)),
         };
+      case "POST /v1/send": {
+        const peer = await this.target(operation.to, context.signal);
+        const receipt = await this.send(peer.id, operation.message, context, {
+          messageId: operation.messageId,
+          delivery: operation.passive === true ? "passive" : "steer",
+        });
+        return { ...receipt };
       }
-      case "POST /v1/send":
-        return {
-          ...(await this.send(
-            (await this.target(operation.to, context.signal)).id,
-            operation.message,
-            context,
-          )),
-        };
       case "POST /v1/reply":
         return this.answer(operation.replyTo, operation.message, context);
     }

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

@@ -0,0 +1,83 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, realpathSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { isRecord } from "../shared/unknown.ts";
+import { label } from "./bridge-protocol.ts";
+
+export function stateDirectory(value: unknown): string | undefined {
+  if (value === undefined) {
+    return;
+  }
+  const path = label(value, "stateDir", 4096);
+  const stat = lstatSync(path);
+  if (
+    !isAbsolute(path) ||
+    !stat.isDirectory() ||
+    stat.uid !== process.getuid?.() ||
+    (stat.mode & 0o777) !== 0o700
+  ) {
+    throw new Error("stateDir must be an absolute owned directory with mode 0700, not a symlink.");
+  }
+  return realpathSync(path);
+}
+
+export function privateFile(path: string): void {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (
+      !stat.isFile() ||
+      stat.uid !== process.getuid?.() ||
+      (stat.mode & 0o777) !== 0o600 ||
+      stat.nlink !== 1
+    ) {
+      throw new Error("Storage files must be owned regular files with mode 0600 and one link.");
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Native SQLite FULL commits own durability; never replace an unreadable existing database. */
+export function privateDatabase(
+  stateDir: string,
+  name: string,
+): { readonly db: DatabaseSync; readonly created: boolean } {
+  stateDirectory(stateDir);
+  const path = join(stateDir, name);
+  let created = false;
+  try {
+    const fd = openSync(
+      path,
+      constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+      0o600,
+    );
+    closeSync(fd);
+    created = true;
+  } catch (error) {
+    if (!isRecord(error) || error.code !== "EEXIST") {
+      throw error;
+    }
+  }
+  privateFile(path);
+  for (const suffix of ["-journal", "-wal", "-shm"]) {
+    try {
+      lstatSync(`${path}${suffix}`);
+    } catch (error) {
+      if (isRecord(error) && error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    privateFile(`${path}${suffix}`);
+  }
+  const db = new DatabaseSync(path, { enableDoubleQuotedStringLiterals: false });
+  try {
+    db.exec(`PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL; PRAGMA secure_delete=ON;
+      PRAGMA cache_size=-1024; PRAGMA busy_timeout=1000;`);
+    return { db, created };
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}

package/src/pi-intercom/bridge-wake-owner.ts

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { privateDatabase, privateFile } from "./bridge-storage.ts";
+import { isRecord } from "../shared/unknown.ts";
+
+export const WAKE_OWNER_FILE = /^wake-owner-[0-9a-f-]{36}\.lock$/;
+
+/** SQLite's OS lock survives pauses and is released on exit, without PID reuse or stale leases. */
+export class WakeOwner {
+  readonly name = `wake-owner-${randomUUID()}.lock`;
+  private readonly db: DatabaseSync;
+  private readonly path: string;
+
+  constructor(stateDir: string) {
+    this.path = join(stateDir, this.name);
+    this.db = privateDatabase(stateDir, this.name).db;
+    try {
+      this.db.exec("BEGIN EXCLUSIVE");
+    } catch (error) {
+      this.db.close();
+      throw error;
+    }
+  }
+
+  close(): void {
+    this.db.close();
+    rmSync(this.path, { force: true });
+  }
+}
+
+export function stoppedWakeOwner(stateDir: string, name: string): boolean {
+  if (!WAKE_OWNER_FILE.test(name)) {
+    throw new Error("Invalid wake owner.");
+  }
+  const path = join(stateDir, name);
+  try {
+    privateFile(path);
+  } catch (error) {
+    if (isRecord(error) && error.code === "ENOENT") {
+      return true;
+    }
+    throw error;
+  }
+  const db = new DatabaseSync(path);
+  try {
+    db.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE");
+    return true;
+  } catch (error) {
+    if (isRecord(error) && error.errcode === 5) {
+      return false;
+    }
+    throw error;
+  } finally {
+    db.close();
+  }
+}