@llblab/pi-actors 0.22.5 → 0.24.0

package/dist/lib/tools.js

@@ -7,6 +7,7 @@ import * as ActorMessages from "./actor-messages.js";
 import * as ActorRooms from "./actor-rooms.js";
 import * as AsyncRuns from "./async-runs.js";
 import * as Execution from "./execution.js";
+import * as Limits from "./limits.js";
 import * as Paths from "./paths.js";
 import * as Prompts from "./prompts.js";
 import * as RecipeDiscovery from "./recipe-discovery.js";
@@ -154,7 +155,7 @@ function compactRunMessages(messages) {
     ].join(" "))
         .join("\n")}`;
 }
-function compactPreview(value, maxLength = 80) {
+function compactPreview(value, maxLength = Limits.COMPACT_PREVIEW_CHARS) {
     if (value === undefined)
         return undefined;
     const text = typeof value === "string" ? value : JSON.stringify(value, undefined, 0);
@@ -173,7 +174,9 @@ function compactRoomPreviews(previews) {
         `to=${preview.to}`,
         `type=${preview.type}`,
         preview.summary ? `summary=${compactPreview(preview.summary)}` : "",
-        preview.body_preview ? `body=${compactPreview(preview.body_preview)}` : "",
+        preview.body_preview
+            ? `body=${compactPreview(preview.body_preview)}`
+            : "",
     ]
         .filter(Boolean)
         .join(" "))
@@ -189,7 +192,9 @@ function compactRoomMessages(messages) {
         `to=${message.to}`,
         `type=${message.type}`,
         `summary=${String(message.summary ?? "").replaceAll(/\s+/g, "_")}`,
-        compactPreview(message.body) ? `body=${compactPreview(message.body)}` : "",
+        compactPreview(message.body)
+            ? `body=${compactPreview(message.body)}`
+            : "",
     ]
         .filter(Boolean)
         .join(" "))
@@ -203,8 +208,12 @@ function compactRoomContacts(contacts) {
         `address=${contact.address}`,
         contact.role !== undefined ? `role=${String(contact.role)}` : "",
         contact.parent !== undefined ? `parent=${String(contact.parent)}` : "",
-        contact.caps !== undefined ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}` : "",
-        contact.claim !== undefined ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}` : "",
+        contact.caps !== undefined
+            ? `caps=${Array.isArray(contact.caps) ? contact.caps.join(",") : String(contact.caps)}`
+            : "",
+        contact.claim !== undefined
+            ? `claim=${String(contact.claim).replaceAll(/\s+/g, "_")}`
+            : "",
         contact.status !== undefined ? `status=${String(contact.status)}` : "",
     ]
         .filter(Boolean)
@@ -220,15 +229,19 @@ function compactRoomRoster(roster) {
         `address=${member.address}`,
         `role=${String(member.role ?? "")}`,
         member.parent !== undefined ? `parent=${String(member.parent)}` : "",
-        member.caps !== undefined ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}` : "",
-        member.claim !== undefined ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}` : "",
+        member.caps !== undefined
+            ? `caps=${Array.isArray(member.caps) ? member.caps.join(",") : String(member.caps)}`
+            : "",
+        member.claim !== undefined
+            ? `claim=${String(member.claim).replaceAll(/\s+/g, "_")}`
+            : "",
         `status=${String(member.status ?? "")}`,
         `last_seen=${member.last_seen}`,
     ].join(" "))
         .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)
@@ -245,19 +258,72 @@ function compactInboxMessages(messages, emptyLabel) {
         `type=${String(message.type ?? "")}`,
         `from=${String(message.from ?? "")}`,
         `to=${String(message.to ?? "")}`,
-        ...(message.queued_at ? [`queued_at=${String(message.queued_at)}`] : []),
+        ...(message.queued_at
+            ? [`queued_at=${String(message.queued_at)}`]
+            : []),
         ...(message.sent_at ? [`sent_at=${String(message.sent_at)}`] : []),
-        ...(message.claimed_at ? [`claimed_at=${String(message.claimed_at)}`] : []),
-        ...(message.handled_at ? [`handled_at=${String(message.handled_at)}`] : []),
-        ...(message.failed_at ? [`failed_at=${String(message.failed_at)}`] : []),
+        ...(message.claimed_at
+            ? [`claimed_at=${String(message.claimed_at)}`]
+            : []),
+        ...(message.handled_at
+            ? [`handled_at=${String(message.handled_at)}`]
+            : []),
+        ...(message.failed_at
+            ? [`failed_at=${String(message.failed_at)}`]
+            : []),
     ].join(" "))
         .join("\n")}`;
 }
 function compactBranchInbox(messages) {
     return compactInboxMessages(messages, "branch inbox");
 }
+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 } : {}),
+    };
+}
+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 };
+}
+function mailboxTypes(entries) {
+    return entries.flatMap((entry) => typeof asRecord(entry).type === "string"
+        ? [String(asRecord(entry).type)]
+        : []);
+}
 function compactRunMailbox(run, mailbox, messages) {
-    return `\nrun=${run} accepts=${Array.isArray(mailbox.accepts) ? mailbox.accepts.join(",") : ""} emits=${Array.isArray(mailbox.emits) ? mailbox.emits.join(",") : ""}${compactInboxMessages(messages, "run inbox")}`;
+    const normalized = normalizeMailboxContracts(mailbox);
+    return `\nrun=${run} accepts=${mailboxTypes(normalized.accepts).join(",")} emits=${mailboxTypes(normalized.emits).join(",")}${compactInboxMessages(messages, "run inbox")}`;
+}
+function compactArtifactPath(value) {
+    if (typeof value === "string")
+        return value;
+    const record = asRecord(value);
+    return String(record.path ?? "<missing>");
 }
 function compactActorFiles(status) {
     const run = String(status.run ?? "<unknown>");
@@ -267,12 +333,14 @@ function compactActorFiles(status) {
         status.stderrLog,
         status.eventsFile,
         status.outboxFile,
-        status.state_dir ? `${String(status.state_dir)}/communication.json` : undefined,
+        status.state_dir
+            ? `${String(status.state_dir)}/communication.json`
+            : undefined,
         status.state_dir ? `${String(status.state_dir)}/result.json` : undefined,
     ].filter((file) => typeof file === "string");
     const artifactText = Object.keys(artifacts).length
         ? ` artifacts=${Object.entries(artifacts)
-            .map(([key, value]) => `${key}:${String(value)}`)
+            .map(([key, value]) => `${key}:${compactArtifactPath(value)}`)
             .join(",")}`
         : "";
     return `\nrun=${run}${artifactText}${files.length ? ` files=${files.join(",")}` : ""}`;
@@ -302,11 +370,49 @@ function compactToolActor(name, tool) {
     const properties = asRecord(parameters.properties);
     return `\ntool=${name} description=${String(tool.description ?? "").replaceAll(/\s+/g, "_")} args=${Object.keys(properties).join(",")} required=${required}`;
 }
+function compactRecipeImports(summary) {
+    const active = Array.isArray(summary.active)
+        ? summary.active
+        : [];
+    const lines = active.flatMap((entry) => {
+        const imports = asRecord(entry.imports);
+        return Object.entries(imports).map(([alias, value]) => {
+            const binding = typeof value === "string" ? { from: value } : asRecord(value);
+            return `recipe=${String(entry.id ?? "<unknown>")} alias=${alias} from=${String(binding.from ?? value)}`;
+        });
+    });
+    return lines.length ? `\n${lines.join("\n")}` : "\n(no recipe imports)";
+}
+function compactRecipeDoctor(summary) {
+    const details = Array.isArray(summary.diagnostic_details)
+        ? summary.diagnostic_details
+        : [];
+    const recommendations = Array.isArray(summary.recommendations)
+        ? summary.recommendations
+        : [];
+    const counts = { error: 0, info: 0, warning: 0 };
+    for (const detail of details) {
+        const severity = String(detail.severity ?? "info");
+        if (severity === "error" || severity === "warning" || severity === "info")
+            counts[severity] += 1;
+    }
+    const lines = [
+        `recipes doctor errors=${counts.error} warnings=${counts.warning} info=${counts.info} recommendations=${recommendations.length}`,
+    ];
+    for (const detail of details.slice(0, 8)) {
+        lines.push(`${String(detail.severity ?? "info")} id=${String(detail.id ?? "root")} action=${compactPreview(detail.action, Limits.DOCTOR_ACTION_PREVIEW_CHARS) ?? "inspect"}`);
+    }
+    return `\n${lines.join("\n")}`;
+}
 function compactRecipeRegistry(summary) {
     const active = Array.isArray(summary.active) ? summary.active.length : 0;
-    const shadowed = Array.isArray(summary.shadowed) ? summary.shadowed.length : 0;
+    const shadowed = Array.isArray(summary.shadowed)
+        ? summary.shadowed.length
+        : 0;
     const invalid = Array.isArray(summary.invalid) ? summary.invalid.length : 0;
-    const disabled = Array.isArray(summary.disabled) ? summary.disabled.length : 0;
+    const disabled = Array.isArray(summary.disabled)
+        ? summary.disabled.length
+        : 0;
     const diagnostics = Array.isArray(summary.diagnostics)
         ? summary.diagnostics.length
         : 0;
@@ -420,6 +526,11 @@ function assertMessageSenderBelongsToRun(message, run, routeLabel) {
         throw new Error(`message to ${routeLabel} requires from=run:${run} or branch:${run}/<branch>; got ${message.from}.`);
     }
 }
+async function routeBranchEnvelope(stateDir, runId, recipient, message, _options) {
+    const branchMessage = { ...message, to: recipient };
+    ActorRooms.appendBranchInboxMessage(stateDir, runId, recipient, branchMessage);
+    return AsyncRuns.sendRunMessage(runId, JSON.stringify(branchMessage));
+}
 function getRoomMulticastRecipients(message, run) {
     const raw = message.metadata?.recipients;
     if (raw === undefined)
@@ -471,13 +582,17 @@ export function createSpawnToolDefinition() {
                 run_id: runId,
                 state_dir: typeof input.state_dir === "string" ? input.state_dir : undefined,
                 ...(input.template !== undefined
-                    ? { template: input.template }
+                    ? {
+                        template: input.template,
+                    }
                     : {}),
                 values: asRecord(input.values),
                 ...(input.artifacts &&
                     typeof input.artifacts === "object" &&
                     !Array.isArray(input.artifacts)
-                    ? { artifacts: input.artifacts }
+                    ? {
+                        artifacts: input.artifacts,
+                    }
                     : {}),
             }, ctx.cwd);
             ActorRooms.ensureDefaultRoom(meta.state_dir, String(meta.run));
@@ -532,11 +647,15 @@ export function createInspectToolDefinition(deps = {}) {
             const target = String(input.target ?? "");
             const view = String(input.view ?? "");
             if (target === "recipes" || target === "recipe-registry") {
-                if (view !== "status" && view !== "summary") {
-                    throw new Error("inspect recipes supports view=status or view=summary.");
+                if (view !== "status" && view !== "summary" && view !== "doctor" && view !== "imports") {
+                    throw new Error("inspect recipes supports view=status, view=summary, view=doctor, or view=imports.");
                 }
                 const discovered = RecipeDiscovery.discoverRecipeSources([
-                    { root: deps.recipeRoot ?? Paths.getRecipeRoot(), defaultTool: true, mutableUsage: true },
+                    {
+                        root: deps.recipeRoot ?? Paths.getRecipeRoot(),
+                        defaultTool: true,
+                        mutableUsage: true,
+                    },
                     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
                 ]);
                 const summary = RecipeDiscovery.summarizeDiscovery(discovered);
@@ -544,7 +663,11 @@ export function createInspectToolDefinition(deps = {}) {
                     content: [
                         {
                             type: "text",
-                            text: maybeJsonText(summary, input.verbose === true, compactRecipeRegistry(summary)),
+                            text: maybeJsonText(summary, input.verbose === true, view === "doctor"
+                                ? compactRecipeDoctor(summary)
+                                : view === "imports"
+                                    ? compactRecipeImports(summary)
+                                    : compactRecipeRegistry(summary)),
                         },
                     ],
                     details: summary,
@@ -627,7 +750,7 @@ export function createInspectToolDefinition(deps = {}) {
                     };
                 }
                 if (view === "previews") {
-                    const previews = ActorRooms.readRoomMessagePreviews(stateDir, address.room, Number(input.lines || 40));
+                    const previews = ActorRooms.readRoomMessagePreviews(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [
                             {
@@ -639,7 +762,7 @@ export function createInspectToolDefinition(deps = {}) {
                     };
                 }
                 if (view === "messages") {
-                    const messages = ActorRooms.readRoomMessages(stateDir, address.room, Number(input.lines || 40));
+                    const messages = ActorRooms.readRoomMessages(stateDir, address.room, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [
                             {
@@ -676,14 +799,16 @@ export function createInspectToolDefinition(deps = {}) {
                 }
                 throw new Error("inspect room:<run> supports view=status, view=messages, view=previews, view=roster, or view=contacts.");
             }
-            const runId = address.kind === "run" || address.kind === "branch" ? address.value : undefined;
+            const runId = address.kind === "run" || address.kind === "branch"
+                ? address.value
+                : undefined;
             if (!runId)
                 throw new Error("inspect target must be run:<id>, branch:<run>/<branch>, coordinator, session:<id>, or tool:<name>.");
             if (address.kind === "branch") {
                 if (view !== "mailbox")
                     throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
                 const status = assertRunAccessibleToContext(runId, ctx);
-                const branchInbox = ActorRooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                const branchInbox = ActorRooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                 const messages = branchInbox.messages;
                 return {
                     content: [
@@ -710,7 +835,7 @@ export function createInspectToolDefinition(deps = {}) {
                 }
                 case "tail": {
                     assertRunAccessibleToContext(runId, ctx);
-                    const text = AsyncRuns.tailRun(runId, Number(input.lines || 40));
+                    const text = AsyncRuns.tailRun(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [{ type: "text", text: `\n${text}` }],
                         details: {},
@@ -718,7 +843,7 @@ export function createInspectToolDefinition(deps = {}) {
                 }
                 case "messages": {
                     assertRunAccessibleToContext(runId, ctx);
-                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || 40));
+                    const messages = AsyncRuns.readRunEvents(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
                     return {
                         content: [
                             {
@@ -732,21 +857,30 @@ export function createInspectToolDefinition(deps = {}) {
                 case "artifacts":
                 case "files": {
                     const status = assertRunAccessibleToContext(runId, ctx);
+                    const artifactManifest = AsyncRuns.resolveArtifactManifest(status.artifacts);
+                    const details = artifactManifest
+                        ? { ...status, artifact_manifest: artifactManifest }
+                        : status;
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: maybeJsonText(status, input.verbose === true, compactActorFiles(status)),
+                                text: maybeJsonText(details, input.verbose === true, compactActorFiles(status)),
                             },
                         ],
-                        details: status,
+                        details,
                     };
                 }
                 case "mailbox": {
                     const status = assertRunAccessibleToContext(runId, ctx);
                     const mailbox = asRecord(status.mailbox);
-                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || 40));
-                    const details = { mailbox, messages };
+                    const normalizedMailbox = normalizeMailboxContracts(mailbox);
+                    const messages = AsyncRuns.readRunInboxMessages(runId, Number(input.lines || Limits.DEFAULT_INSPECT_LINES));
+                    const details = {
+                        mailbox,
+                        normalized_mailbox: normalizedMailbox,
+                        messages,
+                    };
                     return {
                         content: [
                             {
@@ -802,7 +936,14 @@ export function createActorMessageToolDefinition(deps = {}) {
             const address = ActorMessages.parseActorAddress(message.to);
             let result;
             if (address.kind === "run" && address.value) {
-                assertRunAccessibleToContext(address.value, ctx);
+                const status = assertRunAccessibleToContext(address.value, ctx);
+                const normalizedMailbox = normalizeMailboxContracts(asRecord(status.mailbox));
+                const acceptedTypes = new Set(mailboxTypes(normalizedMailbox.accepts));
+                const advisoryWarnings = acceptedTypes.size > 0 && !acceptedTypes.has(message.type)
+                    ? [
+                        `Message type ${message.type} is not declared in mailbox.accepts for run:${address.value}.`,
+                    ]
+                    : [];
                 if (message.type === "control.stop" ||
                     message.type === "control.cancel") {
                     result = AsyncRuns.cancelRun(address.value);
@@ -810,9 +951,21 @@ export function createActorMessageToolDefinition(deps = {}) {
                 else if (message.type === "control.kill") {
                     result = AsyncRuns.killRun(address.value);
                 }
+                else if (message.type === "control.archive") {
+                    result = AsyncRuns.archiveRun(address.value);
+                }
+                else if (message.type === "control.prune") {
+                    const body = asRecord(message.body);
+                    result = AsyncRuns.pruneRun(address.value, {
+                        preserveArtifacts: body.preserve_artifacts === true ||
+                            body.preserveArtifacts === true,
+                    });
+                }
                 else {
                     result = await AsyncRuns.sendRunMessage(address.value, messageBodyToRunLine(message));
                 }
+                if (advisoryWarnings.length > 0)
+                    result = { ...result, warnings: advisoryWarnings };
             }
             else if (address.kind === "branch" && address.value) {
                 const runId = address.value;
@@ -837,9 +990,10 @@ export function createActorMessageToolDefinition(deps = {}) {
                         }
                     }
                     ActorRooms.writeCommunicationSnapshot(stateDir, runId);
-                    ActorRooms.appendBranchInboxMessage(stateDir, runId, message.to, message);
                 }
-                result = await AsyncRuns.sendRunMessage(address.value, JSON.stringify(message));
+                result = await routeBranchEnvelope(stateDir, runId, message.to, message, {
+                    source: "direct",
+                });
             }
             else if (address.kind === "room" && address.value && address.room) {
                 const runId = address.value;
@@ -850,7 +1004,9 @@ export function createActorMessageToolDefinition(deps = {}) {
                     throw new Error(`${message.to} has no run state directory.`);
                 const recipients = getRoomMulticastRecipients(message, runId);
                 const roomResult = ActorRooms.appendRoomMessage(stateDir, address.room, message);
-                await Promise.all(recipients.map((recipient) => AsyncRuns.sendRunMessage(runId, JSON.stringify({ ...message, to: recipient }))));
+                await Promise.all(recipients.map((recipient) => routeBranchEnvelope(stateDir, runId, recipient, message, {
+                    source: "room-multicast",
+                })));
                 result = {
                     ...roomResult,
                     ...(recipients.length > 0
@@ -898,7 +1054,10 @@ export function createActorMessageToolDefinition(deps = {}) {
                 result = AsyncRuns.appendRunOutboxEvent(sender.value, {
                     body: message.body,
                     correlation_id: message.correlation_id,
-                    delivery: address.kind === "session" ? "followup" : undefined,
+                    delivery: message.metadata?.requires_response === true ||
+                        address.kind === "session"
+                        ? "followup"
+                        : undefined,
                     event: message.type,
                     from: message.from,
                     metadata: message.metadata,
@@ -965,7 +1124,7 @@ export function createRuntimeToolDefinition(cfg, exec) {
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             try {
                 if (cfg.sourcePath)
-                    RecipeUsage.recordRecipeLaunch(cfg.sourcePath);
+                    RecipeUsage.recordRecipeLaunch(cfg.sourcePath, new Date(), "tool");
                 if (isAsyncRecipe) {
                     const input = params;
                     const { run_id, ...values } = input;

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}"
+}

package/dist/recipes/coordinator-locker.json

@@ -0,0 +1,45 @@
+{
+  "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}"
+}