@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/src/host/client.ts

@@ -1,293 +0,0 @@
-import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { once } from "node:events";
-import fs from "node:fs";
-import { createRequire } from "node:module";
-import net from "node:net";
-import { fileURLToPath } from "node:url";
-import { workflowStatePath } from "../state/database.js";
-import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
-import {
-  encodeProtocolLine,
-  hostSocketPath,
-  NdjsonFrameDecoder,
-  parseHostResponse,
-  type HostOperation,
-  type HostRequest,
-  type HostResponse,
-} from "./protocol.js";
-import type {
-  ResolvedControllerInitialization,
-  ResolvedSettingsChange,
-  ResolvedWorkflowLaunch,
-} from "./resolver-entry.js";
-
-const CONNECT_TIMEOUT_MS = 2_000;
-const START_TIMEOUT_MS = 10_000;
-
-export class WorkflowHostClient {
-  readonly clientId: string;
-  readonly databasePath: string;
-  readonly endpoint: string;
-
-  constructor(
-    options: {
-      clientId?: string;
-      databasePath?: string;
-      hostEntryPath?: string;
-      env?: Record<string, string>;
-    } = {},
-  ) {
-    this.clientId = options.clientId ?? `client-${randomUUID()}`;
-    this.databasePath = options.databasePath ?? workflowStatePath();
-    this.endpoint = hostSocketPath(this.databasePath);
-    this.hostEntryPath = options.hostEntryPath;
-    this.env = options.env;
-  }
-
-  private readonly hostEntryPath: string | undefined;
-  private readonly env: Record<string, string> | undefined;
-
-  async request(options: {
-    operation: HostOperation;
-    requestId?: string;
-    idempotencyKey?: string;
-    runId?: string;
-    expectedRevision?: number;
-    payload?: JsonValue;
-  }): Promise<HostResponse> {
-    const request: HostRequest = {
-      schema: "pi-workflows.host-request.v1",
-      requestId: options.requestId ?? randomUUID(),
-      clientId: this.clientId,
-      operation: options.operation,
-      idempotencyKey: options.idempotencyKey ?? randomUUID(),
-      ...(options.runId === undefined ? {} : { runId: options.runId }),
-      ...(options.expectedRevision === undefined
-        ? {}
-        : { expectedRevision: options.expectedRevision }),
-      payload: options.payload ?? {},
-    };
-    return await sendRequest(this.endpoint, request);
-  }
-
-  async resolveWorkflow(options: {
-    cwd: string;
-    workflowRef: string;
-    timeoutMs?: number;
-  }): Promise<ResolvedWorkflowLaunch> {
-    return (await this.runResolver(
-      {
-        schema: "pi-workflows.resolve-request.v1",
-        cwd: options.cwd,
-        workflowRef: options.workflowRef,
-      },
-      options.cwd,
-      "pi-workflows.resolved-launch.v1",
-      options.timeoutMs,
-    )) as unknown as ResolvedWorkflowLaunch;
-  }
-
-  async resolveControllerInitialization(options: {
-    cwd: string;
-    controllerName: string;
-    spec: JsonValue;
-    timeoutMs?: number;
-  }): Promise<ResolvedControllerInitialization> {
-    return (await this.runResolver(
-      {
-        schema: "pi-workflows.controller-initialization-request.v1",
-        cwd: options.cwd,
-        controllerName: options.controllerName,
-        spec: options.spec,
-      },
-      options.cwd,
-      "pi-workflows.resolved-controller-initialization.v1",
-      options.timeoutMs,
-    )) as unknown as ResolvedControllerInitialization;
-  }
-
-  async resolveSettingsChange(options: {
-    cwd: string;
-    workflowRef: string;
-    definitionDigest: string;
-    mountPath: string;
-    current: JsonValue;
-    patch: JsonValue;
-    actorId: string;
-    timeoutMs?: number;
-  }): Promise<ResolvedSettingsChange> {
-    return (await this.runResolver(
-      {
-        schema: "pi-workflows.settings-validation-request.v1",
-        cwd: options.cwd,
-        workflowRef: options.workflowRef,
-        definitionDigest: options.definitionDigest,
-        mountPath: options.mountPath,
-        current: options.current,
-        patch: options.patch,
-        actorId: options.actorId,
-      },
-      options.cwd,
-      "pi-workflows.resolved-settings-change.v1",
-      options.timeoutMs,
-    )) as unknown as ResolvedSettingsChange;
-  }
-
-  private async runResolver(
-    request: JsonValue,
-    cwd: string,
-    expectedSchema: string,
-    timeoutMs = START_TIMEOUT_MS,
-  ): Promise<JsonValue> {
-    const builtEntry = fileURLToPath(new URL("./resolver-entry.js", import.meta.url));
-    const sourceEntry = fileURLToPath(new URL("./resolver-entry.ts", import.meta.url));
-    const args = fs.existsSync(builtEntry)
-      ? [builtEntry]
-      : ["--import", createRequire(import.meta.url).resolve("tsx"), sourceEntry];
-    const child = spawn(process.execPath, args, {
-      cwd,
-      detached: process.platform !== "win32",
-      stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, ...this.env },
-    });
-    let stdout: Buffer = Buffer.alloc(0);
-    let stderr: Buffer = Buffer.alloc(0);
-    let outputError: Error | undefined;
-    const append = (current: Buffer, chunk: Buffer): Buffer => {
-      const next = Buffer.concat([current, chunk]);
-      if (next.byteLength > 1024 * 1024) {
-        outputError = new Error("Workflow resolver output exceeds 1 MiB");
-        stopProcessGroup(child.pid);
-        return current;
-      }
-      return next;
-    };
-    child.stdout.on("data", (chunk: Buffer) => {
-      stdout = append(stdout, chunk);
-    });
-    child.stderr.on("data", (chunk: Buffer) => {
-      stderr = append(stderr, chunk);
-    });
-    child.stdin.end(canonicalJson(request));
-    const timeout = setTimeout(() => stopProcessGroup(child.pid), timeoutMs);
-    timeout.unref?.();
-    const [code, signal] = (await once(child, "exit")) as [number | null, NodeJS.Signals | null];
-    clearTimeout(timeout);
-    if (outputError !== undefined) throw outputError;
-    if (code !== 0) {
-      const detail = stderr.toString("utf8").trim().slice(0, 2_000);
-      throw new Error(
-        detail || `Workflow resolver exited before completion (code ${code}, signal ${signal})`,
-      );
-    }
-    const value = parseJson(stdout.toString("utf8").trimEnd());
-    if (!isRecord(value) || value.schema !== expectedSchema) {
-      throw new Error("Workflow resolver returned an invalid result envelope");
-    }
-    return value as JsonValue;
-  }
-
-  async ensureRunning(): Promise<HostResponse> {
-    try {
-      return await this.request({
-        operation: "host.status",
-        requestId: `host-status-${randomUUID()}`,
-        idempotencyKey: `host-status-${randomUUID()}`,
-      });
-    } catch {
-      this.startDetached();
-    }
-    const deadline = Date.now() + START_TIMEOUT_MS;
-    let lastError: unknown;
-    while (Date.now() < deadline) {
-      await new Promise((resolve) => setTimeout(resolve, 50));
-      try {
-        return await this.request({
-          operation: "host.status",
-          requestId: `host-status-${randomUUID()}`,
-          idempotencyKey: `host-status-${randomUUID()}`,
-        });
-      } catch (error) {
-        lastError = error;
-      }
-    }
-    throw new Error(
-      `Workflow host did not become ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
-    );
-  }
-
-  private startDetached(): void {
-    const builtEntry = fileURLToPath(new URL("./host-entry.js", import.meta.url));
-    const sourceEntry = fileURLToPath(new URL("./host-entry.ts", import.meta.url));
-    const entry = this.hostEntryPath ?? builtEntry;
-    const args =
-      this.hostEntryPath === undefined && !fs.existsSync(builtEntry)
-        ? ["--import", createRequire(import.meta.url).resolve("tsx"), sourceEntry]
-        : [entry];
-    const child = spawn(process.execPath, [...args, "--database", this.databasePath], {
-      detached: true,
-      stdio: "ignore",
-      env: { ...process.env, ...this.env },
-    });
-    child.unref();
-  }
-}
-
-function stopProcessGroup(pid: number | undefined): void {
-  if (pid === undefined) return;
-  try {
-    if (process.platform !== "win32") process.kill(-pid, "SIGKILL");
-    else process.kill(pid, "SIGKILL");
-  } catch {
-    // The resolver has already exited.
-  }
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-async function sendRequest(endpoint: string, request: HostRequest): Promise<HostResponse> {
-  const socket = net.createConnection(endpoint);
-  const decoder = new NdjsonFrameDecoder();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  try {
-    await Promise.race([
-      once(socket, "connect"),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(
-          () => reject(new Error("Workflow host connection timed out")),
-          CONNECT_TIMEOUT_MS,
-        );
-        timer.unref?.();
-      }),
-      once(socket, "error").then(([error]) => Promise.reject(error)),
-    ]);
-    if (!socket.write(encodeProtocolLine(request))) await once(socket, "drain");
-    const response = await new Promise<HostResponse>((resolve, reject) => {
-      const timeout = setTimeout(
-        () => reject(new Error("Workflow host response timed out")),
-        CONNECT_TIMEOUT_MS,
-      );
-      timeout.unref?.();
-      socket.on("data", (chunk: Buffer) => {
-        try {
-          const frame = decoder.push(chunk)[0];
-          if (frame === undefined) return;
-          clearTimeout(timeout);
-          resolve(parseHostResponse(frame));
-        } catch (error) {
-          clearTimeout(timeout);
-          reject(error);
-        }
-      });
-      socket.once("error", reject);
-      socket.once("close", () => reject(new Error("Workflow host closed before responding")));
-    });
-    return response;
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
-    socket.destroy();
-  }
-}

package/src/host/protocol.ts

@@ -1,196 +0,0 @@
-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);
-}

package/src/viewer/watch.ts

@@ -1,51 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-export type Unsubscribe = () => void;
-
-/** Watch the canonical database and its WAL with a polling fallback. */
-export function watchStateDatabase(
-  databasePath: string,
-  onChange: () => void,
-  options: { pollMs?: number; debounceMs?: number } = {},
-): Unsubscribe {
-  const pollMs = options.pollMs ?? 1_000;
-  const debounceMs = options.debounceMs ?? 80;
-  const directory = path.dirname(databasePath);
-  const base = path.basename(databasePath);
-  const relevant = new Set([base, `${base}-wal`, `${base}-shm`]);
-  let debounceTimer: NodeJS.Timeout | null = null;
-  let closed = false;
-
-  const fire = () => {
-    if (closed) return;
-    if (debounceTimer !== null) clearTimeout(debounceTimer);
-    debounceTimer = setTimeout(() => {
-      debounceTimer = null;
-      onChange();
-    }, debounceMs);
-  };
-
-  let watcher: fs.FSWatcher | null = null;
-  try {
-    watcher = fs.watch(directory, (_event, filename) => {
-      if (filename === null || relevant.has(filename.toString())) fire();
-    });
-    watcher.on("error", () => {
-      watcher?.close();
-      watcher = null;
-    });
-  } catch {
-    watcher = null;
-  }
-
-  const poller = setInterval(fire, pollMs);
-  poller.unref?.();
-
-  return () => {
-    closed = true;
-    if (debounceTimer !== null) clearTimeout(debounceTimer);
-    clearInterval(poller);
-    watcher?.close();
-  };
-}