@llblab/pi-actors 0.42.3 → 0.43.0

package/dist/lib/runs-control-delivery.js

@@ -0,0 +1,127 @@
+/**
+ * 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.js";
+import { readJsonFileResilient } from "./state-readers.js";
+export const FIFO_ATOMIC_CONTROL_MAX_BYTES = 512;
+export function readRunControlEndpoint(stateDir, runInstanceId) {
+    const endpoint = readJsonFileResilient(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, payload) {
+    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;
+    try {
+        fd = openSync(endpoint.path, constants.O_WRONLY | constants.O_NONBLOCK);
+        return writeSync(fd, payload);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function sendToNamedPipe(endpoint, payload, send) {
+    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) => {
+            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, stateDir, request, options = {}) {
+    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;
+        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/dist/lib/runs-controls.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+export declare 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;
+}
+export declare function runControlsFile(stateDir: string): string;
+export declare function readRunControlsFromStateDir(stateDir: string): RunControlRecord[];
+export declare function appendRunControlInStateDir(stateDir: string, request: {
+    run_instance_id: string;
+    action: string;
+    input?: unknown;
+}): RunControlRecord;
+export declare function updateRunControlStatusInStateDir(stateDir: string, id: string, nextStatus: RunControlStatus, metadata?: Pick<RunControlRecord, "error">, expectedStatuses?: readonly RunControlStatus[]): boolean;
+export declare function claimRunControlInStateDir(stateDir: string, runInstanceId: string): RunControlRecord | undefined;
+export declare function processRunControlsInStateDir(stateDir: string, runInstanceId: string, handler: (control: RunControlRecord) => Promise<void> | void, limit?: number): Promise<ProcessRunControlsResult>;

package/dist/lib/runs-controls.js

@@ -0,0 +1,144 @@
+/**
+ * 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.js";
+import { readJsonlFileResilient } from "./state-readers.js";
+export const RUN_CONTROL_TERMINAL_LIMIT = 128;
+const TERMINAL_STATUSES = new Set(["handled", "failed"]);
+export function runControlsFile(stateDir) {
+    return join(stateDir, "controls.jsonl");
+}
+export function readRunControlsFromStateDir(stateDir) {
+    return readJsonlFileResilient(runControlsFile(stateDir))
+        .records;
+}
+function acquireRunControlsLock(stateDir) {
+    return acquireFileMutationLock(runControlsFile(stateDir));
+}
+function compactRunControls(records) {
+    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, records) {
+    const compacted = compactRunControls(records);
+    writeTextAtomic(runControlsFile(stateDir), compacted.length
+        ? `${compacted.map((record) => JSON.stringify(record)).join("\n")}\n`
+        : "");
+}
+export function appendRunControlInStateDir(stateDir, request) {
+    const record = {
+        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, id, nextStatus, metadata = {}, expectedStatuses) {
+    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" } : {}),
+            };
+        }
+        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`;
+            records[index] = {
+                ...record,
+                ...metadata,
+                [timestampKey]: timestamp,
+                status: nextStatus,
+            };
+        }
+        writeRunControls(stateDir, records);
+        return true;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function claimRunControlInStateDir(stateDir, runInstanceId) {
+    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 = {
+            ...records[index],
+            claimed_at: new Date().toISOString(),
+            status: "claimed",
+        };
+        records[index] = claimed;
+        writeRunControls(stateDir, records);
+        return claimed;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export async function processRunControlsInStateDir(stateDir, runInstanceId, handler, limit = 1) {
+    const result = { 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/dist/lib/runs-retention.d.ts

@@ -3,6 +3,13 @@
  * Owns: terminal-run archive and prune filesystem behavior.
  */
 import { cpSync } from "node:fs";
+export type RunRetentionAction = "archive" | "prune";
+export type RunRetentionOutcome = "queued" | "handled" | "failed";
+export declare function appendRunRetentionEvidence(status: Record<string, unknown>, action: RunRetentionAction, outcome: RunRetentionOutcome, options?: {
+    error?: string;
+    id?: string;
+    result?: Record<string, unknown>;
+}): string;
 export declare function archiveTerminalRun(status: Record<string, unknown>): Record<string, unknown>;
 export declare function pruneTerminalRun(status: Record<string, unknown>, options?: {
     preserveArtifacts?: boolean;

package/dist/lib/runs-retention.js

@@ -2,13 +2,37 @@
  * Async run retention operations.
  * 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.js";
+import { acquireFileMutationLock, writeJsonAtomic } from "./file-state.js";
 import { resolveArtifactManifest, } from "./runs-artifacts.js";
 import { safeRunId } from "./runs-identity.js";
 import { assertOwnedRunStateDirectory } from "./runs-ownership.js";
+export function appendRunRetentionEvidence(status, action, outcome, options = {}) {
+    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, path) {
     const readableName = name.replace(/[^A-Za-z0-9_.-]+/g, "_") || "artifact";
     const identity = createHash("sha256")

package/dist/lib/runs-start.js

@@ -45,15 +45,17 @@ export function prepareStateDirForStart(stateDir, readJson, _runnerPath) {
         }
     }
     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/dist/lib/runs-status.js

@@ -7,8 +7,15 @@ import { join } from "node:path";
 import { verifyRunProcessIdentity, } from "./runs-process.js";
 import { readJsonlFileResilient } from "./state-readers.js";
 function getInterruptedRunStatus(stateDir) {
-    const events = readJsonlFileResilient(join(stateDir, "events.jsonl")).records.slice(-200);
-    for (const event of events.reverse()) {
+    const trace = readJsonlFileResilient(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(join(stateDir, "events.jsonl")).records.slice(-200);
+    for (const event of legacyEvents.reverse()) {
         if (event.event === "run.kill")
             return "killed";
         if (event.event === "run.cancel")
@@ -33,10 +40,8 @@ export function buildRunStatus(stateDir, runOrDir, meta, readJson, _runnerPath,
     const terminalDeliveryFailure = readJson(join(stateDir, "terminal-delivery-failure.json"));
     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/dist/lib/runs-trace.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+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"];
+}
+export declare function runTraceFile(stateDir: string): string;
+export declare function appendRunTraceEvent(stateDir: string, input: AppendTraceEventInput): TraceEvent;
+export declare function readRunTraceEvents(stateDir: string, limit?: number): TraceEvent[];

package/dist/lib/runs-trace.js

@@ -0,0 +1,98 @@
+/**
+ * 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.js";
+import { readJsonlFileResilient } from "./state-readers.js";
+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) {
+    return join(stateDir, "trace.jsonl");
+}
+function normalizeTraceEventInput(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Trace event must be an object");
+    }
+    const record = input;
+    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 }
+            : {}),
+        ...(record.attention !== undefined
+            ? { attention: record.attention }
+            : {}),
+    };
+}
+export function appendRunTraceEvent(stateDir, input) {
+    const normalized = normalizeTraceEventInput(input);
+    const event = {
+        id: randomUUID(),
+        ts: new Date().toISOString(),
+        ...normalized,
+    };
+    let encoded;
+    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, limit = Limits.TRACE_EVENT_MAX_READ) {
+    const records = readJsonlFileResilient(runTraceFile(stateDir)).records;
+    return records.slice(-Math.max(1, Math.min(limit, Limits.TRACE_EVENT_MAX_READ)));
+}

package/dist/lib/runtime-notifier.d.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.
  */
 export interface RuntimeWakeEvent {
     actor: string;

package/dist/lib/runtime-notifier.js

@@ -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";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, watch, } from "node:fs";

package/dist/lib/tools-inspect.d.ts

@@ -1,7 +1,7 @@
 /**
- * Public inspect tool behavior
- * Zones: actor observation, recipe registry inspection, room/session/tool/run views
- * Owns the public inspect execution path and compact observation responses
+ * Public inspect tool behavior.
+ * Zones: Run Recipe/Trace/Control views and runtime/recipe/tool diagnostics
+ * Owns exact inspect target/view dispatch; source projection stays in domain modules.
  */
 export interface InspectToolDeps<TContext = unknown> {
     getRunStatus?: (runOrDir: string) => Record<string, any>;