@llblab/pi-actors 0.12.5 → 0.12.7

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.12.7: Tool Argument Usage Hints
+
+- `[Tools]` Added compact usage hints to runtime actor-tool argument errors when typed normalization or placeholder resolution fails. Impact: if an agent supplies a wrong enum/type value or misses a required template value after schema validation, the error now shows the expected call shape with required and optional fields.
+
+## 0.12.6: Documentation Example Alignment
+
+- `[Docs]` Replaced remaining shader-ring recipe examples in registry and template-recipe docs with the concrete docs-review actor recipe example, aligned test fixtures, and changed async-run outbox docs to show actor message envelopes without public delivery knobs. Impact: public docs now consistently demonstrate useful actor wrapping and keep coordinator attention policy out of recipe-authored message examples.
+
 ## 0.12.5: README Actor Recipe Example
 
 - `[Docs]` Replaced the placeholder shader-ring onboarding recipe with a concrete async docs-review actor recipe that includes typed args, mailbox metadata, and a real launch template. Impact: README onboarding now demonstrates actor wrapping instead of an abstract placeholder.

package/docs/async-runs.md

@@ -188,22 +188,19 @@ Shape:
 
 ```json
 {
-  "event": "player.track",
+  "type": "player.track",
+  "to": "coordinator",
+  "from": "run:music-player",
   "summary": "Now playing: track.flac",
   "level": "info",
-  "delivery": "log",
   "ts": "2026-05-19T00:00:00.000Z",
-  "data": { "track": "/Music/track.flac", "index": 3, "count": 42 }
+  "body": { "track": "/Music/track.flac", "index": 3, "count": 42 }
 }
 ```
 
-`level` is `info`, `warning`, or `error`. `delivery` is `log`, `notify`, or `followup`:
+`level` is `info`, `warning`, or `error`. The public message describes sender, receiver, type, summary, and body; it does not choose notification mechanics. Runtime attention policy infers whether a coordinator-bound message stays available for explicit `inspect`, becomes a UI notification, or re-enters the launching coordinator as compact follow-up context.
 
-- `log`: stored only; read explicitly with `inspect view=events`.
-- `notify`: shown as a UI notification to the launching coordinator session.
-- `followup`: notification plus compact follow-up context to the launching coordinator session.
-
-Use `followup` for completion and decision-point messages that should reach the coordinator, not for every progress tick. Packaged multi-agent branch completion is a completion message and should bubble by default. Follow-up path lists use Markdown hierarchy: a section heading, `- Base: ...`, and `- Files: ...`, so repeated run-state prefixes do not flood agent context.
+Use coordinator-bound messages for completion and decision points, not for every progress tick. Packaged multi-agent branch completion is a completion message and should bubble by default. Follow-up path lists use Markdown hierarchy: a section heading, `- Base: ...`, and `- Files: ...`, so repeated run-state prefixes do not flood agent context.
 
 ## Cancellation And Ownership
 

package/docs/template-recipes.md

@@ -170,15 +170,15 @@ A registered tool can point at an actor recipe by storing the recipe path or nam
 
 ```json
 {
-  "shader_ring": {
-    "description": "Start the shader ring recipe",
-    "args": ["theme", "out_dir"],
-    "template": "shader-ring-8-parallel.json"
+  "docs_review": {
+    "description": "Start an async docs review actor",
+    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "template": "docs-review.json"
   }
 }
 ```
 
-If `shader-ring-8-parallel.json` contains `async: true`, calling `shader_ring` starts a detached run and returns metadata. If `async` is omitted or false, calling `shader_ring` executes the recipe foreground and returns normal tool output.
+If `docs-review.json` contains `async: true`, calling `docs_review` starts a detached actor run and returns metadata. If `async` is omitted or false, calling `docs_review` executes the recipe foreground and returns normal tool output.
 
 A registered tool may also co-locate an actor recipe directly in `actors-tools.json`:
 

package/docs/tool-registry.md

@@ -47,16 +47,16 @@ Use `update=true` to overwrite an existing tool. Omit `template` and co-located
 ]
 ```
 
-For reusable workflows, register a small tool whose `template` points to a template recipe instead of embedding a large parallel template in the tool itself:
+For reusable actor workflows, register a small tool whose `template` points to an actor recipe instead of embedding the launch graph in the tool itself:
 
 ```text
-register_tool name=shader_ring \
-  description="Start the shader ring recipe" \
-  template="shader-ring-8-parallel.json" \
-  args="theme,out_dir"
+register_tool name=docs_review \
+  description="Start an async docs review actor" \
+  template="docs-review.json" \
+  args="scope:path,model:string=openai-codex/gpt-5.5"
 ```
 
-This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/shader-ring-8-parallel.json` contains `async: true`, calling the tool starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/docs-review.json` contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
 When co-location is clearer than a separate file, the registry entry may include recipe fields directly beside tool metadata:
 
@@ -93,10 +93,10 @@ Tool names come from the top-level registry keys. Tool entries define `template`
     "description": "Run pi as a non-interactive sub-agent",
     "template": "pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
   },
-  "shader_ring": {
-    "description": "Start the shader ring recipe",
-    "args": ["theme", "out_dir"],
-    "template": "shader-ring-8-parallel.json"
+  "docs_review": {
+    "description": "Start an async docs review actor",
+    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
+    "template": "docs-review.json"
   }
 }
 ```

package/lib/tools.ts

@@ -68,6 +68,71 @@ function objectSchema(
   return { additionalProperties: false, properties, required, type: "object" };
 }
 
+function sampleValueForArg(
+  arg: string,
+  type: Schema.ToolArgType | undefined,
+  defaults: Record<string, unknown>,
+): unknown {
+  if (Object.hasOwn(defaults, arg)) return defaults[arg];
+  if (!type || type.kind === "string") return `<${arg}>`;
+  if (type.kind === "path") return `./${arg}`;
+  if (type.kind === "int") return 1;
+  if (type.kind === "number") return 1.5;
+  if (type.kind === "bool") return true;
+  if (type.kind === "array") return [`<${arg}>`];
+  return type.values[0] ?? `<${arg}>`;
+}
+
+function shouldAddRuntimeToolUsageHint(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    /^Argument \S+ must /.test(message) ||
+    /^Missing .* value: /.test(message)
+  );
+}
+
+function formatRuntimeToolUsageHint(
+  cfg: RegisteredTool,
+  required: string[],
+  includeRunId: boolean,
+): string {
+  const optional = cfg.args.filter((arg) => !required.includes(arg));
+  const example: Record<string, unknown> = {};
+  for (const arg of required)
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+  for (const arg of optional)
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+  if (includeRunId) example.run_id = `${cfg.name}-1`;
+  const lines = [
+    `Expected call shape for ${cfg.name}:`,
+    `${cfg.name}(${JSON.stringify(example, null, 2)})`,
+  ];
+  if (required.length) lines.push(`Required: ${required.join(", ")}`);
+  if (optional.length || includeRunId)
+    lines.push(
+      `Optional: ${[...optional, ...(includeRunId ? ["run_id"] : [])].join(", ")}`,
+    );
+  return lines.join("\n");
+}
+
+function formatRuntimeToolArgumentError(
+  cfg: RegisteredTool,
+  error: unknown,
+  required: string[],
+  includeRunId: boolean,
+): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  if (!shouldAddRuntimeToolUsageHint(error))
+    return error instanceof Error ? error : new Error(message);
+  return new Error(
+    `Invalid arguments for tool "${cfg.name}": ${message}\n\n${formatRuntimeToolUsageHint(
+      cfg,
+      required,
+      includeRunId,
+    )}`,
+  );
+}
+
 function looseObjectSchema(description: string): JsonSchema {
   return { additionalProperties: true, description, type: "object" };
 }
@@ -594,58 +659,62 @@ export function createRuntimeToolDefinition(
       _onUpdate: unknown,
       ctx: AsyncRunToolContext,
     ) {
-      if (isAsyncRecipe) {
-        const input = params as Record<string, unknown>;
-        const { run_id, ...values } = input;
-        const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
-        const runId =
-          typeof run_id === "string" && run_id.trim()
-            ? run_id.trim()
-            : `${cfg.name}-${Date.now()}`;
-        const meta = AsyncRuns.startRun(
-          {
-            ...base,
-            ownerId: getRunOwnerId(ctx),
-            run_id: runId,
-            tool: cfg.name,
-            values: Schema.normalizeRuntimeValues(
-              { ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values },
-              cfg.argTypes,
-            ),
-          },
-          ctx.cwd,
-        );
-        return {
-          content: [
-            { type: "text" as const, text: compactAsyncRunStatus(meta) },
-          ],
-          details: meta,
-        };
-      }
-      if (isRecipe && recipeTemplate) {
-        const paramsWithDefaults = {
-          ...(cfg.recipe?.values ?? {}),
-          ...cfg.defaults,
-          ...(params as Record<string, unknown>),
-        };
-        return Execution.executeRegisteredTool(
-          { ...cfg, template: recipeTemplate },
-          Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes),
+      try {
+        if (isAsyncRecipe) {
+          const input = params as Record<string, unknown>;
+          const { run_id, ...values } = input;
+          const base = cfg.recipe ? cfg.recipe : { file: String(cfg.template) };
+          const runId =
+            typeof run_id === "string" && run_id.trim()
+              ? run_id.trim()
+              : `${cfg.name}-${Date.now()}`;
+          const meta = AsyncRuns.startRun(
+            {
+              ...base,
+              ownerId: getRunOwnerId(ctx),
+              run_id: runId,
+              tool: cfg.name,
+              values: Schema.normalizeRuntimeValues(
+                { ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values },
+                cfg.argTypes,
+              ),
+            },
+            ctx.cwd,
+          );
+          return {
+            content: [
+              { type: "text" as const, text: compactAsyncRunStatus(meta) },
+            ],
+            details: meta,
+          };
+        }
+        if (isRecipe && recipeTemplate) {
+          const paramsWithDefaults = {
+            ...(cfg.recipe?.values ?? {}),
+            ...cfg.defaults,
+            ...(params as Record<string, unknown>),
+          };
+          return await Execution.executeRegisteredTool(
+            { ...cfg, template: recipeTemplate },
+            Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes),
+            exec,
+            ctx.cwd,
+            signal,
+          );
+        }
+        return await Execution.executeRegisteredTool(
+          cfg,
+          Schema.normalizeRuntimeValues(
+            params as Record<string, unknown>,
+            cfg.argTypes,
+          ),
           exec,
           ctx.cwd,
           signal,
         );
+      } catch (error) {
+        throw formatRuntimeToolArgumentError(cfg, error, required, isAsyncRecipe);
       }
-      return Execution.executeRegisteredTool(
-        cfg,
-        Schema.normalizeRuntimeValues(
-          params as Record<string, unknown>,
-          cfg.argTypes,
-        ),
-        exec,
-        ctx.cwd,
-        signal,
-      );
     },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.12.5",
+  "version": "0.12.7",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "type": "module",