@llblab/pi-actors 0.12.6 → 0.12.8

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.12.8: Usage Hint Documentation
+
+- `[Docs]` Documented runtime actor-tool argument usage hints in README and tool-registry docs, and covered missing template-value hints separately from typed value errors. Impact: users and agents can discover the self-correction behavior without reading tests.
+
+## 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.

package/README.md

@@ -361,6 +361,7 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - Tool args are derived from placeholders when `args` is omitted.
 - Typed arg declarations are progressive: `file:path`, `request_timeout:int=60000`, `speed:number=1.5`, `dry_run:bool=true`, `prompts:array`, and `mode:enum(check,fix)=check` can live in `args` or inline placeholders such as `{request_timeout:int=60000}`. They generate narrower tool schemas and runtime validation while existing untyped `args` and placeholders keep working.
 - `{arg=default}` inline defaults resolve after runtime values and stored `defaults`; `{arg??fallback}` handles empty/null fallback values; `{flag?--flag:}` ternaries map small truthy/falsy values to strings such as optional CLI flags.
+- Runtime actor-tool argument errors include a compact usage hint when typed normalization or template value resolution fails, including example call shape plus required and optional fields.
 - `template: [...]` sequences execute left to right; each successful step passes stdout to the next step on stdin.
 - Object nodes may set `parallel: true`; children receive the same stdin and joined stdout flows to the next sequence step.
 - Parallel nodes use soft-quorum semantics: failed branches are reported as degraded coverage unless failure propagation escalates to the root.

package/docs/tool-registry.md

@@ -149,6 +149,20 @@ Supported compact types are `string` (implicit), `path`, `int`, `number`, `bool`
 
 Defaults are applied before substitution, with resolution order runtime values → stored `defaults` → inline default → error. Missing required values are rejected before or during execution. Typed runtime values are normalized before substitution: `int` and `number` values become numeric strings, booleans become `true`/`false`, and enums must match one of the declared values.
 
+When typed normalization or template value resolution fails at runtime, the tool error includes a compact usage hint:
+
+```text
+Invalid arguments for tool "check_tool": Argument mode must be one of: check, fix.
+
+Expected call shape for check_tool:
+check_tool({
+  "file": "<file>",
+  "mode": "check"
+})
+Required: file
+Optional: mode
+```
+
 Template recipe tools derive public arguments from the referenced or co-located command template when the recipe is available locally. Explicit `args` is still available when the public tool surface should be narrower or defaulted differently, or when a file-backed recipe is not available during registration. Runtime values are passed as `values`; async recipe tools also accept optional `run_id` to override the generated run id.
 
 ## File Argument Naming

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.6",
+  "version": "0.12.8",
   "private": false,
   "description": "Actor runtime and orchestrator for agent-managed local processes",
   "type": "module",