@llblab/pi-actors 0.12.6 → 0.12.7

package/CHANGELOG.md

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

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