@llblab/pi-actors 0.32.0 → 0.34.0

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

package/lib/runs-outbox.ts

@@ -0,0 +1,144 @@
+/**
+ * Async run outbox events.
+ * Owns outbox event normalization, parsing, and append payload formatting.
+ */
+
+export type RunOutboxDelivery = "log" | "notify" | "followup";
+export type RunOutboxLevel = "info" | "warning" | "error";
+
+export interface RunOutboxEvent {
+  body?: unknown;
+  correlation_id?: string;
+  data?: unknown;
+  delivery: RunOutboxDelivery;
+  event: string;
+  from?: string;
+  id: string;
+  level: RunOutboxLevel;
+  metadata?: Record<string, unknown>;
+  reply_to?: string;
+  run: string;
+  state_dir: string;
+  summary: string;
+  to?: string;
+  ts: string;
+  type?: string;
+}
+
+export function normalizeRunOutboxDelivery(value: unknown): RunOutboxDelivery {
+  return value === "notify" || value === "followup" ? value : "log";
+}
+
+export function normalizeRunOutboxLevel(value: unknown): RunOutboxLevel {
+  return value === "warning" || value === "error" ? value : "info";
+}
+
+function normalizeRunOutboxEvent(
+  raw: unknown,
+  run: string,
+  stateDir: string,
+  index: number,
+): RunOutboxEvent | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const record = raw as Record<string, unknown>;
+  const event =
+    typeof record.event === "string" && record.event.trim()
+      ? record.event.trim()
+      : "run.event";
+  const summary =
+    typeof record.summary === "string" && record.summary.trim()
+      ? record.summary.trim()
+      : event;
+  const ts =
+    typeof record.ts === "string" && record.ts.trim()
+      ? record.ts.trim()
+      : new Date(0).toISOString();
+  const id =
+    typeof record.id === "string" && record.id.trim()
+      ? record.id.trim()
+      : `${run}:${index}`;
+  return {
+    ...(record.body !== undefined ? { body: record.body } : {}),
+    ...(typeof record.correlation_id === "string"
+      ? { correlation_id: record.correlation_id }
+      : {}),
+    ...(record.data !== undefined ? { data: record.data } : {}),
+    delivery: normalizeRunOutboxDelivery(record.delivery),
+    ...(record.metadata &&
+    typeof record.metadata === "object" &&
+    !Array.isArray(record.metadata)
+      ? { metadata: record.metadata as Record<string, unknown> }
+      : {}),
+    event,
+    ...(typeof record.from === "string" ? { from: record.from } : {}),
+    id,
+    level: normalizeRunOutboxLevel(record.level),
+    ...(typeof record.reply_to === "string"
+      ? { reply_to: record.reply_to }
+      : {}),
+    run,
+    state_dir: stateDir,
+    summary,
+    ...(typeof record.to === "string" ? { to: record.to } : {}),
+    ts,
+    ...(typeof record.type === "string" ? { type: record.type } : {}),
+  };
+}
+
+export function parseRunOutboxEventLine(
+  line: string,
+  run: string,
+  stateDir: string,
+  index: number,
+): RunOutboxEvent | undefined {
+  try {
+    return normalizeRunOutboxEvent(JSON.parse(line), run, stateDir, index);
+  } catch {
+    return undefined;
+  }
+}
+
+export function buildRunOutboxEventPayload(
+  run: string,
+  event: {
+    body?: unknown;
+    correlation_id?: string;
+    data?: unknown;
+    delivery?: string;
+    event?: string;
+    from?: string;
+    level?: string;
+    metadata?: Record<string, unknown>;
+    reply_to?: string;
+    summary?: string;
+    to?: string;
+    type?: string;
+  },
+): Record<string, unknown> {
+  const type = event.type || event.event || "run.message";
+  const to = event.to || "coordinator";
+  const metadata = event.metadata ?? {};
+  const requiresResponse = metadata.requires_response === true;
+  return {
+    ...(event.body !== undefined ? { body: event.body } : {}),
+    ...(event.correlation_id ? { correlation_id: event.correlation_id } : {}),
+    ...(event.data !== undefined ? { data: event.data } : {}),
+    delivery: normalizeRunOutboxDelivery(
+      event.delivery ??
+        (requiresResponse
+          ? "followup"
+          : to === "coordinator"
+            ? "notify"
+            : "log"),
+    ),
+    event: type,
+    from: event.from || `run:${run}`,
+    level: normalizeRunOutboxLevel(event.level),
+    ...(event.metadata ? { metadata: event.metadata } : {}),
+    ...(event.reply_to ? { reply_to: event.reply_to } : {}),
+    summary: event.summary || type,
+    to,
+    ts: new Date().toISOString(),
+    type,
+  };
+}

package/lib/runs-process.ts

@@ -0,0 +1,51 @@
+/**
+ * Async run process identity helpers.
+ * Owns liveness checks and Linux runner identity matching for run-owned processes.
+ */
+
+import { existsSync, readFileSync, readlinkSync } from "node:fs";
+import { platform } from "node:os";
+import { resolve } from "node:path";
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function pidMatchesRun(
+  pid: number,
+  cwd: string,
+  stateDir: string,
+  runnerPath: string,
+): boolean {
+  if (platform() !== "linux" || !existsSync(`/proc/${pid}`))
+    return isAlive(pid);
+  try {
+    const procCwd = readlinkSync(`/proc/${pid}/cwd`);
+    const cmdline = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+    return (
+      procCwd === resolve(cwd) &&
+      cmdline.includes(runnerPath) &&
+      cmdline.includes(stateDir)
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function isWithinRunnerIdentityGrace(
+  meta: Record<string, unknown>,
+  graceMs: number,
+): boolean {
+  const createdAt =
+    typeof meta.createdAt === "string" ? Date.parse(meta.createdAt) : NaN;
+  return (
+    Number.isFinite(createdAt) &&
+    Date.now() - createdAt >= 0 &&
+    Date.now() - createdAt <= graceMs
+  );
+}

package/lib/runs-retention.ts

@@ -0,0 +1,77 @@
+/**
+ * Async run retention operations.
+ * Owns terminal-run archive and prune filesystem behavior.
+ */
+
+import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { writeJsonAtomic } from "./file-state.ts";
+import {
+  resolveArtifactManifest,
+  type RunArtifactDeclaration,
+} from "./runs-artifacts.ts";
+import { safeRunId } from "./runs-identity.ts";
+
+function archivePathFor(run: string, stateDir: string): string {
+  const archiveRoot = join(dirname(stateDir), "archived");
+  mkdirSync(archiveRoot, { recursive: true });
+  return join(
+    archiveRoot,
+    `${safeRunId(run)}-${new Date().toISOString().replace(/[:.]/g, "-")}`,
+  );
+}
+
+export function archiveTerminalRun(
+  status: Record<string, unknown>,
+): Record<string, unknown> {
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  const archiveDir = archivePathFor(run, stateDir);
+  renameSync(stateDir, archiveDir);
+  mkdirSync(stateDir, { recursive: true });
+  const tombstone = {
+    archived: true,
+    archive_dir: archiveDir,
+    original_state_dir: stateDir,
+    run,
+    status: status.status,
+    ts: new Date().toISOString(),
+  };
+  writeJsonAtomic(join(stateDir, "archive-tombstone.json"), tombstone);
+  return tombstone;
+}
+
+export function pruneTerminalRun(
+  status: Record<string, unknown>,
+  options: { preserveArtifacts?: boolean } = {},
+): Record<string, unknown> {
+  const stateDir = String(status.state_dir);
+  const run = String(status.run ?? basename(stateDir));
+  const manifest = resolveArtifactManifest(
+    status.artifacts as Record<string, RunArtifactDeclaration> | undefined,
+  );
+  const preserved: Record<string, string> = {};
+  if (options.preserveArtifacts && manifest) {
+    const preserveRoot = join(
+      dirname(stateDir),
+      "preserved-artifacts",
+      safeRunId(run),
+    );
+    mkdirSync(preserveRoot, { recursive: true });
+    for (const [name, artifact] of Object.entries(manifest)) {
+      if (!artifact.exists) continue;
+      const target = join(preserveRoot, basename(artifact.path));
+      cpSync(artifact.path, target, { force: true });
+      preserved[name] = target;
+    }
+  }
+  rmSync(stateDir, { recursive: true, force: true });
+  return {
+    pruned: true,
+    preserved_artifacts: preserved,
+    run,
+    state_dir: stateDir,
+    ts: new Date().toISOString(),
+  };
+}

package/lib/runs-start.ts

@@ -0,0 +1,98 @@
+/**
+ * Async run start guards.
+ * Owns active-run reuse checks, start lock acquisition, and safe state-dir
+ * preparation before a new runner process is spawned.
+ */
+
+import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { isAlive, pidMatchesRun } from "./runs-process.ts";
+
+const START_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+
+export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+
+export function assertNoActiveRunState(
+  stateDir: string,
+  readJson: RunJsonReader,
+  runnerPath: string,
+): void {
+  const meta = readJson(join(stateDir, "run.json"));
+  if (!meta) return;
+  const pid = Number(meta.pid || 0);
+  const cwd = String(meta.cwd ?? "");
+  if (!pid || !isAlive(pid) || !pidMatchesRun(pid, cwd, stateDir, runnerPath))
+    return;
+  throw new Error(
+    `Run state already has an active owned process: ${String(meta.run ?? stateDir)}. Stop it before reusing the same run_id or state_dir.`,
+  );
+}
+
+export function acquireStateStartLock(stateDir: string): () => void {
+  const lockDir = join(stateDir, ".start.lock");
+  try {
+    mkdirSync(lockDir);
+    writeFileSync(
+      join(lockDir, "owner.json"),
+      `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+      "utf8",
+    );
+  } catch (error) {
+    try {
+      const stat = statSync(lockDir);
+      if (Date.now() - stat.mtimeMs > START_LOCK_MAX_AGE_MS) {
+        rmSync(lockDir, { recursive: true, force: true });
+        mkdirSync(lockDir);
+        writeFileSync(
+          join(lockDir, "owner.json"),
+          `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString(), recovered: true })}\n`,
+          "utf8",
+        );
+        return () => rmSync(lockDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Keep the original lock acquisition error below.
+    }
+    throw new Error(
+      `Run state is already being started: ${stateDir}. Retry after the current start finishes.`,
+      { cause: error },
+    );
+  }
+  return () => rmSync(lockDir, { recursive: true, force: true });
+}
+
+export function prepareStateDirForStart(
+  stateDir: string,
+  readJson: RunJsonReader,
+  runnerPath: string,
+): void {
+  const existing = readJson(join(stateDir, "run.json"));
+  const existingPid = Number(existing?.pid || 0);
+  const existingCwd =
+    typeof existing?.cwd === "string" ? existing.cwd : undefined;
+  const existingResult = readJson(join(stateDir, "result.json"));
+  if (
+    !existingResult &&
+    existingPid &&
+    existingCwd &&
+    isAlive(existingPid) &&
+    pidMatchesRun(existingPid, existingCwd, stateDir, runnerPath)
+  ) {
+    throw new Error(
+      `Run state already has an active owned process: ${String(existing?.run ?? stateDir)}. Stop it before restarting.`,
+    );
+  }
+  for (const file of [
+    "events.jsonl",
+    "inbox.jsonl",
+    "outbox.jsonl",
+    "progress.json",
+    "result.json",
+    "stderr.log",
+    "stdout.log",
+    "terminal-handled.json",
+  ]) {
+    rmSync(join(stateDir, file), { force: true });
+  }
+}

package/lib/runs-status.ts

@@ -0,0 +1,78 @@
+/**
+ * Async run status and log readers.
+ * Owns status derivation from run state files plus bounded log/event tails.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AsyncRunStatus } from "./async-runs.ts";
+import { isAlive, isWithinRunnerIdentityGrace, pidMatchesRun } from "./runs-process.ts";
+import { readJsonlFileResilient } from "./state-readers.ts";
+
+export type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
+
+function getInterruptedRunStatus(
+  stateDir: string,
+): "cancelled" | "killed" | undefined {
+  const events = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "events.jsonl"),
+  ).records.slice(-200);
+  for (const event of events.reverse()) {
+    if (event.event === "run.kill") return "killed";
+    if (event.event === "run.cancel") return "cancelled";
+  }
+  return undefined;
+}
+
+export function buildRunStatus(
+  stateDir: string,
+  runOrDir: string,
+  meta: Record<string, unknown>,
+  readJson: RunJsonReader,
+  runnerPath: string,
+  runnerIdentityGraceMs: number,
+): Record<string, unknown> {
+  const result = readJson(join(stateDir, "result.json"));
+  const pid = Number(meta.pid || 0);
+  const aliveOwnedRunner = Boolean(
+    pid &&
+      isAlive(pid) &&
+      (!Array.isArray(meta.argv) ||
+        pidMatchesRun(pid, String(meta.cwd ?? ""), stateDir, runnerPath) ||
+        isWithinRunnerIdentityGrace(meta, runnerIdentityGraceMs)),
+  );
+  const status: AsyncRunStatus = result
+    ? Number(result.code ?? 0) === 0
+      ? "done"
+      : "failed"
+    : aliveOwnedRunner
+      ? "running"
+      : (getInterruptedRunStatus(stateDir) ?? "exited");
+  const terminalHandled = readJson(join(stateDir, "terminal-handled.json"));
+  return {
+    ...meta,
+    eventsFile: join(stateDir, "events.jsonl"),
+    inboxFile: join(stateDir, "inbox.jsonl"),
+    outboxFile: join(stateDir, "outbox.jsonl"),
+    progress: readJson(join(stateDir, "progress.json")) || null,
+    result: result || null,
+    ...(terminalHandled ? { terminal_handled: terminalHandled } : {}),
+    state_dir: String(meta.state_dir ?? stateDir),
+    stderrLog: join(stateDir, "stderr.log"),
+    stdoutLog: join(stateDir, "stdout.log"),
+    status,
+  };
+}
+
+export function tailFile(path: string, lines: number): string {
+  if (!existsSync(path)) return "";
+  const content = readFileSync(path, "utf8").trimEnd();
+  if (!content) return "";
+  return content.split("\n").slice(-lines).join("\n");
+}
+
+export function tailLines(path: string, lines: number): string[] {
+  const content = tailFile(path, lines);
+  return content ? content.split("\n") : [];
+}