@llblab/pi-actors 0.22.2 → 0.22.4

package/lib/recipe-discovery.ts

@@ -8,9 +8,9 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 
+import * as CommandTemplates from "./command-templates.ts";
 import type { RegisteredTool } from "./config.ts";
 import type { TemplateRecipeConfig } from "./recipe-references.ts";
-import * as CommandTemplates from "./command-templates.ts";
 import * as RecipeReferences from "./recipe-references.ts";
 import * as Schema from "./schema.ts";
 
@@ -61,18 +61,28 @@ function assertToolSafeRepeatConfig(
   argTypes: Record<string, { kind: string }>,
   defaults: Record<string, unknown>,
 ): void {
-  if (typeof config === "string" || config === undefined || config === null) return;
+  if (typeof config === "string" || config === undefined || config === null)
+    return;
   if (Array.isArray(config)) {
-    for (const step of config) assertToolSafeRepeatConfig(step, argTypes, defaults);
+    for (const step of config)
+      assertToolSafeRepeatConfig(step, argTypes, defaults);
     return;
   }
   if (typeof config !== "object") return;
-  const node = config as { repeat?: unknown; template?: unknown; recover?: unknown };
+  const node = config as {
+    repeat?: unknown;
+    template?: unknown;
+    recover?: unknown;
+  };
   if (typeof node.repeat === "string") {
     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.",
         );
@@ -92,23 +102,30 @@ function listRecipeFiles(root: string): string[] {
         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: string,
   config: TemplateRecipeConfig | undefined,
 ): string[] {
-  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;
   return CommandTemplates.getCommandTemplateWarnings(
     commandTemplateConfig as CommandTemplates.CommandTemplateConfig,
-  ).map(
-    (warning) => `Recipe ${file}: ${warning}`,
-  );
+  ).map((warning) => `Recipe ${file}: ${warning}`);
 }
 
 function readDiscoveredRecipe(
@@ -158,13 +175,23 @@ function readDiscoveredRecipe(
   }
 }
 
-function filesForSource(
-  source: RecipeDiscoverySource,
-): Array<{ root: string; file: string; defaultTool: boolean; mutableUsage: boolean }> {
+function filesForSource(source: RecipeDiscoverySource): Array<{
+  root: string;
+  file: string;
+  defaultTool: boolean;
+  mutableUsage: boolean;
+}> {
   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!,
@@ -226,7 +253,9 @@ export function discoverRecipeSources(
     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];
@@ -262,14 +291,18 @@ export function discoverRecipes(roots: string[]): RecipeDiscoveryResult {
   return discoverRecipeSources(roots.map((root) => ({ root })));
 }
 
-function recipeUsage(config: TemplateRecipeConfig | undefined): Record<string, unknown> | undefined {
+function recipeUsage(
+  config: TemplateRecipeConfig | undefined,
+): Record<string, unknown> | undefined {
   const usage = (config as { usage?: unknown } | undefined)?.usage;
   return usage && typeof usage === "object" && !Array.isArray(usage)
     ? (usage as Record<string, unknown>)
     : undefined;
 }
 
-function cleanupRecommendation(entry: DiscoveredRecipe): Record<string, unknown> | undefined {
+function cleanupRecommendation(
+  entry: DiscoveredRecipe,
+): Record<string, unknown> | undefined {
   if (entry.invalid) {
     return {
       id: entry.id,
@@ -309,7 +342,13 @@ function cleanupRecommendation(entry: DiscoveredRecipe): Record<string, unknown>
       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) {
@@ -342,9 +381,78 @@ export function createRecipeIntegrityManifest(
         tool: entry.tool,
       };
     })
-    .sort(
-      (a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path),
+    .sort((a, b) => a.id.localeCompare(b.id) || a.path.localeCompare(b.path));
+}
+
+function diagnosticSeverity(message: string): "info" | "warning" | "error" {
+  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: string): string {
+  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: RecipeDiscoveryResult,
+): Array<Record<string, unknown>> {
+  const details: Array<Record<string, unknown>> = [];
+  const seen = new Set<string>();
+  const push = (message: string, entry?: DiscoveredRecipe): void => {
+    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 } as const;
+    return (
+      rank[a.severity as keyof typeof rank] -
+        rank[b.severity as keyof typeof rank] ||
+      String(a.message).localeCompare(String(b.message))
     );
+  });
 }
 
 function recommendationForEntry(
@@ -362,29 +470,49 @@ function recommendationForEntry(
   return recommendation;
 }
 
-export function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string, unknown> {
+export function summarizeDiscovery(
+  result: RecipeDiscoveryResult,
+): Record<string, unknown> {
   const recommendations = result.entries
-    .map((entry) => recommendationForEntry(entry, result.active.get(entry.id)?.path))
+    .map((entry) =>
+      recommendationForEntry(entry, result.active.get(entry.id)?.path),
+    )
     .filter((entry): entry is Record<string, unknown> => 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) => ({
-      id: entry.id,
-      path: entry.path,
-      description: entry.config?.description,
-      tool: entry.tool,
-      disabled: entry.disabled,
-      invalid: entry.invalid,
-      shadows: entry.shadows,
-      ...(recipeUsage(entry.config) ? { usage: recipeUsage(entry.config) } : {}),
-    })).sort((a, b) => a.id.localeCompare(b.id)),
+    active: [...result.active.values()]
+      .map((entry) => ({
+        id: entry.id,
+        path: entry.path,
+        description: entry.config?.description,
+        tool: entry.tool,
+        disabled: entry.disabled,
+        invalid: entry.invalid,
+        shadows: entry.shadows,
+        ...(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)
@@ -392,12 +520,16 @@ export function summarizeDiscovery(result: RecipeDiscoveryResult): Record<string
       .sort((a, b) => a.id.localeCompare(b.id)),
     recommendations,
     diagnostics: result.diagnostics,
+    diagnostic_details: diagnosticDetails(result),
     integrity_manifest: createRecipeIntegrityManifest(result),
   };
 }
 
-export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | undefined {
-  if (!entry.tool || entry.invalid || entry.disabled || !entry.config) return undefined;
+export function toRegisteredTool(
+  entry: DiscoveredRecipe,
+): RegisteredTool | undefined {
+  if (!entry.tool || entry.invalid || entry.disabled || !entry.config)
+    return undefined;
   const cfg = entry.config;
   const template = entry.path;
   const description = cfg.description ?? `Execute template recipe: ${entry.id}`;
@@ -407,7 +539,10 @@ export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | unde
       ? {
           ...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(
@@ -416,7 +551,11 @@ export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | unde
       return [parsed.arg, parsed.type];
     }),
   );
-  assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, cfg.defaults ?? {});
+  assertToolSafeRepeatConfig(
+    argTemplateConfig,
+    explicitArgTypes,
+    cfg.defaults ?? {},
+  );
   const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
   return {
     name: entry.id,
@@ -425,7 +564,10 @@ export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | unde
     recipe: cfg,
     args: Schema.getToolArgNames(argTemplateConfig),
     defaults: Object.fromEntries(
-      Object.entries(cfg.defaults ?? {}).map(([key, value]) => [key, String(value)]),
+      Object.entries(cfg.defaults ?? {}).map(([key, value]) => [
+        key,
+        String(value),
+      ]),
     ),
     ...(Object.keys(argTypes).length > 0 ? { argTypes } : {}),
     ...(entry.mutableUsage ? { sourcePath: entry.path } : {}),
@@ -433,7 +575,10 @@ export function toRegisteredTool(entry: DiscoveredRecipe): RegisteredTool | unde
     ...(cfg.defaults
       ? {
           storedDefaults: Object.fromEntries(
-            Object.entries(cfg.defaults).map(([key, value]) => [key, String(value)]),
+            Object.entries(cfg.defaults).map(([key, value]) => [
+              key,
+              String(value),
+            ]),
           ),
         }
       : {}),

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.2",
+  "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.2
+  version: 0.22.4
 ---
 
 # Actors (pi-actors)