@llblab/pi-actors 0.42.2 → 0.43.0

package/dist/lib/runs-mailbox.js

@@ -1,146 +0,0 @@
-/**
- * Async run mailbox state.
- * Owns: durable run inbox records, claim locks, and handler status transitions.
- */
-import { randomUUID } from "node:crypto";
-import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { readJsonlFileResilient } from "./state-readers.js";
-const RUN_INBOX_LOCK_TIMEOUT_MS = 5000;
-const STALE_INBOX_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
-export function runInboxFile(stateDir) {
-    return join(stateDir, "inbox.jsonl");
-}
-export function parseRunInboxLine(line) {
-    try {
-        return JSON.parse(line);
-    }
-    catch {
-        return undefined;
-    }
-}
-export function readRunInboxMessagesFromStateDir(stateDir) {
-    return readJsonlFileResilient(runInboxFile(stateDir))
-        .records;
-}
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-function acquireRunInboxLock(stateDir) {
-    const lockDir = join(stateDir, ".inbox.lock");
-    const started = Date.now();
-    while (true) {
-        try {
-            mkdirSync(lockDir, { recursive: false });
-            writeFileSync(join(lockDir, "owner.json"), `${JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() })}\n`, "utf8");
-            return () => rmSync(lockDir, { recursive: true, force: true });
-        }
-        catch (error) {
-            try {
-                const stat = statSync(lockDir);
-                if (Date.now() - stat.mtimeMs > STALE_INBOX_LOCK_MAX_AGE_MS) {
-                    rmSync(lockDir, { recursive: true, force: true });
-                    continue;
-                }
-            }
-            catch {
-                continue;
-            }
-            if (Date.now() - started > RUN_INBOX_LOCK_TIMEOUT_MS) {
-                throw new Error("Run inbox lock timed out.", { cause: error });
-            }
-            sleepSync(10);
-        }
-    }
-}
-function writeRunInboxMessages(stateDir, messages) {
-    writeFileSync(runInboxFile(stateDir), messages.length
-        ? `${messages.map((message) => JSON.stringify(message)).join("\n")}\n`
-        : "", "utf8");
-}
-export function updateRunInboxMessageStatusInStateDir(stateDir, id, nextStatus, metadata = {}) {
-    const releaseLock = acquireRunInboxLock(stateDir);
-    try {
-        const messages = readRunInboxMessagesFromStateDir(stateDir);
-        const timestampKey = `${nextStatus}_at`;
-        let changed = false;
-        const updated = messages.map((message) => {
-            if (message.id !== id)
-                return message;
-            changed = true;
-            return {
-                ...message,
-                ...metadata,
-                [timestampKey]: new Date().toISOString(),
-                status: nextStatus,
-            };
-        });
-        if (changed)
-            writeRunInboxMessages(stateDir, updated);
-        return changed;
-    }
-    finally {
-        releaseLock();
-    }
-}
-export function claimRunInboxMessageInStateDir(stateDir, owner = "runtime", statuses = ["queued"]) {
-    const releaseLock = acquireRunInboxLock(stateDir);
-    try {
-        const messages = readRunInboxMessagesFromStateDir(stateDir);
-        const index = messages.findIndex((message) => statuses.includes(String(message.status ?? "queued")));
-        if (index < 0)
-            return undefined;
-        const claimed = {
-            ...messages[index],
-            claimed_at: new Date().toISOString(),
-            claimed_by: owner,
-            id: typeof messages[index].id === "string"
-                ? messages[index].id
-                : randomUUID(),
-            status: "claimed",
-        };
-        messages[index] = claimed;
-        writeRunInboxMessages(stateDir, messages);
-        return claimed;
-    }
-    finally {
-        releaseLock();
-    }
-}
-export function appendRunInboxMessageInStateDir(stateDir, record) {
-    const id = randomUUID();
-    const ts = new Date().toISOString();
-    const releaseLock = acquireRunInboxLock(stateDir);
-    try {
-        writeFileSync(runInboxFile(stateDir), `${JSON.stringify({ ...record, id, queued_at: ts, received_at: ts, status: "queued" })}\n`, { flag: "a" });
-    }
-    finally {
-        releaseLock();
-    }
-    return id;
-}
-export async function processRunInboxMessagesInStateDir(stateDir, handler, options = {}) {
-    const result = { claimed: 0, failed: 0, handled: 0 };
-    const limit = Math.max(1, Number(options.limit ?? 1));
-    const owner = options.owner ?? "runtime";
-    for (let index = 0; index < limit; index += 1) {
-        const message = claimRunInboxMessageInStateDir(stateDir, owner, options.statuses);
-        if (!message?.id)
-            break;
-        result.claimed += 1;
-        try {
-            await handler(message);
-            if (updateRunInboxMessageStatusInStateDir(stateDir, message.id, "handled")) {
-                result.handled += 1;
-            }
-        }
-        catch (error) {
-            if (updateRunInboxMessageStatusInStateDir(stateDir, message.id, "failed", {
-                error: error instanceof Error ? error.message : String(error),
-            })) {
-                result.failed += 1;
-            }
-        }
-    }
-    return result;
-}

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

@@ -1,15 +0,0 @@
-/**
- * Async run message delivery.
- * Owns: run control endpoint resolution, inbox enqueueing, wake notification,
- * transport writes, and delivery receipts.
- */
-export interface RunControlEndpoint {
-    path: string;
-    type: "fifo" | "mailbox" | "named-pipe";
-}
-export interface SendRunMessageOptions {
-    namedPipeSend?: (path: string, payload: string) => Promise<number>;
-    platform?: NodeJS.Platform;
-}
-export declare function getRunControlEndpoint(status: Record<string, unknown>, stateDir: string): RunControlEndpoint;
-export declare function deliverRunMessage(status: Record<string, unknown>, run: string, stateDir: string, message: string, options?: SendRunMessageOptions): Promise<Record<string, unknown>>;

package/dist/lib/runs-messages.js

@@ -1,179 +0,0 @@
-/**
- * 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.js";
-import { appendRunInboxMessageInStateDir, updateRunInboxMessageStatusInStateDir, } from "./runs-mailbox.js";
-import { notifyRuntimeWake } from "./runtime-notifier.js";
-export function getRunControlEndpoint(status, stateDir) {
-    const control = status.control;
-    if (control && typeof control === "object" && !Array.isArray(control)) {
-        const record = control;
-        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, message) {
-    let record;
-    try {
-        const parsed = JSON.parse(message);
-        record =
-            parsed && typeof parsed === "object" && !Array.isArray(parsed)
-                ? parsed
-                : { body: parsed, type: "run.message" };
-    }
-    catch {
-        record = { body: message, type: "run.message" };
-    }
-    return appendRunInboxMessageInStateDir(stateDir, record);
-}
-function writeRunMessageReceipt(stateDir, message, bytes, inboxId) {
-    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, 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 notifyRunMessageWake(stateDir, run, bytes, endpoint, inboxId) {
-    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, 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 deliverRunMessage(status, run, stateDir, message, options = {}) {
-    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/dist/lib/runs-outbox.d.ts

@@ -1,41 +0,0 @@
-/**
- * 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 declare function normalizeRunOutboxDelivery(value: unknown): RunOutboxDelivery;
-export declare function normalizeRunOutboxLevel(value: unknown): RunOutboxLevel;
-export declare function parseRunOutboxEventLine(line: string, run: string, stateDir: string, index: number): RunOutboxEvent | undefined;
-export declare 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>;

package/dist/lib/runs-outbox.js

@@ -1,87 +0,0 @@
-/**
- * Async run outbox events.
- * Owns: outbox event normalization, parsing, and append payload formatting.
- */
-export function normalizeRunOutboxDelivery(value) {
-    return value === "notify" || value === "followup" ? value : "log";
-}
-export function normalizeRunOutboxLevel(value) {
-    return value === "warning" || value === "error" ? value : "info";
-}
-function normalizeRunOutboxEvent(raw, run, stateDir, index) {
-    if (!raw || typeof raw !== "object" || Array.isArray(raw))
-        return undefined;
-    const record = raw;
-    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 }
-            : {}),
-        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, run, stateDir, index) {
-    try {
-        return normalizeRunOutboxEvent(JSON.parse(line), run, stateDir, index);
-    }
-    catch {
-        return undefined;
-    }
-}
-export function buildRunOutboxEventPayload(run, event) {
-    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/dist/lib/tools-mailbox.d.ts

@@ -1,8 +0,0 @@
-/**
- * Public tool mailbox contract helpers
- * Zones: accepted/emitted message type declarations, contract normalization, compact type extraction
- * Owns mailbox metadata normalization for public message and inspect tool paths
- */
-export declare function normalizeMailboxEntry(value: unknown): Record<string, unknown> | undefined;
-export declare function normalizeMailboxContracts(mailbox: Record<string, unknown>): Record<string, unknown[]>;
-export declare function mailboxTypes(entries: unknown[]): string[];

package/dist/lib/tools-mailbox.js

@@ -1,48 +0,0 @@
-/**
- * Public tool mailbox contract helpers
- * Zones: accepted/emitted message type declarations, contract normalization, compact type extraction
- * Owns mailbox metadata normalization for public message and inspect tool paths
- */
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : {};
-}
-export function normalizeMailboxEntry(value) {
-    if (typeof value === "string")
-        return { type: value };
-    const record = asRecord(value);
-    if (typeof record.type !== "string" || !record.type.trim())
-        return undefined;
-    return {
-        type: record.type.trim(),
-        ...(record.body_schema !== undefined
-            ? { body_schema: record.body_schema }
-            : {}),
-        ...(record.ack !== undefined ? { ack: record.ack } : {}),
-        ...(typeof record.idempotency === "string"
-            ? { idempotency: record.idempotency }
-            : {}),
-        ...(typeof record.level === "string" ? { level: record.level } : {}),
-        ...(record.requires_response === true ? { requires_response: true } : {}),
-        ...(typeof record.summary === "string" ? { summary: record.summary } : {}),
-    };
-}
-export function normalizeMailboxContracts(mailbox) {
-    const accepts = Array.isArray(mailbox.accepts)
-        ? mailbox.accepts
-            .map(normalizeMailboxEntry)
-            .filter((entry) => Boolean(entry))
-        : [];
-    const emits = Array.isArray(mailbox.emits)
-        ? mailbox.emits
-            .map(normalizeMailboxEntry)
-            .filter((entry) => Boolean(entry))
-        : [];
-    return { accepts, emits };
-}
-export function mailboxTypes(entries) {
-    return entries.flatMap((entry) => typeof asRecord(entry).type === "string"
-        ? [String(asRecord(entry).type)]
-        : []);
-}

package/dist/recipes/actor-worker.json

@@ -1,39 +0,0 @@
-{
-  "async": true,
-  "description": "Start a canonical mailbox-backed branch worker demo actor.",
-  "args": [
-    "repo:path",
-    "branch:string",
-    "poll_ms:int",
-    "stale_claim_ms:int",
-    "write_artifacts:bool"
-  ],
-  "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
-    "branch": "worker",
-    "poll_ms": "1000",
-    "stale_claim_ms": "0",
-    "write_artifacts": "true"
-  },
-  "mailbox": {
-    "accepts": [
-      "task.assign",
-      "control.kill"
-    ],
-    "emits": [
-      "actor.join",
-      "task.claim",
-      "task.result",
-      "awaiting_assignment",
-      "actor.leave",
-      "run.done",
-      "run.failed"
-    ]
-  },
-  "artifacts": {
-    "journal": "{state_dir}/worker-events.jsonl",
-    "status": "{state_dir}/worker-status.json",
-    "results": "{state_dir}/worker-artifacts"
-  },
-  "template": "{repo}/scripts/actor-worker.mjs --state-dir {state_dir} --run {run_id} --branch {branch} --poll-ms {poll_ms} --stale-claim-ms {stale_claim_ms} --write-artifacts {write_artifacts}"
-}

package/dist/recipes/coordinator-locker.json

@@ -1,45 +0,0 @@
-{
-  "async": true,
-  "args": [
-    "repo:path",
-    "lease_ms:int"
-  ],
-  "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
-    "lease_ms": "600000"
-  },
-  "mailbox": {
-    "accepts": [
-      "coord.enqueue",
-      "coord.claim",
-      "coord.complete",
-      "coord.fail",
-      "lock.acquire",
-      "lock.renew",
-      "lock.release",
-      "control.stop",
-      "control.cancel",
-      "control.kill"
-    ],
-    "emits": [
-      "coord.started",
-      "coord.enqueued",
-      "coord.assigned",
-      "coord.empty",
-      "coord.completed",
-      "coord.failed",
-      "lock.granted",
-      "lock.denied",
-      "lock.renewed",
-      "lock.released",
-      "run.done",
-      "run.failed"
-    ]
-  },
-  "artifacts": {
-    "queue": "{state_dir}/queue.json",
-    "locks": "{state_dir}/locks.json",
-    "journal": "{state_dir}/journal.jsonl"
-  },
-  "template": "{repo}/scripts/locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
-}

package/dist/recipes/locker.json

@@ -1,45 +0,0 @@
-{
-  "async": true,
-  "args": [
-    "repo:path",
-    "lease_ms:int"
-  ],
-  "defaults": {
-    "repo": "~/.pi/agent/extensions/pi-actors",
-    "lease_ms": "600000"
-  },
-  "mailbox": {
-    "accepts": [
-      "lock.enqueue",
-      "lock.claim",
-      "lock.complete",
-      "lock.fail",
-      "lock.acquire",
-      "lock.renew",
-      "lock.release",
-      "control.stop",
-      "control.cancel",
-      "control.kill"
-    ],
-    "emits": [
-      "lock.started",
-      "lock.enqueued",
-      "lock.assigned",
-      "lock.empty",
-      "lock.completed",
-      "lock.failed",
-      "lock.granted",
-      "lock.denied",
-      "lock.renewed",
-      "lock.released",
-      "run.done",
-      "run.failed"
-    ]
-  },
-  "artifacts": {
-    "queue": "{state_dir}/queue.json",
-    "locks": "{state_dir}/locks.json",
-    "journal": "{state_dir}/journal.jsonl"
-  },
-  "template": "{repo}/scripts/locker.mjs serve --state-dir {state_dir} --lease-ms {lease_ms}"
-}