@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/src/host/controller-worker-supervisor.ts

@@ -0,0 +1,79 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { canonicalJson, type JsonValue } from "../state/json.js";
+import { ChildWorkerSupervisor, type SupervisedWorkerResult } from "./child-worker-supervisor.js";
+import {
+  encodeControllerWorkerLine,
+  parseControllerWorkerMessage,
+  type ControllerWorkerLaunchEnvelope,
+  type ControllerWorkerMessage,
+  type ControllerWorkerResponse,
+} from "./controller-worker-protocol.js";
+import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
+import type { WorkerOutcome } from "./state.js";
+
+export class ControllerWorkerSupervisor {
+  private readonly supervisor: ChildWorkerSupervisor<
+    ControllerWorkerMessage,
+    ControllerWorkerResponse
+  >;
+
+  constructor(
+    readonly envelope: ControllerWorkerLaunchEnvelope,
+    private readonly options: {
+      registry: HostProcessRegistry;
+      onMessage: (message: ControllerWorkerMessage) => Promise<ControllerWorkerResponse>;
+      env?: Record<string, string>;
+      startupTimeoutMs?: number;
+      workerEntryPath?: string;
+      onSpawn?: (identity: ProcessIdentity) => void;
+      onDiagnostic?: (message: string) => void;
+    },
+  ) {
+    this.supervisor = new ChildWorkerSupervisor({
+      label: "Controller worker",
+      registry: options.registry,
+      onMessage: options.onMessage,
+      parseMessage: parseControllerWorkerMessage,
+      encodeResponse: encodeControllerWorkerLine,
+      isReady: (message) => message.operation === "worker.ready",
+      isTerminal: (message) =>
+        message.operation === "worker.finished" || message.operation === "worker.failed",
+      ...(options.startupTimeoutMs === undefined
+        ? {}
+        : { startupTimeoutMs: options.startupTimeoutMs }),
+      ...(options.onSpawn === undefined ? {} : { onSpawn: options.onSpawn }),
+      ...(options.onDiagnostic === undefined ? {} : { onDiagnostic: options.onDiagnostic }),
+    });
+  }
+
+  async start(): Promise<void> {
+    const builtEntry = fileURLToPath(new URL("./controller-worker-entry.js", import.meta.url));
+    const sourceEntry = fileURLToPath(new URL("./controller-worker-entry.ts", import.meta.url));
+    const workerEntry = this.options.workerEntryPath ?? builtEntry;
+    const args =
+      this.options.workerEntryPath === undefined && !fs.existsSync(builtEntry)
+        ? ["--import", createRequire(import.meta.url).resolve("tsx"), sourceEntry]
+        : [workerEntry];
+    await this.supervisor.start({
+      args,
+      cwd: this.envelope.projectPath,
+      env: {
+        ...process.env,
+        ...this.options.env,
+        PI_WORKFLOWS_CONTROLLER_WORKER_LAUNCH: Buffer.from(
+          canonicalJson(this.envelope as unknown as JsonValue),
+        ).toString("base64url"),
+      },
+    });
+  }
+
+  async wait(): Promise<SupervisedWorkerResult> {
+    return await this.supervisor.wait();
+  }
+
+  async stop(outcome: WorkerOutcome = "cancelled"): Promise<void> {
+    await this.supervisor.stop(outcome);
+  }
+}

package/src/host/host-entry.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { errorMessage } from "../workflows/errors.js";
+import { WorkflowHost } from "./runner.js";
+
+async function main(): Promise<void> {
+  const databaseIndex = process.argv.indexOf("--database");
+  const databasePath = databaseIndex < 0 ? undefined : process.argv[databaseIndex + 1];
+  const host = new WorkflowHost({
+    ...(databasePath === undefined ? {} : { databasePath }),
+    onLog: (message) => process.stderr.write(`[pi-workflows host] ${message}\n`),
+  });
+  const shutdown = () => void host.stop();
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  try {
+    await host.start();
+  } catch (error) {
+    process.stderr.write(`${errorMessage(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+void main();

package/src/host/processes.ts

@@ -1,111 +1,228 @@
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 
+export type ProcessIdentity = {
+  pid: number;
+  startIdentity: string;
+};
+
+type ProcessRegistryFile = {
+  schema: "pi-workflows.process-registry.v1";
+  processes: ProcessIdentity[];
+};
+
 /**
- * Tracks headless child processes (spawned `pi --mode rpc` sessions) so a
- * killed host never leaves orphans working. Children spawn in their own
- * process group; the registry file lets a later host reap leftovers by
- * killing the whole group. The file lives next to the project store and is
- * only ever touched by one host at a time (the advisory lock ensures it).
+ * Tracks supervised process groups by PID and operating-system start identity.
+ * A later host kills a recorded process only when both values still match.
  */
 export class HostProcessRegistry {
   private readonly filePath: string;
-  private readonly pids = new Set<number>();
+  private readonly processes = new Map<number, ProcessIdentity>();
 
   constructor(storeDir: string) {
     this.filePath = path.join(storeDir, "host.children.json");
   }
 
-  register(pid: number): void {
-    this.pids.add(pid);
+  register(pid: number): ProcessIdentity {
+    const startIdentity = processStartIdentity(pid);
+    if (startIdentity === undefined) {
+      throw new Error(`Cannot attest supervised process start identity: ${pid}`);
+    }
+    const identity = { pid, startIdentity };
+    this.processes.set(pid, identity);
     this.persist();
+    return identity;
   }
 
   unregister(pid: number): void {
-    this.pids.delete(pid);
+    this.processes.delete(pid);
     this.persist();
   }
 
   get size(): number {
-    return this.pids.size;
+    return this.processes.size;
+  }
+
+  /** Kill one exact registered process group and remove its durable record. */
+  kill(pid: number): boolean {
+    const identity = this.processes.get(pid);
+    if (identity === undefined) return false;
+    if (matchesProcessIdentity(identity)) {
+      killProcessGroup(identity.pid, "SIGTERM");
+      if (matchesProcessIdentity(identity)) killProcessGroup(identity.pid, "SIGKILL");
+    }
+    this.processes.delete(pid);
+    this.persist();
+    return true;
   }
 
-  /** Kill every registered child's process group, escalating to SIGKILL. */
+  /** Kill every process that still has its registered start identity. */
   killAll(): void {
-    for (const pid of this.pids) {
-      killProcessGroup(pid, "SIGTERM");
+    for (const identity of this.processes.values()) {
+      if (matchesProcessIdentity(identity)) killProcessGroup(identity.pid, "SIGTERM");
     }
-    for (const pid of this.pids) {
-      killProcessGroup(pid, "SIGKILL");
+    for (const identity of this.processes.values()) {
+      if (matchesProcessIdentity(identity)) killProcessGroup(identity.pid, "SIGKILL");
     }
-    this.pids.clear();
+    this.processes.clear();
     this.persist();
   }
 
-  /**
-   * Reap children recorded by a previous host that died without cleanup.
-   * Called once at host start, before the lock is taken.
-   */
+  /** Reap only exact stale process identities recorded by an older host. */
   reapOrphans(): number[] {
     const recorded = this.readFile();
     const reaped: number[] = [];
-    const stillAlive: number[] = [];
-    for (const pid of recorded) {
-      if (isAlive(pid)) {
-        killProcessGroup(pid, "SIGKILL");
-        reaped.push(pid);
-        if (isAlive(pid)) {
-          // A group kill that left the leader alive stays registered so a
-          // later start tries again instead of forgetting it.
-          stillAlive.push(pid);
-        }
-      }
-    }
-    this.pids.clear();
-    for (const pid of stillAlive) {
-      this.pids.add(pid);
+    const stillAlive: ProcessIdentity[] = [];
+    for (const identity of recorded) {
+      if (!matchesProcessIdentity(identity)) continue;
+      killProcessGroup(identity.pid, "SIGKILL");
+      reaped.push(identity.pid);
+      if (matchesProcessIdentity(identity)) stillAlive.push(identity);
     }
+    this.processes.clear();
+    for (const identity of stillAlive) this.processes.set(identity.pid, identity);
     this.persist();
     return reaped;
   }
 
-  private readFile(): number[] {
+  private readFile(): ProcessIdentity[] {
     try {
       const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf8")) as unknown;
-      if (!Array.isArray(parsed)) {
-        return [];
-      }
-      return parsed.filter((pid): pid is number => Number.isSafeInteger(pid) && pid > 0);
+      if (!isRegistryFile(parsed)) return [];
+      return parsed.processes;
     } catch {
       return [];
     }
   }
 
   private persist(): void {
+    fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
+    const file: ProcessRegistryFile = {
+      schema: "pi-workflows.process-registry.v1",
+      processes: [...this.processes.values()].sort((left, right) => left.pid - right.pid),
+    };
+    const temporary = `${this.filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(file)}\n`, { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(temporary, this.filePath);
+    fs.chmodSync(this.filePath, 0o600);
+  }
+}
+
+/** Return the operating-system parent PID for a live process. */
+export function processParentPid(pid: number): number | undefined {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
+  if (process.platform === "linux") {
     try {
-      fs.mkdirSync(path.dirname(this.filePath), { recursive: true, mode: 0o700 });
-      // Write exactly the live set. Unioning with the previous file would
-      // resurrect exited pids, and a later host reaping them could kill an
-      // unrelated process group that reused one.
-      fs.writeFileSync(this.filePath, `${JSON.stringify([...this.pids])}\n`, {
-        encoding: "utf8",
-        mode: 0o600,
-      });
+      const fields = linuxStatFields(pid);
+      const parentPid = Number(fields[1]);
+      return Number.isSafeInteger(parentPid) && parentPid > 0 ? parentPid : undefined;
     } catch {
-      // Registry bookkeeping is best-effort; orphan reaping is the backstop.
+      return undefined;
     }
   }
+  if (process.platform === "win32") {
+    try {
+      const parentPid = Number(
+        execFileSync(
+          "powershell.exe",
+          [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").ParentProcessId`,
+          ],
+          { encoding: "utf8", timeout: 2_000, windowsHide: true },
+        ).trim(),
+      );
+      return Number.isSafeInteger(parentPid) && parentPid > 0 ? parentPid : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  try {
+    const parentPid = Number(
+      execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: 2_000,
+      }).trim(),
+    );
+    return Number.isSafeInteger(parentPid) && parentPid > 0 ? parentPid : undefined;
+  } catch {
+    return undefined;
+  }
 }
 
-function isAlive(pid: number): boolean {
+/** Return an operating-system process start value that fences PID reuse. */
+export function processStartIdentity(pid: number): string | undefined {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return undefined;
+  if (process.platform === "linux") {
+    try {
+      const startTicks = linuxStatFields(pid)[19];
+      if (startTicks !== undefined) return `linux-proc-start:${startTicks}`;
+    } catch {
+      return undefined;
+    }
+  }
+  if (process.platform === "win32") {
+    try {
+      const ticks = execFileSync(
+        "powershell.exe",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+        ],
+        { encoding: "utf8", timeout: 2_000, windowsHide: true },
+      ).trim();
+      return ticks.length === 0 ? undefined : `windows-start-ticks:${ticks}`;
+    } catch {
+      return undefined;
+    }
+  }
   try {
-    process.kill(pid, 0);
-    return true;
+    const started = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 2_000,
+    }).trim();
+    return started.length === 0 ? undefined : `${process.platform}-ps-start:${started}`;
   } catch {
-    return false;
+    return undefined;
   }
 }
 
+function linuxStatFields(pid: number): string[] {
+  const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+  const commandEnd = stat.lastIndexOf(")");
+  if (commandEnd < 0) throw new Error(`Linux process stat is invalid: ${pid}`);
+  return stat
+    .slice(commandEnd + 2)
+    .trim()
+    .split(/\s+/);
+}
+
+export function matchesProcessIdentity(identity: ProcessIdentity): boolean {
+  return processStartIdentity(identity.pid) === identity.startIdentity;
+}
+
+function isRegistryFile(value: unknown): value is ProcessRegistryFile {
+  if (!isRecord(value) || value.schema !== "pi-workflows.process-registry.v1") return false;
+  if (!Array.isArray(value.processes)) return false;
+  return value.processes.every(
+    (entry) =>
+      isRecord(entry) &&
+      Number.isSafeInteger(entry.pid) &&
+      (entry.pid as number) > 0 &&
+      typeof entry.startIdentity === "string" &&
+      entry.startIdentity.length > 0,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function killProcessGroup(pid: number, signal: NodeJS.Signals): void {
   try {
     process.kill(-pid, signal);
@@ -113,7 +230,7 @@ function killProcessGroup(pid: number, signal: NodeJS.Signals): void {
     try {
       process.kill(pid, signal);
     } catch {
-      // Already gone.
+      // The exact process has already exited.
     }
   }
 }

package/src/host/protocol.ts

@@ -0,0 +1,196 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+
+export const HOST_PROTOCOL_VERSION = 1;
+export const HOST_REQUEST_SCHEMA = "pi-workflows.host-request.v1" as const;
+export const HOST_RESPONSE_SCHEMA = "pi-workflows.host-response.v1" as const;
+export const MAX_PROTOCOL_MESSAGE_BYTES = 1024 * 1024;
+
+export const HOST_OPERATIONS = [
+  "run.start",
+  "run.pause",
+  "run.resume",
+  "run.cancel",
+  "run.status",
+  "run.list",
+  "checkpoint.answer",
+  "decision.answer",
+  "interaction.submit",
+  "interaction.update",
+  "notification.claim",
+  "notification.deliver",
+  "turn.claim",
+  "turn.resolve",
+  "controller.list",
+  "controller.get",
+  "controller.apply",
+  "controller.reconcile",
+  "controller.delete",
+  "host.status",
+  "host.stop",
+] as const;
+
+export type HostOperation = (typeof HOST_OPERATIONS)[number];
+export type HostOutcome =
+  | "accepted"
+  | "adopted"
+  | "rejected"
+  | "conflict"
+  | "notFound"
+  | "claimLost"
+  | "unavailable";
+
+export type HostRequest = {
+  schema: typeof HOST_REQUEST_SCHEMA;
+  requestId: string;
+  clientId: string;
+  operation: HostOperation;
+  idempotencyKey: string;
+  runId?: string;
+  expectedRevision?: number;
+  payload: JsonValue;
+};
+
+export type HostResponse = {
+  schema: typeof HOST_RESPONSE_SCHEMA;
+  requestId: string;
+  outcome: HostOutcome;
+  revision?: number;
+  receipt?: JsonValue;
+  error?: string;
+};
+
+export class HostProtocolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "HostProtocolError";
+  }
+}
+
+export function encodeProtocolLine(message: HostRequest | HostResponse): Buffer {
+  const encoded = Buffer.from(`${canonicalJson(message)}\n`, "utf8");
+  if (encoded.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new HostProtocolError("Host protocol message exceeds 1 MiB");
+  }
+  return encoded;
+}
+
+export function parseHostRequest(line: string | Buffer): HostRequest {
+  const value = parseProtocolValue(line);
+  if (value.schema !== HOST_REQUEST_SCHEMA)
+    throw new HostProtocolError("Invalid host request schema");
+  requireOpaqueId(value.requestId, "requestId");
+  requireOpaqueId(value.clientId, "clientId");
+  requireOpaqueId(value.idempotencyKey, "idempotencyKey");
+  if (!HOST_OPERATIONS.includes(value.operation as HostOperation)) {
+    throw new HostProtocolError("Invalid host request operation");
+  }
+  if (value.runId !== undefined) requireOpaqueId(value.runId, "runId");
+  if (
+    value.expectedRevision !== undefined &&
+    (!Number.isSafeInteger(value.expectedRevision) || (value.expectedRevision as number) < 0)
+  ) {
+    throw new HostProtocolError("Host request expectedRevision must be a non-negative integer");
+  }
+  if (!Object.hasOwn(value, "payload"))
+    throw new HostProtocolError("Host request payload is required");
+  canonicalJson(value.payload);
+  return value as HostRequest;
+}
+
+export function parseHostResponse(line: string | Buffer): HostResponse {
+  const value = parseProtocolValue(line);
+  if (value.schema !== HOST_RESPONSE_SCHEMA) {
+    throw new HostProtocolError("Invalid host response schema");
+  }
+  requireOpaqueId(value.requestId, "requestId");
+  const outcomes: HostOutcome[] = [
+    "accepted",
+    "adopted",
+    "rejected",
+    "conflict",
+    "notFound",
+    "claimLost",
+    "unavailable",
+  ];
+  if (!outcomes.includes(value.outcome as HostOutcome)) {
+    throw new HostProtocolError("Invalid host response outcome");
+  }
+  if (
+    value.revision !== undefined &&
+    (!Number.isSafeInteger(value.revision) || (value.revision as number) < 0)
+  ) {
+    throw new HostProtocolError("Host response revision must be a non-negative integer");
+  }
+  if (value.error !== undefined && typeof value.error !== "string") {
+    throw new HostProtocolError("Host response error must be text");
+  }
+  if (value.receipt !== undefined) canonicalJson(value.receipt);
+  return value as HostResponse;
+}
+
+export function requestFingerprint(request: HostRequest): Buffer {
+  return createHash("sha256").update(canonicalJson(request)).digest();
+}
+
+export function hostSocketPath(databasePath: string): string {
+  const stateDirectory = path.dirname(path.resolve(databasePath));
+  if (process.platform === "win32") {
+    const suffix = createHash("sha256").update(stateDirectory).digest("hex").slice(0, 24);
+    return `\\\\.\\pipe\\pi-workflows-${suffix}`;
+  }
+  return path.join(stateDirectory, "host", "host.sock");
+}
+
+export class NdjsonFrameDecoder {
+  private buffered = Buffer.alloc(0);
+
+  push(chunk: Buffer): Buffer[] {
+    this.buffered = Buffer.concat([this.buffered, chunk]);
+    if (this.buffered.byteLength > MAX_PROTOCOL_MESSAGE_BYTES && !this.buffered.includes(0x0a)) {
+      throw new HostProtocolError("Host protocol message exceeds 1 MiB");
+    }
+    const frames: Buffer[] = [];
+    for (;;) {
+      const newline = this.buffered.indexOf(0x0a);
+      if (newline < 0) break;
+      const frame = this.buffered.subarray(0, newline);
+      this.buffered = this.buffered.subarray(newline + 1);
+      if (frame.byteLength === 0) continue;
+      if (frame.byteLength + 1 > MAX_PROTOCOL_MESSAGE_BYTES) {
+        throw new HostProtocolError("Host protocol message exceeds 1 MiB");
+      }
+      frames.push(frame);
+    }
+    return frames;
+  }
+}
+
+function parseProtocolValue(line: string | Buffer): Record<string, unknown> {
+  const buffer = Buffer.isBuffer(line) ? line : Buffer.from(line, "utf8");
+  if (buffer.byteLength + 1 > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new HostProtocolError("Host protocol message exceeds 1 MiB");
+  }
+  let value: unknown;
+  try {
+    value = parseJson(buffer.toString("utf8"));
+  } catch {
+    throw new HostProtocolError("Host protocol message is not valid canonical JSON");
+  }
+  if (!isRecord(value)) throw new HostProtocolError("Host protocol message must be an object");
+  if (canonicalJson(value) !== buffer.toString("utf8")) {
+    throw new HostProtocolError("Host protocol message must use canonical JSON");
+  }
+  return value;
+}
+
+function requireOpaqueId(value: unknown, field: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256) {
+    throw new HostProtocolError(`Host request ${field} must be nonempty text of at most 256 bytes`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}