@fitchmultz/pi-subagents 0.47.0 → 0.49.0

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

@@ -0,0 +1,169 @@
+import { lstatSync, mkdirSync } from "node:fs";
+import { join, matchesGlob } from "node:path";
+import { readBridgeFile, writeBridgeJson } from "./bridge-files.ts";
+import { isUnknownArray, hasErrorCode } from "../shared/unknown.ts";
+import { Fault, label, object } from "./bridge-protocol.ts";
+import { resolveSessionTarget, nativePeerId } from "./session-targets.ts";
+import type { SessionInfo } from "./types.ts";
+
+export interface GroupDefinition {
+  readonly name: string;
+  readonly members?: readonly string[];
+  readonly namePattern?: string;
+  readonly cwdPattern?: string;
+}
+const GROUP_LIMIT = 64;
+function normalizedGroup(value: unknown): Record<string, unknown> {
+  const input = object(value, ["name", "members", "namePattern", "cwdPattern", "match"]);
+  if (input.match === undefined) {
+    return input;
+  }
+  if ([input.members, input.namePattern, input.cwdPattern].some((field) => field !== undefined)) {
+    throw new Fault(400, "invalid_input", "Use match or canonical selectors, not both.");
+  }
+  const match =
+    typeof input.match === "string"
+      ? { nameglob: input.match }
+      : object(input.match, ["id", "nameglob", "cwd"]);
+  return {
+    name: input.name,
+    members: typeof match.id === "string" ? [match.id] : match.id,
+    namePattern: match.nameglob,
+    cwdPattern: match.cwd,
+  };
+}
+export function groupDefinition(value: unknown): GroupDefinition {
+  const input = normalizedGroup(value);
+  const name = label(input.name, "group name", 64).trim();
+  if (
+    input.members !== undefined &&
+    (!isUnknownArray(input.members) || input.members.length > 256)
+  ) {
+    throw new Fault(400, "invalid_input", "members must contain at most 256 peer IDs/names.");
+  }
+  const members = isUnknownArray(input.members)
+    ? [...new Set(input.members.map((member) => label(member, "member", 512).trim()))]
+    : undefined;
+  const namePattern =
+    input.namePattern === undefined ? undefined : label(input.namePattern, "name pattern", 128);
+  const cwdPattern =
+    input.cwdPattern === undefined ? undefined : label(input.cwdPattern, "cwd pattern", 512);
+  if (members === undefined && namePattern === undefined && cwdPattern === undefined) {
+    throw new Fault(400, "invalid_input", "Define explicit members or at least one glob pattern.");
+  }
+  return { name, members, namePattern, cwdPattern };
+}
+function privateDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const stat = lstatSync(path);
+  if (
+    !stat.isDirectory() ||
+    stat.isSymbolicLink() ||
+    stat.uid !== process.getuid?.() ||
+    (stat.mode & 0o777) !== 0o700
+  ) {
+    throw new Fault(
+      503,
+      "state_unavailable",
+      "Group stateDir must be owned by the current user with mode 0700.",
+    );
+  }
+}
+export function nativePeers(
+  peers: readonly SessionInfo[],
+  source?: string | null,
+): readonly SessionInfo[] {
+  return peers.filter((peer) => /^pi-[a-f0-9]{32}$/.test(peer.id) && peer.id !== source);
+}
+export interface GroupTargets {
+  readonly peers: readonly SessionInfo[];
+  readonly errors: readonly { readonly member: string; readonly code: string }[];
+}
+export class Groups {
+  private readonly stateDir: string;
+  constructor(stateDir: string) {
+    this.stateDir = stateDir;
+    privateDirectory(stateDir);
+  }
+  private file(fingerprint: string): string {
+    if (!/^[a-fA-F0-9]{64}$/.test(fingerprint)) {
+      throw new Fault(403, "unauthorized", "Invalid identity.");
+    }
+    return join(this.stateDir, `groups-${fingerprint.toLowerCase()}.json`);
+  }
+  list(fingerprint: string): readonly GroupDefinition[] {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(readBridgeFile(this.file(fingerprint), true, 1024 * 1024).toString("utf8"));
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT")) {
+        return [];
+      }
+      throw error;
+    }
+    if (!isUnknownArray(raw) || raw.length > GROUP_LIMIT) {
+      throw new Fault(503, "state_unavailable", "Invalid group state.");
+    }
+    return raw.map(groupDefinition);
+  }
+  upsert(fingerprint: string, group: GroupDefinition): readonly GroupDefinition[] {
+    privateDirectory(this.stateDir);
+    const groups = this.list(fingerprint).filter((entry) => entry.name !== group.name);
+    if (groups.length >= GROUP_LIMIT) {
+      throw new Fault(409, "group_limit", "At most 64 groups are allowed per identity.");
+    }
+    groups.push(groupDefinition(group));
+    const file = this.file(fingerprint);
+    const serialized = JSON.stringify(groups);
+    if (Buffer.byteLength(serialized) > 1024 * 1024) {
+      throw new Fault(
+        413,
+        "state_too_large",
+        "Group definitions exceed the 1 MiB identity budget.",
+      );
+    }
+    writeBridgeJson(file, groups);
+    return groups;
+  }
+  targets(
+    fingerprint: string,
+    name: string | undefined,
+    peers: readonly SessionInfo[],
+  ): GroupTargets {
+    if (name === undefined) {
+      return { peers: nativePeers(peers), errors: [] };
+    }
+    const group = this.list(fingerprint).find((entry) => entry.name === name);
+    if (!group) {
+      throw new Fault(404, "unknown_group", "Define this group before sending to it.");
+    }
+    return selectTargets(group, nativePeers(peers));
+  }
+}
+function selectTargets(group: GroupDefinition, peers: readonly SessionInfo[]): GroupTargets {
+  const selected = new Map<string, SessionInfo>();
+  const errors: { member: string; code: string }[] = [];
+  for (const member of group.members ?? []) {
+    const result = resolveSessionTarget(peers, member);
+    const target = result.target ?? peers.find((peer) => peer.id === nativePeerId(member));
+    if (target) {
+      selected.set(target.id, target);
+    } else {
+      errors.push({ member, code: result.status === "none" ? "peer_offline" : "ambiguous_target" });
+    }
+  }
+  if (group.namePattern !== undefined || group.cwdPattern !== undefined) {
+    for (const peer of peers) {
+      if (matchesSelectors(group, peer)) {
+        selected.set(peer.id, peer);
+      }
+    }
+  }
+  return { peers: [...selected.values()], errors };
+}
+function matchesSelectors(group: GroupDefinition, peer: SessionInfo): boolean {
+  return (
+    (group.namePattern === undefined || matchesGlob(peer.name ?? "", group.namePattern)) &&
+    (group.cwdPattern === undefined || matchesGlob(peer.cwd, group.cwdPattern))
+  );
+}

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

@@ -1,7 +1,13 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import { BODY_LIMIT, Fault } from "./bridge-protocol.ts";
+import { BODY_LIMIT, Fault, BroadcastFault } from "./bridge-protocol.ts";
 import { errorMessage, type UnknownRecord } from "../shared/unknown.ts";
 
+export interface RequestContext {
+  readonly signal: AbortSignal;
+  readonly requestId: string;
+  readonly onPeer: (peer: string) => void;
+}
+
 function validateHeaders(req: IncomingMessage): void {
   const type = req.headers["content-type"];
   if (typeof type !== "string" || !/^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(type)) {
@@ -95,3 +101,11 @@ export function reply(
   });
   res.end(payload);
 }
+
+export function replyFault(res: ServerResponse, requestId: string, fault: Fault): void {
+  reply(res, requestId, fault.status, {
+    ok: false,
+    ...(fault instanceof BroadcastFault ? fault.outcome : {}),
+    error: { code: fault.code, message: fault.message, ...fault.details },
+  });
+}

package/src/pi-intercom/bridge-launch-journal.ts

@@ -0,0 +1,122 @@
+import { statSync } from "node:fs";
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import { loadNativeSession } from "../shared/native-session-loader.ts";
+import { isRecord, type UnknownRecord } from "../shared/unknown.ts";
+import { Fault, cancelled, wait } from "./bridge-protocol.ts";
+import { trustedJournal, inspectResumeIdentity } from "./bridge-catalog.ts";
+import { nativePeerId } from "./session-targets.ts";
+import type { LaunchPolicy } from "./bridge-launch-policy.ts";
+
+export interface LaunchJournal {
+  readonly sessionId: string;
+  readonly peerId: string;
+  readonly sessionFile: string;
+  readonly name?: string;
+  readonly cwd: string;
+  readonly model?: { readonly provider: string; readonly modelId: string };
+}
+export function validateLaunchState(saved: LaunchJournal, state: UnknownRecord): void {
+  if (
+    state.sessionId !== saved.sessionId ||
+    state.sessionFile !== saved.sessionFile ||
+    state.sessionName !== saved.name ||
+    state.isStreaming !== false ||
+    state.pendingMessageCount !== 0 ||
+    !isRecord(state.model)
+  ) {
+    throw new Fault(503, "readiness_failed", "Pi did not start idle with the exact saved session.");
+  }
+  if (
+    saved.model &&
+    (state.model.provider !== saved.model.provider || state.model.id !== saved.model.modelId)
+  ) {
+    throw new Fault(
+      503,
+      "model_restore_failed",
+      "Pi could not restore the saved model exactly; no task submitted and no silent fallback allowed.",
+    );
+  }
+}
+function journal(manager: Readonly<SessionManager>): LaunchJournal {
+  const sessionFile = manager.getSessionFile();
+  if (sessionFile === undefined) {
+    throw new Fault(503, "journal_invalid", "Native journal was not persisted.");
+  }
+  const branch = manager.getBranch();
+  const change = branch.findLast((entry) => entry.type === "model_change");
+  const model =
+    change?.type === "model_change"
+      ? { provider: change.provider, modelId: change.modelId }
+      : (manager.buildSessionContext().model ?? undefined);
+  return {
+    sessionId: manager.getSessionId(),
+    peerId: nativePeerId(manager.getSessionId()),
+    sessionFile,
+    name: manager.getSessionName(),
+    cwd: manager.getCwd(),
+    model,
+  };
+}
+export async function createLaunchJournal(
+  policy: LaunchPolicy,
+  target: { readonly cwd: string; readonly name: string },
+  signal: AbortSignal,
+): Promise<LaunchJournal> {
+  const { SessionManager: Manager } = await wait(loadNativeSession(policy.packageRoot), signal);
+  cancelled(signal);
+  const storage = statSync(policy.sessionDir);
+  if (
+    !storage.isDirectory() ||
+    storage.uid !== process.getuid?.() ||
+    (storage.mode & 0o777) !== 0o700
+  ) {
+    throw new Fault(503, "storage_invalid", "Private launch storage is no longer valid.");
+  }
+  const previous = process.umask(0o077);
+  try {
+    const manager = Manager.create(target.cwd, policy.sessionDir);
+    manager.appendSessionInfo(target.name);
+    if (policy.provider !== undefined && policy.model !== undefined) {
+      manager.appendModelChange(policy.provider, policy.model);
+    }
+    manager.appendMessage({ role: "user", content: policy.context, timestamp: Date.now() });
+    const result = journal(manager);
+    trustedJournal(policy, result.sessionFile);
+    if ((statSync(result.sessionFile).mode & 0o777) !== 0o600) {
+      throw new Fault(503, "journal_invalid", "New native journal was not privately persisted.");
+    }
+    return result;
+  } finally {
+    process.umask(previous);
+  }
+}
+export async function resumeLaunchJournal(
+  policy: LaunchPolicy,
+  saved: LaunchJournal,
+  signal: AbortSignal,
+): Promise<LaunchJournal> {
+  const sdk = await wait(loadNativeSession(policy.packageRoot), signal);
+  cancelled(signal);
+  trustedJournal(policy, saved.sessionFile);
+  validateResumeIdentity(saved, await inspectResumeIdentity(saved.sessionFile, sdk, signal));
+  cancelled(signal);
+  const result = journal(sdk.SessionManager.open(saved.sessionFile));
+  validateResumeIdentity(saved, result);
+  return result;
+}
+function validateResumeIdentity(
+  saved: LaunchJournal,
+  actual: Pick<LaunchJournal, "sessionId" | "cwd" | "name">,
+): void {
+  if (
+    actual.sessionId !== saved.sessionId ||
+    actual.cwd !== saved.cwd ||
+    actual.name !== saved.name
+  ) {
+    throw new Fault(
+      409,
+      "journal_changed",
+      "Native session identity changed while preparing resume.",
+    );
+  }
+}

package/src/pi-intercom/bridge-launch-policy.ts

@@ -1,14 +1,16 @@
 import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 import { isRecord, isUnknownArray } from "../shared/unknown.ts";
-import { label, object, text } from "./bridge-protocol.ts";
+import { Fault, label, object, text } from "./bridge-protocol.ts";
 
 export interface LaunchPolicy {
   readonly packageRoot: string;
   readonly cli: string;
   readonly sessionDir: string;
-  readonly provider: string;
-  readonly model: string;
+  readonly provider?: string;
+  readonly model?: string;
+  readonly workspaceRoots: readonly string[];
+  readonly resumeDirs: readonly string[];
   readonly context: string;
   readonly extensions: readonly string[];
   readonly discoverResources: boolean;
@@ -52,8 +54,8 @@ function executable(packageRoot: string): string {
   }
   const bin = label(manifest.bin.pi, "Pi manifest bin", 4096);
   const cli = realpathSync(join(packageRoot, bin));
-  const within = relative(packageRoot, cli);
-  if (within.startsWith("..") || isAbsolute(within) || !statSync(cli).isFile()) {
+  const suffix = relative(packageRoot, cli);
+  if (suffix.startsWith("..") || isAbsolute(suffix) || !statSync(cli).isFile()) {
     throw new Error("Pi bin must be a file inside the pinned package.");
   }
   return cli;
@@ -65,6 +67,78 @@ function extensions(value: unknown): readonly string[] {
   return value.map((entry) => absolute(entry, "extension path"));
 }
 
+function directories(value: unknown, owned = true): readonly string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!isUnknownArray(value) || value.length > 32) {
+    throw new Error("Launch roots must contain at most 32 local directories.");
+  }
+  return [
+    ...new Set(
+      value.map((entry) => {
+        const path = absolute(entry, "trusted root");
+        const stat = lstatSync(path);
+        if (!stat.isDirectory() || (owned && stat.uid !== process.getuid?.())) {
+          throw new Error("Launch roots must be owned directories.");
+        }
+        return path;
+      }),
+    ),
+  ];
+}
+
+export function within(root: string, path: string): boolean {
+  const suffix = relative(root, path);
+  return (
+    suffix !== ".." &&
+    !suffix.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) &&
+    !isAbsolute(suffix)
+  );
+}
+export function launchCwd(policy: LaunchPolicy, requested: string): string {
+  if (!isAbsolute(requested)) {
+    throw new Fault(400, "invalid_cwd", "cwd must be an absolute approved workspace directory.");
+  }
+  let cwd: string;
+  try {
+    cwd = realpathSync(requested);
+    if (!statSync(cwd).isDirectory()) {
+      throw new Error("Not a directory");
+    }
+  } catch {
+    throw new Fault(400, "invalid_cwd", "cwd must be an existing workspace directory.");
+  }
+  if (!policy.workspaceRoots.some((root) => within(root, cwd))) {
+    throw new Fault(403, "cwd_forbidden", "cwd is outside locally approved workspaceRoots.");
+  }
+  return cwd;
+}
+
+export function spawnPolicy(
+  policy: LaunchPolicy,
+  input: { readonly provider?: string; readonly model?: string },
+): LaunchPolicy {
+  if (input.model === undefined) {
+    if (input.provider !== undefined) {
+      throw new Fault(400, "invalid_input", "Spawn provider requires model.");
+    }
+    return policy;
+  }
+  // Native provider/model convention splits at the first slash; model IDs may contain further slashes.
+  const slash = input.model.indexOf("/");
+  const provider = input.provider ?? (slash > 0 ? input.model.slice(0, slash) : policy.provider);
+  const model =
+    input.provider === undefined && slash > 0 ? input.model.slice(slash + 1) : input.model;
+  if (provider === undefined || provider.trim() === "" || model.trim() === "") {
+    throw new Fault(
+      400,
+      "invalid_input",
+      "Use an exact provider/model reference or a provider and model pair.",
+    );
+  }
+  return { ...policy, provider: provider.trim(), model: model.trim() };
+}
 export function launchPolicy(value: unknown): LaunchPolicy | undefined {
   if (value === undefined) {
     return;
@@ -81,6 +155,8 @@ export function launchPolicy(value: unknown): LaunchPolicy | undefined {
     "offline",
     "maxSessions",
     "startupTimeoutMs",
+    "workspaceRoots",
+    "resumeDirs",
   ]);
   const packageRoot = absolute(raw.packageRoot, "Pi package root");
   const sessionDir = absolute(raw.sessionDir, "session directory");
@@ -92,12 +168,17 @@ export function launchPolicy(value: unknown): LaunchPolicy | undefined {
   ) {
     throw new Error("Launch storage must be an owned directory with mode 0700.");
   }
+  if ((raw.provider === undefined) !== (raw.model === undefined)) {
+    throw new Error("Launch provider and model must both be supplied or both omitted.");
+  }
   return {
     packageRoot,
     cli: executable(packageRoot),
     sessionDir,
-    provider: label(raw.provider, "provider", 128),
-    model: label(raw.model, "model", 256),
+    provider: raw.provider === undefined ? undefined : label(raw.provider, "provider", 128),
+    model: raw.model === undefined ? undefined : label(raw.model, "model", 256),
+    workspaceRoots: directories(raw.workspaceRoots, false),
+    resumeDirs: directories(raw.resumeDirs),
     context: text(raw.context),
     extensions: extensions(raw.extensions),
     discoverResources: boolean(raw.discoverResources, false),