@osolmaz/pi-workflows 0.16.2 → 0.16.3

package/src/controllers/loader.ts

@@ -1,104 +0,0 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { createJiti } from "jiti";
-import { isControllerDefinition } from "./definition.js";
-import type { AnyControllerDefinition } from "./types.js";
-
-const CONTROLLER_FILE_SUFFIXES = [
-  ".controller.ts",
-  ".controller.js",
-  ".controller.mts",
-  ".controller.mjs",
-];
-
-export type DiscoveredController = {
-  name: string;
-  path: string;
-  source: "project" | "global";
-};
-
-export function controllerSearchDirs(options: {
-  cwd: string;
-  homeDir?: string;
-}): { dir: string; source: DiscoveredController["source"] }[] {
-  const homeDir = options.homeDir ?? os.homedir();
-  return [
-    { dir: path.join(options.cwd, ".pi", "controllers"), source: "project" },
-    { dir: path.join(homeDir, ".pi", "agent", "controllers"), source: "global" },
-  ];
-}
-
-export function controllerFileStem(filePath: string): string {
-  const base = path.basename(filePath);
-  const suffix = CONTROLLER_FILE_SUFFIXES.find((candidate) => base.endsWith(candidate));
-  return suffix === undefined ? base : base.slice(0, -suffix.length);
-}
-
-const CONTROLLER_ENTRY = path.join(path.dirname(fileURLToPath(import.meta.url)), "index");
-const WORKFLOW_ENTRY = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "../workflows/index",
-);
-
-export async function loadControllerFile(filePath: string): Promise<AnyControllerDefinition> {
-  const absolutePath = path.resolve(filePath);
-  const jiti = createJiti(pathToFileURL(absolutePath).href, {
-    interopDefault: true,
-    moduleCache: false,
-    alias: {
-      "@osolmaz/pi-workflows/controllers": CONTROLLER_ENTRY,
-      "@osolmaz/pi-workflows": WORKFLOW_ENTRY,
-    },
-  });
-  const loaded = (await jiti.import(absolutePath, { default: true })) as unknown;
-  if (!isControllerDefinition(loaded)) {
-    throw new Error(`Controller module must default-export defineController(...): ${absolutePath}`);
-  }
-  return loaded;
-}
-
-export async function discoverControllers(options: {
-  cwd: string;
-  homeDir?: string;
-}): Promise<DiscoveredController[]> {
-  const discovered: DiscoveredController[] = [];
-  const seen = new Set<string>();
-  for (const { dir, source } of controllerSearchDirs(options)) {
-    for (const filePath of await listControllerFiles(dir)) {
-      const name = controllerFileStem(filePath);
-      if (seen.has(name)) {
-        continue;
-      }
-      seen.add(name);
-      discovered.push({ name, path: filePath, source });
-    }
-  }
-  return discovered;
-}
-
-export async function loadDiscoveredControllers(options: {
-  cwd: string;
-  homeDir?: string;
-}): Promise<AnyControllerDefinition[]> {
-  return await Promise.all(
-    (await discoverControllers(options)).map(async (entry) => await loadControllerFile(entry.path)),
-  );
-}
-
-async function listControllerFiles(dir: string): Promise<string[]> {
-  let entries: import("node:fs").Dirent[];
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter(
-      (entry) =>
-        entry.isFile() && CONTROLLER_FILE_SUFFIXES.some((suffix) => entry.name.endsWith(suffix)),
-    )
-    .map((entry) => path.join(dir, entry.name))
-    .sort();
-}

package/src/extension/controller-command.ts

@@ -1,45 +0,0 @@
-import type { JsonValue } from "../state/json.js";
-
-export type ParsedControllerArgs =
-  | { kind: "list" }
-  | { kind: "get"; controller: string; key: string }
-  | { kind: "apply"; controller: string; key: string; spec: JsonValue }
-  | { kind: "reconcile"; controller: string; key: string }
-  | { kind: "delete"; controller: string; key: string };
-
-const CONTROLLER_USAGE =
-  "Usage: /controller [list|get <controller> <key>|apply <controller> <key> <json>|reconcile <controller> <key>|delete <controller> <key>]";
-
-export function parseControllerArgs(args: string): ParsedControllerArgs {
-  const trimmed = args.trim();
-  if (trimmed.length === 0 || trimmed === "list") return { kind: "list" };
-
-  const apply = trimmed.match(/^apply\s+(\S+)\s+(\S+)\s+([\s\S]+)$/u);
-  if (apply !== null) {
-    let spec: JsonValue;
-    try {
-      spec = JSON.parse(apply[3] as string) as JsonValue;
-    } catch (error) {
-      throw new Error(
-        `Invalid controller spec JSON: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-    return {
-      kind: "apply",
-      controller: apply[1] as string,
-      key: apply[2] as string,
-      spec,
-    };
-  }
-
-  const operation = trimmed.match(/^(get|reconcile|delete)\s+(\S+)\s+(\S+)$/u);
-  if (operation !== null) {
-    return {
-      kind: operation[1] as "get" | "reconcile" | "delete",
-      controller: operation[2] as string,
-      key: operation[3] as string,
-    };
-  }
-
-  throw new Error(CONTROLLER_USAGE);
-}

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

@@ -1,104 +0,0 @@
-import type { ControllerResource } from "../controllers/types.js";
-import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
-
-export const CONTROLLER_WORKER_LAUNCH_SCHEMA = "pi-workflows.controller-worker-launch.v1" as const;
-export const CONTROLLER_WORKER_MESSAGE_SCHEMA =
-  "pi-workflows.controller-worker-message.v1" as const;
-export const CONTROLLER_WORKER_RESPONSE_SCHEMA =
-  "pi-workflows.controller-worker-response.v1" as const;
-
-export type ControllerWorkerLaunchEnvelope = {
-  schema: typeof CONTROLLER_WORKER_LAUNCH_SCHEMA;
-  workerEpoch: string;
-  hostEpoch: number;
-  generation: number;
-  projectPath: string;
-  definitionPath: string;
-  controllerName: string;
-  resource: ControllerResource;
-  timeoutMs: number;
-};
-
-export type ControllerWorkerOperation =
-  | "worker.ready"
-  | "effect.reserve"
-  | "effect.settle"
-  | "workflow.ensure"
-  | "workflow.changeSettings"
-  | "workflow.queueFollowUp"
-  | "workflow.removeFollowUp"
-  | "worker.finished"
-  | "worker.failed";
-
-export type ControllerWorkerMessage = {
-  schema: typeof CONTROLLER_WORKER_MESSAGE_SCHEMA;
-  launchSchema: typeof CONTROLLER_WORKER_LAUNCH_SCHEMA;
-  messageId: string;
-  workerEpoch: string;
-  generation: number;
-  operation: ControllerWorkerOperation;
-  payload: JsonValue;
-};
-
-export type ControllerWorkerResponse = {
-  schema: typeof CONTROLLER_WORKER_RESPONSE_SCHEMA;
-  messageId: string;
-  outcome: "accepted" | "rejected" | "claimLost";
-  result?: JsonValue;
-  error?: string;
-};
-
-export function encodeControllerWorkerLine(
-  value: ControllerWorkerMessage | ControllerWorkerResponse,
-): Buffer {
-  return Buffer.from(`${canonicalJson(value)}\n`, "utf8");
-}
-
-export function parseControllerWorkerMessage(frame: Buffer): ControllerWorkerMessage {
-  const value = parseJson(frame.toString("utf8"));
-  if (!isRecord(value) || value.schema !== CONTROLLER_WORKER_MESSAGE_SCHEMA) {
-    throw new Error("Invalid controller worker message schema");
-  }
-  if (
-    value.launchSchema !== CONTROLLER_WORKER_LAUNCH_SCHEMA ||
-    typeof value.messageId !== "string" ||
-    typeof value.workerEpoch !== "string" ||
-    !Number.isSafeInteger(value.generation) ||
-    typeof value.operation !== "string" ||
-    !OPERATIONS.has(value.operation as ControllerWorkerOperation) ||
-    !Object.hasOwn(value, "payload")
-  ) {
-    throw new Error("Invalid controller worker message");
-  }
-  return value as ControllerWorkerMessage;
-}
-
-export function parseControllerWorkerResponse(frame: Buffer): ControllerWorkerResponse {
-  const value = parseJson(frame.toString("utf8"));
-  if (!isRecord(value) || value.schema !== CONTROLLER_WORKER_RESPONSE_SCHEMA) {
-    throw new Error("Invalid controller worker response schema");
-  }
-  if (
-    typeof value.messageId !== "string" ||
-    !["accepted", "rejected", "claimLost"].includes(String(value.outcome))
-  ) {
-    throw new Error("Invalid controller worker response");
-  }
-  return value as ControllerWorkerResponse;
-}
-
-const OPERATIONS = new Set<ControllerWorkerOperation>([
-  "worker.ready",
-  "effect.reserve",
-  "effect.settle",
-  "workflow.ensure",
-  "workflow.changeSettings",
-  "workflow.queueFollowUp",
-  "workflow.removeFollowUp",
-  "worker.finished",
-  "worker.failed",
-]);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

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

@@ -1,79 +0,0 @@
-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/worker-protocol.ts

@@ -1,176 +0,0 @@
-import { MAX_PROTOCOL_MESSAGE_BYTES } from "../client/protocol.js";
-import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
-
-export const WORKER_MESSAGE_SCHEMA = "pi-workflows.worker-message.v1" as const;
-export const WORKER_RESPONSE_SCHEMA = "pi-workflows.worker-response.v1" as const;
-
-export type WorkerRunCommand =
-  | { kind: "start"; input: JsonValue }
-  | { kind: "resume"; resumeInteractionAttemptId?: string }
-  | {
-      kind: "continue";
-      parentRunId: string;
-      input: JsonValue;
-      humanDecision?: JsonValue;
-    }
-  | { kind: "restart"; input: JsonValue };
-
-export const WORKER_MESSAGE_KINDS = [
-  "worker.ready",
-  "node.started",
-  "node.update",
-  "node.finished",
-  "node.failed",
-  "run.parked",
-  "run.finished",
-  "interaction.requested",
-  "interaction.accepted",
-  "interaction.rejected",
-  "notification.requested",
-  "presentation.requested",
-  "effect.reserve",
-  "effect.settle",
-  "worker.progress",
-  "worker.exiting",
-] as const;
-
-export type WorkerMessageKind = (typeof WORKER_MESSAGE_KINDS)[number];
-export type WorkerStoreOperation =
-  | "store.initializeRun"
-  | "store.prepareRunResume"
-  | "store.readRun"
-  | "store.writeSnapshot"
-  | "store.publishUpdate"
-  | "store.findSettingsScope"
-  | "store.ensureSettingsScope"
-  | "store.getSettingsScopeAtChange"
-  | "store.createHumanDecisionRequest"
-  | "store.readResolvedHumanDecision"
-  | "store.reserveEffect"
-  | "store.settleEffect"
-  | "process.register"
-  | "process.unregister"
-  | "interaction.request"
-  | "interaction.accept"
-  | "interaction.reject"
-  | "notification.request"
-  | "presentation.request";
-
-export type WorkerMessage = {
-  schema: typeof WORKER_MESSAGE_SCHEMA;
-  launchSchema: "pi-workflows.worker-launch.v1";
-  messageId: string;
-  kind: WorkerMessageKind;
-  operation: WorkerStoreOperation | "worker.ready" | "worker.exiting";
-  runId: string;
-  generation: number;
-  workerEpoch: string;
-  expectedRevision: number;
-  attemptId?: string;
-  payload: JsonValue;
-};
-
-export type WorkerResponse = {
-  schema: typeof WORKER_RESPONSE_SCHEMA;
-  messageId: string;
-  outcome: "accepted" | "adopted" | "rejected" | "claimLost";
-  revision?: number;
-  result?: JsonValue;
-  error?: string;
-};
-
-export function workerKindForOperation(
-  operation: WorkerStoreOperation,
-  payload: Record<string, unknown>,
-): WorkerMessageKind {
-  if (operation === "store.publishUpdate") return "node.update";
-  if (operation === "store.reserveEffect") return "effect.reserve";
-  if (operation === "store.settleEffect") return "effect.settle";
-  if (operation === "store.createHumanDecisionRequest" || operation === "interaction.request") {
-    return "interaction.requested";
-  }
-  if (operation === "interaction.accept") return "interaction.accepted";
-  if (operation === "interaction.reject") return "interaction.rejected";
-  if (operation === "notification.request") return "notification.requested";
-  if (operation === "presentation.request") return "presentation.requested";
-  if (operation === "store.writeSnapshot") {
-    const event = payload.event;
-    const eventType = isRecord(event) && typeof event.type === "string" ? event.type : "";
-    if (eventType === "node_started") return "node.started";
-    if (eventType === "node_finished") return "node.finished";
-    if (eventType === "node_failed" || eventType === "node_timed_out") return "node.failed";
-    if (eventType === "run_waiting" || eventType.includes("park")) return "run.parked";
-    if (eventType.startsWith("run_") && eventType !== "run_started") return "run.finished";
-  }
-  return "worker.progress";
-}
-
-export function encodeWorkerLine(message: WorkerMessage | WorkerResponse): Buffer {
-  const encoded = Buffer.from(`${canonicalJson(message)}\n`, "utf8");
-  if (encoded.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
-    throw new Error("Worker protocol message exceeds 1 MiB");
-  }
-  return encoded;
-}
-
-export function parseWorkerMessage(line: Buffer | string): WorkerMessage {
-  const value = parseWorkerValue(line);
-  if (
-    value.schema !== WORKER_MESSAGE_SCHEMA ||
-    value.launchSchema !== "pi-workflows.worker-launch.v1"
-  ) {
-    throw new Error("Invalid worker message schema");
-  }
-  requireText(value.messageId, "messageId");
-  requireText(value.runId, "runId");
-  requireText(value.workerEpoch, "workerEpoch");
-  if (!WORKER_MESSAGE_KINDS.includes(value.kind as WorkerMessageKind)) {
-    throw new Error("Invalid worker message kind");
-  }
-  if (!Number.isSafeInteger(value.generation) || (value.generation as number) <= 0) {
-    throw new Error("Worker generation must be positive");
-  }
-  if (!Number.isSafeInteger(value.expectedRevision) || (value.expectedRevision as number) < 0) {
-    throw new Error("Worker expectedRevision must be non-negative");
-  }
-  requireText(value.operation, "operation");
-  if (value.attemptId !== undefined) requireText(value.attemptId, "attemptId");
-  if (!Object.hasOwn(value, "payload")) throw new Error("Worker payload is required");
-  return value as WorkerMessage;
-}
-
-export function parseWorkerResponse(line: Buffer | string): WorkerResponse {
-  const value = parseWorkerValue(line);
-  if (value.schema !== WORKER_RESPONSE_SCHEMA) throw new Error("Invalid worker response schema");
-  requireText(value.messageId, "messageId");
-  if (!["accepted", "adopted", "rejected", "claimLost"].includes(value.outcome as string)) {
-    throw new Error("Invalid worker response outcome");
-  }
-  if (value.error !== undefined && typeof value.error !== "string") {
-    throw new Error("Worker response error must be text");
-  }
-  return value as WorkerResponse;
-}
-
-function parseWorkerValue(line: Buffer | string): Record<string, unknown> {
-  const buffer = Buffer.isBuffer(line) ? line : Buffer.from(line, "utf8");
-  if (buffer.byteLength + 1 > MAX_PROTOCOL_MESSAGE_BYTES) {
-    throw new Error("Worker protocol message exceeds 1 MiB");
-  }
-  const text = buffer.toString("utf8");
-  const value = parseJson(text);
-  if (!isRecord(value) || canonicalJson(value) !== text) {
-    throw new Error("Worker protocol message must be a canonical JSON object");
-  }
-  return value;
-}
-
-function requireText(value: unknown, field: string): asserts value is string {
-  if (typeof value !== "string" || value.length === 0 || value.length > 256) {
-    throw new Error(`Worker ${field} must be nonempty bounded text`);
-  }
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/src/host/worker-supervisor.ts

@@ -1,74 +0,0 @@
-import fs from "node:fs";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-import { canonicalJson } from "../state/json.js";
-import { ChildWorkerSupervisor, type SupervisedWorkerResult } from "./child-worker-supervisor.js";
-import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
-import type { WorkerLaunchEnvelope, WorkerOutcome } from "./state.js";
-import {
-  encodeWorkerLine,
-  parseWorkerMessage,
-  type WorkerMessage,
-  type WorkerResponse,
-} from "./worker-protocol.js";
-
-export type WorkflowWorkerResult = SupervisedWorkerResult;
-
-export class WorkflowWorkerSupervisor {
-  private readonly supervisor: ChildWorkerSupervisor<WorkerMessage, WorkerResponse>;
-
-  constructor(
-    readonly envelope: WorkerLaunchEnvelope,
-    private readonly options: {
-      registry: HostProcessRegistry;
-      onMessage: (message: WorkerMessage) => Promise<WorkerResponse>;
-      env?: Record<string, string>;
-      startupTimeoutMs?: number;
-      workerEntryPath?: string;
-      onSpawn?: (identity: ProcessIdentity) => void;
-      onDiagnostic?: (message: string) => void;
-    },
-  ) {
-    this.supervisor = new ChildWorkerSupervisor({
-      label: "Workflow worker",
-      registry: options.registry,
-      onMessage: options.onMessage,
-      parseMessage: parseWorkerMessage,
-      encodeResponse: encodeWorkerLine,
-      isReady: (message) => message.kind === "worker.ready",
-      isTerminal: (message) => message.kind === "worker.exiting",
-      ...(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("./worker-entry.js", import.meta.url));
-    const sourceEntry = fileURLToPath(new URL("./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_WORKER_LAUNCH: Buffer.from(canonicalJson(this.envelope)).toString("base64url"),
-      },
-    });
-  }
-
-  async wait(): Promise<WorkflowWorkerResult> {
-    return await this.supervisor.wait();
-  }
-
-  async stop(outcome: WorkerOutcome = "cancelled"): Promise<void> {
-    await this.supervisor.stop(outcome);
-  }
-}