@sars267/pi-delegation-broker 0.1.0-alpha.0

package/src/supervisor.mjs

@@ -0,0 +1,278 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { SqliteLeaseBroker } from "./broker.mjs";
+import { BrokerIpcServer } from "./ipc.mjs";
+import { verifySignedRegistry } from "./signed-registry.mjs";
+
+const SOCKET_NAME = "broker.sock";
+const DATABASE_NAME = "broker.sqlite";
+const LOCK_NAME = "broker.lock";
+// macOS permits roughly 104 bytes for a Unix-domain socket path; stay below
+// the narrower common limit so startup fails clearly instead of listen(EINVAL).
+const MAX_SOCKET_PATH_BYTES = 100;
+
+function requireOwnerOnlyDirectory(path) {
+  if (typeof path !== "string" || !isAbsolute(path)) throw new Error("Broker stateDir must be an absolute path");
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const link = lstatSync(path);
+  if (link.isSymbolicLink()) throw new Error("Broker stateDir must not be a symbolic link");
+  const canonical = realpathSync(path);
+  const stat = statSync(canonical);
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0) {
+    throw new Error(`Broker stateDir must be an owner-only directory: ${canonical}`);
+  }
+  return canonical;
+}
+
+function rejectUnsafeExistingFile(path, label) {
+  if (!existsSync(path)) return;
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Broker ${label} must be a regular non-symlink file: ${path}`);
+}
+
+function hardenFile(path) {
+  if (existsSync(path)) chmodSync(path, 0o600);
+}
+
+function validateControllerToken(token) {
+  if (typeof token !== "string" || token.length < 32 || token.length > 512 || /[\0\r\n]/.test(token)) {
+    throw new Error("Broker controller token must be a bounded non-empty secret of at least 32 characters");
+  }
+  return token;
+}
+
+function deepFreeze(value) {
+  if (Array.isArray(value)) value.forEach(deepFreeze);
+  else if (value && typeof value === "object") Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+/**
+ * Lifecycle owner for the current single-host fake broker MVP.
+ *
+ * It establishes one fail-closed owner-only state directory, a durable SQLite
+ * ledger, a private Unix socket, periodic lease expiry and a bounded shutdown.
+ * It intentionally is not a detached production daemon: the controller keeps
+ * the object and its bootstrap token in-process. It has no provider client or
+ * credential path.
+ */
+export class SingleHostBrokerSupervisor {
+  #stateDir;
+  #registry;
+  #registryStatus;
+  #controllerToken;
+  #fakeProvider;
+  #sweepIntervalMs;
+  #shutdownDrainMs;
+  #instanceId = randomUUID();
+  #broker;
+  #server;
+  #sweepTimer;
+  #state = "new";
+  #startedAt;
+  #lastSweepAt;
+  #lastSweepError;
+
+  constructor({
+    stateDir,
+    registry,
+    signedRegistry,
+    trustedRegistryKeys,
+    /** Explicit test-only escape hatch. Production callers must use signedRegistry. */
+    allowUnsignedFixture = false,
+    controllerToken = randomBytes(32).toString("base64url"),
+    fakeProvider,
+    sweepIntervalMs = 1_000,
+    shutdownDrainMs = 2_000,
+  }) {
+    if (signedRegistry !== undefined && registry !== undefined) {
+      throw new Error("Broker supervisor accepts either signedRegistry or unsigned fixture registry, not both");
+    }
+    if (signedRegistry !== undefined) {
+      const verified = verifySignedRegistry(signedRegistry, { trustedKeys: trustedRegistryKeys });
+      this.#registry = verified.brokerRegistry;
+      this.#registryStatus = Object.freeze({
+        source: "signed",
+        keyId: verified.keyId,
+        registryVersion: verified.registryVersion,
+        fingerprint: verified.fingerprint,
+        expiresAt: verified.expiresAt,
+      });
+    } else {
+      if (!allowUnsignedFixture || !registry) {
+        throw new Error("Broker supervisor requires a signedRegistry; unsigned fixture registry needs allowUnsignedFixture: true");
+      }
+      this.#registry = registry;
+      this.#registryStatus = Object.freeze({ source: "unsigned_fixture" });
+    }
+    this.#stateDir = requireOwnerOnlyDirectory(stateDir);
+    if (Buffer.byteLength(join(this.#stateDir, SOCKET_NAME)) > MAX_SOCKET_PATH_BYTES) {
+      throw new Error(`Broker stateDir makes Unix socket path exceed ${MAX_SOCKET_PATH_BYTES} bytes`);
+    }
+    if (!Number.isInteger(sweepIntervalMs) || sweepIntervalMs < 100 || sweepIntervalMs > 60_000) {
+      throw new Error("Broker sweepIntervalMs must be an integer between 100 and 60000");
+    }
+    if (!Number.isInteger(shutdownDrainMs) || shutdownDrainMs < 0 || shutdownDrainMs > 60_000) {
+      throw new Error("Broker shutdownDrainMs must be an integer between 0 and 60000");
+    }
+    this.#controllerToken = validateControllerToken(controllerToken);
+    this.#fakeProvider = fakeProvider;
+    this.#sweepIntervalMs = sweepIntervalMs;
+    this.#shutdownDrainMs = shutdownDrainMs;
+  }
+
+  get stateDir() { return this.#stateDir; }
+  get socketPath() { return join(this.#stateDir, SOCKET_NAME); }
+  get databasePath() { return join(this.#stateDir, DATABASE_NAME); }
+  /** Controller-only bootstrap capability; never put this in a child policy. */
+  get controllerToken() { return this.#controllerToken; }
+
+  /** Controller-local redacted read-only state; never exposed through child IPC. */
+  auditSnapshot() {
+    if (!this.#broker) throw new Error("Broker supervisor is not running");
+    return deepFreeze(structuredClone({ leases: this.#broker.leases(), events: this.#broker.events() }));
+  }
+
+  status() {
+    return Object.freeze({
+      state: this.#state,
+      stateDir: this.#stateDir,
+      registry: this.#registryStatus,
+      ...(this.#state === "running" ? { socketPath: this.socketPath, startedAt: this.#startedAt, lastSweepAt: this.#lastSweepAt } : {}),
+      ...(this.#lastSweepError ? { lastSweepError: "broker_sweep_failed" } : {}),
+    });
+  }
+
+  async start() {
+    if (this.#state !== "new") throw new Error(`Broker supervisor cannot start from state ${this.#state}`);
+    this.#state = "starting";
+    try {
+      this.#acquireLock();
+      rejectUnsafeExistingFile(this.databasePath, "database");
+      this.#broker = new SqliteLeaseBroker({ path: this.databasePath, registry: this.#registry });
+      hardenFile(this.databasePath);
+      this.#server = new BrokerIpcServer({
+        broker: this.#broker,
+        socketPath: this.socketPath,
+        controllerToken: this.#controllerToken,
+        ...(this.#fakeProvider === undefined ? {} : { fakeProvider: this.#fakeProvider }),
+      });
+      await this.#server.start();
+      // SQLite may create WAL/SHM beside the DB. The owner-only directory is
+      // the primary protection; harden files too when present.
+      hardenFile(this.databasePath);
+      hardenFile(`${this.databasePath}-wal`);
+      hardenFile(`${this.databasePath}-shm`);
+      this.#startedAt = Date.now();
+      this.#runSweep();
+      this.#sweepTimer = setInterval(() => this.#runSweep(), this.#sweepIntervalMs);
+      this.#sweepTimer.unref?.();
+      this.#state = "running";
+      return this.status();
+    } catch (error) {
+      await this.#cleanupAfterFailedStart();
+      this.#state = "failed";
+      throw error;
+    }
+  }
+
+  async stop() {
+    if (this.#state === "stopped") return this.status();
+    if (this.#state !== "running" && this.#state !== "failed") {
+      throw new Error(`Broker supervisor cannot stop from state ${this.#state}`);
+    }
+    this.#state = "stopping";
+    clearInterval(this.#sweepTimer);
+    let failure;
+    try {
+      await this.#server?.stop({ drainMs: this.#shutdownDrainMs });
+    } catch (error) {
+      failure = error;
+    }
+    try {
+      this.#broker?.close();
+      this.#broker = undefined;
+    } catch (error) {
+      failure ??= error;
+    }
+    try {
+      this.#releaseOwnLock();
+    } catch (error) {
+      failure ??= error;
+    }
+    this.#state = "stopped";
+    if (failure) throw failure;
+    return this.status();
+  }
+
+  #lockPath() { return join(this.#stateDir, LOCK_NAME); }
+
+  #acquireLock() {
+    const lockPath = this.#lockPath();
+    rejectUnsafeExistingFile(lockPath, "lock");
+    let descriptor;
+    try {
+      descriptor = openSync(lockPath, "wx", 0o600);
+    } catch (error) {
+      if (error && typeof error === "object" && error.code === "EEXIST") {
+        throw new Error("Broker stateDir is already locked or has a stale lock; manual recovery is required");
+      }
+      throw error;
+    }
+    try {
+      writeFileSync(descriptor, `${JSON.stringify({ instanceId: this.#instanceId, pid: process.pid, startedAt: Date.now() })}\n`);
+      fsyncSync(descriptor);
+    } finally {
+      closeSync(descriptor);
+    }
+    hardenFile(lockPath);
+  }
+
+  #releaseOwnLock() {
+    const lockPath = this.#lockPath();
+    if (!existsSync(lockPath)) return;
+    rejectUnsafeExistingFile(lockPath, "lock");
+    let parsed;
+    try { parsed = JSON.parse(readFileSync(lockPath, "utf8")); } catch {
+      throw new Error("Broker lock contents are invalid; refusing to remove lock");
+    }
+    if (parsed?.instanceId !== this.#instanceId) {
+      throw new Error("Broker lock ownership changed; refusing to remove lock");
+    }
+    rmSync(lockPath);
+  }
+
+  #runSweep() {
+    try {
+      this.#broker?.expire(Date.now());
+      this.#lastSweepAt = Date.now();
+      this.#lastSweepError = undefined;
+    } catch {
+      // Status surfaces the failure without copying SQLite/path details into a
+      // child-visible channel or an audit event.
+      this.#lastSweepError = true;
+    }
+  }
+
+  async #cleanupAfterFailedStart() {
+    clearInterval(this.#sweepTimer);
+    try { await this.#server?.stop({ drainMs: 0 }); } catch { /* cleanup only */ }
+    try { this.#broker?.close(); } catch { /* cleanup only */ }
+    this.#broker = undefined;
+    try { this.#releaseOwnLock(); } catch { /* preserve uncertain lock */ }
+  }
+}

package/src/testing.mjs

@@ -0,0 +1,3 @@
+/** Test-only fixtures and deterministic fake transport. Never use as a real provider adapter. */
+export { ScriptedFakeProvider } from "./fake-provider.mjs";
+export { fixtureContract, fixtureRegistry } from "./broker.mjs";

package/src/trusted-launch-resolver.mjs

@@ -0,0 +1,194 @@
+import { existsSync, lstatSync, mkdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { provisionBrokeredAgentDir } from "./isolated-child-config.mjs";
+import { requestBrokerIpc } from "./ipc.mjs";
+
+const CHILD_ID = /^[A-Za-z0-9_-]{1,160}$/;
+
+function ownerOnlyDirectory(path, label) {
+  if (typeof path !== "string" || !isAbsolute(path)) throw new Error(`${label} must be an absolute path`);
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  if (lstatSync(path).isSymbolicLink()) throw new Error(`${label} must not be a symbolic link`);
+  const canonical = realpathSync(path);
+  const stat = statSync(canonical);
+  if (!stat.isDirectory() || (stat.mode & 0o077) !== 0) throw new Error(`${label} must be an owner-only directory`);
+  return canonical;
+}
+
+function expectedModel(selection) {
+  const model = selection?.expectedModel;
+  if (!model || typeof model.provider !== "string" || !model.provider || typeof model.modelId !== "string" || !model.modelId) {
+    throw new Error("Broker launch selection needs an explicit expectedModel");
+  }
+  return model;
+}
+
+/**
+ * Controller-side implementation of pi-subagent-workflow's trusted resolver.
+ * It is intentionally separate from child code: only this object can use the
+ * supervisor controller token to reserve/release; a child receives only the
+ * lease-scoped capability placed into its normalized launch policy.
+ */
+export class BrokeredLaunchResolver {
+  #socketPath;
+  #controllerToken;
+  #agentRoot;
+  #extensionPaths;
+  #offline;
+  #selectContract;
+  #admissions = new Map();
+
+  constructor({
+    socketPath,
+    controllerToken,
+    agentRoot,
+    extensionPaths,
+    offline = false,
+    selectContract,
+  }) {
+    if (typeof socketPath !== "string" || !isAbsolute(socketPath)) throw new Error("Broker launch resolver needs an absolute socketPath");
+    if (typeof controllerToken !== "string" || controllerToken.length < 32) throw new Error("Broker launch resolver needs a controller-only token");
+    if (!Array.isArray(extensionPaths) || extensionPaths.length === 0 || extensionPaths.some((path) => typeof path !== "string" || !isAbsolute(path))) {
+      throw new Error("Broker launch resolver needs non-empty absolute explicit extension paths");
+    }
+    if (typeof offline !== "boolean") throw new Error("Broker launch resolver offline must be boolean");
+    if (typeof selectContract !== "function") throw new Error("Broker launch resolver needs a controller selectContract function");
+    this.#socketPath = socketPath;
+    this.#controllerToken = controllerToken;
+    this.#agentRoot = ownerOnlyDirectory(agentRoot, "Broker child agent root");
+    this.#extensionPaths = Object.freeze([...extensionPaths]);
+    this.#offline = offline;
+    this.#selectContract = selectContract;
+  }
+
+  /** Compatible with TrustedChildLaunchResolver; request has no raw prompt. */
+  async resolve(request) {
+    if (!request || !CHILD_ID.test(request.childId ?? "")) throw new Error("Broker launch request has an invalid childId");
+    if (this.#admissions.has(request.childId)) return { action: "deny", reason: "duplicate child admission" };
+    const selection = await this.#selectContract(Object.freeze({ ...request }));
+    if (selection?.action === "deny") return { action: "deny", reason: safeReason(selection.reason) };
+    if (!selection?.contract) throw new Error("Broker launch selection did not return a contract");
+    const expected = expectedModel(selection);
+    if (request.model?.provider !== expected.provider || request.model?.modelId !== expected.modelId) {
+      return { action: "deny", reason: "resolved model is not approved for this broker contract" };
+    }
+
+    const reservation = await this.#controller("reserve", { contract: selection.contract });
+    if (reservation?.status !== "leased") return { action: "deny", reason: reservation?.status === "denied_capacity" ? "no compatible broker capacity" : "broker policy denied launch" };
+    const lease = reservation.lease;
+    let agentDir;
+    try {
+      const issued = await this.#controller("issueLeaseCapability", { leaseId: lease.leaseId, fencingToken: lease.fencingToken });
+      if (issued?.status !== "issued" || typeof issued.capability !== "string") throw new Error("Broker declined lease capability issuance");
+      agentDir = provisionBrokeredAgentDir(join(this.#agentRoot, request.childId)).agentDir;
+      const admission = { lease, agentDir, capability: issued.capability, phase: "pending_handoff" };
+      this.#admissions.set(request.childId, admission);
+      return {
+        action: "allow",
+        policy: {
+          policyId: lease.leaseId,
+          agentDir,
+          offline: this.#offline,
+          extensionPaths: this.#extensionPaths,
+          environment: {
+            PI_BROKER_SOCKET: this.#socketPath,
+            PI_BROKER_LEASE_ID: lease.leaseId,
+            PI_BROKER_FENCING_TOKEN: String(lease.fencingToken),
+            PI_BROKER_CAPABILITY: issued.capability,
+          },
+          onBeforeChildAbandoned: async () => this.releaseUnhanded(request.childId),
+          onChildSessionOpened: async () => this.markChildHanded(request.childId),
+          onChildSessionClosed: async () => this.finalizeHandedChild(request.childId),
+        },
+      };
+    } catch (error) {
+      await this.#releaseLease(lease).catch(() => undefined);
+      if (agentDir) this.#removeAgentDir(agentDir);
+      throw error;
+    }
+  }
+
+  /** Idempotent pre-handoff cleanup called only by the trusted parent runner. */
+  async releaseUnhanded(childId) {
+    return this.#releaseAdmission(childId, "release_pending");
+  }
+
+  /** Called after the trusted runner has a real ChildSession/process. */
+  async markChildHanded(childId) {
+    const admission = this.#admissions.get(childId);
+    if (!admission) return { status: "already_released" };
+    if (admission.phase === "pending_handoff") admission.phase = "handed";
+    return { status: admission.phase };
+  }
+
+  /** Idempotent post-session cleanup called only after trusted runner disposal. */
+  async finalizeHandedChild(childId) {
+    return this.#releaseAdmission(childId, "closed_release_pending");
+  }
+
+  /** Retry only records explicitly known to be unhanded or session-closed. */
+  async reconcilePendingReleases() {
+    const outcomes = [];
+    for (const [childId, admission] of this.#admissions) {
+      if (admission.phase !== "release_pending" && admission.phase !== "closed_release_pending") continue;
+      try {
+        outcomes.push(Object.freeze({ childId, ...(await this.#releaseAdmission(childId, admission.phase)) }));
+      } catch {
+        outcomes.push(Object.freeze({ childId, status: "pending" }));
+      }
+    }
+    return Object.freeze(outcomes);
+  }
+
+  /** Redacted controller-local visibility; capabilities/controller token stay private. */
+  admissions() {
+    return Object.freeze([...this.#admissions.entries()].map(([childId, admission]) => Object.freeze({
+      childId,
+      leaseId: admission.lease.leaseId,
+      fencingToken: admission.lease.fencingToken,
+      expiresAt: admission.lease.expiresAt,
+      phase: admission.phase,
+    })));
+  }
+
+  async #releaseAdmission(childId, pendingPhase) {
+    const admission = this.#admissions.get(childId);
+    if (!admission) return { status: "already_released" };
+    admission.phase = pendingPhase;
+    // Do not forget an admission before controller IPC confirms. On a broker
+    // transport failure the controller retains a redacted record and agent dir
+    // for explicit retry/reconciliation instead of silently relying on TTL.
+    await this.#releaseLease(admission.lease);
+    this.#removeAgentDir(admission.agentDir);
+    this.#admissions.delete(childId);
+    return { status: "released" };
+  }
+
+  async #controller(method, params) {
+    return requestBrokerIpc({
+      socketPath: this.#socketPath,
+      authorization: this.#controllerToken,
+      method,
+      params,
+    });
+  }
+
+  async #releaseLease(lease) {
+    await this.#controller("release", { leaseId: lease.leaseId, fencingToken: lease.fencingToken });
+  }
+
+  #removeAgentDir(agentDir) {
+    // agentDir was constructed from a validated child ID under the canonical
+    // root. Refuse a surprising path rather than recursively removing outside.
+    if (join(this.#agentRoot, agentDir.slice(this.#agentRoot.length + 1)) !== agentDir || !agentDir.startsWith(`${this.#agentRoot}/`)) {
+      throw new Error("Broker resolver refused to remove an agent directory outside its root");
+    }
+    if (existsSync(agentDir)) rmSync(agentDir, { recursive: true, force: true });
+  }
+}
+
+function safeReason(reason) {
+  if (typeof reason !== "string") return "broker policy denied launch";
+  // Denial enters a child-visible runner error; do not pass controller detail.
+  return /^[A-Za-z0-9 _.-]{1,120}$/.test(reason) ? reason : "broker policy denied launch";
+}