@llblab/pi-actors 0.33.0 → 0.34.1

package/lib/runs-control.ts

@@ -0,0 +1,85 @@
+/**
+ * Async run process control primitives.
+ * Owns platform signal planning, owned-process signalling, and terminal control markers.
+ */
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+
+export interface RunProcessSignalPlan {
+  args?: string[];
+  command?: string;
+  signalTarget: "processGroup" | "process" | "processTree";
+}
+
+export function getRunProcessSignalPlan(
+  pid: number,
+  signal: NodeJS.Signals,
+  runtimePlatform: NodeJS.Platform = process.platform,
+): RunProcessSignalPlan {
+  if (runtimePlatform === "win32") {
+    return {
+      args: [
+        "/PID",
+        String(pid),
+        "/T",
+        ...(signal === "SIGKILL" ? ["/F"] : []),
+      ],
+      command: "taskkill",
+      signalTarget: "processTree",
+    };
+  }
+  return { signalTarget: "processGroup" };
+}
+
+export function signalOwnedRunProcess(
+  pid: number,
+  signal: NodeJS.Signals,
+): RunProcessSignalPlan {
+  const plan = getRunProcessSignalPlan(pid, signal);
+  if (plan.command && plan.args) {
+    const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
+    if (result.status !== 0) {
+      throw new Error(
+        result.stderr?.trim() ||
+          result.stdout?.trim() ||
+          `${plan.command} failed`,
+      );
+    }
+    return plan;
+  }
+  try {
+    process.kill(-pid, signal);
+    return { signalTarget: "processGroup" };
+  } catch {
+    process.kill(pid, signal);
+    return { signalTarget: "process" };
+  }
+}
+
+export function markTerminalHandled(
+  stateDir: string,
+  details: Record<string, unknown>,
+): void {
+  writeJsonAtomic(join(stateDir, "terminal-handled.json"), {
+    ...details,
+    ts: new Date().toISOString(),
+  });
+}
+
+export function buildTerminalProgress(
+  existing: Record<string, unknown> | undefined,
+  phase: "cancelled" | "killed",
+): Record<string, unknown> {
+  const progress = existing ?? {};
+  const { activeSubagents: _activeSubagents, ...rest } = progress;
+  return {
+    ...rest,
+    completed: typeof progress.completed === "number" ? progress.completed : 0,
+    failures: Array.isArray(progress.failures) ? progress.failures : [],
+    phase,
+    updatedAt: new Date().toISOString(),
+  };
+}

package/lib/runs-identity.ts

@@ -0,0 +1,14 @@
+/**
+ * Async run identity helpers.
+ * Owns run id normalization shared by run lifecycle and retention paths.
+ */
+
+export function safeRunId(value: string | undefined): string {
+  const run = (value || `run-${Date.now()}`).trim();
+  if (!/^[A-Za-z0-9_.-]+$/.test(run)) {
+    throw new Error(
+      "Run id may contain only letters, numbers, dot, underscore, and dash.",
+    );
+  }
+  return run;
+}

package/lib/runs-index.ts

@@ -0,0 +1,156 @@
+/**
+ * Async run state index.
+ * Owns recursive run-state discovery, index rebuild/read, and status filtering.
+ */
+
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+
+export interface RunStateIndexEntry {
+  ownerId?: string;
+  recipe?: string;
+  run: string;
+  state_dir: string;
+  status: string;
+  tool?: string;
+  updated_at?: string;
+}
+
+export type RunStatusReader = (runOrDir: string) => Record<string, unknown>;
+
+function matchesStatusFilter(
+  status: unknown,
+  filter: string | undefined,
+): boolean {
+  if (!filter || filter === "all") return true;
+  if (filter === "active") return status === "running";
+  if (filter === "terminal") return status !== "running";
+  return status === filter;
+}
+
+export function listRunStateDirs(
+  stateRoot: string,
+  depth = 0,
+  seen = new Set<string>(),
+): string[] {
+  if (!existsSync(stateRoot) || seen.has(resolve(stateRoot))) return [];
+  seen.add(resolve(stateRoot));
+  let entries: import("node:fs").Dirent[];
+  try {
+    entries = readdirSync(stateRoot, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const result: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const child = join(stateRoot, entry.name);
+    if (existsSync(join(child, "run.json"))) result.push(child);
+    if (depth + 1 < 8) result.push(...listRunStateDirs(child, depth + 1, seen));
+  }
+  return result;
+}
+
+function runIndexPath(stateRoot: string): string {
+  return join(stateRoot, "index.json");
+}
+
+function indexEntryFromStatus(
+  status: Record<string, unknown>,
+): RunStateIndexEntry {
+  const progress =
+    status.progress && typeof status.progress === "object"
+      ? (status.progress as Record<string, unknown>)
+      : {};
+  return {
+    ...(typeof status.ownerId === "string" ? { ownerId: status.ownerId } : {}),
+    ...(typeof status.recipe === "string" ? { recipe: status.recipe } : {}),
+    run: String(status.run),
+    state_dir: String(status.state_dir),
+    status: String(status.status),
+    ...(typeof status.tool === "string" ? { tool: status.tool } : {}),
+    updated_at:
+      typeof progress.updatedAt === "string"
+        ? progress.updatedAt
+        : typeof status.createdAt === "string"
+          ? status.createdAt
+          : new Date(0).toISOString(),
+  };
+}
+
+export function rebuildRunStateIndex(
+  stateRoot: string,
+  getRunStatus: RunStatusReader,
+): RunStateIndexEntry[] {
+  mkdirSync(stateRoot, { recursive: true });
+  const entries = listRunStateDirs(stateRoot)
+    .flatMap((stateDir) => {
+      try {
+        return [indexEntryFromStatus(getRunStatus(stateDir))];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+  writeJsonAtomic(runIndexPath(stateRoot), {
+    entries,
+    rebuilt_at: new Date().toISOString(),
+  });
+  return entries;
+}
+
+export function readRunStateIndex(
+  stateRoot: string,
+  readJson: (path: string) => Record<string, unknown> | undefined,
+): RunStateIndexEntry[] | undefined {
+  const index = readJson(runIndexPath(stateRoot));
+  if (!index || typeof index !== "object") return undefined;
+  const entries = (index as Record<string, unknown>).entries;
+  if (!Array.isArray(entries)) return undefined;
+  const valid = entries.filter((entry): entry is RunStateIndexEntry => {
+    const record =
+      entry && typeof entry === "object"
+        ? (entry as Record<string, unknown>)
+        : {};
+    return (
+      typeof record.run === "string" &&
+      typeof record.state_dir === "string" &&
+      typeof record.status === "string"
+    );
+  });
+  if (valid.some((entry) => !existsSync(join(entry.state_dir, "run.json"))))
+    return undefined;
+  const indexedDirs = new Set(valid.map((entry) => resolve(entry.state_dir)));
+  const stateDirs = listRunStateDirs(stateRoot).map((stateDir) =>
+    resolve(stateDir),
+  );
+  if (stateDirs.some((stateDir) => !indexedDirs.has(stateDir)))
+    return undefined;
+  return valid;
+}
+
+function compactIndexEntry(entry: RunStateIndexEntry): Record<string, unknown> {
+  return {
+    run: entry.run,
+    state_dir: entry.state_dir,
+    status: entry.status,
+    ...(entry.tool ? { tool: entry.tool } : {}),
+    ...(entry.recipe ? { recipe: entry.recipe } : {}),
+  };
+}
+
+export function listRuns(
+  stateRoot: string,
+  getRunStatus: RunStatusReader,
+  readJson: (path: string) => Record<string, unknown> | undefined,
+  statusFilter?: string,
+): Array<Record<string, unknown>> {
+  if (!existsSync(stateRoot)) return [];
+  const indexed = readRunStateIndex(stateRoot, readJson);
+  const entries = indexed ?? rebuildRunStateIndex(stateRoot, getRunStatus);
+  return entries
+    .filter((entry) => matchesStatusFilter(entry.status, statusFilter))
+    .map(compactIndexEntry);
+}

package/lib/runs-mailbox.ts

@@ -0,0 +1,208 @@
+/**
+ * Async run mailbox state.
+ * Owns durable run inbox records, claim locks, and handler status transitions.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { readJsonlFileResilient } from "./state-readers.ts";
+
+const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
+const STALE_INBOX_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+
+export type RunInboxStatus =
+  | "queued"
+  | "sent"
+  | "claimed"
+  | "handled"
+  | "failed";
+
+export type RunInboxMessage = Record<string, unknown> & {
+  id?: string;
+  status?: RunInboxStatus | string;
+};
+
+export interface ProcessRunInboxResult {
+  claimed: number;
+  failed: number;
+  handled: number;
+}
+
+export function runInboxFile(stateDir: string): string {
+  return join(stateDir, "inbox.jsonl");
+}
+
+export function parseRunInboxLine(line: string): RunInboxMessage | undefined {
+  try {
+    return JSON.parse(line) as RunInboxMessage;
+  } catch {
+    return undefined;
+  }
+}
+
+export function readRunInboxMessagesFromStateDir(
+  stateDir: string,
+): RunInboxMessage[] {
+  return readJsonlFileResilient<RunInboxMessage>(runInboxFile(stateDir))
+    .records;
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireRunInboxLock(stateDir: string): () => void {
+  const lockDir = join(stateDir, ".inbox.lock");
+  const started = Date.now();
+  while (true) {
+    try {
+      mkdirSync(lockDir, { recursive: false });
+      writeFileSync(
+        join(lockDir, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`,
+        "utf8",
+      );
+      return () => rmSync(lockDir, { recursive: true, force: true });
+    } catch (error) {
+      try {
+        const stat = statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > STALE_INBOX_LOCK_MAX_AGE_MS) {
+          rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - started > RUN_INBOX_LOCK_TIMEOUT_MS) {
+        throw new Error("Run inbox lock timed out.", { cause: error });
+      }
+      sleepSync(10);
+    }
+  }
+}
+
+function writeRunInboxMessages(
+  stateDir: string,
+  messages: RunInboxMessage[],
+): void {
+  writeFileSync(
+    runInboxFile(stateDir),
+    messages.length
+      ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
+      : "",
+    "utf8",
+  );
+}
+
+export function updateRunInboxMessageStatusInStateDir(
+  stateDir: string,
+  id: string,
+  nextStatus: RunInboxStatus,
+  metadata: Record<string, unknown> = {},
+): boolean {
+  const releaseLock = acquireRunInboxLock(stateDir);
+  try {
+    const messages = readRunInboxMessagesFromStateDir(stateDir);
+    const timestampKey = `${nextStatus}_at`;
+    let changed = false;
+    const updated = messages.map((message) => {
+      if (message.id !== id) return message;
+      changed = true;
+      return {
+        ...message,
+        ...metadata,
+        [timestampKey]: new Date().toISOString(),
+        status: nextStatus,
+      };
+    });
+    if (changed) writeRunInboxMessages(stateDir, updated);
+    return changed;
+  } finally {
+    releaseLock();
+  }
+}
+
+export function claimRunInboxMessageInStateDir(
+  stateDir: string,
+  owner = "runtime",
+  statuses: string[] = ["queued"],
+): RunInboxMessage | undefined {
+  const releaseLock = acquireRunInboxLock(stateDir);
+  try {
+    const messages = readRunInboxMessagesFromStateDir(stateDir);
+    const index = messages.findIndex((message) =>
+      statuses.includes(String(message.status ?? "queued")),
+    );
+    if (index < 0) return undefined;
+    const claimed = {
+      ...messages[index],
+      claimed_at: new Date().toISOString(),
+      claimed_by: owner,
+      id:
+        typeof messages[index].id === "string"
+          ? messages[index].id
+          : randomUUID(),
+      status: "claimed",
+    } satisfies RunInboxMessage;
+    messages[index] = claimed;
+    writeRunInboxMessages(stateDir, messages);
+    return claimed;
+  } finally {
+    releaseLock();
+  }
+}
+
+export function appendRunInboxMessageInStateDir(
+  stateDir: string,
+  record: Record<string, unknown>,
+): string {
+  const id = randomUUID();
+  const ts = new Date().toISOString();
+  const releaseLock = acquireRunInboxLock(stateDir);
+  try {
+    writeFileSync(
+      runInboxFile(stateDir),
+      `${JSON.stringify({ ...record, id, queued_at: ts, received_at: ts, status: "queued" })}\n`,
+      { flag: "a" },
+    );
+  } finally {
+    releaseLock();
+  }
+  return id;
+}
+
+export async function processRunInboxMessagesInStateDir(
+  stateDir: string,
+  handler: (message: RunInboxMessage) => Promise<void> | void,
+  options: { limit?: number; owner?: string; statuses?: string[] } = {},
+): Promise<ProcessRunInboxResult> {
+  const result: ProcessRunInboxResult = { claimed: 0, failed: 0, handled: 0 };
+  const limit = Math.max(1, Number(options.limit ?? 1));
+  const owner = options.owner ?? "runtime";
+  for (let index = 0; index < limit; index += 1) {
+    const message = claimRunInboxMessageInStateDir(
+      stateDir,
+      owner,
+      options.statuses,
+    );
+    if (!message?.id) break;
+    result.claimed += 1;
+    try {
+      await handler(message);
+      if (updateRunInboxMessageStatusInStateDir(stateDir, message.id, "handled")) {
+        result.handled += 1;
+      }
+    } catch (error) {
+      if (
+        updateRunInboxMessageStatusInStateDir(stateDir, message.id, "failed", {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      ) {
+        result.failed += 1;
+      }
+    }
+  }
+  return result;
+}

package/lib/runs-messages.ts

@@ -0,0 +1,252 @@
+/**
+ * Async run message delivery.
+ * Owns run control endpoint resolution, inbox enqueueing, wake notification,
+ * transport writes, and delivery receipts.
+ */
+
+import {
+  closeSync,
+  constants,
+  existsSync,
+  openSync,
+  statSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+
+import { markTerminalHandled } from "./runs-control.ts";
+import {
+  appendRunInboxMessageInStateDir,
+  updateRunInboxMessageStatusInStateDir,
+} from "./runs-mailbox.ts";
+import { notifyRuntimeWake } from "./runtime-notifier.ts";
+
+export interface RunControlEndpoint {
+  path: string;
+  type: "fifo" | "mailbox" | "named-pipe";
+}
+
+export interface SendRunMessageOptions {
+  namedPipeSend?: (path: string, payload: string) => Promise<number>;
+  platform?: NodeJS.Platform;
+}
+
+export function getRunControlEndpoint(
+  status: Record<string, unknown>,
+  stateDir: string,
+): RunControlEndpoint {
+  const control = status.control;
+  if (control && typeof control === "object" && !Array.isArray(control)) {
+    const record = control as Record<string, unknown>;
+    if (
+      (record.type === "fifo" ||
+        record.type === "mailbox" ||
+        record.type === "named-pipe") &&
+      typeof record.path === "string" &&
+      record.path.trim()
+    ) {
+      return { path: record.path, type: record.type };
+    }
+  }
+  return { path: join(stateDir, "control.fifo"), type: "fifo" };
+}
+
+function appendRunInboxMessage(stateDir: string, message: string): string {
+  let record: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(message) as unknown;
+    record =
+      parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : { body: parsed, type: "run.message" };
+  } catch {
+    record = { body: message, type: "run.message" };
+  }
+  return appendRunInboxMessageInStateDir(stateDir, record);
+}
+
+function writeRunMessageReceipt(
+  stateDir: string,
+  message: string,
+  bytes: number,
+  inboxId: string,
+): void {
+  const trimmedMessage = message.trim().toLowerCase();
+  const terminalMessage = ["stop", "cancel", "quit", "exit"].includes(
+    trimmedMessage,
+  );
+  const ts = new Date().toISOString();
+  writeFileSync(
+    join(stateDir, "events.jsonl"),
+    `${JSON.stringify({ bytes, event: "run.message", inbox_id: inboxId, terminal: terminalMessage || undefined, ts })}\n`,
+    { flag: "a" },
+  );
+  updateRunInboxMessageStatusInStateDir(stateDir, inboxId, "sent", { bytes });
+  if (terminalMessage) {
+    markTerminalHandled(stateDir, {
+      event: "run.message",
+      message: trimmedMessage,
+    });
+  }
+}
+
+function sendRunMessageToFifo(
+  endpoint: RunControlEndpoint,
+  payload: string,
+): number {
+  if (!existsSync(endpoint.path))
+    throw new Error(`Run control FIFO not found: ${endpoint.path}`);
+  const stat = statSync(endpoint.path);
+  if ((stat.mode & constants.S_IFMT) !== constants.S_IFIFO) {
+    throw new Error(`Run control endpoint is not a FIFO: ${endpoint.path}`);
+  }
+  let fd: number | undefined;
+  try {
+    fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+    return writeSync(fd, payload);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function notifyRunMessageWake(
+  stateDir: string,
+  run: string,
+  bytes: number,
+  endpoint: RunControlEndpoint,
+  inboxId: string,
+): Record<string, unknown> | undefined {
+  try {
+    const event = notifyRuntimeWake(stateDir, {
+      actor: `run:${run}`,
+      metadata: { bytes, control_type: endpoint.type, inbox_id: inboxId },
+      reason: "run.message",
+    });
+    return { wake: "wake.jsonl", wake_id: event.id };
+  } catch {
+    return undefined;
+  }
+}
+
+function sendRunMessageToNamedPipe(
+  endpoint: RunControlEndpoint,
+  payload: string,
+  send?: (path: string, payload: string) => Promise<number>,
+): Promise<number> {
+  if (send) return send(endpoint.path, payload);
+  return new Promise((resolve, reject) => {
+    const socket = createConnection(endpoint.path);
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(new Error("named pipe connection timed out"));
+    }, 5000);
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (error) reject(error);
+      else resolve(Buffer.byteLength(payload));
+    };
+    socket.on("error", finish);
+    socket.on("connect", () => {
+      socket.end(payload, () => finish());
+    });
+  });
+}
+
+export async function deliverRunMessage(
+  status: Record<string, unknown>,
+  run: string,
+  stateDir: string,
+  message: string,
+  options: SendRunMessageOptions = {},
+): Promise<Record<string, unknown>> {
+  const endpoint = getRunControlEndpoint(status, stateDir);
+  const payload = message.endsWith("\n") ? message : `${message}\n`;
+  const payloadBytes = Buffer.byteLength(payload);
+  const inboxId = appendRunInboxMessage(stateDir, message);
+  const wake = notifyRunMessageWake(
+    stateDir,
+    run,
+    payloadBytes,
+    endpoint,
+    inboxId,
+  );
+  const runtimePlatform = options.platform ?? process.platform;
+  if (endpoint.type === "mailbox") {
+    return {
+      ...(wake ?? {}),
+      bytes: payloadBytes,
+      control: "inbox.jsonl",
+      control_path: endpoint.path,
+      control_type: endpoint.type,
+      inbox_id: inboxId,
+      queued: true,
+      run,
+      sent: true,
+      state_dir: stateDir,
+    };
+  }
+  try {
+    if (endpoint.type === "fifo") {
+      if (runtimePlatform === "win32") {
+        throw new Error(
+          "run actor messages on native Windows require a named-pipe control endpoint; this recipe still exposes Unix FIFO control.",
+        );
+      }
+      const bytes = sendRunMessageToFifo(endpoint, payload);
+      writeRunMessageReceipt(stateDir, message, bytes, inboxId);
+      return {
+        ...(wake ?? {}),
+        bytes,
+        control: "control.fifo",
+        control_path: endpoint.path,
+        control_type: endpoint.type,
+        inbox_id: inboxId,
+        run,
+        sent: true,
+        state_dir: stateDir,
+      };
+    }
+    const bytes = await sendRunMessageToNamedPipe(
+      endpoint,
+      payload,
+      options.namedPipeSend,
+    );
+    writeRunMessageReceipt(stateDir, message, bytes, inboxId);
+    return {
+      ...(wake ?? {}),
+      bytes,
+      control: endpoint.path,
+      control_path: endpoint.path,
+      control_type: endpoint.type,
+      inbox_id: inboxId,
+      run,
+      sent: true,
+      state_dir: stateDir,
+    };
+  } catch (error) {
+    const deliveryError =
+      error instanceof Error ? error.message : String(error);
+    throw Object.assign(
+      new Error(
+        `Run control endpoint is not ready: ${endpoint.path}: ${deliveryError}`,
+      ),
+      {
+        control_path: endpoint.path,
+        control_type: endpoint.type,
+        delivery_error: deliveryError,
+        inbox_id: inboxId,
+        queued: true,
+        run,
+        sent: false,
+        state_dir: stateDir,
+      },
+    );
+  }
+}