@llblab/pi-actors 0.23.0 → 0.24.0

package/dist/lib/locker.js

@@ -0,0 +1,310 @@
+/**
+ * Local coordination locker service entrypoint logic.
+ * Zones: coordination locks, task leases, platform control endpoint
+ */
+// @ts-nocheck
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { createServer } from "node:net";
+import { dirname, join, resolve } from "node:path";
+import readline from "node:readline";
+function parseArgs(argv) {
+    const args = { mode: "serve", stateDir: "", leaseMs: 600000, lines: 20 };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "serve" || arg === "snapshot")
+            args.mode = arg;
+        else if (arg === "--state-dir")
+            args.stateDir = argv[++index] ?? "";
+        else if (arg === "--lease-ms")
+            args.leaseMs = Number(argv[++index] ?? args.leaseMs);
+        else if (arg === "--lines")
+            args.lines = Number(argv[++index] ?? args.lines);
+    }
+    if (!args.stateDir)
+        throw new Error("--state-dir is required");
+    if (!Number.isFinite(args.leaseMs) || args.leaseMs <= 0)
+        args.leaseMs = 600000;
+    if (!Number.isFinite(args.lines) || args.lines <= 0)
+        args.lines = 20;
+    return args;
+}
+export async function runLocker(argv = process.argv.slice(2)) {
+    const { mode, stateDir, leaseMs, lines } = parseArgs(argv);
+    const queuePath = join(stateDir, "queue.json");
+    const locksPath = join(stateDir, "locks.json");
+    const journalPath = join(stateDir, "journal.jsonl");
+    const outboxPath = join(stateDir, "outbox.jsonl");
+    const controlPath = join(stateDir, "control.fifo");
+    mkdirSync(stateDir, { recursive: true });
+    function readJson(path, fallback) {
+        if (!existsSync(path))
+            return fallback;
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return fallback;
+        }
+    }
+    function writeJson(path, value) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    }
+    function getControlEndpoint() {
+        if (process.platform !== "win32")
+            return { path: controlPath, type: "fifo" };
+        const hash = createHash("sha256")
+            .update(resolve(stateDir))
+            .digest("hex")
+            .slice(0, 20);
+        return { path: `\\\\.\\pipe\\pi-actors-locker-${hash}`, type: "named-pipe" };
+    }
+    function writeControlEndpoint(endpoint) {
+        writeJson(join(stateDir, "control.json"), endpoint);
+        const runPath = join(stateDir, "run.json");
+        const run = readJson(runPath, undefined);
+        if (run && typeof run === "object")
+            writeJson(runPath, { ...run, control: endpoint });
+    }
+    function journal(event, data = {}) {
+        appendFileSync(journalPath, `${JSON.stringify({ event, ts: new Date().toISOString(), ...data })}\n`);
+    }
+    function outbox(type, summary, body = {}, level = "info") {
+        appendFileSync(outboxPath, `${JSON.stringify({ to: "coordinator", from: `run:${process.env.run_id ?? "locker"}`, type, event: type, summary, body, data: body, delivery: "followup", level, ts: new Date().toISOString() })}\n`);
+    }
+    function now() {
+        return Date.now();
+    }
+    function cleanExpiredLocks(locks) {
+        const current = now();
+        const kept = {};
+        for (const [key, lock] of Object.entries(locks)) {
+            if (Number(lock.expiresAt) > current)
+                kept[key] = lock;
+            else
+                journal("lock.expired", { resource: key, owner: lock.owner });
+        }
+        return kept;
+    }
+    function normalizeMessage(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return undefined;
+        if (["stop", "quit", "exit", "cancel"].includes(trimmed.toLowerCase())) {
+            return { type: "control.stop", body: {} };
+        }
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return { type: "lock.enqueue", body: { task: trimmed } };
+        }
+    }
+    function tailJournal(count) {
+        if (!existsSync(journalPath))
+            return [];
+        return readFileSync(journalPath, "utf8")
+            .trimEnd()
+            .split("\n")
+            .filter(Boolean)
+            .slice(-count)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return { raw: line };
+            }
+        });
+    }
+    function printSnapshot() {
+        const locks = cleanExpiredLocks(readJson(locksPath, {}));
+        writeJson(locksPath, locks);
+        const queue = readJson(queuePath, { items: [] });
+        console.log(JSON.stringify({
+            queueDepth: Array.isArray(queue.items) ? queue.items.length : 0,
+            queue,
+            locks,
+            journal: tailJournal(lines),
+        }, null, 2));
+    }
+    function nextTask(queue, locks) {
+        const items = Array.isArray(queue.items) ? queue.items : [];
+        const index = items.findIndex((item) => {
+            const resources = Array.isArray(item.resources) ? item.resources : [];
+            return resources.every((resource) => !locks[resource]);
+        });
+        if (index < 0)
+            return undefined;
+        return items.splice(index, 1)[0];
+    }
+    function handle(message) {
+        const type = message.type || message.event || "lock.enqueue";
+        const body = message.body && typeof message.body === "object" ? message.body : message;
+        let queue = readJson(queuePath, { items: [] });
+        let locks = cleanExpiredLocks(readJson(locksPath, {}));
+        if (type === "control.stop" || type === "control.cancel") {
+            writeJson(locksPath, locks);
+            journal("control.stop", {});
+            outbox("lock.stopped", "Locker stopped", {
+                queueDepth: queue.items?.length ?? 0,
+            });
+            process.exit(0);
+        }
+        if (type === "lock.enqueue" || type === "coord.enqueue") {
+            const item = {
+                id: body.id || `task-${Date.now()}`,
+                task: body.task ?? body,
+                resources: body.resources ?? [],
+                enqueuedAt: new Date().toISOString(),
+            };
+            queue.items = [...(queue.items ?? []), item];
+            writeJson(queuePath, queue);
+            writeJson(locksPath, locks);
+            journal("lock.enqueued", { id: item.id, resources: item.resources });
+            outbox("lock.enqueued", `Queued task ${item.id}`, {
+                id: item.id,
+                queueDepth: queue.items.length,
+            });
+            return;
+        }
+        if (type === "lock.claim" || type === "coord.claim") {
+            const owner = body.owner || message.from || "worker";
+            const item = nextTask(queue, locks);
+            if (!item) {
+                writeJson(queuePath, queue);
+                writeJson(locksPath, locks);
+                outbox("lock.empty", "No claimable task", {
+                    owner,
+                    queueDepth: queue.items?.length ?? 0,
+                });
+                return;
+            }
+            for (const resource of item.resources ?? [])
+                locks[resource] = { owner, task: item.id, expiresAt: now() + leaseMs };
+            writeJson(queuePath, queue);
+            writeJson(locksPath, locks);
+            journal("lock.assigned", {
+                id: item.id,
+                owner,
+                resources: item.resources,
+            });
+            outbox("lock.assigned", `Assigned task ${item.id}`, { owner, task: item });
+            return;
+        }
+        if (type === "lock.acquire") {
+            const resource = body.resource;
+            const owner = body.owner || message.from || "worker";
+            if (!resource)
+                throw new Error("lock.acquire body.resource is required");
+            if (locks[resource])
+                outbox("lock.denied", `Lock denied ${resource}`, { resource, owner, current: locks[resource] }, "warning");
+            else {
+                locks[resource] = { owner, expiresAt: now() + leaseMs };
+                outbox("lock.granted", `Lock granted ${resource}`, { resource, owner });
+            }
+            writeJson(locksPath, locks);
+            return;
+        }
+        if (type === "lock.renew") {
+            const resource = body.resource;
+            const owner = body.owner || message.from || "worker";
+            if (!resource)
+                throw new Error("lock.renew body.resource is required");
+            const current = locks[resource];
+            if (!current) {
+                outbox("lock.denied", `Lock renew denied ${resource}`, { resource, owner, reason: "missing" }, "warning");
+            }
+            else if (current.owner !== owner) {
+                outbox("lock.denied", `Lock renew denied ${resource}`, { resource, owner, current }, "warning");
+            }
+            else {
+                locks[resource] = { ...current, expiresAt: now() + leaseMs };
+                outbox("lock.renewed", `Lock renewed ${resource}`, { resource, owner });
+            }
+            writeJson(locksPath, locks);
+            return;
+        }
+        if (type === "lock.release") {
+            const resource = body.resource;
+            if (resource)
+                delete locks[resource];
+            writeJson(locksPath, locks);
+            outbox("lock.released", `Lock released ${resource}`, { resource });
+            return;
+        }
+        if (type === "lock.complete" ||
+            type === "lock.fail" ||
+            type === "coord.complete" ||
+            type === "coord.fail") {
+            const eventType = type.startsWith("coord.")
+                ? type.replace("coord.", "lock.")
+                : type;
+            journal(eventType, body);
+            outbox(eventType, `${eventType} ${body.id ?? ""}`.trim(), body, eventType === "lock.fail" ? "error" : "info");
+            writeJson(locksPath, locks);
+            writeJson(queuePath, queue);
+            return;
+        }
+        journal("lock.unknown", { type, body });
+        outbox("lock.unknown", `Unknown message ${type}`, { type, body }, "warning");
+    }
+    if (mode === "snapshot") {
+        printSnapshot();
+        process.exit(0);
+    }
+    function handleLine(line) {
+        const message = normalizeMessage(line);
+        if (!message)
+            return;
+        try {
+            handle(message);
+        }
+        catch (error) {
+            const text = error instanceof Error ? error.message : String(error);
+            journal("lock.error", { error: text });
+            outbox("lock.error", text, { error: text }, "error");
+        }
+    }
+    async function serveFifo(endpoint) {
+        if (!existsSync(endpoint.path)) {
+            const result = spawnSync("mkfifo", [endpoint.path]);
+            if (result.status !== 0)
+                throw new Error(`mkfifo failed: ${result.stderr?.toString?.() ?? ""}`);
+        }
+        writeControlEndpoint(endpoint);
+        while (true) {
+            const stream = await import("node:fs").then((fs) => fs.createReadStream(endpoint.path, { encoding: "utf8" }));
+            const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+            for await (const line of rl)
+                handleLine(line);
+        }
+    }
+    async function serveNamedPipe(endpoint) {
+        rmSync(endpoint.path, { force: true });
+        const server = createServer((socket) => {
+            const rl = readline.createInterface({ input: socket, crlfDelay: Infinity });
+            rl.on("line", handleLine);
+        });
+        await new Promise((resolveReady, rejectReady) => {
+            server.once("error", rejectReady);
+            server.listen(endpoint.path, () => {
+                server.off("error", rejectReady);
+                writeControlEndpoint(endpoint);
+                resolveReady();
+            });
+        });
+        await new Promise(() => { });
+    }
+    const endpoint = getControlEndpoint();
+    writeJson(queuePath, readJson(queuePath, { items: [] }));
+    writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));
+    journal("lock.started", { leaseMs, control: endpoint.type });
+    outbox("lock.started", "Locker ready", { leaseMs, control: endpoint.type });
+    if (endpoint.type === "named-pipe")
+        await serveNamedPipe(endpoint);
+    else
+        await serveFifo(endpoint);
+}

package/dist/lib/mailbox-loop.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal mailbox loop helpers.
+ * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
+ * Owns small reusable primitives for recipe authors; scheduling and task policy stay outside.
+ */
+import { type BranchInboxRecord } from "./actor-rooms.ts";
+import { type RunInboxMessage } from "./async-runs.ts";
+export type MailboxLoopMessage = RunInboxMessage | BranchInboxRecord;
+export type MailboxLoopTarget = {
+    kind: "run";
+    runOrDir: string;
+} | {
+    address: string;
+    kind: "branch";
+    run: string;
+    stateDir: string;
+};
+export interface MailboxLoopClaimOptions {
+    owner?: string;
+    statuses?: string[];
+}
+export interface MailboxLoopHandleResult {
+    handled: boolean;
+    id?: string;
+    message?: MailboxLoopMessage;
+    target: MailboxLoopTarget;
+}
+export interface MailboxLoopDrainOptions extends MailboxLoopClaimOptions {
+    maxMessages?: number;
+    stopOnControl?: boolean;
+}
+export interface MailboxLoopDrainResult {
+    handled: number;
+    stopped: boolean;
+    target: MailboxLoopTarget;
+}
+export declare function isMailboxLoopStopMessage(message: unknown): boolean;
+export declare function claimMailboxLoopMessage(target: MailboxLoopTarget, options?: MailboxLoopClaimOptions): MailboxLoopMessage | undefined;
+export declare function updateMailboxLoopMessageStatus(target: MailboxLoopTarget, id: string, status: "claimed" | "handled" | "failed", metadata?: Record<string, unknown>): boolean;
+export declare function handleMailboxLoopOnce(target: MailboxLoopTarget, handler: (message: MailboxLoopMessage) => Promise<void> | void, options?: MailboxLoopClaimOptions): Promise<MailboxLoopHandleResult>;
+export declare function drainMailboxLoopMessages(target: MailboxLoopTarget, handler: (message: MailboxLoopMessage) => Promise<void> | void, options?: MailboxLoopDrainOptions): Promise<MailboxLoopDrainResult>;

package/dist/lib/mailbox-loop.js

@@ -0,0 +1,62 @@
+/**
+ * Minimal mailbox loop helpers.
+ * Zones: mailbox-consuming actors, run/branch inbox claiming, handler status transitions
+ * Owns small reusable primitives for recipe authors; scheduling and task policy stay outside.
+ */
+import { claimBranchInboxMessage, updateBranchInboxMessageStatus, } from "./actor-rooms.js";
+import { claimRunInboxMessage, updateRunInboxMessageStatus, } from "./async-runs.js";
+export function isMailboxLoopStopMessage(message) {
+    const type = message && typeof message === "object" && "type" in message
+        ? message.type
+        : undefined;
+    return (type === "control.stop" ||
+        type === "control.cancel" ||
+        type === "control.kill");
+}
+function messageId(message) {
+    return typeof message?.id === "string" ? message.id : undefined;
+}
+export function claimMailboxLoopMessage(target, options = {}) {
+    const owner = options.owner ?? "mailbox-loop";
+    const statuses = options.statuses ?? ["queued"];
+    return target.kind === "run"
+        ? claimRunInboxMessage(target.runOrDir, owner, statuses)
+        : claimBranchInboxMessage(target.stateDir, target.run, target.address, owner, statuses);
+}
+export function updateMailboxLoopMessageStatus(target, id, status, metadata = {}) {
+    return target.kind === "run"
+        ? updateRunInboxMessageStatus(target.runOrDir, id, status, metadata)
+        : updateBranchInboxMessageStatus(target.stateDir, target.run, target.address, id, status, metadata);
+}
+export async function handleMailboxLoopOnce(target, handler, options = {}) {
+    const message = claimMailboxLoopMessage(target, options);
+    const id = messageId(message);
+    if (!message || !id)
+        return { handled: false, target };
+    try {
+        await handler(message);
+        updateMailboxLoopMessageStatus(target, id, "handled");
+        return { handled: true, id, message, target };
+    }
+    catch (error) {
+        updateMailboxLoopMessageStatus(target, id, "failed", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+    }
+}
+export async function drainMailboxLoopMessages(target, handler, options = {}) {
+    const maxMessages = Math.max(1, Math.floor(options.maxMessages ?? 100));
+    let handled = 0;
+    for (; handled < maxMessages; handled += 1) {
+        const result = await handleMailboxLoopOnce(target, handler, options);
+        if (!result.handled || !result.message) {
+            return { handled, stopped: false, target };
+        }
+        if (options.stopOnControl !== false &&
+            isMailboxLoopStopMessage(result.message)) {
+            return { handled: handled + 1, stopped: true, target };
+        }
+    }
+    return { handled, stopped: false, target };
+}

package/dist/lib/observability.d.ts

@@ -88,8 +88,8 @@ export declare function renderRunStatus(summary: RunSummary, frame?: number): st
 export declare function findRunRetirementCandidates(summary: RunSummary): RunRetirementCandidate[];
 export declare function executeRunRetirements(summary: RunSummary, options: RunRetirementExecutorOptions): Promise<RunRetirementExecution[]>;
 export declare function detectRunTransitions(previous: Map<string, RunObservedStatus>, summary: RunSummary): RunTransition[];
-export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>): void;
-export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary): RunOutboxEvent[];
+export declare function pruneRunObservationState(previousStatuses: Map<string, RunObservedStatus>, previousLineCounts: Map<string, number>, summary: RunSummary, terminalRuns?: Iterable<string>, seenEventIds?: Map<string, Set<string>>): void;
+export declare function detectRunOutboxEvents(previousLineCounts: Map<string, number>, summary: RunSummary, seenEventIds?: Map<string, Set<string>>): RunOutboxEvent[];
 export declare function getRunOutboxNotificationType(event: RunOutboxEvent): RunTransitionNotificationType;
 export declare function shouldNotifyRunOutboxEvent(event: RunOutboxEvent): boolean;
 export declare function shouldSendRunOutboxFollowUp(event: RunOutboxEvent): boolean;

package/dist/lib/observability.js

@@ -7,6 +7,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
+import { readJsonlFileResilient } from "./state-readers.js";
 const TERMINAL = new Set([
     "done",
     "failed",
@@ -409,57 +410,45 @@ function normalizeOutboxDelivery(value) {
 function normalizeOutboxLevel(value) {
     return value === "warning" || value === "error" ? value : "info";
 }
-function parseOutboxLine(line, run, index) {
+function parseOutboxRecord(raw, run, index) {
     if (!run.stateDir)
         return undefined;
-    try {
-        const raw = JSON.parse(line);
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            return undefined;
-        const event = typeof raw.event === "string" && raw.event.trim()
-            ? raw.event.trim()
-            : "run.event";
-        const summary = typeof raw.summary === "string" && raw.summary.trim()
-            ? raw.summary.trim()
-            : event;
-        const ts = typeof raw.ts === "string" && raw.ts.trim()
-            ? raw.ts.trim()
-            : new Date(0).toISOString();
-        const id = typeof raw.id === "string" && raw.id.trim()
-            ? raw.id.trim()
-            : `${run.run}:${index}`;
-        return {
-            ...(raw.body !== undefined ? { body: raw.body } : {}),
-            ...(raw.data !== undefined ? { data: raw.data } : {}),
-            delivery: normalizeOutboxDelivery(raw.delivery),
-            event,
-            id,
-            level: normalizeOutboxLevel(raw.level),
-            ...(raw.metadata &&
-                typeof raw.metadata === "object" &&
-                !Array.isArray(raw.metadata)
-                ? { metadata: raw.metadata }
-                : {}),
-            run: run.run,
-            stateDir: run.stateDir,
-            summary,
-            ts,
-        };
-    }
-    catch {
-        return undefined;
-    }
+    const event = typeof raw.event === "string" && raw.event.trim()
+        ? raw.event.trim()
+        : "run.event";
+    const summary = typeof raw.summary === "string" && raw.summary.trim()
+        ? raw.summary.trim()
+        : event;
+    const ts = typeof raw.ts === "string" && raw.ts.trim()
+        ? raw.ts.trim()
+        : new Date(0).toISOString();
+    const id = typeof raw.id === "string" && raw.id.trim()
+        ? raw.id.trim()
+        : `${run.run}:${index}`;
+    return {
+        ...(raw.body !== undefined ? { body: raw.body } : {}),
+        ...(raw.data !== undefined ? { data: raw.data } : {}),
+        delivery: normalizeOutboxDelivery(raw.delivery),
+        event,
+        id,
+        level: normalizeOutboxLevel(raw.level),
+        ...(raw.metadata &&
+            typeof raw.metadata === "object" &&
+            !Array.isArray(raw.metadata)
+            ? { metadata: raw.metadata }
+            : {}),
+        run: run.run,
+        stateDir: run.stateDir,
+        summary,
+        ts,
+    };
 }
-function readOutboxLines(run) {
+function readOutboxRecords(run) {
     if (!run.stateDir)
         return [];
-    const path = join(run.stateDir, "outbox.jsonl");
-    if (!existsSync(path))
-        return [];
-    const content = readFileSync(path, "utf8").trimEnd();
-    return content ? content.split("\n") : [];
+    return readJsonlFileResilient(join(run.stateDir, "outbox.jsonl")).records;
 }
-export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = []) {
+export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = [], seenEventIds = new Map()) {
     const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
     const terminalRunSet = new Set(terminalRuns);
     const terminalLineKeys = new Set(summary.runs
@@ -477,20 +466,29 @@ export function pruneRunObservationState(previousStatuses, previousLineCounts, s
             previousLineCounts.delete(key);
         }
     }
+    for (const key of seenEventIds.keys()) {
+        if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+            seenEventIds.delete(key);
+        }
+    }
 }
-export function detectRunOutboxEvents(previousLineCounts, summary) {
+export function detectRunOutboxEvents(previousLineCounts, summary, seenEventIds = new Map()) {
     const events = [];
     for (const run of summary.runs) {
         const key = run.stateDir ?? run.run;
-        const lines = readOutboxLines(run);
+        const records = readOutboxRecords(run);
         const previousCount = previousLineCounts.get(key) ?? 0;
-        const start = Math.min(previousCount, lines.length);
-        for (let index = start; index < lines.length; index += 1) {
-            const event = parseOutboxLine(lines[index], run, index);
-            if (event)
-                events.push(event);
+        const start = Math.min(previousCount, records.length);
+        const seen = seenEventIds.get(key) ?? new Set();
+        for (let index = start; index < records.length; index += 1) {
+            const event = parseOutboxRecord(records[index], run, index);
+            if (!event || seen.has(event.id))
+                continue;
+            events.push(event);
+            seen.add(event.id);
         }
-        previousLineCounts.set(key, lines.length);
+        previousLineCounts.set(key, records.length);
+        seenEventIds.set(key, seen);
     }
     return events;
 }

package/dist/lib/prompts.d.ts

@@ -6,7 +6,7 @@
 export declare const REGISTER_TOOL_DESCRIPTION: string;
 export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.\n- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.\n- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync: string leaf, array sequence, object node; flags include args/defaults, parallel, when, timeout, delay, retry, failure, recover, repeat, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: every recipe there is auto-registered as an agent tool across sessions; register_tool writes there.\n- Recipes own template directly and may declare metadata/defaults/imports/mailbox/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.\n- Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.\n- Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.\n- For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";

package/dist/lib/prompts.js

@@ -23,7 +23,7 @@ export const ONBOARDING_SYSTEM_PROMPT = `pi-actors quick model:
 - Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.
 - Use spawn/message/inspect for actor-level start/send/observe; avoid runtime/FIFO/outbox vocabulary in public guidance.
 - Run state lives under ~/.pi/agent/tmp/pi-actors/runs; inspect status/tail/messages/mailbox/files/artifacts intentionally and avoid busy-polling.
-- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
+- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; packaged/ad hoc recipes are lower-priority components; offer to save successful recurring patterns only after confirmation.
 - Foreground tools/templates fit short work; async recipes/runs fit subagents, services, fanout, media, and long pipelines.
 - Long fanout = parent async recipe wrapping template(parallel:true) and imports; packaged fanout recipes bubble branch completion messages; grow recurring multi-agent workflows as packaged recipes/pipelines, not ad hoc external scripts.
 - For deeper pi-actors guidance, inspect installed extension sources/docs/recipes; README and docs are not automatically in context.`;

package/dist/lib/recipe-references.js

@@ -195,6 +195,29 @@ function parseMarkdownFrontmatterObject(lines) {
     }
     return result;
 }
+function normalizeMarkdownFrontmatterField(key, value) {
+    if (key === "args" && typeof value === "string") {
+        return value
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean);
+    }
+    if (key === "defaults" && Array.isArray(value)) {
+        return Object.fromEntries(value
+            .filter((item) => typeof item === "string")
+            .map((item) => {
+            const separator = item.indexOf(":");
+            return separator < 0
+                ? [item.trim(), ""]
+                : [
+                    item.slice(0, separator).trim(),
+                    parseMarkdownScalar(item.slice(separator + 1)),
+                ];
+        })
+            .filter(([name]) => Boolean(name)));
+    }
+    return value;
+}
 function parseMarkdownFrontmatter(value) {
     const result = {};
     const lines = value.split(/\r?\n/);
@@ -206,7 +229,7 @@ function parseMarkdownFrontmatter(value) {
         if (!match)
             continue;
         if (match[2]) {
-            result[match[1]] = parseMarkdownScalar(match[2]);
+            result[match[1]] = normalizeMarkdownFrontmatterField(match[1], parseMarkdownScalar(match[2]));
             continue;
         }
         const nested = [];
@@ -214,7 +237,7 @@ function parseMarkdownFrontmatter(value) {
             index += 1;
             nested.push(lines[index]);
         }
-        result[match[1]] = parseMarkdownFrontmatterObject(nested);
+        result[match[1]] = normalizeMarkdownFrontmatterField(match[1], parseMarkdownFrontmatterObject(nested));
     }
     return result;
 }

package/dist/lib/recipe-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Recipe utility command bundle entrypoint logic.
+ * Zones: recipe utilities, deterministic helper subcommands
+ */
+export declare function runRecipeUtils(argv?: string[]): void;