@llblab/pi-actors 0.12.7 → 0.12.8

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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.

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/package.json

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