@llblab/pi-actors 0.19.10 → 0.20.0

package/dist/lib/actor-rooms.js

@@ -0,0 +1,468 @@
+/**
+ * Actor room persistence helpers.
+ * Zones: room timelines, room rosters, cross-branch discovery state
+ * Owns small file-backed room state; routing policy stays in tools/runtime adapters.
+ */
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+const STATE_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
+const STATE_LOCK_TIMEOUT_MS = 5000;
+const DEFAULT_ROOM_MAX_MESSAGES = 10000;
+const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 250;
+function roomDir(stateDir, room) {
+    return path.join(stateDir, "rooms", room);
+}
+function messagesFile(stateDir, room) {
+    return path.join(roomDir(stateDir, room), "messages.jsonl");
+}
+function rosterFile(stateDir, room) {
+    return path.join(roomDir(stateDir, room), "roster.json");
+}
+function snapshotFile(stateDir) {
+    return path.join(stateDir, "communication.json");
+}
+function branchSnapshotFile(stateDir, branch) {
+    return path.join(stateDir, "branches", branch, "communication.json");
+}
+function branchInboxFile(stateDir, branch) {
+    return path.join(stateDir, "branches", branch, "inbox.jsonl");
+}
+function branchIdFromAddress(address, run) {
+    if (!address)
+        return undefined;
+    const match = new RegExp(`^branch:${run}/(.+)$`).exec(address);
+    return match?.[1];
+}
+function ensureRoomDir(stateDir, room) {
+    fs.mkdirSync(roomDir(stateDir, room), { recursive: true });
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireStateLock(parentDir, name, label) {
+    fs.mkdirSync(parentDir, { recursive: true });
+    const lockDir = path.join(parentDir, name);
+    const started = Date.now();
+    while (true) {
+        try {
+            fs.mkdirSync(lockDir);
+            fs.writeFileSync(path.join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`);
+            return () => fs.rmSync(lockDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            try {
+                const stat = fs.statSync(lockDir);
+                if (Date.now() - stat.mtimeMs > STATE_LOCK_MAX_AGE_MS) {
+                    fs.rmSync(lockDir, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() - started > STATE_LOCK_TIMEOUT_MS) {
+                throw new Error(`${label} lock timed out.`, { cause: error });
+            }
+            sleepSync(10);
+        }
+    }
+}
+function acquireRoomLock(stateDir, room) {
+    return acquireStateLock(roomDir(stateDir, room), ".append.lock", `Room append ${room}`);
+}
+function acquireBranchInboxLock(stateDir, branch) {
+    return acquireStateLock(path.dirname(branchInboxFile(stateDir, branch)), ".inbox.lock", `Branch inbox ${branch}`);
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function runFromRoomAddress(address) {
+    const match = /^room:([^/]+)(?:\/main)?$/.exec(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;
+    }
+}
+function writeJsonFile(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+function positiveEnvInt(name, fallback) {
+    const value = Number(process.env[name] ?? fallback);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+function roomMaxMessages() {
+    return positiveEnvInt("PI_ACTORS_ROOM_MAX_MESSAGES", DEFAULT_ROOM_MAX_MESSAGES);
+}
+function snapshotMinIntervalMs() {
+    return positiveEnvInt("PI_ACTORS_COMMUNICATION_SNAPSHOT_MIN_MS", DEFAULT_SNAPSHOT_MIN_INTERVAL_MS);
+}
+function rosterMinIntervalMs() {
+    return positiveEnvInt("PI_ACTORS_ROOM_ROSTER_MIN_MS", DEFAULT_SNAPSHOT_MIN_INTERVAL_MS);
+}
+function compactRoomMessages(stateDir, room) {
+    const maxMessages = roomMaxMessages();
+    const file = messagesFile(stateDir, room);
+    const lines = readJsonlTailLines(file, maxMessages + 1);
+    if (lines.length <= maxMessages)
+        return;
+    const kept = lines.slice(-maxMessages);
+    fs.writeFileSync(file, `${kept.join("\n")}\n`);
+    writeJsonFile(path.join(roomDir(stateDir, room), "compaction.json"), {
+        compacted_at: new Date().toISOString(),
+        max_messages: maxMessages,
+    });
+}
+function readJsonlLineCount(file) {
+    const stat = fs.statSync(file);
+    if (stat.size === 0)
+        return 0;
+    const fd = fs.openSync(file, "r");
+    try {
+        const chunkSize = 64 * 1024;
+        const chunk = Buffer.allocUnsafe(chunkSize);
+        let position = 0;
+        let count = 0;
+        let lastByte;
+        while (position < stat.size) {
+            const bytesRead = fs.readSync(fd, chunk, 0, Math.min(chunkSize, stat.size - position), position);
+            if (bytesRead <= 0)
+                break;
+            position += bytesRead;
+            for (let index = 0; index < bytesRead; index += 1) {
+                if (chunk[index] === 10)
+                    count += 1;
+            }
+            lastByte = chunk[bytesRead - 1];
+        }
+        return lastByte === 10 ? count : count + 1;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function readJsonlTailLines(file, limit) {
+    const lineLimit = Math.max(1, limit);
+    const stat = fs.statSync(file);
+    if (stat.size === 0)
+        return [];
+    const fd = fs.openSync(file, "r");
+    try {
+        const chunkSize = 64 * 1024;
+        const chunks = [];
+        let position = stat.size;
+        let newlines = 0;
+        while (position > 0 && newlines <= lineLimit) {
+            const size = Math.min(chunkSize, position);
+            position -= size;
+            const chunk = Buffer.allocUnsafe(size);
+            fs.readSync(fd, chunk, 0, size, position);
+            chunks.unshift(chunk);
+            for (let index = size - 1; index >= 0; index -= 1) {
+                if (chunk[index] === 10)
+                    newlines += 1;
+            }
+        }
+        return Buffer.concat(chunks)
+            .toString("utf8")
+            .split("\n")
+            .filter(Boolean)
+            .slice(-lineLimit);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function readRoomRoster(stateDir, room) {
+    return readJsonFile(rosterFile(stateDir, room), {});
+}
+function writeRoomRoster(stateDir, room, roster) {
+    ensureRoomDir(stateDir, room);
+    writeJsonFile(rosterFile(stateDir, room), roster);
+}
+function shouldDebounceFile(file, minIntervalMs) {
+    try {
+        return Date.now() - fs.statSync(file).mtimeMs < minIntervalMs;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function shouldDebounceSnapshot(file) {
+    return shouldDebounceFile(file, snapshotMinIntervalMs());
+}
+function comparableRosterMember(member) {
+    if (!member)
+        return "";
+    const { last_seen: _lastSeen, ...semantic } = member;
+    return JSON.stringify(semantic);
+}
+function shouldWriteRoomRosterMember(stateDir, room, before, after) {
+    if (!before)
+        return true;
+    if (comparableRosterMember(before) !== comparableRosterMember(after)) {
+        return true;
+    }
+    return !shouldDebounceFile(rosterFile(stateDir, room), rosterMinIntervalMs());
+}
+function updateRosterForMessage(stateDir, room, message, receivedAt) {
+    const roster = readRoomRoster(stateDir, room);
+    if (!message.from)
+        return roster;
+    const body = asRecord(message.body);
+    const current = roster[message.from];
+    const next = message.type === "actor.leave"
+        ? {
+            address: message.from,
+            joined_at: current?.joined_at ?? receivedAt,
+            last_seen: receivedAt,
+            ...(current?.caps !== undefined ? { caps: current.caps } : {}),
+            ...(current?.claim !== undefined ? { claim: current.claim } : {}),
+            ...(current?.display !== undefined ? { display: current.display } : {}),
+            ...(current?.parent !== undefined ? { parent: current.parent } : {}),
+            ...(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" }),
+            status: String(body.status ?? current?.status ?? "present"),
+        };
+    roster[message.from] = next;
+    if (shouldWriteRoomRosterMember(stateDir, room, current, next)) {
+        writeRoomRoster(stateDir, room, roster);
+    }
+    return roster;
+}
+export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
+    const branch = branchIdFromAddress(address, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+    try {
+        return readJsonlTailLines(branchInboxFile(stateDir, branch), limit).map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+export function appendBranchInboxMessage(stateDir, run, address, message) {
+    const branch = branchIdFromAddress(address, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+    const releaseLock = acquireBranchInboxLock(stateDir, branch);
+    try {
+        fs.writeFileSync(branchInboxFile(stateDir, branch), `${JSON.stringify({ ...message, id: randomUUID(), queued_at: new Date().toISOString(), status: "queued" })}\n`, { flag: "a" });
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function updateBranchInboxMessageStatus(stateDir, run, address, id, status, metadata = {}) {
+    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 messages = readBranchInboxMessages(stateDir, run, address, Number.MAX_SAFE_INTEGER);
+        let changed = false;
+        const timestampKey = `${status}_at`;
+        const updated = messages.map((message) => {
+            if (message.id !== id)
+                return message;
+            changed = true;
+            return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
+        });
+        if (!changed)
+            return false;
+        fs.writeFileSync(file, `${updated.map((message) => JSON.stringify(message)).join("\n")}\n`);
+        return true;
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function appendRoomMessage(stateDir, room, message) {
+    const releaseLock = acquireRoomLock(stateDir, room);
+    try {
+        const receivedAt = new Date().toISOString();
+        const entry = { ...message, received_at: receivedAt };
+        fs.appendFileSync(messagesFile(stateDir, room), `${JSON.stringify(entry)}\n`);
+        compactRoomMessages(stateDir, room);
+        const roster = updateRosterForMessage(stateDir, room, message, receivedAt);
+        const run = runFromRoomAddress(message.to);
+        if (run) {
+            writeCommunicationSnapshot(stateDir, run);
+            if (message.from && branchIdFromAddress(message.from, run)) {
+                writeBranchCommunicationSnapshotDebounced(stateDir, run, message.from);
+            }
+        }
+        return {
+            message_count: readRoomMessages(stateDir, room).length,
+            room,
+            roster_count: Object.keys(roster).length,
+            sent: true,
+        };
+    }
+    finally {
+        releaseLock();
+    }
+}
+export function readRoomMessages(stateDir, room, limit = 40) {
+    try {
+        const lines = readJsonlTailLines(messagesFile(stateDir, room), limit);
+        return lines.map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+function previewValue(value, maxLength = 120) {
+    if (value === undefined)
+        return undefined;
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const compact = text.replaceAll(/\s+/g, " ").trim();
+    if (!compact)
+        return undefined;
+    return compact.length > maxLength
+        ? `${compact.slice(0, Math.max(0, maxLength - 1))}…`
+        : compact;
+}
+export function readRoomMessagePreviews(stateDir, room, limit = 40) {
+    return readRoomMessages(stateDir, room, limit).map((message) => ({
+        ...(previewValue(message.body) ? { body_preview: previewValue(message.body) } : {}),
+        ...(message.from ? { from: message.from } : {}),
+        ...(message.summary ? { summary: message.summary } : {}),
+        timestamp: message.received_at,
+        to: message.to,
+        type: message.type,
+    }));
+}
+export function getRoomStatus(stateDir, room) {
+    let messageCount = 0;
+    try {
+        messageCount = readJsonlLineCount(messagesFile(stateDir, room));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const [last] = readRoomMessages(stateDir, room, 1);
+    return {
+        ...(last
+            ? {
+                last_message_at: last.received_at,
+                ...(last.from ? { last_message_from: last.from } : {}),
+                ...(last.summary ? { last_message_summary: last.summary } : {}),
+                last_message_type: last.type,
+            }
+            : {}),
+        message_count: messageCount,
+        room,
+        roster_count: Object.keys(readRoomRoster(stateDir, room)).length,
+    };
+}
+export function ensureRoomMember(stateDir, run, room, address, body, summary) {
+    const roster = readRoomRoster(stateDir, room);
+    if (roster[address]) {
+        return {
+            message_count: readRoomMessages(stateDir, room).length,
+            room,
+            roster_count: Object.keys(roster).length,
+            sent: true,
+        };
+    }
+    return appendRoomMessage(stateDir, room, {
+        body,
+        from: address,
+        summary,
+        to: `room:${run}`,
+        type: "actor.join",
+    });
+}
+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;
+    }
+}
+export function readRoomContacts(stateDir, room, self) {
+    return Object.values(readRoomRoster(stateDir, room))
+        .filter((member) => member.address !== self)
+        .map((member) => ({
+        address: member.address,
+        ...(member.caps !== undefined ? { caps: member.caps } : {}),
+        ...(member.claim !== undefined ? { claim: member.claim } : {}),
+        ...(member.parent !== undefined ? { parent: member.parent } : {}),
+        ...(member.role !== undefined ? { role: member.role } : {}),
+        ...(member.status !== undefined ? { status: member.status } : {}),
+    }));
+}
+function buildCommunicationSnapshot(stateDir, run, self) {
+    const mainRoster = Object.values(readRoomRoster(stateDir, "main"));
+    const contacts = readRoomContacts(stateDir, "main", self);
+    return {
+        ...(contacts.length > 0 ? { contacts } : {}),
+        ...(self !== `run:${run}` ? { parent: `run:${run}` } : {}),
+        root: `run:${run}`,
+        self,
+        rooms: [
+            {
+                address: `room:${run}`,
+                ...(mainRoster.length > 0 ? { members: mainRoster } : {}),
+                name: "main",
+            },
+        ],
+        updated_at: new Date().toISOString(),
+    };
+}
+export function writeCommunicationSnapshot(stateDir, run) {
+    const snapshot = buildCommunicationSnapshot(stateDir, run, `run:${run}`);
+    writeJsonFile(snapshotFile(stateDir), snapshot);
+    return snapshot;
+}
+export function writeBranchCommunicationSnapshot(stateDir, run, self) {
+    const branch = branchIdFromAddress(self, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
+    const snapshot = buildCommunicationSnapshot(stateDir, run, self);
+    writeJsonFile(branchSnapshotFile(stateDir, branch), snapshot);
+    return snapshot;
+}
+function writeBranchCommunicationSnapshotDebounced(stateDir, run, self) {
+    const branch = branchIdFromAddress(self, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${self}`);
+    if (shouldDebounceSnapshot(branchSnapshotFile(stateDir, branch)))
+        return undefined;
+    return writeBranchCommunicationSnapshot(stateDir, run, self);
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Command-template async run primitives
+ * Zones: async runtime, lifecycle, state files
+ * Owns detached run state, observation, log tailing, listing, and cancellation safety
+ */
+import type { CommandTemplateFailureScope, CommandTemplateValue } from "./command-templates.ts";
+import * as RecipeReferences from "./recipe-references.ts";
+export type AsyncRunLaunchSource = "spawn" | "tool";
+export interface AsyncRunStartParams {
+    async?: boolean;
+    file?: string;
+    launch_source?: AsyncRunLaunchSource;
+    name?: string;
+    ownerId?: string;
+    run_id?: string;
+    state_dir?: string;
+    tool?: string;
+    template?: CommandTemplateValue;
+    args?: string[];
+    defaults?: Record<string, unknown>;
+    parallel?: boolean;
+    label?: string;
+    when?: boolean | string;
+    timeout?: number | string;
+    delay?: number | string;
+    output?: string;
+    artifacts?: Record<string, string>;
+    mailbox?: RecipeReferences.TemplateRecipeMailbox;
+    retire_when?: "children_terminal";
+    retry?: number | string;
+    failure?: CommandTemplateFailureScope;
+    recover?: CommandTemplateValue;
+    repeat?: number;
+    values?: Record<string, unknown>;
+    actor_context?: boolean | string;
+    cwd?: string;
+}
+export type AsyncRunStatus = "running" | "done" | "failed" | "exited" | "cancelled" | "killed";
+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 interface AsyncRunMeta {
+    argv: string[];
+    createdAt: string;
+    cwd: string;
+    launch_source?: AsyncRunLaunchSource;
+    ownerId?: string;
+    pid: number;
+    recipe?: string;
+    recipe_file?: string;
+    run: string;
+    state_dir: string;
+    status: AsyncRunStatus;
+    tool?: string;
+    template: CommandTemplateValue;
+    values: Record<string, unknown>;
+    artifacts?: Record<string, string>;
+    mailbox?: RecipeReferences.TemplateRecipeMailbox;
+    recipe_context_records?: RecipeReferences.TemplateRecipeContextRecord[];
+    retire_when?: "children_terminal";
+}
+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 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[];
+export declare function appendRunOutboxEvent(runOrDir: 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>;
+export declare function sendRunMessage(runOrDir: string, message: string): Record<string, unknown>;
+export declare function cancelRun(runOrDir: string): Record<string, unknown>;
+export declare function killRun(runOrDir: string): Record<string, unknown>;