@llblab/pi-actors 0.23.0 → 0.24.0

package/dist/lib/recipe-utils.js

@@ -0,0 +1,385 @@
+/**
+ * Recipe utility command bundle entrypoint logic.
+ * Zones: recipe utilities, deterministic helper subcommands
+ */
+// @ts-nocheck
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+function usage() {
+    console.error(`Usage:
+  recipe-utils.mjs run-summary <state-root>
+  recipe-utils.mjs run-ops-snapshot <state-root> <run-id> [lines] [stale-minutes]
+  recipe-utils.mjs playlist <source-dir> [extensions] [max-depth] [paths|m3u|inline]
+  recipe-utils.mjs changelog-section <file> <version>
+  recipe-utils.mjs artifact-manifest <artifact-path> <title> <status> [summary]
+  recipe-utils.mjs artifact-write <artifact-path> [create|overwrite|append]
+  recipe-utils.mjs actor-message <type> [to] [from] [summary] [metadata-json] [correlation-id] [reply-to]
+  recipe-utils.mjs package-summary <package-json>
+  recipe-utils.mjs skill-summary <skill-md> [package-json]`);
+}
+function fail(message) {
+    console.error(message);
+    process.exit(1);
+}
+const ADDRESS_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const MESSAGE_TYPE_PATTERN = /^[A-Za-z][A-Za-z0-9_.:-]*$/;
+function assertToken(value, label) {
+    const normalized = String(value ?? "").trim();
+    if (!normalized)
+        fail(`${label} is required`);
+    if (!ADDRESS_PATTERN.test(normalized))
+        fail(`${label} contains unsupported characters: ${value}`);
+    return normalized;
+}
+function validateActorAddress(address, label) {
+    const value = String(address ?? "").trim();
+    if (value === "coordinator")
+        return value;
+    const separator = value.indexOf(":");
+    if (separator < 0)
+        fail(`${label} must include an actor kind: ${address}`);
+    const kind = value.slice(0, separator);
+    const rest = value.slice(separator + 1);
+    if (kind === "branch") {
+        const [run, branch, ...extra] = rest.split("/");
+        if (extra.length > 0)
+            fail(`${label} branch address has too many parts: ${address}`);
+        return `branch:${assertToken(run, `${label} branch run`)}/${assertToken(branch, `${label} branch id`)}`;
+    }
+    if (["run", "session", "tool"].includes(kind))
+        return `${kind}:${assertToken(rest, label)}`;
+    fail(`${label} has unsupported actor kind: ${kind}`);
+}
+function validateMessageType(type) {
+    const value = String(type ?? "").trim();
+    if (!MESSAGE_TYPE_PATTERN.test(value))
+        fail(`Invalid actor message type: ${type}`);
+    return value;
+}
+function walkFiles(dir, maxDepth = 2, depth = 0, out = []) {
+    if (depth > maxDepth || !existsSync(dir))
+        return out;
+    for (const entry of readdirSync(dir)) {
+        const path = join(dir, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory())
+            walkFiles(path, maxDepth, depth + 1, out);
+        else if (stat.isFile())
+            out.push(path);
+    }
+    return out;
+}
+function readJson(file) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function getRunStatus(run, progress, result) {
+    if (progress?.phase)
+        return progress.phase;
+    if (result?.code !== undefined)
+        return result.code === 0 ? "done" : "failed";
+    return run.status ?? "unknown";
+}
+function collectRunSummary(rootValue) {
+    const root = resolve(rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const files = walkFiles(root, 2).filter((file) => file.endsWith("/run.json"));
+    const rows = [];
+    for (const file of files) {
+        const run = readJson(file);
+        if (!run) {
+            rows.push({
+                run: relative(root, file),
+                status: "invalid-json",
+                recipe: "",
+                updated: "",
+            });
+            continue;
+        }
+        const runDir = dirname(file);
+        const progress = readJson(join(runDir, "progress.json"));
+        const result = readJson(join(runDir, "result.json"));
+        rows.push({
+            run: run.run_id ?? run.run ?? relative(root, file).split("/")[0],
+            status: getRunStatus(run, progress, result),
+            recipe: run.recipe ?? run.recipe_file ?? "",
+            updated: progress?.updatedAt ??
+                result?.completedAt ??
+                run.updated_at ??
+                run.completed_at ??
+                run.started_at ??
+                "",
+        });
+    }
+    rows.sort((a, b) => `${a.status}:${a.run}`.localeCompare(`${b.status}:${b.run}`));
+    return rows;
+}
+function runSummary(rootValue) {
+    console.log(JSON.stringify(collectRunSummary(rootValue), null, 2));
+}
+function tailJsonl(fileValue, linesValue = "80") {
+    const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    if (!existsSync(file))
+        return [];
+    const lines = Number.parseInt(linesValue, 10);
+    const count = Number.isFinite(lines) && lines > 0 ? lines : 80;
+    return readFileSync(file, "utf8")
+        .trimEnd()
+        .split("\n")
+        .filter(Boolean)
+        .slice(-count)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return { raw: line };
+        }
+    });
+}
+function runOpsSnapshot(rootValue, runIdValue = "music", linesValue = "80", staleMinutesValue = "60") {
+    const runs = collectRunSummary(rootValue);
+    const root = resolve(rootValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const inspectedRun = String(runIdValue || "music");
+    const messageFile = join(root, inspectedRun, "outbox.jsonl");
+    const staleMs = Number(staleMinutesValue) * 60 * 1000;
+    const now = Date.now();
+    const recommendations = runs.flatMap((run) => {
+        const updatedMs = Date.parse(run.updated || "");
+        const stale = Number.isFinite(updatedMs) &&
+            Number.isFinite(staleMs) &&
+            now - updatedMs > staleMs;
+        if (run.status === "running" && stale) {
+            return [
+                {
+                    run: run.run,
+                    reason: "running-stale",
+                    suggested_message: {
+                        to: `run:${run.run}`,
+                        type: "control.stop",
+                        body: "stop",
+                    },
+                },
+            ];
+        }
+        if (["failed", "exited", "killed"].includes(run.status)) {
+            return [
+                {
+                    run: run.run,
+                    reason: `terminal-${run.status}`,
+                    suggested_inspect: { target: `run:${run.run}`, view: "tail" },
+                },
+            ];
+        }
+        return [];
+    });
+    console.log(JSON.stringify({
+        runs,
+        inspectedRun,
+        messages: tailJsonl(messageFile, linesValue),
+        recommendations,
+    }, null, 2));
+}
+function playlist(sourceValue, extensionsValue = ".mp3,.ogg,.wav,.flac,.m4a", maxDepthValue = "2", outputMode = "paths") {
+    const source = resolve(sourceValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const maxDepth = Number.parseInt(maxDepthValue, 10);
+    const extensions = new Set(extensionsValue
+        .split(",")
+        .map((item) => item.trim().toLowerCase())
+        .filter(Boolean));
+    const files = walkFiles(source, Number.isFinite(maxDepth) ? maxDepth : 2)
+        .filter((file) => extensions.has(extname(file).toLowerCase()))
+        .sort((a, b) => a.localeCompare(b));
+    if (outputMode === "m3u")
+        console.log(["#EXTM3U", ...files].join("\n"));
+    else if (outputMode === "inline")
+        console.log(files.join("|"));
+    else
+        console.log(files.join("\n"));
+}
+function artifactManifest(pathValue, title = "Artifact", status = "draft", summary = "") {
+    const path = resolve(pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const exists = existsSync(path);
+    const stat = exists ? statSync(path) : undefined;
+    console.log(JSON.stringify({
+        title,
+        status,
+        path,
+        exists,
+        bytes: stat?.size ?? 0,
+        modified: stat?.mtime?.toISOString?.() ?? null,
+        summary,
+    }, null, 2));
+}
+function artifactWrite(pathValue, mode = "create") {
+    const path = resolve(pathValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    if (!["create", "overwrite", "append"].includes(mode)) {
+        fail(`Invalid artifact write mode: ${mode}`);
+    }
+    if (mode === "create" && existsSync(path)) {
+        fail(`Artifact already exists: ${path}`);
+    }
+    const content = readFileSync(0, "utf8");
+    mkdirSync(dirname(path), { recursive: true });
+    if (mode === "append")
+        appendFileSync(path, content);
+    else
+        writeFileSync(path, content, "utf8");
+    const stat = statSync(path);
+    console.log(JSON.stringify({ path, mode, bytes: stat.size, written: true }, null, 2));
+}
+function actorMessage(type = "event", to = "coordinator", from = "run:{run_id}", summary = "", metadataValue = "", correlationId = "", replyTo = "") {
+    const messageType = validateMessageType(type);
+    const messageTo = validateActorAddress(to, "message.to");
+    const messageFrom = validateActorAddress(from, "message.from");
+    let metadata = {};
+    if (metadataValue) {
+        try {
+            const parsed = JSON.parse(metadataValue);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                metadata = parsed;
+            else
+                fail("Actor message metadata must be a JSON object");
+        }
+        catch (error) {
+            fail(`Invalid actor message metadata JSON: ${error.message}`);
+        }
+    }
+    const bodyText = readFileSync(0, "utf8");
+    const trimmed = bodyText.trim();
+    let body = bodyText;
+    if (trimmed) {
+        try {
+            body = JSON.parse(trimmed);
+        }
+        catch {
+            body = bodyText;
+        }
+    }
+    console.log(JSON.stringify({
+        to: messageTo,
+        from: messageFrom,
+        type: messageType,
+        summary: summary || messageType,
+        body,
+        ...(correlationId ? { correlation_id: correlationId } : {}),
+        ...(replyTo ? { reply_to: replyTo } : {}),
+        metadata,
+    }, null, 2));
+}
+function packageSummary(fileValue = "package.json") {
+    const file = resolve(fileValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const pkg = readJson(file);
+    if (!pkg)
+        fail(`Package JSON not found or invalid: ${fileValue}`);
+    const scripts = pkg.scripts && typeof pkg.scripts === "object"
+        ? Object.keys(pkg.scripts).sort()
+        : [];
+    const dependencies = pkg.dependencies && typeof pkg.dependencies === "object"
+        ? Object.keys(pkg.dependencies).sort()
+        : [];
+    const devDependencies = pkg.devDependencies && typeof pkg.devDependencies === "object"
+        ? Object.keys(pkg.devDependencies).sort()
+        : [];
+    console.log(JSON.stringify({
+        name: pkg.name ?? "",
+        version: pkg.version ?? "",
+        type: pkg.type ?? "",
+        private: Boolean(pkg.private),
+        packageManager: pkg.packageManager ?? "",
+        files: Array.isArray(pkg.files) ? pkg.files : [],
+        bin: pkg.bin ?? null,
+        main: pkg.main ?? "",
+        exports: pkg.exports ?? null,
+        scripts,
+        dependencyCount: dependencies.length,
+        devDependencyCount: devDependencies.length,
+        dependencies,
+        devDependencies,
+    }, null, 2));
+}
+function parseSkillFrontmatter(content) {
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
+    const fields = {};
+    for (const line of frontmatter.split(/\r?\n/)) {
+        const match = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
+        if (match)
+            fields[match[1]] = match[2].trim();
+    }
+    return { frontmatter, fields };
+}
+function skillSummary(skillValue, packageValue = "package.json") {
+    const skillFile = resolve(skillValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const packageFile = resolve(packageValue.replace(/^~(?=\/|$)/, process.env.HOME ?? "~"));
+    const content = readFileSync(skillFile, "utf8");
+    const pkg = readJson(packageFile) ?? {};
+    const { frontmatter, fields } = parseSkillFrontmatter(content);
+    const scalarLines = frontmatter
+        .split(/\r?\n/)
+        .filter((line) => /^\w+:\s*\S/.test(line));
+    const extraColonLines = scalarLines.filter((line) => (line.match(/:/g) ?? []).length > 1);
+    const body = content.replace(/^---\n[\s\S]*?\n---\n?/, "");
+    const version = fields.version ??
+        frontmatter.match(/^\s+version:\s*([^\n]+)\s*$/m)?.[1]?.trim() ??
+        "";
+    console.log(JSON.stringify({
+        path: skillValue,
+        name: fields.name ?? "",
+        description: fields.description ?? "",
+        version,
+        packageVersion: pkg.version ?? "",
+        versionMatchesPackage: version === pkg.version,
+        frontmatterExtraColonLines: extraColonLines,
+        bodyLineCount: body.split(/\r?\n/).length,
+        headings: body.split(/\r?\n/).filter((line) => /^#{1,6}\s/.test(line)),
+    }, null, 2));
+}
+function changelogSection(fileValue, version) {
+    const file = resolve(fileValue);
+    const lines = readFileSync(file, "utf8").split(/\r?\n/);
+    const start = lines.findIndex((line) => line.startsWith("## ") && line.includes(version));
+    if (start < 0)
+        fail(`Version section not found: ${version}`);
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (lines[index].startsWith("## ")) {
+            end = index;
+            break;
+        }
+    }
+    console.log(lines.slice(start, end).join("\n").trimEnd());
+}
+export function runRecipeUtils(argv = process.argv.slice(2)) {
+    const [command, ...args] = argv;
+    if (!command) {
+        usage();
+        process.exit(1);
+    }
+    if (command === "run-summary")
+        runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
+    else if (command === "run-ops-snapshot")
+        runOpsSnapshot(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs", args[1] ?? "music", args[2], args[3]);
+    else if (command === "playlist")
+        playlist(args[0] ?? "~/Music", args[1], args[2], args[3]);
+    else if (command === "changelog-section")
+        changelogSection(args[0] ?? "CHANGELOG.md", args[1] ?? "Unreleased");
+    else if (command === "artifact-manifest")
+        artifactManifest(args[0] ?? "artifact.md", args[1], args[2], args[3]);
+    else if (command === "artifact-write")
+        artifactWrite(args[0] ?? "artifact.md", args[1] ?? "create");
+    else if (command === "actor-message")
+        actorMessage(args[0], args[1], args[2], args[3], args[4], args[5], args[6]);
+    else if (command === "package-summary")
+        packageSummary(args[0] ?? "package.json");
+    else if (command === "skill-summary")
+        skillSummary(args[0] ?? "skills/actors/SKILL.md", args[1] ?? "package.json");
+    else {
+        usage();
+        fail(`Unknown command: ${command}`);
+    }
+}

package/dist/lib/runtime-notifier.js

@@ -6,6 +6,7 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, watch, } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { readJsonlFileResilient } from "./state-readers.js";
 const DEFAULT_POLL_INTERVAL_MS = 1000;
 export function runtimeWakeFile(stateDir) {
     return join(stateDir, "wake.jsonl");
@@ -61,13 +62,8 @@ export function parseRuntimeWakeEventLine(line) {
     }
 }
 export function readRuntimeWakeEvents(stateDir) {
-    const file = runtimeWakeFile(stateDir);
-    if (!existsSync(file))
-        return [];
-    return readFileSync(file, "utf8")
-        .split("\n")
-        .filter((line) => line.trim())
-        .map(parseRuntimeWakeEventLine)
+    return readJsonlFileResilient(runtimeWakeFile(stateDir))
+        .records.map((record) => parseRuntimeWakeEventLine(JSON.stringify(record)))
         .filter((event) => Boolean(event));
 }
 export function createFileRuntimeNotifier(stateDir, options = {}) {

package/dist/lib/state-readers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Resilient state readers.
+ * Zones: file-backed actor state, JSON/JSONL diagnostics, inspect safety
+ * Owns best-effort JSON and JSONL parsing helpers for operator-facing state reads.
+ */
+export interface StateReadDiagnostic {
+    line?: number;
+    message: string;
+    path: string;
+}
+export interface JsonReadResult<T> {
+    diagnostics: StateReadDiagnostic[];
+    value: T;
+}
+export interface JsonlReadResult<T> {
+    diagnostics: StateReadDiagnostic[];
+    records: T[];
+}
+export declare function readJsonFileResilient<T>(path: string, fallback: T): JsonReadResult<T>;
+export declare function readJsonlFileResilient<T>(path: string): JsonlReadResult<T>;
+export declare function formatStateReadDiagnostics(diagnostics: StateReadDiagnostic[], limit?: number): string[];

package/dist/lib/state-readers.js

@@ -0,0 +1,74 @@
+/**
+ * Resilient state readers.
+ * Zones: file-backed actor state, JSON/JSONL diagnostics, inspect safety
+ * Owns best-effort JSON and JSONL parsing helpers for operator-facing state reads.
+ */
+import { readFileSync } from "node:fs";
+function isEnoent(error) {
+    return error.code === "ENOENT";
+}
+function diagnosticMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function readJsonFileResilient(path, fallback) {
+    try {
+        return {
+            diagnostics: [],
+            value: JSON.parse(readFileSync(path, "utf8")),
+        };
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return { diagnostics: [], value: fallback };
+        return {
+            diagnostics: [
+                {
+                    message: diagnosticMessage(error),
+                    path,
+                },
+            ],
+            value: fallback,
+        };
+    }
+}
+export function readJsonlFileResilient(path) {
+    try {
+        const records = [];
+        const diagnostics = [];
+        const lines = readFileSync(path, "utf8").split("\n");
+        for (const [index, line] of lines.entries()) {
+            if (!line.trim())
+                continue;
+            try {
+                records.push(JSON.parse(line));
+            }
+            catch (error) {
+                diagnostics.push({
+                    line: index + 1,
+                    message: diagnosticMessage(error),
+                    path,
+                });
+            }
+        }
+        return { diagnostics, records };
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return { diagnostics: [], records: [] };
+        return {
+            diagnostics: [
+                {
+                    message: diagnosticMessage(error),
+                    path,
+                },
+            ],
+            records: [],
+        };
+    }
+}
+export function formatStateReadDiagnostics(diagnostics, limit = 5) {
+    return diagnostics.slice(0, limit).map((diagnostic) => {
+        const line = diagnostic.line === undefined ? "" : `:${diagnostic.line}`;
+        return `${diagnostic.path}${line}: ${diagnostic.message}`;
+    });
+}

package/dist/lib/tools.js

@@ -241,7 +241,7 @@ function compactRoomRoster(roster) {
         .join("\n")}`;
 }
 function compactRoomStatus(status) {
-    return `\nroom=${status.room} messages=${status.message_count} roster=${status.roster_count}${status.last_message_at ? ` last_message_at=${status.last_message_at}` : ""}${status.last_message_from ? ` last_from=${status.last_message_from}` : ""}${status.last_message_type ? ` last_type=${status.last_message_type}` : ""}${status.last_message_summary ? ` last_summary=${compactPreview(status.last_message_summary)}` : ""}`;
+    return `\nroom=${status.room} messages=${status.message_count} roster=${status.roster_count}${status.diagnostics_count ? ` diagnostics=${status.diagnostics_count}` : ""}${status.last_message_at ? ` last_message_at=${status.last_message_at}` : ""}${status.last_message_from ? ` last_from=${status.last_message_from}` : ""}${status.last_message_type ? ` last_type=${status.last_message_type}` : ""}${status.last_message_summary ? ` last_summary=${compactPreview(status.last_message_summary)}` : ""}`;
 }
 function compactCommunicationSnapshot(snapshot) {
     if (!snapshot)

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

@@ -0,0 +1,6 @@
+/**
+ * Template recipe validator CLI logic.
+ * Zones: recipe validation, installed script entrypoint
+ */
+export declare function validateRecipeUsage(): string;
+export declare function validateRecipes(argv: string[]): Record<string, unknown>;

package/dist/lib/validate-recipe.js

@@ -0,0 +1,104 @@
+/**
+ * Template recipe validator CLI logic.
+ * Zones: recipe validation, installed script entrypoint
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { readResolvedRecipeConfig } from "./recipe-references.js";
+export function validateRecipeUsage() {
+    return `Usage:
+  validate-recipe.mjs <recipe-file-or-dir> [--all]
+
+Validates one template recipe file, or all *.json/*.md files in a directory when --all is set.`;
+}
+function expandPath(value) {
+    return resolve(String(value).replace(/^~(?=\/|$)/, process.env.HOME ?? homedir()));
+}
+function templateKind(template) {
+    if (typeof template === "string")
+        return "leaf";
+    if (Array.isArray(template))
+        return "sequence";
+    if (template && typeof template === "object") {
+        const node = template;
+        if (typeof node.template === "string")
+            return "leaf";
+        if (Array.isArray(node.template))
+            return node.parallel === true ? "parallel" : "sequence";
+        if (node.parallel === true)
+            return "parallel";
+        return "object";
+    }
+    return "unknown";
+}
+function recipeFiles(target, all) {
+    if (!existsSync(target))
+        throw new Error(`Recipe path not found: ${target}`);
+    const stat = statSync(target);
+    if (stat.isFile())
+        return [target];
+    if (!stat.isDirectory())
+        throw new Error(`Recipe path is not a file or directory: ${target}`);
+    if (!all)
+        throw new Error("Directory validation requires --all.");
+    return readdirSync(target)
+        .filter((file) => file.endsWith(".json") || file.endsWith(".md"))
+        .sort((a, b) => a.localeCompare(b))
+        .map((file) => resolve(target, file));
+}
+function validateFile(file) {
+    try {
+        const config = readResolvedRecipeConfig(file);
+        if (!config?.template)
+            throw new Error("Recipe must define a non-empty template.");
+        return {
+            file,
+            ok: true,
+            name: config.name ?? "",
+            async: Boolean(config.async),
+            args: Array.isArray(config.args) ? config.args : [],
+            defaults: config.defaults && typeof config.defaults === "object"
+                ? Object.keys(config.defaults).sort()
+                : [],
+            imports: config.imports && typeof config.imports === "object"
+                ? Object.keys(config.imports).sort()
+                : [],
+            mailbox: config.mailbox && typeof config.mailbox === "object"
+                ? {
+                    accepts: Array.isArray(config.mailbox.accepts)
+                        ? config.mailbox.accepts
+                        : [],
+                    emits: Array.isArray(config.mailbox.emits)
+                        ? config.mailbox.emits
+                        : [],
+                }
+                : undefined,
+            template: templateKind(config.template),
+        };
+    }
+    catch (error) {
+        return {
+            file,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function validateRecipes(argv) {
+    const targetArg = argv.find((arg) => !arg.startsWith("-"));
+    const all = argv.includes("--all");
+    if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
+        return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
+    }
+    const files = recipeFiles(expandPath(targetArg), all);
+    const results = files.map(validateFile);
+    const failed = results.filter((result) => !result.ok).length;
+    return {
+        ok: failed === 0,
+        total: results.length,
+        passed: results.length - failed,
+        failed,
+        results,
+    };
+}

package/dist/recipes/actor-worker.json

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