@llblab/pi-actors 0.22.3 → 0.22.4

package/lib/recipe-references.ts

@@ -109,7 +109,12 @@ export function resolveRecipePath(
 
 function isBareRecipeName(value: string): boolean {
   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: string): string[] {
@@ -118,8 +123,12 @@ function recipeNameFiles(value: string): string[] {
   return [`${trimmed}.json`, `${trimmed}.md`];
 }
 
-function resolveRecipeImportPath(value: string, currentRecipeRoot: string): string {
-  if (!isBareRecipeName(value)) return resolveRecipePath(value, currentRecipeRoot);
+function resolveRecipeImportPath(
+  value: string,
+  currentRecipeRoot: string,
+): string {
+  if (!isBareRecipeName(value))
+    return resolveRecipePath(value, currentRecipeRoot);
   const roots = [
     Paths.getRecipeRoot(),
     currentRecipeRoot,
@@ -266,11 +275,15 @@ function parseMarkdownFrontmatterObject(
   lines: string[],
 ): Record<string, unknown> | unknown[] {
   if (lines.every((line) => /^\s*-\s+/.test(line))) {
-    return lines.map((line) => parseMarkdownScalar(line.replace(/^\s*-\s+/, "")));
+    return lines.map((line) =>
+      parseMarkdownScalar(line.replace(/^\s*-\s+/, "")),
+    );
   }
   const result: Record<string, unknown> = {};
   for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(/^\s{2}([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/);
+    const match = lines[index].match(
+      /^\s{2}([A-Za-z_][A-Za-z0-9_.-]*):\s*(.*)$/,
+    );
     if (!match) continue;
     if (match[2]) {
       result[match[1]] = parseMarkdownScalar(match[2]);
@@ -331,11 +344,14 @@ function parseMarkdownRecipeConfig(
 ): Record<string, unknown> | undefined {
   const lines = content.split(/\r?\n/);
   if (lines[0]?.trim() !== "---") return undefined;
-  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  const end = lines.findIndex(
+    (line, index) => index > 0 && line.trim() === "---",
+  );
   if (end === -1) return undefined;
   const frontmatter = parseMarkdownFrontmatter(lines.slice(1, end).join("\n"));
   const fence = findMarkdownRecipeFence(lines.slice(end + 1).join("\n"));
-  if (!fence) return Object.hasOwn(frontmatter, "template") ? frontmatter : undefined;
+  if (!fence)
+    return Object.hasOwn(frontmatter, "template") ? frontmatter : undefined;
   const text = fence.body.trim();
   if (!text) return undefined;
   if (
@@ -351,12 +367,50 @@ function parseMarkdownRecipeConfig(
         return { ...frontmatter, ...parsed };
       return { ...frontmatter, template: parsed };
     } catch {
-      if (fence.info.includes("json") || fence.info.includes("recipe")) return undefined;
+      if (fence.info.includes("json") || fence.info.includes("recipe"))
+        return undefined;
     }
   }
   return { ...frontmatter, template: text };
 }
 
+export function diagnoseRawRecipeConfigFailure(
+  path: string,
+): string | undefined {
+  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) as unknown;
+    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: string,
 ): Record<string, unknown> | undefined {
@@ -593,7 +647,8 @@ function expandImportNodes(
   if (typeof value === "string") return value;
   if (Array.isArray(value)) {
     return value.map(
-      (item) => expandImportNodes(item, imports, options) as CommandTemplateConfig,
+      (item) =>
+        expandImportNodes(item, imports, options) as CommandTemplateConfig,
     );
   }
   const record = value as Record<string, unknown>;
@@ -614,7 +669,11 @@ function expandImportNodes(
       nodeDefaults,
       nodeValues,
     );
-    const expanded = applyDefaultsToTemplate(imported.config.template, defaults, record);
+    const expanded = applyDefaultsToTemplate(
+      imported.config.template,
+      defaults,
+      record,
+    );
     return options.includeActorRecipeContext
       ? withActorRecipeContext(expanded, {
           alias: imported.alias,
@@ -672,8 +731,15 @@ export function readResolvedRecipeConfig(
   if (!raw || !Object.hasOwn(raw, "template")) return undefined;
   const imports: Record<string, ImportedRecipe> = {};
   for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
-    const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
-    const config = readResolvedRecipeConfig(importPath, [...stack, path], options);
+    const importPath = resolveRecipeImportPath(
+      getImportFrom(binding),
+      dirname(path),
+    );
+    const config = readResolvedRecipeConfig(
+      importPath,
+      [...stack, path],
+      options,
+    );
     if (!config) throw new Error(`Recipe import not found: ${alias}`);
     const bindingDefaults =
       typeof binding === "string" ? undefined : binding.defaults;
@@ -836,8 +902,16 @@ function collectRecipeContextRecords(
   };
   const imports = getRecipeImports(raw);
   const children = Object.entries(imports).flatMap(([childAlias, binding]) => {
-    const importFile = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
-    return collectRecipeContextRecords(importFile, [...stack, path], [...importPath, childAlias], childAlias);
+    const importFile = resolveRecipeImportPath(
+      getImportFrom(binding),
+      dirname(path),
+    );
+    return collectRecipeContextRecords(
+      importFile,
+      [...stack, path],
+      [...importPath, childAlias],
+      childAlias,
+    );
   });
   return [record, ...children];
 }

package/lib/registry.ts

@@ -161,8 +161,14 @@ function getInputTemplate(
       );
     return value;
   }
+  if (value && typeof value === "object") {
+    CommandTemplates.expandCommandTemplateConfigs(
+      value as CommandTemplates.CommandTemplateConfig,
+    );
+    return value as CommandTemplates.CommandTemplateConfig;
+  }
   throw new Error(
-    Output.formatToolText("Tool template must be a string or sequence."),
+    Output.formatToolText("Tool template must be a string, object, or sequence."),
   );
 }
 

package/lib/tools.ts

@@ -436,6 +436,7 @@ export function createRegisterToolDefinition<TContext>(
         ),
         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),
         ]),
@@ -485,6 +486,27 @@ function messageBodyToToolParams(
   return { input: message.body };
 }
 
+function formatToolActorFailure(
+  tool: string,
+  message: ActorMessages.ActorMessage,
+  params: Record<string, unknown>,
+  error: unknown,
+): 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: string | undefined,
 ): string | undefined {
@@ -915,24 +937,25 @@ export function createInspectToolDefinition<TContext = unknown>(
       if (address.kind === "branch") {
         if (view !== "mailbox") throw new Error("inspect branch:<run>/<branch> supports view=mailbox.");
         const status = assertRunAccessibleToContext(runId, ctx);
-        const messages = ActorRooms.readBranchInboxMessages(
+        const branchInbox = ActorRooms.readBranchInboxDiagnostics(
           String(status.state_dir ?? ""),
           runId,
           target,
           Number(input.lines || 40),
         );
+        const messages = branchInbox.messages;
         return {
           content: [
             {
               type: "text" as const,
               text: maybeJsonText(
-                messages,
+                input.verbose === true ? branchInbox : messages,
                 input.verbose === true,
-                compactBranchInbox(messages.map((message) => ({ ...message }))),
+                `${compactBranchInbox(messages.map((message) => ({ ...message })))}${branchInbox.corrupted > 0 ? `\ncorrupted=${branchInbox.corrupted}` : ""}`,
               ),
             },
           ],
-          details: { messages },
+          details: { corrupted: branchInbox.corrupted, messages },
         };
       }
       switch (view) {
@@ -1118,9 +1141,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
       } else if (address.kind === "branch" && address.value) {
         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: string) => {
@@ -1159,7 +1180,7 @@ export function createActorMessageToolDefinition<TContext = unknown>(
       } 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.`);
         const recipients = getRoomMulticastRecipients(message, runId);
@@ -1185,13 +1206,19 @@ export function createActorMessageToolDefinition<TContext = unknown>(
             `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: unknown;
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [

package/skills/actors/SKILL.md

@@ -2,7 +2,7 @@
 name: actors
 description: Highest-density practical guide for pi-actors. Read this skill whenever prompt and tools are not enough for spawn, message, inspect, actor runs, tools, recipes, command templates, async lifecycle, mailboxes, artifacts, and local orchestration mechanics.
 metadata:
-  version: 0.22.3
+  version: 0.22.4
 ---
 
 # Actors (pi-actors)

package/skills/swarm/SKILL.md

@@ -2,7 +2,7 @@
 name: swarm
 description: Subagent orchestration with scoped locks and quorum consensus. Use for multi-model review, parallel scoped work, delegated audit, and coordinated subagent execution.
 metadata:
-  version: 0.22.3
+  version: 0.22.4
 ---
 
 # Swarm