@llblab/pi-actors 0.32.0 → 0.34.0

package/lib/runs-artifacts.ts

@@ -0,0 +1,96 @@
+/**
+ * Async run artifact declarations and manifest resolution.
+ * Owns artifact path template expansion and filesystem-backed artifact metadata.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+import { substituteCommandTemplateToken } from "./command-templates.ts";
+
+export type RunArtifactDeclaration =
+  | string
+  | { path: string; kind?: string; media_type?: string; required?: boolean };
+
+export interface RunArtifactManifestEntry {
+  exists: boolean;
+  kind?: string;
+  media_type?: string;
+  path: string;
+  required?: boolean;
+  sha256?: string;
+  size?: number;
+}
+
+export function resolveArtifactPaths(
+  artifacts: Record<string, RunArtifactDeclaration> | undefined,
+  values: Record<string, unknown>,
+): Record<string, RunArtifactDeclaration> | undefined {
+  if (!artifacts) return undefined;
+  const resolved: Record<string, RunArtifactDeclaration> = {};
+  for (const [key, value] of Object.entries(artifacts)) {
+    if (!key.trim()) continue;
+    if (typeof value === "string") {
+      resolved[key] = substituteCommandTemplateToken(
+        value,
+        values,
+        `recipe artifacts.${key}`,
+      );
+    } else if (
+      value &&
+      typeof value === "object" &&
+      typeof value.path === "string"
+    ) {
+      resolved[key] = {
+        ...value,
+        path: substituteCommandTemplateToken(
+          value.path,
+          values,
+          `recipe artifacts.${key}.path`,
+        ),
+      };
+    }
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+export function resolveArtifactManifest(
+  artifacts: Record<string, RunArtifactDeclaration> | undefined,
+): Record<string, RunArtifactManifestEntry> | undefined {
+  if (!artifacts) return undefined;
+  const manifest: Record<string, RunArtifactManifestEntry> = {};
+  for (const [name, artifact] of Object.entries(artifacts)) {
+    const declaration =
+      typeof artifact === "string" ? { path: artifact } : artifact;
+    if (!declaration?.path) continue;
+    try {
+      const content = readFileSync(declaration.path);
+      manifest[name] = {
+        exists: true,
+        ...(declaration.kind ? { kind: declaration.kind } : {}),
+        ...(declaration.media_type
+          ? { media_type: declaration.media_type }
+          : {}),
+        path: declaration.path,
+        ...(declaration.required !== undefined
+          ? { required: declaration.required }
+          : {}),
+        sha256: createHash("sha256").update(content).digest("hex"),
+        size: content.byteLength,
+      };
+    } catch {
+      manifest[name] = {
+        exists: false,
+        ...(declaration.kind ? { kind: declaration.kind } : {}),
+        ...(declaration.media_type
+          ? { media_type: declaration.media_type }
+          : {}),
+        path: declaration.path,
+        ...(declaration.required !== undefined
+          ? { required: declaration.required }
+          : {}),
+      };
+    }
+  }
+  return Object.keys(manifest).length > 0 ? manifest : undefined;
+}

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;
+}