@llblab/pi-actors 0.22.2 → 0.22.4

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

package/dist/lib/tools.js

@@ -361,6 +361,7 @@ export function createRegisterToolDefinition(deps) {
             state_dir: stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.state_dir),
             template: unionSchema([
                 stringSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
+                looseObjectSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.template),
                 arraySchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateArray),
                 nullSchema(Prompts.REGISTER_TOOL_PARAM_DESCRIPTIONS.templateNull),
             ]),
@@ -390,6 +391,16 @@ function messageBodyToToolParams(message) {
         return {};
     return { input: message.body };
 }
+function formatToolActorFailure(tool, message, params, error) {
+    const original = error instanceof Error ? error.message : String(error);
+    const paramsPreview = compactPreview(params, 240) ?? "{}";
+    return Object.assign(new Error(`tool actor ${tool} failed for message type ${message.type}: ${original}; params=${paramsPreview}`), {
+        message_type: message.type,
+        original_error: original,
+        params_preview: paramsPreview,
+        tool,
+    });
+}
 function runIdFromActorAddress(address) {
     if (!address)
         return undefined;
@@ -672,15 +683,16 @@ export function createInspectToolDefinition(deps = {}) {
                 if (view !== "mailbox")
                     throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
                 const status = assertRunAccessibleToContext(runId, ctx);
-                const messages = ActorRooms.readBranchInboxMessages(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                const branchInbox = ActorRooms.readBranchInboxDiagnostics(String(status.state_dir ?? ""), runId, target, Number(input.lines || 40));
+                const messages = branchInbox.messages;
                 return {
                     content: [
                         {
                             type: "text",
-                            text: maybeJsonText(messages, input.verbose === true, compactBranchInbox(messages.map((message) => ({ ...message })))),
+                            text: maybeJsonText(input.verbose === true ? branchInbox : messages, input.verbose === true, `${compactBranchInbox(messages.map((message) => ({ ...message })))}${branchInbox.corrupted > 0 ? `\ncorrupted=${branchInbox.corrupted}` : ""}`),
                         },
                     ],
-                    details: { messages },
+                    details: { corrupted: branchInbox.corrupted, messages },
                 };
             }
             switch (view) {
@@ -806,9 +818,7 @@ export function createActorMessageToolDefinition(deps = {}) {
                 const runId = address.value;
                 if (message.from)
                     assertMessageSenderBelongsToRun(message, runId, `branch:${runId}/<branch>`);
-                const status = message.from
-                    ? assertRunExistsForActorMessage(runId)
-                    : assertRunAccessibleToContext(runId, ctx);
+                const status = assertRunAccessibleToContext(runId, ctx);
                 const stateDir = String(status.state_dir ?? "");
                 if (stateDir && address.branch) {
                     const ensureBranchMember = (actorAddress) => {
@@ -834,7 +844,7 @@ export function createActorMessageToolDefinition(deps = {}) {
             else if (address.kind === "room" && address.value && address.room) {
                 const runId = address.value;
                 assertMessageSenderBelongsToRun(message, runId, `room:${runId}`);
-                const status = assertRunExistsForActorMessage(runId);
+                const status = assertRunAccessibleToContext(runId, ctx);
                 const stateDir = String(status.state_dir ?? "");
                 if (!stateDir)
                     throw new Error(`${message.to} has no run state directory.`);
@@ -853,7 +863,14 @@ export function createActorMessageToolDefinition(deps = {}) {
                 if (!tool || typeof tool.execute !== "function") {
                     throw new Error(`tool actor not found or not executable: ${address.value}`);
                 }
-                const toolResult = await tool.execute(`message:${message.type}`, messageBodyToToolParams(message), _signal, _onUpdate, ctx);
+                const toolParams = messageBodyToToolParams(message);
+                let toolResult;
+                try {
+                    toolResult = await tool.execute(`message:${message.type}`, toolParams, _signal, _onUpdate, ctx);
+                }
+                catch (error) {
+                    throw formatToolActorFailure(address.value, message, toolParams, error);
+                }
                 result = {
                     invoked: true,
                     sent: true,

package/index.ts

@@ -174,7 +174,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       observedRuns,
       observedRunEventLines,
       summary,
-      transitions.map((transition) => transition.run),
+      transitions.map((transition) => transition.stateDir ?? transition.run),
     );
     for (const event of outboxEvents) {
       if (!Observability.shouldNotifyRunOutboxEvent(event)) continue;

package/lib/actor-rooms.ts

@@ -383,24 +383,86 @@ function updateRosterForMessage(
   return roster;
 }
 
-export function readBranchInboxMessages(
+export interface BranchInboxRecord extends ActorMessage {
+  id?: string;
+  queued_at?: string;
+  status?: string;
+}
+
+export interface BranchInboxReadResult {
+  corrupted: number;
+  messages: BranchInboxRecord[];
+}
+
+function readBranchInboxFile(
   stateDir: string,
   run: string,
   address: string,
   limit = 40,
-): Array<ActorMessage & { id?: string; queued_at?: string; status?: string }> {
+): BranchInboxReadResult {
   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 lines = readJsonlTailLines(branchInboxFile(stateDir, branch), limit);
+    const messages: BranchInboxRecord[] = [];
+    let corrupted = 0;
+    for (const line of lines) {
+      try {
+        messages.push(JSON.parse(line));
+      } catch {
+        corrupted += 1;
+      }
+    }
+    return { corrupted, messages };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { corrupted: 0, messages: [] };
+    throw error;
+  }
+}
+
+function readAllBranchInboxLines(
+  stateDir: string,
+  run: string,
+  address: string,
+): Array<{ raw: string } | { message: BranchInboxRecord }> {
+  const branch = branchIdFromAddress(address, run);
+  if (!branch) throw new Error(`Expected branch:${run}/<branch>; got ${address}`);
+  try {
+    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) as BranchInboxRecord };
+        } catch {
+          return { raw: line };
+        }
+      });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
     throw error;
   }
 }
 
+export function readBranchInboxMessages(
+  stateDir: string,
+  run: string,
+  address: string,
+  limit = 40,
+): BranchInboxRecord[] {
+  return readBranchInboxFile(stateDir, run, address, limit).messages;
+}
+
+export function readBranchInboxDiagnostics(
+  stateDir: string,
+  run: string,
+  address: string,
+  limit = 40,
+): BranchInboxReadResult {
+  return readBranchInboxFile(stateDir, run, address, limit);
+}
+
 export function getBranchInboxTerminalRetainLimit(): number {
   const value = Number(process.env.PI_ACTORS_BRANCH_INBOX_TERMINAL_RETAINED ?? "");
   return Number.isInteger(value) && value >= 0
@@ -458,17 +520,23 @@ export function updateBranchInboxMessageStatus(
   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;
   } finally {