@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/src/host/resolver-entry.ts

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { builtinWorkflowCatalog } from "../builtins/catalog.js";
+import { discoverControllers, loadControllerFile } from "../controllers/loader.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+import { compositionMetadata } from "../workflows/composition.js";
+import { errorMessage } from "../workflows/errors.js";
+import { validateWorkflowDefinition } from "../workflows/graph.js";
+import { resolveWorkflowRef } from "../workflows/loader.js";
+import { applyWorkflowSettingsPatch } from "../workflows/settings.js";
+import { createDefinitionSnapshot } from "../workflows/store.js";
+import type { WorkflowDefinition, WorkflowSource } from "../workflows/types.js";
+import { MAX_PROTOCOL_MESSAGE_BYTES } from "./protocol.js";
+
+export type ResolvedWorkflowLaunch = {
+  schema: "pi-workflows.resolved-launch.v1";
+  workflowName: string;
+  workflowSourceRef: string;
+  workflowSource: JsonValue;
+  definitionDigest: string;
+  definitionSnapshot: JsonValue;
+};
+
+export type ResolvedControllerInitialization = {
+  schema: "pi-workflows.resolved-controller-initialization.v1";
+  controllerName: string;
+  controllerPath: string;
+  sourceHash: string;
+  initialStatus: JsonValue;
+};
+
+export type ResolvedSettingsChange = {
+  schema: "pi-workflows.resolved-settings-change.v1";
+  definitionDigest: string;
+  patch: JsonValue;
+  settings: JsonValue;
+  paths: JsonValue;
+};
+
+type ResolverRequest = {
+  schema: "pi-workflows.resolve-request.v1";
+  cwd: string;
+  workflowRef: string;
+};
+
+type SettingsValidationRequest = {
+  schema: "pi-workflows.settings-validation-request.v1";
+  cwd: string;
+  workflowRef: string;
+  definitionDigest: string;
+  mountPath: string;
+  current: JsonValue;
+  patch: JsonValue;
+  actorId: string;
+};
+
+type ControllerInitializationRequest = {
+  schema: "pi-workflows.controller-initialization-request.v1";
+  cwd: string;
+  controllerName: string;
+  spec: JsonValue;
+};
+
+type ResolverInput = ResolverRequest | SettingsValidationRequest | ControllerInitializationRequest;
+type ResolverOutput =
+  | ResolvedWorkflowLaunch
+  | ResolvedSettingsChange
+  | ResolvedControllerInitialization;
+
+export async function resolveWorkflowLaunch(
+  request: ResolverRequest,
+): Promise<ResolvedWorkflowLaunch> {
+  if (request.schema !== "pi-workflows.resolve-request.v1") {
+    throw new Error("Invalid workflow resolver request schema");
+  }
+  const resolved = await loadResolvedWorkflow(request.cwd, request.workflowRef);
+  return {
+    schema: "pi-workflows.resolved-launch.v1",
+    workflowName: resolved.definition.name,
+    workflowSourceRef: sourceRef(resolved.source),
+    workflowSource: {
+      root: resolved.source,
+      mounted: compositionMetadata(resolved.definition)?.sources ?? [],
+    } as JsonValue,
+    definitionDigest: resolved.definitionDigest,
+    definitionSnapshot: resolved.snapshot,
+  };
+}
+
+export async function resolveControllerInitialization(
+  request: ControllerInitializationRequest,
+): Promise<ResolvedControllerInitialization> {
+  const discovered = (await discoverControllers({ cwd: request.cwd })).find(
+    (candidate) => candidate.name === request.controllerName,
+  );
+  if (discovered === undefined) {
+    throw new Error(`Controller not found: ${request.controllerName}`);
+  }
+  const definition = await loadControllerFile(discovered.path);
+  if (definition.name !== request.controllerName) {
+    throw new Error("Controller source name does not match its discovered name");
+  }
+  const initialStatus = parseJson(canonicalJson(definition.initialStatus(request.spec)));
+  const sourceHash = createHash("sha256")
+    .update(await fs.readFile(discovered.path))
+    .digest("hex");
+  return {
+    schema: "pi-workflows.resolved-controller-initialization.v1",
+    controllerName: definition.name,
+    controllerPath: discovered.path,
+    sourceHash,
+    initialStatus,
+  };
+}
+
+export async function resolveSettingsChange(
+  request: SettingsValidationRequest,
+): Promise<ResolvedSettingsChange> {
+  if (request.schema !== "pi-workflows.settings-validation-request.v1") {
+    throw new Error("Invalid workflow settings validation request schema");
+  }
+  const resolved = await loadResolvedWorkflow(request.cwd, request.workflowRef);
+  if (resolved.definitionDigest !== request.definitionDigest) {
+    throw new Error("Workflow source changed before the settings proposal was validated");
+  }
+  const definition = settingsDefinition(resolved.definition, request.mountPath);
+  if (definition === undefined) {
+    throw new Error(
+      `Workflow scope ${request.mountPath || "/"} does not declare editable settings`,
+    );
+  }
+  const applied = await applyWorkflowSettingsPatch(
+    definition,
+    request.current,
+    request.patch,
+    { type: "controller", id: request.actorId },
+    "controller-request",
+  );
+  return {
+    schema: "pi-workflows.resolved-settings-change.v1",
+    definitionDigest: resolved.definitionDigest,
+    patch: applied.patch as JsonValue,
+    settings: applied.json,
+    paths: definition.paths as unknown as JsonValue,
+  };
+}
+
+async function loadResolvedWorkflow(
+  cwd: string,
+  workflowRef: string,
+): Promise<{
+  definition: WorkflowDefinition;
+  source: WorkflowSource;
+  snapshot: JsonValue;
+  definitionDigest: string;
+}> {
+  const resolved = await resolveWorkflowRef(workflowRef, { cwd }, builtinWorkflowCatalog);
+  validateWorkflowDefinition(resolved.definition);
+  const snapshot = createDefinitionSnapshot(resolved.definition) as unknown as JsonValue;
+  const definitionDigest = `sha256:${createHash("sha256")
+    .update(canonicalJson(snapshot))
+    .digest("hex")}`;
+  return { definition: resolved.definition, source: resolved.source, snapshot, definitionDigest };
+}
+
+function settingsDefinition(definition: WorkflowDefinition, mountPath: string) {
+  return mountPath === ""
+    ? definition.settings
+    : compositionMetadata(definition)?.scopes[mountPath]?.settings;
+}
+
+function sourceRef(source: WorkflowSource): string {
+  return source.kind === "builtin" ? `builtin:${source.id}` : source.path;
+}
+
+async function readRequest(): Promise<ResolverInput> {
+  const chunks: Buffer[] = [];
+  let length = 0;
+  for await (const chunk of process.stdin) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    length += buffer.byteLength;
+    if (length > MAX_PROTOCOL_MESSAGE_BYTES) {
+      throw new Error("Workflow resolver request exceeds 1 MiB");
+    }
+    chunks.push(buffer);
+  }
+  const value = parseJson(Buffer.concat(chunks).toString("utf8").trimEnd());
+  if (!isRecord(value) || typeof value.cwd !== "string") {
+    throw new Error("Invalid source resolver request");
+  }
+  if (value.schema === "pi-workflows.resolve-request.v1" && typeof value.workflowRef === "string") {
+    return value as ResolverRequest;
+  }
+  if (
+    value.schema === "pi-workflows.controller-initialization-request.v1" &&
+    typeof value.controllerName === "string" &&
+    Object.hasOwn(value, "spec")
+  ) {
+    return value as ControllerInitializationRequest;
+  }
+  if (
+    value.schema === "pi-workflows.settings-validation-request.v1" &&
+    typeof value.workflowRef === "string" &&
+    typeof value.definitionDigest === "string" &&
+    typeof value.mountPath === "string" &&
+    typeof value.actorId === "string" &&
+    Object.hasOwn(value, "current") &&
+    Object.hasOwn(value, "patch")
+  ) {
+    return value as SettingsValidationRequest;
+  }
+  throw new Error("Invalid workflow resolver request schema");
+}
+
+async function main(): Promise<void> {
+  try {
+    const request = await readRequest();
+    const result: ResolverOutput =
+      request.schema === "pi-workflows.resolve-request.v1"
+        ? await resolveWorkflowLaunch(request)
+        : request.schema === "pi-workflows.controller-initialization-request.v1"
+          ? await resolveControllerInitialization(request)
+          : await resolveSettingsChange(request);
+    const encoded = `${canonicalJson(result)}\n`;
+    if (Buffer.byteLength(encoded) > MAX_PROTOCOL_MESSAGE_BYTES) {
+      throw new Error("Workflow resolver result exceeds 1 MiB");
+    }
+    process.stdout.write(encoded);
+  } catch (error) {
+    process.stderr.write(`${errorMessage(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) void main();

package/src/host/rpc-executor.ts

@@ -7,7 +7,6 @@ import type {
   AgentStepRequest,
   AgentStepSubmission,
 } from "../workflows/types.js";
-import type { HostProcessRegistry } from "./processes.js";
 import { RPC_SUBMISSION_PREFIX } from "./rpc-bridge.js";
 
 // Production resolves the compiled .js; tests and dev checkouts load the .ts
@@ -15,7 +14,7 @@ import { RPC_SUBMISSION_PREFIX } from "./rpc-bridge.js";
 const BRIDGE_PATH = ["./rpc-bridge.js", "./rpc-bridge.ts"]
   .map((candidate) => fileURLToPath(new URL(candidate, import.meta.url)))
   .find((candidate) => fs.existsSync(candidate));
-const ABORT_GRACE_MS = 3_000;
+const DEFAULT_ABORT_GRACE_MS = 3_000;
 
 type StepSubmission = {
   action: "submit";
@@ -34,9 +33,18 @@ type StepUpdate = {
 
 type StepAction = StepSubmission | StepUpdate;
 
+export interface SupervisedProcessRegistry {
+  register(pid: number): unknown | Promise<unknown>;
+  unregister(pid: number): unknown | Promise<unknown>;
+}
+
 export type RpcStepExecutorOptions = {
   cwd: string;
-  registry: HostProcessRegistry;
+  registry?: SupervisedProcessRegistry;
+  /** Start a separate process group, or inherit the caller's process group. */
+  processGroup?: "own" | "inherit";
+  /** Grace period before a process group receives SIGKILL. */
+  abortGraceMs?: number;
   /** Absolute path to the pi binary; defaults to the installed `pi`. */
   piBin?: string;
   /** Extra environment for the child; the host's environment is inherited. */
@@ -63,6 +71,8 @@ export class RpcStepExecutor implements AgentStepExecutor {
   private actions: StepAction[] = [];
   private submissionWaiters: Array<() => void> = [];
   private stdoutBuffer = "";
+  private registeredPid: number | null = null;
+  private closePromise: Promise<void> | null = null;
 
   constructor(options: RpcStepExecutorOptions) {
     this.options = options;
@@ -70,7 +80,7 @@ export class RpcStepExecutor implements AgentStepExecutor {
   }
 
   async runAgentStep(request: AgentStepRequest, signal: AbortSignal): Promise<AgentStepSubmission> {
-    this.ensureStarted();
+    await this.ensureStarted();
     let prompt = request.prompt;
     for (;;) {
       throwIfAborted(signal);
@@ -88,38 +98,41 @@ export class RpcStepExecutor implements AgentStepExecutor {
     }
   }
 
-  /** Stop the child's whole process group, then unregister it. */
+  /** Stop the child process tree, then unregister its exact group leader. */
   async close(): Promise<void> {
+    this.closePromise ??= this.closeChild();
+    await this.closePromise;
+  }
+
+  private async closeChild(): Promise<void> {
     const child = this.child;
     this.child = null;
-    if (child === null) {
-      return;
-    }
+    if (child === null) return;
     const pid = child.pid;
-    if (this.childExited === null) {
+    try {
       try {
         child.stdin?.end();
       } catch {
         // The pipe may already be closed.
       }
-      // The child spawns in its own group; tool calls can leave
-      // grandchildren that leader-only signals would orphan forever.
-      if (pid !== undefined) {
+      const ownGroup = this.options.processGroup !== "inherit";
+      if (pid !== undefined && ownGroup) {
         killGroup(pid, "SIGTERM");
-      } else {
+        const exited = await waitForGroupExit(
+          pid,
+          this.options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS,
+        );
+        if (!exited) killGroup(pid, "SIGKILL");
+      } else if (this.childExited === null) {
         child.kill("SIGTERM");
+        const exited = await waitForExit(
+          child,
+          this.options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS,
+        );
+        if (!exited) child.kill("SIGKILL");
       }
-      const exited = await waitForExit(child, ABORT_GRACE_MS);
-      if (!exited) {
-        if (pid !== undefined) {
-          killGroup(pid, "SIGKILL");
-        } else {
-          child.kill("SIGKILL");
-        }
-      }
-    }
-    if (pid !== undefined) {
-      this.options.registry.unregister(pid);
+    } finally {
+      await this.unregisterChild();
     }
   }
 
@@ -127,7 +140,8 @@ export class RpcStepExecutor implements AgentStepExecutor {
     return this.childExited;
   }
 
-  private ensureStarted(): void {
+  private async ensureStarted(): Promise<void> {
+    if (this.closePromise !== null) throw new Error("Headless pi session is closed");
     if (this.child !== null) {
       const exited = this.currentExit();
       if (exited !== null) {
@@ -159,20 +173,12 @@ export class RpcStepExecutor implements AgentStepExecutor {
         cwd: this.options.cwd,
         env: { ...process.env, ...this.options.env },
         stdio: ["pipe", "pipe", "pipe"],
-        // Own process group: the host kills groups, never individual PIDs,
-        // so a killed host cannot leave an orphaned agent working.
-        detached: true,
+        detached: this.options.processGroup !== "inherit",
       },
     );
     this.child = child;
-    if (child.pid !== undefined) {
-      this.options.registry.register(child.pid);
-    }
     child.on("exit", (code, signal) => {
       this.childExited = { code, signal };
-      if (child.pid !== undefined) {
-        this.options.registry.unregister(child.pid);
-      }
       this.wakeSubmissionWaiters();
     });
     // A failed spawn (missing binary, EACCES) emits error instead of exit;
@@ -213,6 +219,23 @@ export class RpcStepExecutor implements AgentStepExecutor {
     child.stdout?.on("data", (chunk: Buffer) => {
       this.stdoutBuffer = (this.stdoutBuffer + chunk.toString("utf8")).slice(-64 * 1024);
     });
+    if (child.pid !== undefined && this.options.registry !== undefined) {
+      try {
+        await this.options.registry.register(child.pid);
+        this.registeredPid = child.pid;
+      } catch (error) {
+        killGroup(child.pid, "SIGKILL");
+        this.child = null;
+        throw error;
+      }
+    }
+  }
+
+  private async unregisterChild(): Promise<void> {
+    const pid = this.registeredPid;
+    if (pid === null) return;
+    this.registeredPid = null;
+    await this.options.registry?.unregister(pid);
   }
 
   private async promptForSubmission(
@@ -310,6 +333,25 @@ function throwIfAborted(signal: AbortSignal): void {
   }
 }
 
+async function waitForGroupExit(pid: number, timeoutMs: number): Promise<boolean> {
+  if (process.platform === "win32") return true;
+  const deadline = Date.now() + timeoutMs;
+  while (processGroupExists(pid)) {
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  return true;
+}
+
+function processGroupExists(pid: number): boolean {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function waitForExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
   if (child.exitCode !== null || child.signalCode !== null) {
     return true;