@fitchmultz/pi-subagents 0.47.0 → 0.48.0

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

@@ -0,0 +1,169 @@
+import { join } from "node:path";
+import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
+import type { Identity } from "./bridge-config.ts";
+import type { RequestContext } from "./bridge-http.ts";
+import type { Operation } from "./bridge-routes.ts";
+import type { Session } from "./bridge-session.ts";
+import { Launcher } from "./bridge-launch.ts";
+import { SessionCatalog, savedView, trustedJournal } from "./bridge-catalog.ts";
+import { Groups } from "./bridge-groups.ts";
+import { broadcastTargets } from "./bridge-broadcast.ts";
+import { getPiAgentDir } from "./agent-dir.ts";
+import { Fault } from "./bridge-protocol.ts";
+import { resolveBridgeTarget } from "./bridge-target.ts";
+import { readSavedTranscript } from "./saved-transcript.ts";
+
+type OperationContext = RequestContext & {
+  readonly expires: number;
+  readonly certificate: string;
+};
+
+/** Request operations own launch/catalog/group state; transport owns admission and cancellation. */
+export class BridgeOperations {
+  private readonly catalog = new SessionCatalog();
+  private readonly launcher = new Launcher(this.catalog);
+  private readonly stateDir: string;
+  private groups?: Groups;
+
+  constructor(stateDir?: string) {
+    this.stateDir = stateDir ?? join(getPiAgentDir(), "intercom", "bridge-state");
+  }
+  revoke(clients: ReadonlyMap<string, Identity>): Promise<void> {
+    return this.launcher.revoke(clients);
+  }
+  shutdown(): Promise<void> {
+    return this.launcher.shutdown();
+  }
+  private groupStore(): Groups {
+    this.groups ??= new Groups(this.stateDir);
+    return this.groups;
+  }
+  async execute(
+    operation: Operation,
+    session: Readonly<Session>,
+    context: OperationContext,
+  ): Promise<UnknownRecord> {
+    const launchContext = {
+      identity: session.identity,
+      expires: context.expires,
+      signal: context.signal,
+      peers: (signal: AbortSignal) => session.connectedPeers(signal),
+      submit: (peer: string, task: string) => session.send(peer, task, context),
+    };
+    switch (operation.route) {
+      case "POST /v1/start":
+        return this.launcher.start(operation.name, launchContext);
+      case "POST /v1/spawn":
+        return this.launcher.spawn(operation, launchContext);
+      case "POST /v1/resume":
+        return this.launcher.resume(operation, launchContext);
+      case "GET /v1/sessions":
+        return operation.query === undefined
+          ? this.launcher.list(session.identity)
+          : this.launcher.browse(operation.query, launchContext);
+      case "POST /v1/stop":
+      case "POST /v1/cancel":
+        return this.stop(operation, session, context);
+      case "GET /v1/groups":
+        return { groups: this.groupStore().list(session.identity.fingerprint256) };
+      case "POST /v1/groups":
+        return {
+          groups: this.groupStore().upsert(session.identity.fingerprint256, operation.group),
+        };
+      case "POST /v1/broadcast":
+        return broadcastTargets(
+          session,
+          this.groupStore().targets(
+            session.identity.fingerprint256,
+            operation.group,
+            await session.connectedPeers(context.signal),
+          ),
+          operation.message,
+          context,
+        );
+      case "POST /v1/control":
+        return session.nativeControl(operation, context.certificate, context);
+      case "GET /v1/transcript":
+        return this.transcript(operation, session, context);
+      case "GET /v1/inbox":
+      case "GET /v1/list":
+      case "POST /v1/ack":
+      case "POST /v1/ask":
+      case "POST /v1/register":
+      case "POST /v1/reply":
+      case "POST /v1/send":
+        return session.execute(operation, context);
+    }
+  }
+  private async stop(
+    operation: Extract<Operation, { readonly route: "POST /v1/stop" | "POST /v1/cancel" }>,
+    session: Readonly<Session>,
+    context: OperationContext,
+  ): Promise<UnknownRecord> {
+    const cancel = operation.route === "POST /v1/cancel";
+    const control = {
+      signal: context.signal,
+      peers: (signal: AbortSignal) => session.connectedPeers(signal),
+    };
+    try {
+      return cancel
+        ? await this.launcher.cancel(session.identity, operation.sessionId, control)
+        : await this.launcher.stop(session.identity, operation.sessionId, control);
+    } catch (error) {
+      // Only a pre-effect ownership miss may dispatch elsewhere; never retry an unknown outcome.
+      if (!(error instanceof Fault) || error.code !== "unknown_session") {
+        throw error;
+      }
+    }
+    return session.nativeControl(
+      { to: operation.sessionId, verb: cancel ? "cancel" : "stop", timeoutMs: operation.timeoutMs },
+      context.certificate,
+      context,
+    );
+  }
+  private async transcript(
+    operation: Extract<Operation, { readonly route: "GET /v1/transcript" }>,
+    session: Readonly<Session>,
+    context: OperationContext,
+  ): Promise<UnknownRecord> {
+    const peers = await session.connectedPeers(context.signal);
+    try {
+      const peer = resolveBridgeTarget(peers, operation.target, null);
+      const result = await session.nativeControl(
+        {
+          to: peer.id,
+          verb: "transcript",
+          options: operation.options,
+          timeoutMs: operation.timeoutMs,
+        },
+        context.certificate,
+        context,
+      );
+      return {
+        ...result,
+        source: "live",
+        transcript: isRecord(result.native) ? result.native.transcript : undefined,
+      };
+    } catch (error) {
+      if (!(error instanceof Fault) || error.code !== "peer_offline") {
+        throw error;
+      }
+    }
+    const policy = session.identity.launch;
+    if (!policy) {
+      throw new Fault(403, "launch_disabled", "Saved transcripts require local resume policy.");
+    }
+    const saved = await this.catalog.resolve(policy, { target: operation.target }, context.signal);
+    trustedJournal(policy, saved.sessionFile);
+    const page = await readSavedTranscript(
+      policy.packageRoot,
+      saved.sessionFile,
+      operation.options,
+    );
+    session.guard(context.signal);
+    if (page.sessionId !== saved.sessionId) {
+      throw new Fault(409, "session_changed", "Saved journal identity changed during reading.");
+    }
+    return { status: "ok", source: "saved", session: savedView(saved), transcript: page };
+  }
+}

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

@@ -17,6 +17,14 @@ export class Fault extends Error {
   }
 }
 
+export class BroadcastFault extends Fault {
+  readonly outcome: UnknownRecord;
+  constructor(fault: Fault, outcome: UnknownRecord) {
+    super(fault.status, fault.code, fault.message, fault.details);
+    this.outcome = { ...outcome, status: "partial" };
+  }
+}
+
 export function object(value: unknown, fields: readonly string[]): UnknownRecord {
   if (!isRecord(value)) {
     throw new Fault(400, "invalid_input", "Expected a JSON object.");

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

@@ -2,13 +2,14 @@ import type { IncomingMessage } from "node:http";
 import { isUnknownArray } from "../shared/unknown.ts";
 import { ASK_TIMEOUT, Fault, INBOX_COUNT, label, object, text } from "./bridge-protocol.ts";
 import { body } from "./bridge-http.ts";
+import type { CatalogQuery } from "./bridge-catalog.ts";
+import { groupDefinition, type GroupDefinition } from "./bridge-groups.ts";
+import { isControlVerb, type NativeControlVerb } from "./native-control-protocol.ts";
+import { transcriptOptions, type TranscriptOptions } from "./transcript.ts";
 
-export type Operation =
+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/sessions" }
-  | { readonly route: "POST /v1/start"; readonly name: string }
-  | { readonly route: "POST /v1/stop"; readonly sessionId: string }
   | { readonly route: "POST /v1/ack"; readonly ids: readonly string[] }
   | { readonly route: "POST /v1/send"; readonly to: string; readonly message: string }
   | {
@@ -18,12 +19,55 @@ export type Operation =
       readonly timeoutMs: number;
     }
   | { readonly route: "POST /v1/reply"; readonly replyTo: string; readonly message: string };
-export type MessagingOperation = Exclude<
-  Operation,
-  { readonly route: "POST /v1/start" | "POST /v1/stop" | "GET /v1/sessions" }
->;
-type Route = Operation["route"];
-
+export type Operation =
+  | MessagingOperation
+  | { readonly route: "GET /v1/sessions"; readonly query?: CatalogQuery }
+  | { readonly route: "POST /v1/start"; readonly name: string }
+  | {
+      readonly route: "POST /v1/spawn";
+      readonly name: string;
+      readonly cwd?: string;
+      readonly provider?: string;
+      readonly model?: string;
+      readonly task?: string;
+    }
+  | {
+      readonly route: "POST /v1/resume";
+      readonly sessionId?: string;
+      readonly target?: string;
+      readonly name?: string;
+      readonly task?: string;
+    }
+  | {
+      readonly route: "POST /v1/stop" | "POST /v1/cancel";
+      readonly sessionId: string;
+      readonly timeoutMs: number;
+    }
+  | { readonly route: "GET /v1/groups" }
+  | { readonly route: "POST /v1/groups"; readonly group: GroupDefinition }
+  | { readonly route: "POST /v1/broadcast"; readonly message: string; readonly group?: string }
+  | {
+      readonly route: "POST /v1/control";
+      readonly to: string;
+      readonly verb: NativeControlVerb;
+      readonly options?: TranscriptOptions;
+      readonly timeoutMs: number;
+    }
+  | {
+      readonly route: "GET /v1/transcript";
+      readonly target: string;
+      readonly options: TranscriptOptions;
+      readonly timeoutMs: number;
+    };
+type Route = Operation["route"] | "POST /v1/transcript" | "POST /v1/capabilities";
+type MessagingRoute =
+  | MessagingOperation["route"]
+  | "GET /v1/groups"
+  | "GET /v1/sessions"
+  | "GET /v1/transcript"
+  | "POST /v1/control"
+  | "POST /v1/transcript"
+  | "POST /v1/capabilities";
 const fields = {
   "GET /v1/list": [],
   "GET /v1/inbox": [],
@@ -33,10 +77,19 @@ const fields = {
   "POST /v1/ask": ["to", "message", "timeoutMs"],
   "POST /v1/reply": ["replyTo", "message"],
   "POST /v1/start": ["name"],
+  "POST /v1/spawn": ["name", "cwd", "task", "provider", "model"],
+  "POST /v1/resume": ["sessionId", "name", "target", "task"],
   "GET /v1/sessions": [],
-  "POST /v1/stop": ["sessionId"],
+  "POST /v1/stop": ["sessionId", "target", "to", "mode", "timeoutMs"],
+  "POST /v1/cancel": ["sessionId", "target", "to", "timeoutMs"],
+  "GET /v1/groups": [],
+  "POST /v1/groups": ["name", "members", "namePattern", "cwdPattern", "match"],
+  "POST /v1/broadcast": ["message", "group"],
+  "POST /v1/control": ["to", "verb", "options", "timeoutMs"],
+  "POST /v1/capabilities": ["to", "timeoutMs"],
+  "POST /v1/transcript": ["to", "limit", "maxBytes", "cursor", "timeoutMs"],
+  "GET /v1/transcript": ["target", "limit", "maxBytes", "cursor", "timeoutMs"],
 };
-
 function isRoute(route: string): route is Route {
   return Object.hasOwn(fields, route);
 }
@@ -51,13 +104,19 @@ export function routeFor(req: IncomingMessage): Route {
   if (!isRoute(route)) {
     throw new Fault(404, "not_found", "Unknown method or path.");
   }
-  if (req.url?.includes("?") === true && route !== "GET /v1/inbox") {
-    throw new Fault(400, "invalid_input", "Only inbox accepts query parameters.");
+  if (
+    req.url?.includes("?") === true &&
+    !["GET /v1/inbox", "GET /v1/sessions", "GET /v1/transcript"].includes(route)
+  ) {
+    throw new Fault(
+      400,
+      "invalid_input",
+      "Query parameters are only supported for inbox, sessions and transcript.",
+    );
   }
   checkGetBody(req);
   return route;
 }
-
 function checkGetBody(req: IncomingMessage): void {
   if (
     req.method === "GET" &&
@@ -67,18 +126,15 @@ function checkGetBody(req: IncomingMessage): void {
     throw new Fault(400, "invalid_input", "GET requests must not have a body.");
   }
 }
-
-function inboxQuery(req: IncomingMessage): Extract<Operation, { readonly route: "GET /v1/inbox" }> {
-  const url = req.url ?? "";
-  const separator = url.indexOf("?");
-  const query = new URLSearchParams(separator === -1 ? "" : url.slice(separator + 1));
-  if (
-    [...query.keys()].some(
-      (key) => !["after", "limit"].includes(key) || query.getAll(key).length !== 1,
-    )
-  ) {
-    throw new Fault(400, "invalid_input", "Unknown or repeated inbox query parameter.");
+function queryFor(req: IncomingMessage, allowed: readonly string[]): URLSearchParams {
+  const query = new URL(req.url ?? "", "https://127.0.0.1").searchParams;
+  if ([...query.keys()].some((key) => !allowed.includes(key) || query.getAll(key).length !== 1)) {
+    throw new Fault(400, "invalid_input", "Unknown or repeated query parameter.");
   }
+  return query;
+}
+function inboxQuery(req: IncomingMessage): Extract<Operation, { readonly route: "GET /v1/inbox" }> {
+  const query = queryFor(req, ["after", "limit"]);
   const after = query.get("after") ?? "0";
   const limit = query.get("limit") ?? String(INBOX_COUNT);
   if (
@@ -95,38 +151,142 @@ function inboxQuery(req: IncomingMessage): Extract<Operation, { readonly route:
   }
   return { route: "GET /v1/inbox", after: Number(after), limit: Number(limit) };
 }
-
-function timeout(value: unknown): number {
-  const ms = value === undefined ? ASK_TIMEOUT : value;
-  if (typeof ms !== "number" || !Number.isInteger(ms) || ms < 100 || ms > ASK_TIMEOUT) {
-    throw new Fault(400, "invalid_input", "timeoutMs must be an integer from 100 to 120000.");
+function pageNumber(value: string | null, fallback: number, min: number, max: number): number {
+  const number = value === null ? fallback : Number(value);
+  if (value === "" || !Number.isSafeInteger(number) || number < min || number > max) {
+    throw new Fault(400, "invalid_input", "Invalid catalog pagination.");
+  }
+  return number;
+}
+function queryBoolean(value: string | null): boolean {
+  if (value !== null && value !== "true" && value !== "false") {
+    throw new Fault(400, "invalid_input", "Catalog switches must be true or false.");
+  }
+  return value === "true";
+}
+function catalogQuery(req: IncomingMessage): CatalogQuery | undefined {
+  if (req.url?.includes("?") !== true) {
+    return undefined;
+  }
+  const params = queryFor(req, ["live", "saved", "q", "offset", "limit"]);
+  return {
+    live: queryBoolean(params.get("live")),
+    saved: queryBoolean(params.get("saved")),
+    q: params.has("q") ? label(params.get("q"), "catalog filter", 128) : undefined,
+    offset: pageNumber(params.get("offset"), 0, 0, Number.MAX_SAFE_INTEGER),
+    limit: pageNumber(params.get("limit"), 50, 1, 100),
+  };
+}
+function timeout(value: unknown, control = false): number {
+  const defaultMs = control ? 3000 : ASK_TIMEOUT;
+  const ms = value === undefined ? defaultMs : value;
+  const max = control ? 10000 : ASK_TIMEOUT;
+  if (typeof ms !== "number" || !Number.isInteger(ms) || ms < 100 || ms > max) {
+    throw new Fault(400, "invalid_input", `timeoutMs must be an integer from 100 to ${max}.`);
   }
   return ms;
 }
-
-export async function operationFor(
+function resume(
+  input: Readonly<Record<string, unknown>>,
+): Extract<Operation, { readonly route: "POST /v1/resume" }> {
+  if (["sessionId", "name", "target"].filter((key) => input[key] !== undefined).length !== 1) {
+    throw new Fault(
+      400,
+      "invalid_input",
+      "Resume requires exactly one of sessionId, name or target.",
+    );
+  }
+  const sessionId =
+    input.sessionId === undefined ? undefined : label(input.sessionId, "native session ID", 128);
+  if (sessionId !== undefined && !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(sessionId)) {
+    throw new Fault(400, "invalid_input", "Resume takes a native ID, never a journal path.");
+  }
+  return {
+    route: "POST /v1/resume",
+    sessionId,
+    target:
+      input.target === undefined ? undefined : label(input.target, "resume target", 256).trim(),
+    name:
+      input.name === undefined ? undefined : label(input.name, "saved session name", 256).trim(),
+    task: input.task === undefined ? undefined : text(input.task),
+  };
+}
+function stop(
+  route: "POST /v1/stop" | "POST /v1/cancel",
+  input: Readonly<Record<string, unknown>>,
+): Extract<Operation, { readonly route: "POST /v1/stop" | "POST /v1/cancel" }> {
+  if (["sessionId", "target", "to"].filter((key) => input[key] !== undefined).length !== 1) {
+    throw new Fault(400, "invalid_input", "Control requires exactly one sessionId, target or to.");
+  }
+  const mode = input.mode ?? "kill";
+  if (mode !== "kill" && mode !== "cancel") {
+    throw new Fault(400, "invalid_input", "Stop mode must be cancel or kill.");
+  }
+  return {
+    route: mode === "cancel" ? "POST /v1/cancel" : route,
+    sessionId: label(input.sessionId ?? input.target ?? input.to, "session target", 256).trim(),
+    timeoutMs: timeout(input.timeoutMs, true),
+  };
+}
+function nativeControl(
+  route: Route,
+  input: Readonly<Record<string, unknown>>,
+): Extract<Operation, { readonly route: "POST /v1/control" | "GET /v1/transcript" }> {
+  const verb = route === "POST /v1/control" ? input.verb : route.split("/").at(-1);
+  if (!isControlVerb(verb)) {
+    throw new Fault(400, "invalid_input", "Unknown native control verb.");
+  }
+  const timeoutMs = timeout(input.timeoutMs, true);
+  const to = label(input.to ?? input.target, "session target").trim();
+  if (verb === "transcript") {
+    const options = transcriptOptions(
+      route === "POST /v1/control"
+        ? input.options
+        : { limit: input.limit, maxBytes: input.maxBytes, cursor: input.cursor },
+    );
+    return { route: "GET /v1/transcript", target: to, options, timeoutMs };
+  }
+  if (input.options !== undefined) {
+    throw new Fault(400, "invalid_input", "Only transcript accepts options.");
+  }
+  return { route: "POST /v1/control", verb, to, timeoutMs };
+}
+async function operationInput(
   req: IncomingMessage,
   route: Route,
   signal: AbortSignal,
-): Promise<Operation> {
-  const input = req.method === "POST" ? object(await body(req, signal), fields[route]) : {};
+): Promise<Record<string, unknown>> {
+  if (req.method === "POST") {
+    return object(await body(req, signal), fields[route]);
+  }
+  if (route !== "GET /v1/transcript") {
+    return {};
+  }
+  const input: Record<string, unknown> = {};
+  for (const [key, value] of queryFor(req, fields[route])) {
+    input[key] = ["limit", "maxBytes", "timeoutMs"].includes(key) ? Number(value) : value;
+  }
+  return input;
+}
+function messagingOperation(
+  route: MessagingRoute,
+  input: Readonly<Record<string, unknown>>,
+  req: IncomingMessage,
+): Operation {
   switch (route) {
     case "GET /v1/list":
     case "POST /v1/register":
-    case "GET /v1/sessions":
+    case "GET /v1/groups":
       return { route };
     case "GET /v1/inbox":
       return inboxQuery(req);
-    case "POST /v1/start":
-      return { route, name: label(input.name, "session name", 64).trim() };
-    case "POST /v1/stop":
-      return { route, sessionId: label(input.sessionId, "session ID", 128) };
-    case "POST /v1/ack": {
+    case "GET /v1/sessions":
+      return { route, query: catalogQuery(req) };
+    case "POST /v1/ack":
       if (!isUnknownArray(input.ids) || input.ids.length > INBOX_COUNT) {
         throw new Fault(400, "invalid_input", "ids must be an array of at most 256 message IDs.");
       }
       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() };
     case "POST /v1/ask":
@@ -138,5 +298,57 @@ export async function operationFor(
       };
     case "POST /v1/reply":
       return { route, message: text(input.message), replyTo: label(input.replyTo, "replyTo") };
+    case "GET /v1/transcript":
+    case "POST /v1/control":
+    case "POST /v1/transcript":
+    case "POST /v1/capabilities":
+      return nativeControl(route, input);
+  }
+}
+export async function operationFor(
+  req: IncomingMessage,
+  route: Route,
+  signal: AbortSignal,
+): Promise<Operation> {
+  const input = await operationInput(req, route, signal);
+  switch (route) {
+    case "POST /v1/start":
+      return { route, name: label(input.name, "session name", 64).trim() };
+    case "POST /v1/spawn":
+      return {
+        route,
+        name: label(input.name, "session name", 64).trim(),
+        cwd: input.cwd === undefined ? undefined : label(input.cwd, "cwd", 4096),
+        provider: input.provider === undefined ? undefined : label(input.provider, "provider", 128),
+        model: input.model === undefined ? undefined : label(input.model, "model reference", 512),
+        task: input.task === undefined ? undefined : text(input.task),
+      };
+    case "POST /v1/resume":
+      return resume(input);
+    case "POST /v1/stop":
+    case "POST /v1/cancel":
+      return stop(route, input);
+    case "POST /v1/groups":
+      return { route, group: groupDefinition(input) };
+    case "POST /v1/broadcast":
+      return {
+        route,
+        message: text(input.message),
+        group: input.group === undefined ? undefined : label(input.group, "group", 64).trim(),
+      };
+    case "GET /v1/groups":
+    case "GET /v1/inbox":
+    case "GET /v1/list":
+    case "GET /v1/sessions":
+    case "GET /v1/transcript":
+    case "POST /v1/ack":
+    case "POST /v1/ask":
+    case "POST /v1/capabilities":
+    case "POST /v1/control":
+    case "POST /v1/register":
+    case "POST /v1/reply":
+    case "POST /v1/send":
+    case "POST /v1/transcript":
+      return messagingOperation(route, input, req);
   }
 }