@llblab/pi-actors 0.22.3 → 0.22.4

package/dist/lib/actor-rooms.js

@@ -272,12 +272,47 @@ function updateRosterForMessage(stateDir, room, message, receivedAt) {
     }
     return roster;
 }
-export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
+function readBranchInboxFile(stateDir, run, address, limit = 40) {
+    const branch = branchIdFromAddress(address, run);
+    if (!branch)
+        throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+    try {
+        const lines = readJsonlTailLines(branchInboxFile(stateDir, branch), limit);
+        const messages = [];
+        let corrupted = 0;
+        for (const line of lines) {
+            try {
+                messages.push(JSON.parse(line));
+            }
+            catch {
+                corrupted += 1;
+            }
+        }
+        return { corrupted, messages };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { corrupted: 0, messages: [] };
+        throw error;
+    }
+}
+function readAllBranchInboxLines(stateDir, run, address) {
     const branch = branchIdFromAddress(address, run);
     if (!branch)
         throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
     try {
-        return readJsonlTailLines(branchInboxFile(stateDir, branch), limit).map((line) => JSON.parse(line));
+        const content = fs.readFileSync(branchInboxFile(stateDir, branch), "utf8");
+        return content
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            try {
+                return { message: JSON.parse(line) };
+            }
+            catch {
+                return { raw: line };
+            }
+        });
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -285,6 +320,12 @@ export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
         throw error;
     }
 }
+export function readBranchInboxMessages(stateDir, run, address, limit = 40) {
+    return readBranchInboxFile(stateDir, run, address, limit).messages;
+}
+export function readBranchInboxDiagnostics(stateDir, run, address, limit = 40) {
+    return readBranchInboxFile(stateDir, run, address, limit);
+}
 export function getBranchInboxTerminalRetainLimit() {
     const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
     return Number.isInteger(value) && value >= 0
@@ -320,19 +361,27 @@ export function updateBranchInboxMessageStatus(stateDir, run, address, id, statu
     const releaseLock = acquireBranchInboxLock(stateDir, branch);
     try {
         const file = branchInboxFile(stateDir, branch);
-        const messages = readBranchInboxMessages(stateDir, run, address, Number.MAX_SAFE_INTEGER);
+        const records = readAllBranchInboxLines(stateDir, run, address);
         let changed = false;
         const timestampKey = `${status}_at`;
-        const updated = messages.map((message) => {
-            if (message.id !== id)
-                return message;
+        const updated = records.map((record) => {
+            if (!("message" in record) || record.message.id !== id)
+                return record;
             changed = true;
-            return { ...message, ...metadata, [timestampKey]: new Date().toISOString(), status };
+            return { message: { ...record.message, ...metadata, [timestampKey]: new Date().toISOString(), status } };
         });
         if (!changed)
             return false;
-        const compacted = compactBranchInboxMessages(updated);
-        fs.writeFileSync(file, `${compacted.map((message) => JSON.stringify(message)).join("\n")}\n`);
+        const validMessages = updated.flatMap((record) => "message" in record ? [record.message] : []);
+        const compactedIds = new Set(compactBranchInboxMessages(validMessages).map((message) => message.id));
+        const lines = updated.flatMap((record) => {
+            if ("raw" in record)
+                return [record.raw];
+            if (record.message.id && !compactedIds.has(record.message.id))
+                return [];
+            return [JSON.stringify(record.message)];
+        });
+        fs.writeFileSync(file, lines.length ? `${lines.join("\n")}\n` : "");
         notifyActorWake(stateDir, address, "branch.inbox.status", { id, status });
         return true;
     }

package/dist/lib/async-runs.js

@@ -3,8 +3,8 @@
  * Zones: async runtime, lifecycle, state files
  * Owns detached run state, observation, log tailing, listing, and cancellation safety
  */
-import { randomUUID } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { closeSync, constants, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
 import { createConnection } from "node:net";
 import { platform } from "node:os";
@@ -22,7 +22,8 @@ const DEFAULT_STATE_ROOT = Paths.getRunStateRoot();
 const DEFAULT_RECIPE_ROOT = Paths.getRecipeRoot();
 function packageRoot() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
-    if (basename(moduleDir) === "lib" && basename(dirname(moduleDir)) === "dist") {
+    if (basename(moduleDir) === "lib" &&
+        basename(dirname(moduleDir)) === "dist") {
         return dirname(dirname(moduleDir));
     }
     return dirname(moduleDir);
@@ -263,7 +264,8 @@ export function startRun(params, cwd) {
             ? resolveRecipeFile(startParams.file)
             : undefined;
         const recipe = startParams.name || getRunIdFromFile(recipeFile);
-        const includeActorRecipeContext = startParams.actor_context !== false && startParams.actor_context !== "off";
+        const includeActorRecipeContext = startParams.actor_context !== false &&
+            startParams.actor_context !== "off";
         const recipeContextRecords = recipeFile && includeActorRecipeContext
             ? RecipeReferences.buildRecipeContextRecords(recipeFile)
             : undefined;
@@ -290,7 +292,9 @@ export function startRun(params, cwd) {
             argv: [process.execPath, ...argv],
             createdAt: new Date().toISOString(),
             cwd,
-            ...(startParams.launch_source ? { launch_source: startParams.launch_source } : {}),
+            ...(startParams.launch_source
+                ? { launch_source: startParams.launch_source }
+                : {}),
             ...(startParams.ownerId ? { ownerId: startParams.ownerId } : {}),
             pid: 0,
             ...(recipe ? { recipe } : {}),
@@ -582,7 +586,9 @@ export function claimRunInboxMessage(runOrDir, owner = "runtime", statuses = ["q
             ...messages[index],
             claimed_at: new Date().toISOString(),
             claimed_by: owner,
-            id: typeof messages[index].id === "string" ? messages[index].id : randomUUID(),
+            id: typeof messages[index].id === "string"
+                ? messages[index].id
+                : randomUUID(),
             status: "claimed",
         };
         messages[index] = claimed;
@@ -669,9 +675,10 @@ 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" };
+        record =
+            parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed
+                : { body: parsed, type: "run.message" };
     }
     catch {
         record = { body: message, type: "run.message" };
@@ -781,6 +788,7 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
             control: "inbox.jsonl",
             control_path: endpoint.path,
             control_type: endpoint.type,
+            inbox_id: inboxId,
             queued: true,
             run,
             sent: true,
@@ -800,6 +808,7 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
                 control: "control.fifo",
                 control_path: endpoint.path,
                 control_type: endpoint.type,
+                inbox_id: inboxId,
                 run,
                 sent: true,
                 state_dir: stateDir,
@@ -813,13 +822,24 @@ export async function sendRunMessage(runOrDir, message, options = {}) {
             control: endpoint.path,
             control_path: endpoint.path,
             control_type: endpoint.type,
+            inbox_id: inboxId,
             run,
             sent: true,
             state_dir: stateDir,
         };
     }
     catch (error) {
-        throw new Error(`Run control endpoint is not ready: ${endpoint.path}: ${error instanceof Error ? error.message : String(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,
+        });
     }
 }
 export function getRunProcessSignalPlan(pid, signal, runtimePlatform = process.platform) {
@@ -842,7 +862,9 @@ function signalOwnedRunProcess(pid, signal) {
     if (plan.command && plan.args) {
         const result = spawnSync(plan.command, plan.args, { encoding: "utf8" });
         if (result.status !== 0) {
-            throw new Error(result.stderr?.trim() || result.stdout?.trim() || `${plan.command} failed`);
+            throw new Error(result.stderr?.trim() ||
+                result.stdout?.trim() ||
+                `${plan.command} failed`);
         }
         return plan;
     }

package/dist/lib/observability.js

@@ -4,7 +4,7 @@
  * Owns ambient summaries, terminal events, and run outbox delivery for detached command-template runs
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
 const TERMINAL = new Set([
@@ -324,14 +324,22 @@ export async function executeRunRetirements(summary, options) {
     const results = [];
     for (const candidate of findRunRetirementCandidates(summary)) {
         if (options.attempted?.has(candidate.stateDir)) {
-            results.push({ action: "skip", run: candidate.run, stateDir: candidate.stateDir });
+            results.push({
+                action: "skip",
+                run: candidate.run,
+                stateDir: candidate.stateDir,
+            });
             continue;
         }
         options.attempted?.add(candidate.stateDir);
         try {
             await options.sendStop(candidate);
             options.notify?.(`Retiring actor ${candidate.run} after child runs reached terminal state`, "info");
-            results.push({ action: "stop", run: candidate.run, stateDir: candidate.stateDir });
+            results.push({
+                action: "stop",
+                run: candidate.run,
+                stateDir: candidate.stateDir,
+            });
             continue;
         }
         catch (error) {
@@ -343,13 +351,19 @@ export async function executeRunRetirements(summary, options) {
                     : `Actor retirement skipped for ${candidate.run}: ${error instanceof Error ? error.message : String(error)}`, cancelled ? "warning" : "error");
                 results.push({
                     action: cancelled ? "cancel" : "skip",
-                    ...(cancelled ? {} : { error: error instanceof Error ? error.message : String(error) }),
+                    ...(cancelled
+                        ? {}
+                        : {
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
                     run: candidate.run,
                     stateDir: candidate.stateDir,
                 });
             }
             catch (cancelError) {
-                const message = cancelError instanceof Error ? cancelError.message : String(cancelError);
+                const message = cancelError instanceof Error
+                    ? cancelError.message
+                    : String(cancelError);
                 options.notify?.(`Actor retirement failed for ${candidate.run}: ${message}`, "error");
                 results.push({
                     action: "failed",
@@ -362,10 +376,14 @@ export async function executeRunRetirements(summary, options) {
     }
     return results;
 }
+function runObservationKey(run) {
+    return run.stateDir ?? run.run;
+}
 export function detectRunTransitions(previous, summary) {
     const transitions = [];
     for (const run of summary.runs) {
-        const old = previous.get(run.run);
+        const key = runObservationKey(run);
+        const old = previous.get(key);
         if (old && old !== run.status && TERMINAL.has(run.status)) {
             transitions.push({
                 from: old,
@@ -379,7 +397,7 @@ export function detectRunTransitions(previous, summary) {
                 ...(run.tool ? { tool: run.tool } : {}),
             });
         }
-        previous.set(run.run, run.status);
+        previous.set(key, run.status);
     }
     return transitions;
 }
@@ -440,11 +458,11 @@ function readOutboxLines(run) {
     return content ? content.split("\n") : [];
 }
 export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = []) {
-    const activeRuns = new Set(summary.runs.map((run) => run.run));
+    const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
     const terminalRunSet = new Set(terminalRuns);
     const terminalLineKeys = new Set(summary.runs
-        .filter((run) => terminalRunSet.has(run.run))
-        .map((run) => run.stateDir ?? run.run));
+        .filter((run) => terminalRunSet.has(runObservationKey(run)))
+        .map((run) => runObservationKey(run)));
     const activeLineKeys = new Set(summary.runs.map((run) => run.stateDir ?? run.run));
     for (const run of terminalRunSet)
         previousStatuses.delete(run);

package/dist/lib/recipe-discovery.js

@@ -24,7 +24,9 @@ function assertToolSafeRepeatConfig(config, argTypes, defaults) {
         const trimmed = node.repeat.trim();
         if (!/^\d+$/.test(trimmed)) {
             const match = trimmed.match(/^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/);
-            if (!match || (argTypes[match[1]]?.kind !== "array" && !Array.isArray(defaults[match[1]])))
+            if (!match ||
+                (argTypes[match[1]]?.kind !== "array" &&
+                    !Array.isArray(defaults[match[1]])))
                 throw new Error("Command template repeat must be a positive integer or {array.length} with an array argument/default.");
         }
     }
@@ -39,11 +41,16 @@ function listRecipeFiles(root) {
         (entry.name.endsWith(".json") || entry.name.endsWith(".md")) &&
         entry.name !== "legacy-tool-registry-migration-report.json")
         .map((entry) => join(root, entry.name))
-        .sort((a, b) => a.replace(/\.md$/, ".json").localeCompare(b.replace(/\.md$/, ".json")) || (a.endsWith(".json") ? -1 : 1));
+        .sort((a, b) => a
+        .replace(/\.md$/, ".json")
+        .localeCompare(b.replace(/\.md$/, ".json")) ||
+        (a.endsWith(".json") ? -1 : 1));
 }
 function getRecipeConfigDiagnostics(file, config) {
-    if (!config)
-        return [`Invalid recipe: ${file}`];
+    if (!config) {
+        const reason = RecipeReferences.diagnoseRawRecipeConfigFailure(file);
+        return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
+    }
     const commandTemplateConfig = typeof config.template === "object" && config.template !== null
         ? config.template
         : config;
@@ -94,7 +101,14 @@ function filesForSource(source) {
     const defaultTool = source.defaultTool === true;
     const mutableUsage = source.mutableUsage === true;
     if (source.file)
-        return [{ root: source.root ?? source.file, file: source.file, defaultTool, mutableUsage }];
+        return [
+            {
+                root: source.root ?? source.file,
+                file: source.file,
+                defaultTool,
+                mutableUsage,
+            },
+        ];
     return source.root
         ? listRecipeFiles(source.root).map((file) => ({
             root: source.root,
@@ -139,7 +153,9 @@ export function discoverRecipeSources(sources) {
     const diagnostics = getRecipeRootDiagnostics(sources);
     for (const [id, bucket] of byId) {
         bucket.sort((a, b) => a.priority - b.priority ||
-            a.path.replace(/\.md$/, ".json").localeCompare(b.path.replace(/\.md$/, ".json")) ||
+            a.path
+                .replace(/\.md$/, ".json")
+                .localeCompare(b.path.replace(/\.md$/, ".json")) ||
             (a.path.endsWith(".json") ? -1 : 1));
         const winner = bucket[0];
         winner.active = true;
@@ -209,7 +225,13 @@ function cleanupRecommendation(entry) {
             id: entry.id,
             path: entry.path,
             reason: "user recipe is a component, not an active tool",
-            actions: ["keep component", "move into tool root", "merge", "delete", "archive"],
+            actions: [
+                "keep component",
+                "move into tool root",
+                "merge",
+                "delete",
+                "archive",
+            ],
         };
     }
     if (entry.shadows.length > 0) {
@@ -241,6 +263,66 @@ export function createRecipeIntegrityManifest(result) {
     })
         .sort((a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path));
 }
+function diagnosticSeverity(message) {
+    if (/invalid|failed to load|not found|cyclic|exceeds|must define|repeat must/i.test(message)) {
+        return "error";
+    }
+    if (/world-writable|group-writable|invokes bash|eval|destructive|unsafe/i.test(message)) {
+        return "warning";
+    }
+    return "info";
+}
+function diagnosticSuggestedAction(message) {
+    if (/must define template/i.test(message))
+        return "add a template field or remove the recipe";
+    if (/JSON|Expected|parse/i.test(message))
+        return "fix recipe syntax or archive the file";
+    if (/Markdown recipe/i.test(message))
+        return "fix frontmatter and add a fenced template or recipe block";
+    if (/cyclic/i.test(message))
+        return "break the import cycle";
+    if (/exceeds.*size/i.test(message))
+        return "split large prompt or data into separate files";
+    if (/repeat must/i.test(message))
+        return "use a positive repeat count or an array-typed repeat source";
+    if (/world-writable|group-writable/i.test(message))
+        return "tighten recipe root permissions";
+    if (/invokes bash/i.test(message))
+        return "audit the trusted shell boundary or move details to recipe doctor";
+    if (/shadows/i.test(message))
+        return "confirm the active override or rename one recipe";
+    if (/disabled/i.test(message))
+        return "keep disabled intentionally or delete/archive the file";
+    return "inspect the recipe and fix or archive it if unexpected";
+}
+function diagnosticDetails(result) {
+    const details = [];
+    const seen = new Set();
+    const push = (message, entry) => {
+        const key = `${entry?.path ?? "root"}\n${message}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        details.push({
+            ...(entry ? { id: entry.id, path: entry.path } : {}),
+            action: diagnosticSuggestedAction(message),
+            message,
+            severity: diagnosticSeverity(message),
+        });
+    };
+    for (const message of result.diagnostics)
+        push(message);
+    for (const entry of result.entries) {
+        for (const message of entry.diagnostics)
+            push(message, entry);
+    }
+    return details.sort((a, b) => {
+        const rank = { error: 0, warning: 1, info: 2 };
+        return (rank[a.severity] -
+            rank[b.severity] ||
+            String(a.message).localeCompare(String(b.message)));
+    });
+}
 function recommendationForEntry(entry, activePath) {
     const recommendation = cleanupRecommendation(entry);
     if (!recommendation)
@@ -257,9 +339,11 @@ export function summarizeDiscovery(result) {
     const recommendations = result.entries
         .map((entry) => recommendationForEntry(entry, result.active.get(entry.id)?.path))
         .filter((entry) => Boolean(entry))
-        .sort((a, b) => String(a.id).localeCompare(String(b.id)) || String(a.path).localeCompare(String(b.path)));
+        .sort((a, b) => String(a.id).localeCompare(String(b.id)) ||
+        String(a.path).localeCompare(String(b.path)));
     return {
-        active: [...result.active.values()].map((entry) => ({
+        active: [...result.active.values()]
+            .map((entry) => ({
             id: entry.id,
             path: entry.path,
             description: entry.config?.description,
@@ -267,15 +351,26 @@ export function summarizeDiscovery(result) {
             disabled: entry.disabled,
             invalid: entry.invalid,
             shadows: entry.shadows,
-            ...(recipeUsage(entry.config) ? { usage: recipeUsage(entry.config) } : {}),
-        })).sort((a, b) => a.id.localeCompare(b.id)),
+            ...(recipeUsage(entry.config)
+                ? { usage: recipeUsage(entry.config) }
+                : {}),
+        }))
+            .sort((a, b) => a.id.localeCompare(b.id)),
         shadowed: result.entries
             .filter((entry) => entry.shadowed)
-            .map((entry) => ({ id: entry.id, path: entry.path, shadowedBy: result.active.get(entry.id)?.path }))
+            .map((entry) => ({
+            id: entry.id,
+            path: entry.path,
+            shadowedBy: result.active.get(entry.id)?.path,
+        }))
             .sort((a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path)),
         invalid: result.entries
             .filter((entry) => entry.invalid)
-            .map((entry) => ({ id: entry.id, path: entry.path, diagnostics: entry.diagnostics }))
+            .map((entry) => ({
+            id: entry.id,
+            path: entry.path,
+            diagnostics: entry.diagnostics,
+        }))
             .sort((a, b) => a.id.localeCompare(b.id)),
         disabled: result.entries
             .filter((entry) => entry.disabled)
@@ -283,6 +378,7 @@ export function summarizeDiscovery(result) {
             .sort((a, b) => a.id.localeCompare(b.id)),
         recommendations,
         diagnostics: result.diagnostics,
+        diagnostic_details: diagnosticDetails(result),
         integrity_manifest: createRecipeIntegrityManifest(result),
     };
 }
@@ -297,7 +393,10 @@ export function toRegisteredTool(entry) {
         ? {
             ...argTemplate,
             ...(cfg.args !== undefined ? { args: cfg.args } : {}),
-            defaults: { ...(argTemplate.defaults ?? {}), ...(cfg.defaults ?? {}) },
+            defaults: {
+                ...(argTemplate.defaults ?? {}),
+                ...(cfg.defaults ?? {}),
+            },
         }
         : { args: cfg.args, defaults: cfg.defaults ?? {}, template: argTemplate };
     const explicitArgTypes = Object.fromEntries((cfg.args ?? []).map((arg) => {
@@ -312,13 +411,19 @@ export function toRegisteredTool(entry) {
         template,
         recipe: cfg,
         args: Schema.getToolArgNames(argTemplateConfig),
-        defaults: Object.fromEntries(Object.entries(cfg.defaults ?? {}).map(([key, value]) => [key, String(value)])),
+        defaults: Object.fromEntries(Object.entries(cfg.defaults ?? {}).map(([key, value]) => [
+            key,
+            String(value),
+        ])),
         ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
         ...(entry.mutableUsage ? { sourcePath: entry.path } : {}),
         ...(cfg.args ? { storedArgs: cfg.args } : {}),
         ...(cfg.defaults
             ? {
-                storedDefaults: Object.fromEntries(Object.entries(cfg.defaults).map(([key, value]) => [key, String(value)])),
+                storedDefaults: Object.fromEntries(Object.entries(cfg.defaults).map(([key, value]) => [
+                    key,
+                    String(value),
+                ])),
             }
             : {}),
     };

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

@@ -57,6 +57,7 @@ export interface ReadResolvedRecipeConfigOptions {
 }
 export declare function resolveRecipePath(value: string, recipeRoot?: string): string;
 export declare function getRecipePath(value: unknown, recipeRoot?: string): string | undefined;
+export declare function diagnoseRawRecipeConfigFailure(path: string): string | undefined;
 export declare function readRawRecipeConfig(path: string): Record<string, unknown> | undefined;
 export declare function getRecipeIdFromPath(file: string): string;
 export declare function readResolvedRecipeConfig(file: string, stack?: string[], options?: ReadResolvedRecipeConfigOptions): TemplateRecipeConfig | undefined;

package/dist/lib/recipe-references.js

@@ -29,7 +29,10 @@ export function resolveRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
 }
 function isBareRecipeName(value) {
     const trimmed = value.trim();
-    return Boolean(trimmed) && !trimmed.includes("/") && !trimmed.startsWith("~") && !trimmed.includes("{");
+    return (Boolean(trimmed) &&
+        !trimmed.includes("/") &&
+        !trimmed.startsWith("~") &&
+        !trimmed.includes("{"));
 }
 function recipeNameFiles(value) {
     const trimmed = value.trim();
@@ -260,6 +263,42 @@ function parseMarkdownRecipeConfig(content) {
     }
     return { ...frontmatter, template: text };
 }
+export function diagnoseRawRecipeConfigFailure(path) {
+    if (!existsSync(path))
+        return "file does not exist";
+    const size = statSync(path).size;
+    if (size > MAX_RECIPE_FILE_BYTES) {
+        return `file exceeds size limit ${MAX_RECIPE_FILE_BYTES} bytes`;
+    }
+    try {
+        const content = readFileSync(path, "utf8");
+        if (path.endsWith(".md")) {
+            const lines = content.split(/\r?\n/);
+            if (lines[0]?.trim() !== "---") {
+                return "Markdown recipe must start with frontmatter";
+            }
+            const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+            if (end === -1)
+                return "Markdown recipe frontmatter is not closed";
+            const parsed = parseMarkdownRecipeConfig(content);
+            if (!parsed)
+                return "Markdown recipe has no executable recipe/template fence";
+            if (!Object.hasOwn(parsed, "template"))
+                return "recipe must define template";
+            return undefined;
+        }
+        const raw = JSON.parse(content);
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+            return "JSON recipe must be an object";
+        }
+        if (!Object.hasOwn(raw, "template"))
+            return "recipe must define template";
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 export function readRawRecipeConfig(path) {
     if (!existsSync(path))
         return undefined;

package/dist/lib/registry.js

@@ -82,7 +82,11 @@ function getInputTemplate(value) {
             throw new Error(Output.formatToolText("Tool template sequence is empty."));
         return value;
     }
-    throw new Error(Output.formatToolText("Tool template must be a string or sequence."));
+    if (value && typeof value === "object") {
+        CommandTemplates.expandCommandTemplateConfigs(value);
+        return value;
+    }
+    throw new Error(Output.formatToolText("Tool template must be a string, object, or sequence."));
 }
 function buildConfig(name, input, existing) {
     const explicitArgs = input.args === undefined