@llblab/pi-actors 0.42.2 → 0.43.0

package/lib/runs-control-delivery.ts

@@ -0,0 +1,181 @@
+/**
+ * Run Control delivery.
+ * Zones: generation-fenced endpoint resolution, FIFO/named-pipe writes, durable outcomes
+ * Owns delivery of persisted actor-local Controls to ready service endpoints.
+ */
+
+import {
+  closeSync,
+  constants,
+  existsSync,
+  openSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { createConnection } from "node:net";
+import { join } from "node:path";
+
+import {
+  appendRunControlInStateDir,
+  updateRunControlStatusInStateDir,
+} from "./runs-controls.ts";
+import { readJsonFileResilient } from "./state-readers.ts";
+
+export interface RunControlEndpoint {
+  path: string;
+  type: "fifo" | "named-pipe";
+}
+
+export interface DeliverRunControlOptions {
+  namedPipeSend?: (path: string, payload: string) => Promise<number>;
+  platform?: NodeJS.Platform;
+}
+
+export interface DeliverRunControlRequest {
+  action: string;
+  input?: unknown;
+  run_instance_id: string;
+}
+
+export const FIFO_ATOMIC_CONTROL_MAX_BYTES = 512;
+
+export function readRunControlEndpoint(
+  stateDir: string,
+  runInstanceId: string,
+): RunControlEndpoint | undefined {
+  const endpoint = readJsonFileResilient<Record<string, unknown>>(
+    join(stateDir, "control-endpoint.json"),
+    {},
+  ).value;
+  if (endpoint.run_instance_id !== runInstanceId) return undefined;
+  if (
+    (endpoint.type === "fifo" || endpoint.type === "named-pipe") &&
+    typeof endpoint.path === "string" &&
+    endpoint.path.trim()
+  ) {
+    return { path: endpoint.path, type: endpoint.type };
+  }
+  return undefined;
+}
+
+function sendToFifo(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 sendToNamedPipe(
+  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 deliverRunControl(
+  run: string,
+  stateDir: string,
+  request: DeliverRunControlRequest,
+  options: DeliverRunControlOptions = {},
+): Promise<Record<string, unknown>> {
+  const control = appendRunControlInStateDir(stateDir, request);
+  const endpoint = readRunControlEndpoint(stateDir, request.run_instance_id);
+  if (!endpoint) {
+    updateRunControlStatusInStateDir(
+      stateDir,
+      control.id,
+      "failed",
+      { error: "control endpoint is not ready for this Run generation" },
+      ["queued", "delivered"],
+    );
+    throw Object.assign(new Error("Run Control endpoint is not ready."), {
+      action: request.action,
+      control_id: control.id,
+      reason: "endpoint_not_ready",
+      run,
+      run_instance_id: request.run_instance_id,
+    });
+  }
+  const wire = {
+    id: control.id,
+    action: request.action,
+    ...(request.input !== undefined ? { input: request.input } : {}),
+  };
+  const payload = `${JSON.stringify(wire)}\n`;
+  const bytes = Buffer.byteLength(payload);
+  try {
+    let written: number;
+    if (endpoint.type === "fifo") {
+      if ((options.platform ?? process.platform) === "win32") {
+        throw new Error("FIFO Control delivery is unsupported on native Windows");
+      }
+      if (bytes > FIFO_ATOMIC_CONTROL_MAX_BYTES) {
+        throw new Error(
+          `FIFO Control payload exceeds the ${FIFO_ATOMIC_CONTROL_MAX_BYTES}-byte portable atomic-write bound`,
+        );
+      }
+      written = sendToFifo(endpoint, payload);
+    } else {
+      written = await sendToNamedPipe(endpoint, payload, options.namedPipeSend);
+    }
+    if (written !== bytes) {
+      throw new Error(`Run Control endpoint wrote ${written} of ${bytes} bytes`);
+    }
+    updateRunControlStatusInStateDir(stateDir, control.id, "delivered");
+    return {
+      action: request.action,
+      bytes,
+      control_id: control.id,
+      delivery: "delivered",
+      endpoint_type: endpoint.type,
+      run,
+      run_instance_id: request.run_instance_id,
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    updateRunControlStatusInStateDir(
+      stateDir,
+      control.id,
+      "failed",
+      { error: reason },
+      ["queued", "delivered"],
+    );
+    throw Object.assign(new Error(`Run Control delivery failed: ${reason}`), {
+      action: request.action,
+      control_id: control.id,
+      endpoint_type: endpoint.type,
+      reason: "delivery_failed",
+      run,
+      run_instance_id: request.run_instance_id,
+    });
+  }
+}

package/lib/runs-controls.ts

@@ -0,0 +1,204 @@
+/**
+ * Run Control journal.
+ * Zones: durable Control records, claim locks, status transitions, bounded compaction
+ * Owns Run-local Control persistence; owner/generation authorization and transport delivery stay in lifecycle adapters.
+ */
+
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { acquireFileMutationLock, writeTextAtomic } from "./file-state.ts";
+import { readJsonlFileResilient } from "./state-readers.ts";
+export const RUN_CONTROL_TERMINAL_LIMIT = 128;
+
+export type RunControlStatus =
+  | "queued"
+  | "delivered"
+  | "claimed"
+  | "handled"
+  | "failed";
+
+export interface RunControlRecord {
+  id: string;
+  run_instance_id: string;
+  action: string;
+  input?: unknown;
+  status: RunControlStatus;
+  queued_at: string;
+  delivered_at?: string;
+  claimed_at?: string;
+  handled_at?: string;
+  failed_at?: string;
+  error?: string;
+}
+
+export interface ProcessRunControlsResult {
+  claimed: number;
+  failed: number;
+  handled: number;
+}
+
+const TERMINAL_STATUSES = new Set<RunControlStatus>(["handled", "failed"]);
+
+export function runControlsFile(stateDir: string): string {
+  return join(stateDir, "controls.jsonl");
+}
+
+export function readRunControlsFromStateDir(stateDir: string): RunControlRecord[] {
+  return readJsonlFileResilient<RunControlRecord>(runControlsFile(stateDir))
+    .records;
+}
+
+function acquireRunControlsLock(stateDir: string): () => void {
+  return acquireFileMutationLock(runControlsFile(stateDir));
+}
+
+function compactRunControls(records: RunControlRecord[]): RunControlRecord[] {
+  const active = records.filter((record) => !TERMINAL_STATUSES.has(record.status));
+  const terminal = records
+    .filter((record) => TERMINAL_STATUSES.has(record.status))
+    .slice(-RUN_CONTROL_TERMINAL_LIMIT);
+  const retained = new Set([...active, ...terminal]);
+  return records.filter((record) => retained.has(record));
+}
+
+function writeRunControls(stateDir: string, records: RunControlRecord[]): void {
+  const compacted = compactRunControls(records);
+  writeTextAtomic(
+    runControlsFile(stateDir),
+    compacted.length
+      ? `${compacted.map((record) => JSON.stringify(record)).join("\n")}\n`
+      : "",
+  );
+}
+
+export function appendRunControlInStateDir(
+  stateDir: string,
+  request: { run_instance_id: string; action: string; input?: unknown },
+): RunControlRecord {
+  const record: RunControlRecord = {
+    id: randomUUID(),
+    run_instance_id: request.run_instance_id,
+    action: request.action,
+    ...(request.input !== undefined ? { input: request.input } : {}),
+    status: "queued",
+    queued_at: new Date().toISOString(),
+  };
+  const releaseLock = acquireRunControlsLock(stateDir);
+  try {
+    writeFileSync(runControlsFile(stateDir), `${JSON.stringify(record)}\n`, {
+      flag: "a",
+    });
+  } finally {
+    releaseLock();
+  }
+  return record;
+}
+
+export function updateRunControlStatusInStateDir(
+  stateDir: string,
+  id: string,
+  nextStatus: RunControlStatus,
+  metadata: Pick<RunControlRecord, "error"> = {},
+  expectedStatuses?: readonly RunControlStatus[],
+): boolean {
+  const releaseLock = acquireRunControlsLock(stateDir);
+  try {
+    const records = readRunControlsFromStateDir(stateDir);
+    const index = records.findIndex((record) => record.id === id);
+    if (index < 0) return false;
+    const record = records[index]!;
+    if (expectedStatuses && !expectedStatuses.includes(record.status)) return false;
+    if (record.status === nextStatus) return false;
+    const timestamp = new Date().toISOString();
+    if (nextStatus === "delivered") {
+      if (record.delivered_at) return false;
+      records[index] = {
+        ...record,
+        delivered_at: timestamp,
+        ...(record.status === "queued" ? { status: "delivered" as const } : {}),
+      };
+    } else {
+      if (TERMINAL_STATUSES.has(record.status) || nextStatus === "queued") return false;
+      if (
+        (nextStatus === "claimed" &&
+          record.status !== "queued" &&
+          record.status !== "delivered") ||
+        (nextStatus === "handled" && record.status !== "claimed")
+      ) {
+        return false;
+      }
+      const timestampKey = `${nextStatus}_at` as const;
+      records[index] = {
+        ...record,
+        ...metadata,
+        [timestampKey]: timestamp,
+        status: nextStatus,
+      };
+    }
+    writeRunControls(stateDir, records);
+    return true;
+  } finally {
+    releaseLock();
+  }
+}
+
+export function claimRunControlInStateDir(
+  stateDir: string,
+  runInstanceId: string,
+): RunControlRecord | undefined {
+  const releaseLock = acquireRunControlsLock(stateDir);
+  try {
+    const records = readRunControlsFromStateDir(stateDir);
+    const index = records.findIndex(
+      (record) =>
+        record.run_instance_id === runInstanceId &&
+        (record.status === "queued" || record.status === "delivered"),
+    );
+    if (index < 0) return undefined;
+    const claimed: RunControlRecord = {
+      ...records[index]!,
+      claimed_at: new Date().toISOString(),
+      status: "claimed",
+    };
+    records[index] = claimed;
+    writeRunControls(stateDir, records);
+    return claimed;
+  } finally {
+    releaseLock();
+  }
+}
+
+export async function processRunControlsInStateDir(
+  stateDir: string,
+  runInstanceId: string,
+  handler: (control: RunControlRecord) => Promise<void> | void,
+  limit = 1,
+): Promise<ProcessRunControlsResult> {
+  const result: ProcessRunControlsResult = { claimed: 0, failed: 0, handled: 0 };
+  for (let index = 0; index < Math.max(1, limit); index += 1) {
+    const control = claimRunControlInStateDir(stateDir, runInstanceId);
+    if (!control) break;
+    result.claimed += 1;
+    try {
+      await handler(control);
+      if (updateRunControlStatusInStateDir(stateDir, control.id, "handled", {}, ["claimed"])) {
+        result.handled += 1;
+      }
+    } catch (error) {
+      if (
+        updateRunControlStatusInStateDir(
+          stateDir,
+          control.id,
+          "failed",
+          { error: error instanceof Error ? error.message : String(error) },
+          ["claimed"],
+        )
+      ) {
+        result.failed += 1;
+      }
+    }
+  }
+  return result;
+}

package/lib/runs-retention.ts

@@ -3,11 +3,11 @@
  * Owns: terminal-run archive and prune filesystem behavior.
  */
 
-import { createHash } from "node:crypto";
-import { cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, cpSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
-import { writeJsonAtomic } from "./file-state.ts";
+import { acquireFileMutationLock, writeJsonAtomic } from "./file-state.ts";
 import {
   resolveArtifactManifest,
   type RunArtifactDeclaration,
@@ -15,6 +15,41 @@ import {
 import { safeRunId } from "./runs-identity.ts";
 import { assertOwnedRunStateDirectory } from "./runs-ownership.ts";
 
+export type RunRetentionAction = "archive" | "prune";
+export type RunRetentionOutcome = "queued" | "handled" | "failed";
+
+export function appendRunRetentionEvidence(
+  status: Record<string, unknown>,
+  action: RunRetentionAction,
+  outcome: RunRetentionOutcome,
+  options: { error?: string; id?: string; result?: Record<string, unknown> } = {},
+): string {
+  const stateDir = String(status.state_dir);
+  const path = join(dirname(stateDir), "retention.jsonl");
+  const id = options.id ?? randomUUID();
+  const release = acquireFileMutationLock(path);
+  try {
+    appendFileSync(
+      path,
+      `${JSON.stringify({
+        action,
+        ...(options.error ? { error: options.error } : {}),
+        id,
+        outcome,
+        ...(options.result ? { result: options.result } : {}),
+        run: String(status.run ?? basename(stateDir)),
+        ...(typeof status.run_instance_id === "string"
+          ? { run_instance_id: status.run_instance_id }
+          : {}),
+        ts: new Date().toISOString(),
+      })}\n`,
+    );
+  } finally {
+    release();
+  }
+  return id;
+}
+
 function retainedArtifactFilename(name: string, path: string): string {
   const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
   const identity = createHash("sha256")

package/lib/runs-start.ts

@@ -86,15 +86,17 @@ export function prepareStateDirForStart(
     }
   }
   for (const file of [
+    "control-endpoint.json",
+    "controls.jsonl",
     "events.jsonl",
-    "inbox.jsonl",
-    "outbox.jsonl",
+    "execution.json",
     "progress.json",
     "result.json",
     "stderr.log",
     "stdout.log",
     "terminal-delivery-failure.json",
     "terminal-handled.json",
+    "trace.jsonl",
   ]) {
     rmSync(join(stateDir, file), { force: true });
   }

package/lib/runs-status.ts

@@ -25,10 +25,17 @@ type RunJsonReader = (path: string) => Record<string, unknown> | undefined;
 function getInterruptedRunStatus(
   stateDir: string,
 ): "cancelled" | "killed" | undefined {
-  const events = readJsonlFileResilient<Record<string, unknown>>(
+  const trace = readJsonlFileResilient<Record<string, unknown>>(
+    join(stateDir, "trace.jsonl"),
+  ).records.slice(-200);
+  for (const event of trace.reverse()) {
+    if (event.kind === "run.kill") return "killed";
+    if (event.kind === "run.cancel") return "cancelled";
+  }
+  const legacyEvents = readJsonlFileResilient<Record<string, unknown>>(
     join(stateDir, "events.jsonl"),
   ).records.slice(-200);
-  for (const event of events.reverse()) {
+  for (const event of legacyEvents.reverse()) {
     if (event.event === "run.kill") return "killed";
     if (event.event === "run.cancel") return "cancelled";
   }
@@ -66,10 +73,8 @@ export function buildRunStatus(
   );
   return {
     ...meta,
-    eventsFile: join(stateDir, "events.jsonl"),
-    evidenceFile: join(stateDir, "review-evidence.json"),
-    inboxFile: join(stateDir, "inbox.jsonl"),
-    outboxFile: join(stateDir, "outbox.jsonl"),
+    traceFile: join(stateDir, "trace.jsonl"),
+    executionFile: join(stateDir, "execution.json"),
     process_identity_status: processIdentity.status,
     progress: readJson(join(stateDir, "progress.json")) || null,
     result: result || null,

package/lib/runs-trace.ts

@@ -0,0 +1,132 @@
+/**
+ * Run Trace event journal.
+ * Zones: structured event validation, bounded append, resilient bounded reads
+ * Owns Run-local semantic Trace events; lifecycle projection and owner attention delivery stay in adapters.
+ */
+
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import * as Limits from "./limits.ts";
+import { readJsonlFileResilient } from "./state-readers.ts";
+
+export interface TraceEvent {
+  id: string;
+  ts: string;
+  kind: string;
+  summary?: string;
+  data?: unknown;
+  level?: "info" | "warning" | "error";
+  attention?: "notify" | "followup";
+}
+
+export interface AppendTraceEventInput {
+  kind: string;
+  summary?: string;
+  data?: unknown;
+  level?: TraceEvent["level"];
+  attention?: TraceEvent["attention"];
+}
+
+const KIND_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)*$/;
+const TRACE_INPUT_FIELDS = new Set([
+  "attention",
+  "data",
+  "kind",
+  "level",
+  "summary",
+]);
+const FORBIDDEN_FIELDS = new Set([
+  "body",
+  "correlation_id",
+  "from",
+  "metadata",
+  "reply_to",
+  "to",
+  "type",
+]);
+
+export function runTraceFile(stateDir: string): string {
+  return join(stateDir, "trace.jsonl");
+}
+
+function normalizeTraceEventInput(input: unknown): AppendTraceEventInput {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Trace event must be an object");
+  }
+  const record = input as Record<string, unknown>;
+  const forbidden = Object.keys(record).filter((key) => FORBIDDEN_FIELDS.has(key));
+  if (forbidden.length > 0) {
+    throw new Error(`Trace event fields are removed: ${forbidden.sort().join(", ")}`);
+  }
+  const unknown = Object.keys(record).filter((key) => !TRACE_INPUT_FIELDS.has(key));
+  if (unknown.length > 0) {
+    throw new Error(`Unsupported Trace event fields: ${unknown.sort().join(", ")}`);
+  }
+  if (typeof record.kind !== "string" || !KIND_PATTERN.test(record.kind)) {
+    throw new Error("Trace event kind must be a lowercase semantic token");
+  }
+  if (record.summary !== undefined && typeof record.summary !== "string") {
+    throw new Error("Trace event summary must be a string");
+  }
+  if (
+    record.level !== undefined &&
+    record.level !== "info" &&
+    record.level !== "warning" &&
+    record.level !== "error"
+  ) {
+    throw new Error("Trace event level must be info, warning, or error");
+  }
+  if (
+    record.attention !== undefined &&
+    record.attention !== "notify" &&
+    record.attention !== "followup"
+  ) {
+    throw new Error("Trace event attention must be notify or followup");
+  }
+  return {
+    kind: record.kind,
+    ...(record.summary !== undefined
+      ? { summary: record.summary.slice(0, 1_000) }
+      : {}),
+    ...(record.data !== undefined ? { data: record.data } : {}),
+    ...(record.level !== undefined
+      ? { level: record.level as TraceEvent["level"] }
+      : {}),
+    ...(record.attention !== undefined
+      ? { attention: record.attention as TraceEvent["attention"] }
+      : {}),
+  };
+}
+
+export function appendRunTraceEvent(
+  stateDir: string,
+  input: AppendTraceEventInput,
+): TraceEvent {
+  const normalized = normalizeTraceEventInput(input);
+  const event: TraceEvent = {
+    id: randomUUID(),
+    ts: new Date().toISOString(),
+    ...normalized,
+  };
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(event);
+  } catch {
+    throw new Error("Trace event data must be JSON-serializable");
+  }
+  if (Buffer.byteLength(encoded) > Limits.TRACE_EVENT_MAX_BYTES) {
+    throw new Error(`Trace event exceeds ${Limits.TRACE_EVENT_MAX_BYTES} bytes`);
+  }
+  writeFileSync(runTraceFile(stateDir), `${encoded}\n`, { flag: "a" });
+  return event;
+}
+
+export function readRunTraceEvents(
+  stateDir: string,
+  limit = Limits.TRACE_EVENT_MAX_READ,
+): TraceEvent[] {
+  const records = readJsonlFileResilient<TraceEvent>(runTraceFile(stateDir)).records;
+  return records.slice(-Math.max(1, Math.min(limit, Limits.TRACE_EVENT_MAX_READ)));
+}

package/lib/runtime-notifier.ts

@@ -1,7 +1,7 @@
 /**
  * Runtime wake notifications for actor state.
  * Zones: advisory wake layer, file-backed runtime state, cross-platform notification boundary
- * Owns best-effort live wake signals while durable mailbox/state files remain canonical.
+ * Owns best-effort live wake signals while durable Run state remains canonical.
  */
 
 import { randomUUID } from "node:crypto";