@llblab/pi-actors 0.22.5 → 0.24.0

package/dist/lib/actor-rooms.js

@@ -6,7 +6,9 @@
 import * as fs from "node:fs";
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
+import * as Limits from "./limits.js";
 import { notifyRuntimeWake } from "./runtime-notifier.js";
+import { formatStateReadDiagnostics, readJsonFileResilient, readJsonlFileResilient, } from "./state-readers.js";
 const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const STATE_LOCK_TIMEOUT_MS = 5000;
 const DEFAULT_ROOM_MAX_MESSAGES = 10000;
@@ -86,14 +88,7 @@ function runFromRoomAddress(address) {
     return match?.[1];
 }
 function readJsonFile(file, fallback) {
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf8"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return fallback;
-        throw error;
-    }
+    return readJsonFileResilient(file, fallback).value;
 }
 function writeJsonFile(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -128,8 +123,23 @@ function compactRoomMessages(stateDir, room) {
         return;
     const kept = lines.slice(-maxMessages);
     fs.writeFileSync(file, `${kept.join("\n")}\n`);
+    const keptMessages = kept.flatMap((line) => {
+        try {
+            return [JSON.parse(line)];
+        }
+        catch {
+            return [];
+        }
+    });
     writeJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), {
         compacted_at: new Date().toISOString(),
+        dropped_count: lines.length - kept.length,
+        ...(keptMessages[0]?.received_at
+            ? { first_kept_at: keptMessages[0].received_at }
+            : {}),
+        ...(keptMessages.at(-1)?.received_at
+            ? { last_kept_at: keptMessages.at(-1)?.received_at }
+            : {}),
         max_messages: maxMessages,
     });
 }
@@ -250,20 +260,44 @@ function updateRosterForMessage(stateDir, room, message, receivedAt) {
             last_seen: receivedAt,
             ...(current?.caps !== undefined ? { caps: current.caps } : {}),
             ...(current?.claim !== undefined ? { claim: current.claim } : {}),
-            ...(current?.display !== undefined ? { display: current.display } : {}),
+            ...(current?.display !== undefined
+                ? { display: current.display }
+                : {}),
             ...(current?.parent !== undefined ? { parent: current.parent } : {}),
-            ...(current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+            ...(current?.role !== undefined
+                ? { role: current.role }
+                : { role: "actor" }),
             status: String(body.status ?? "left"),
         }
         : {
             address: message.from,
             joined_at: current?.joined_at ?? receivedAt,
             last_seen: receivedAt,
-            ...(body.caps !== undefined ? { caps: body.caps } : current?.caps !== undefined ? { caps: current.caps } : {}),
-            ...(body.claim !== undefined ? { claim: body.claim } : current?.claim !== undefined ? { claim: current.claim } : {}),
-            ...(body.display !== undefined ? { display: body.display } : current?.display !== undefined ? { display: current.display } : {}),
-            ...(body.parent !== undefined ? { parent: body.parent } : current?.parent !== undefined ? { parent: current.parent } : {}),
-            ...(body.role !== undefined ? { role: body.role } : current?.role !== undefined ? { role: current.role } : { role: "actor" }),
+            ...(body.caps !== undefined
+                ? { caps: body.caps }
+                : current?.caps !== undefined
+                    ? { caps: current.caps }
+                    : {}),
+            ...(body.claim !== undefined
+                ? { claim: body.claim }
+                : current?.claim !== undefined
+                    ? { claim: current.claim }
+                    : {}),
+            ...(body.display !== undefined
+                ? { display: body.display }
+                : current?.display !== undefined
+                    ? { display: current.display }
+                    : {}),
+            ...(body.parent !== undefined
+                ? { parent: body.parent }
+                : current?.parent !== undefined
+                    ? { parent: current.parent }
+                    : {}),
+            ...(body.role !== undefined
+                ? { role: body.role }
+                : current?.role !== undefined
+                    ? { role: current.role }
+                    : { role: "actor" }),
             status: String(body.status ?? current?.status ?? "present"),
         };
     roster[message.from] = next;
@@ -354,6 +388,43 @@ export function appendBranchInboxMessage(stateDir, run, address, message) {
         releaseLock();
     }
 }
+export function claimBranchInboxMessage(stateDir, run, address, owner = "runtime", statuses = ["queued"]) {
+    const branch = branchIdFromAddress(address, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+    const releaseLock = acquireBranchInboxLock(stateDir, branch);
+    try {
+        const file = branchInboxFile(stateDir, branch);
+        const records = readAllBranchInboxLines(stateDir, run, address);
+        let claimed;
+        const now = new Date().toISOString();
+        const updated = records.map((record) => {
+            if (claimed || !("message" in record))
+                return record;
+            const status = record.message.status ?? "queued";
+            if (!statuses.includes(status))
+                return record;
+            claimed = {
+                ...record.message,
+                claimed_at: now,
+                claimed_by: owner,
+                status: "claimed",
+            };
+            return { message: claimed };
+        });
+        if (!claimed)
+            return undefined;
+        fs.writeFileSync(file, `${updated.map((record) => ("raw" in record ? record.raw : JSON.stringify(record.message))).join("\n")}\n`);
+        notifyActorWake(stateDir, address, "branch.inbox.claim", {
+            id: claimed.id,
+            owner,
+        });
+        return claimed;
+    }
+    finally {
+        releaseLock();
+    }
+}
 export function updateBranchInboxMessageStatus(stateDir, run, address, id, status, metadata = {}) {
     const branch = branchIdFromAddress(address, run);
     if (!branch)
@@ -368,7 +439,14 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
             if (!("message" in record) || record.message.id !== id)
                 return record;
             changed = true;
-            return { message: { ...record.message, ...metadata, [timestampKey]: new Date().toISOString(), status } };
+            return {
+                message: {
+                    ...record.message,
+                    ...metadata,
+                    [timestampKey]: new Date().toISOString(),
+                    status,
+                },
+            };
         });
         if (!changed)
             return false;
@@ -422,7 +500,14 @@ export function appendRoomMessage(stateDir, room, message) {
 export function readRoomMessages(stateDir, room, limit = 40) {
     try {
         const lines = readJsonlTailLines(messagesFile(stateDir, room), limit);
-        return lines.map((line) => JSON.parse(line));
+        return lines.flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -430,7 +515,7 @@ export function readRoomMessages(stateDir, room, limit = 40) {
         throw error;
     }
 }
-function previewValue(value, maxLength = 120) {
+function previewValue(value, maxLength = Limits.ROOM_MESSAGE_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
     const text = typeof value === "string" ? value : JSON.stringify(value);
@@ -443,7 +528,9 @@ function previewValue(value, maxLength = 120) {
 }
 export function readRoomMessagePreviews(stateDir, room, limit = 40) {
     return readRoomMessages(stateDir, room, limit).map((message) => ({
-        ...(previewValue(message.body) ? { body_preview: previewValue(message.body) } : {}),
+        ...(previewValue(message.body)
+            ? { body_preview: previewValue(message.body) }
+            : {}),
         ...(message.from ? { from: message.from } : {}),
         ...(message.summary ? { summary: message.summary } : {}),
         timestamp: message.received_at,
@@ -454,6 +541,14 @@ export function readRoomMessagePreviews(stateDir, room, limit = 40) {
 export function getRoomStatus(stateDir, room) {
     const messageCount = readRoomMessageCount(stateDir, room);
     const [last] = readRoomMessages(stateDir, room, 1);
+    const compactionRead = readJsonFileResilient(path.join(roomDir(stateDir, room), "compaction.json"), undefined);
+    const rosterRead = readJsonFileResilient(rosterFile(stateDir, room), {});
+    const messageRead = readJsonlFileResilient(messagesFile(stateDir, room));
+    const diagnostics = [
+        ...messageRead.diagnostics,
+        ...rosterRead.diagnostics,
+        ...compactionRead.diagnostics,
+    ];
     return {
         ...(last
             ? {
@@ -463,9 +558,16 @@ export function getRoomStatus(stateDir, room) {
                 last_message_type: last.type,
             }
             : {}),
+        ...(compactionRead.value ? { compaction: compactionRead.value } : {}),
+        ...(diagnostics.length
+            ? {
+                diagnostics: formatStateReadDiagnostics(diagnostics),
+                diagnostics_count: diagnostics.length,
+            }
+            : {}),
         message_count: messageCount,
         room,
-        roster_count: Object.keys(readRoomRoster(stateDir, room)).length,
+        roster_count: Object.keys(rosterRead.value).length,
     };
 }
 export function ensureRoomMember(stateDir, run, room, address, body, summary) {
@@ -490,14 +592,7 @@ export function ensureDefaultRoom(stateDir, run) {
     return ensureRoomMember(stateDir, run, "main", `run:${run}`, { role: "run", status: "present" }, "Run joined default room");
 }
 export function readCommunicationSnapshot(stateDir) {
-    try {
-        return JSON.parse(fs.readFileSync(snapshotFile(stateDir), "utf8"));
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
-        throw error;
-    }
+    return readJsonFileResilient(snapshotFile(stateDir), undefined).value;
 }
 export function readRoomContacts(stateDir, room, self) {
     return Object.values(readRoomRoster(stateDir, room))

package/dist/lib/actor-worker.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical mailbox-backed actor worker entrypoint logic.
+ * Zones: worker demo, mailbox loop recipe runtime
+ */
+interface ActorWorkerArgs {
+    branch?: string;
+    poll_ms?: string | number;
+    run?: string;
+    state_dir?: string;
+}
+export declare function parseActorWorkerArgs(argv: string[]): ActorWorkerArgs;
+export declare function runActorWorker(argv?: string[]): Promise<void>;
+export {};

package/dist/lib/actor-worker.js

@@ -0,0 +1,86 @@
+/**
+ * Canonical mailbox-backed actor worker entrypoint logic.
+ * Zones: worker demo, mailbox loop recipe runtime
+ */
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendRoomMessage, ensureRoomMember } from "./actor-rooms.js";
+import { handleMailboxLoopOnce, isMailboxLoopStopMessage } from "./mailbox-loop.js";
+export function parseActorWorkerArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token.startsWith("--"))
+            continue;
+        const key = token.slice(2).replaceAll("-", "_");
+        const next = argv[index + 1];
+        if (!next || next.startsWith("--")) {
+            args[key] = true;
+            continue;
+        }
+        args[key] = next;
+        index += 1;
+    }
+    return args;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function text(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+export async function runActorWorker(argv = process.argv.slice(2)) {
+    const args = parseActorWorkerArgs(argv);
+    const stateDir = String(args.state_dir ?? "");
+    const run = String(args.run ?? "");
+    const branch = String(args.branch ?? "worker");
+    const pollMs = Math.max(50, Number(args.poll_ms ?? 1000));
+    if (!stateDir || !run) {
+        throw new Error("usage: actor-worker.mjs --state-dir <dir> --run <id> [--branch worker] [--poll-ms 1000]");
+    }
+    const branchAddress = `branch:${run}/${branch}`;
+    const roomAddress = `room:${run}`;
+    const journalPath = join(stateDir, "worker-events.jsonl");
+    function journal(event, data = {}) {
+        appendFileSync(journalPath, `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`);
+    }
+    function room(type, summary, body = {}) {
+        appendRoomMessage(stateDir, "main", {
+            body,
+            from: branchAddress,
+            summary,
+            to: roomAddress,
+            type,
+        });
+    }
+    ensureRoomMember(stateDir, run, "main", branchAddress, { display: branch, role: "worker", status: "present" }, `${branch} joined as mailbox worker`);
+    room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+    journal("worker.started", { branch, run });
+    let stopping = false;
+    while (!stopping) {
+        const result = await handleMailboxLoopOnce({ address: branchAddress, kind: "branch", run, stateDir }, (message) => {
+            if (isMailboxLoopStopMessage(message)) {
+                stopping = true;
+                room("actor.leave", `${branch} stopping`, { branch, reason: message.type });
+                journal("worker.stopping", { id: message.id, type: message.type });
+                return;
+            }
+            room("task.claim", `${branch} claimed ${message.type}`, {
+                branch,
+                id: message.id,
+                type: message.type,
+            });
+            room("task.result", `${branch} handled ${message.type}`, {
+                branch,
+                id: message.id,
+                result: text(message.body),
+                type: message.type,
+            });
+            room("awaiting_assignment", `${branch} awaiting assignment`, { branch });
+            journal("task.handled", { id: message.id, type: message.type });
+        }, { owner: branchAddress });
+        if (!result.handled)
+            await sleep(pollMs);
+    }
+    journal("worker.done", { branch, run });
+}

package/dist/lib/async-runner.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Detached async-runner entrypoint logic.
+ * Zones: async run process, command-template execution telemetry
+ */
+export declare function runAsyncRunner(stateDir?: string): Promise<void>;

package/dist/lib/async-runner.js

@@ -0,0 +1,134 @@
+/**
+ * Detached async-runner entrypoint logic.
+ * Zones: async run process, command-template execution telemetry
+ */
+import { appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendRecipeContextToPiArgs } from "./actor-recipe-context.js";
+import { execCommandTemplate } from "./command-templates.js";
+import { executeRegisteredTool } from "./execution.js";
+import { writeJsonAtomic } from "./file-state.js";
+function quoteCommandDetailPart(value) {
+    if (value === "")
+        return "''";
+    if (/^[A-Za-z0-9_/:=.,@%+\-]+$/.test(value))
+        return value;
+    return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+function formatCommandDetail(command, args) {
+    return [command, ...args].map(quoteCommandDetailPart).join(" ");
+}
+function summarizeCommandDetail(commandDetail) {
+    return commandDetail.length > 160
+        ? `${commandDetail.slice(0, 157)}...`
+        : commandDetail;
+}
+export async function runAsyncRunner(stateDir = process.argv[2]) {
+    if (!stateDir)
+        throw new Error("missing state dir");
+    const runPath = join(stateDir, "run.json");
+    const progressPath = join(stateDir, "progress.json");
+    const resultPath = join(stateDir, "result.json");
+    const eventsPath = join(stateDir, "events.jsonl");
+    const outboxPath = join(stateDir, "outbox.jsonl");
+    const stdoutPath = join(stateDir, "stdout.log");
+    const stderrPath = join(stateDir, "stderr.log");
+    const meta = JSON.parse(readFileSync(runPath, "utf8"));
+    function event(name, data = {}) {
+        appendFileSync(eventsPath, `${JSON.stringify({ event: name, ts: new Date().toISOString(), ...data })}\n`);
+    }
+    function outbox(name, summary, data = {}, delivery = "log", level = "info") {
+        appendFileSync(outboxPath, `${JSON.stringify({ body: data, data, delivery, event: name, from: `run:${meta.run}`, level, summary, to: "coordinator", ts: new Date().toISOString(), type: name })}\n`);
+    }
+    function progress(phase, extra = {}) {
+        writeJsonAtomic(progressPath, {
+            phase,
+            updatedAt: new Date().toISOString(),
+            ...extra,
+        });
+    }
+    let activeSubagents = 0;
+    let completedSubagents = 0;
+    const subagentFailures = [];
+    function getCommandDoneDelivery(result) {
+        return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
+    }
+    function progressRunning() {
+        progress("running", {
+            activeSubagents,
+            completed: completedSubagents,
+            failures: subagentFailures,
+        });
+    }
+    async function observedExec(command, args, options) {
+        const commandDetail = formatCommandDetail(command, args);
+        const execArgs = appendRecipeContextToPiArgs(command, args, meta.recipe_context_records, options?.actorRecipeContext);
+        activeSubagents += 1;
+        event("command.start", { activeSubagents, command: commandDetail });
+        progressRunning();
+        const result = await execCommandTemplate(command, execArgs, options);
+        activeSubagents = Math.max(0, activeSubagents - 1);
+        completedSubagents += 1;
+        if (result.code !== 0) {
+            subagentFailures.push({
+                code: result.code,
+                command: commandDetail,
+                killed: result.killed,
+            });
+        }
+        event("command.done", {
+            activeSubagents,
+            code: result.code,
+            command: commandDetail,
+            killed: result.killed,
+        });
+        outbox("command.done", `Command ${summarizeCommandDetail(commandDetail)} completed with code ${result.code}`, {
+            activeSubagents,
+            ...(meta.artifacts ? { artifacts: meta.artifacts } : {}),
+            run_files: [stdoutPath, stderrPath, resultPath, eventsPath, outboxPath],
+            code: result.code,
+            command: commandDetail,
+            killed: result.killed,
+        }, getCommandDoneDelivery(result), result.code === 0 ? "info" : "error");
+        progressRunning();
+        return result;
+    }
+    try {
+        event("run.runner.start", { pid: process.pid });
+        progressRunning();
+        const result = await executeRegisteredTool({
+            name: "run_actor",
+            description: "Detached command-template run actor",
+            template: meta.template,
+            args: [],
+            defaults: {},
+        }, meta.values || {}, observedExec, meta.cwd);
+        const text = result.content?.[0]?.text || "";
+        appendFileSync(stdoutPath, text);
+        writeJsonAtomic(resultPath, {
+            code: result.details.code,
+            command: result.details.command,
+            killed: result.details.killed,
+            truncated: result.details.truncated,
+            completedAt: new Date().toISOString(),
+        });
+        progress("done", {
+            completed: 1,
+            failures: result.details.nonCriticalFailures || [],
+        });
+        event("run.done", { code: result.details.code });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        appendFileSync(stderrPath, `${message}\n`);
+        writeJsonAtomic(resultPath, {
+            code: 1,
+            error: message,
+            killed: false,
+            completedAt: new Date().toISOString(),
+        });
+        progress("failed", { completed: 0, failures: [{ message }] });
+        event("run.failed", { error: message });
+        throw error;
+    }
+}

package/dist/lib/async-runs.d.ts

@@ -29,7 +29,7 @@ export interface AsyncRunStartParams {
     timeout?: number | string;
     delay?: number | string;
     output?: string;
-    artifacts?: Record<string, string>;
+    artifacts?: Record<string, RunArtifactDeclaration>;
     mailbox?: RecipeReferences.TemplateRecipeMailbox;
     retire_when?: "children_terminal";
     retry?: number | string;
@@ -76,15 +76,43 @@ export interface AsyncRunMeta {
     tool?: string;
     template: CommandTemplateValue;
     values: Record<string, unknown>;
-    artifacts?: Record<string, string>;
+    artifacts?: Record<string, RunArtifactDeclaration>;
     control?: AsyncRunControlEndpoint;
     mailbox?: RecipeReferences.TemplateRecipeMailbox;
     recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
     retire_when?: "children_terminal";
 }
+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 declare function resolveArtifactManifest(artifacts: Record<string, RunArtifactDeclaration> | undefined): Record<string, RunArtifactManifestEntry> | undefined;
 export declare function startRun(params: AsyncRunStartParams, cwd: string): AsyncRunMeta;
 export declare function parseRunOutboxEventLine(line: string, run: string, stateDir: string, index: number): RunOutboxEvent | undefined;
 export declare function getRunStatus(runOrDir: string): Record<string, unknown>;
+export interface RunStateIndexEntry {
+    ownerId?: string;
+    recipe?: string;
+    run: string;
+    state_dir: string;
+    status: AsyncRunStatus;
+    tool?: string;
+    updated_at?: string;
+}
+export declare function listRunStateDirs(stateRoot?: string, depth?: number, seen?: Set<string>): string[];
+export declare function rebuildRunStateIndex(stateRoot?: string): RunStateIndexEntry[];
+export declare function readRunStateIndex(stateRoot?: string): RunStateIndexEntry[] | undefined;
 export declare function listRuns(stateRoot?: string, statusFilter?: string): Array<Record<string, unknown>>;
 export declare function tailRun(runOrDir: string, lines?: number): string;
 export declare function readRunEvents(runOrDir: string, lines?: number): RunOutboxEvent[];
@@ -132,4 +160,8 @@ export interface RunProcessSignalPlan {
 }
 export declare function getRunProcessSignalPlan(pid: number, signal: NodeJS.Signals, runtimePlatform?: NodeJS.Platform): RunProcessSignalPlan;
 export declare function cancelRun(runOrDir: string): Record<string, unknown>;
+export declare function archiveRun(runOrDir: string): Record<string, unknown>;
+export declare function pruneRun(runOrDir: string, options?: {
+    preserveArtifacts?: boolean;
+}): Record<string, unknown>;
 export declare function killRun(runOrDir: string): Record<string, unknown>;