@molecule/api-ai-tools 1.0.8 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-09-18T06:57:26.872Z
+Generated: 2026-09-22T18:02:23.461Z
 -->
 
 # @molecule/api-ai-tools
@@ -133,6 +133,50 @@ interface FileDiffEvent {
 }
 ```
 
+#### `GuardOptions`
+
+Options shared by {@link guardToolExecute} and {@link guardAITool}.
+
+```typescript
+interface GuardOptions {
+  /**
+   * Redactor applied to a THROWN error's message before it is returned to the
+   * model. Defaults to this package's `redactSecrets`.
+   */
+  redactError?: (message: string) => string
+}
+```
+
+#### `NormalizableSchema`
+
+The JSON-Schema-ish shape every tool in this package declares.
+
+```typescript
+interface NormalizableSchema {
+  name: string
+  parameters?: {
+    type?: string
+    properties?: Record<string, { type?: string; description?: string }>
+    required?: string[]
+  }
+}
+```
+
+#### `NormalizedInput`
+
+The result of normalizing one tool call's input.
+
+```typescript
+interface NormalizedInput {
+  /** The input to hand the handler, with aliases moved onto the declared names. */
+  input: Record<string, unknown>
+  /** Declared-required parameters still absent after aliasing. */
+  missing: string[]
+  /** `alias→declared` pairs that were moved, for logging. */
+  aliased: string[]
+}
+```
+
 #### `PromptContext`
 
 Context for building a composable system prompt.
@@ -355,6 +399,21 @@ function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): Execu
 
 **Returns:** A backend that proxies all filesystem calls into the sandbox.
 
+#### `declaredBudgetSeconds(command, timeoutParam)`
+
+The time budget a COMMAND declares for itself — a `timeout <seconds>` prefix
+anywhere in it, or the tool call's own `timeout` (ms) parameter, whichever is
+larger. Zero when it declares none.
+
+```typescript
+function declaredBudgetSeconds(command: string, timeoutParam: unknown): number
+```
+
+- `command` — The shell command.
+- `timeoutParam` — The tool call's `timeout` input, in milliseconds.
+
+**Returns:** The declared budget in seconds, or 0.
+
 #### `directoryReadHint(message, path)`
 
 Detect a "read/edit targeted a directory, not a file" failure from a backend
@@ -386,6 +445,50 @@ function discoverSkills(backend: ExecutionBackend): Promise<SkillEntry[]>
 
 **Returns:** Array of discovered skills with name, description, and path
 
+#### `guardAITool(tool)`
+
+Apply {@link guardToolExecute} to a ready-made tool object (the
+`@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
+execute }`), returning a copy whose `execute` is guarded.
+
+Use it at the point a consumer hands its full tool list to the model, so
+tools built outside this package get the same treatment as the ones built
+inside it.
+
+```typescript
+function guardAITool(tool: T, options?: GuardOptions): T
+```
+
+- `tool` — The tool to guard.
+
+**Returns:** A copy with a guarded `execute`.
+
+#### `guardToolExecute(schema, impl)`
+
+Wrap a tool handler so every call is normalized first and a handler that
+THROWS returns something the model can act on.
+
+The guard deliberately does NOT pre-empt the handler when a required
+parameter looks absent: several handlers accept a documented older shape
+(`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
+parameter with far better guidance than a generic message could (`edit_file`
+telling the model to re-read the file). It steps in only where the handler
+would otherwise crash — and when it does, a still-missing required parameter
+is the accurate diagnosis for that crash, so it is reported as one.
+
+```typescript
+function guardToolExecute(
+  schema: NormalizableSchema,
+  impl: (input: Record<string, unknown>, ...rest: never[]) => Promise<unknown>,
+  options?: GuardOptions,
+): (input: unknown, ...rest: never[]) => Promise<unknown>
+```
+
+- `schema` — The tool's declared schema.
+- `impl` — The raw handler.
+
+**Returns:** A handler with the same signature, guarded.
+
 #### `isEnvFilePath(path)`
 
 Whether a path is an env file, for which {@link redactSecrets}' full env-dump
@@ -422,6 +525,62 @@ function isValidGlob(pattern: string): boolean
 
 **Returns:** `true` when the pattern contains only allowed characters.
 
+#### `missingParamError(schema, input, missing)`
+
+The error a tool returns when a required parameter is still absent after
+aliasing. Model-facing, so it names the right parameter, what was actually
+sent, and the shape of a correct call — everything needed to fix it in one
+turn instead of concluding the tool is broken.
+
+```typescript
+function missingParamError(
+  schema: NormalizableSchema,
+  input: Record<string, unknown>,
+  missing: string[],
+): string
+```
+
+- `schema` — The tool's declared schema.
+- `input` — The normalized input (used to list the keys that were sent).
+- `missing` — The required parameters still absent.
+
+**Returns:** A single-sentence-per-clause error string.
+
+#### `normalizeToolInput(schema, raw)`
+
+Move known aliases onto the declared parameter names and report what is still
+missing. Unknown keys are left in place — handlers ignore them, and dropping
+them would hide a model's intent from anything reading the call log.
+
+```typescript
+function normalizeToolInput(schema: NormalizableSchema, raw: unknown): NormalizedInput
+```
+
+- `schema` — The tool's declared schema.
+- `raw` — Whatever the model sent as the tool input.
+
+**Returns:** The normalized input plus the missing-required and aliased lists.
+
+#### `outputIsWithheldUntilExit(command)`
+
+Whether a command's output reaches the tool only when the whole pipeline
+ends — a pipe into `tail`, `grep`, `sort`, `wc` and friends, which
+block-buffer when stdout is not a terminal.
+
+It matters only in combination with an overrun: a command stopped at the
+tool's ceiling normally hands back everything it printed, but behind one of
+these it printed nothing, so the whole budget is spent for no information.
+Measured across six real agent runs: ten such commands, every one of them
+piped, 49 minutes returning a few hundred bytes each.
+
+```typescript
+function outputIsWithheldUntilExit(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when a kill would return no useful output.
+
 #### `pathArgError(path, tool)`
 
 Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -512,6 +671,28 @@ function shellQuote(s: string): string
 
 **Returns:** A single-quoted shell literal representing `s`.
 
+#### `sliceLines(content, window)`
+
+Return a line window of `content`, or null when no window was asked for.
+
+`read_file` returned whole files only, so an executor that wanted part of one
+shelled out: across six real agent runs, 260 of 377 shell-inspection commands
+(69%) were `head`/`tail`/`sed -n` windowing a file the tool could have
+windowed itself. `offset` is 1-based, matching the line numbers every other
+tool reports and what `grep -n` prints.
+
+```typescript
+function sliceLines(
+  content: string,
+  window?: { offset?: unknown; limit?: unknown },
+): { text: string; offset: number; lines: number; totalLines: number; truncated: boolean } | null
+```
+
+- `content` — The file's full text.
+- `window` — The requested `offset` (1-based) and `limit` (line count).
+
+**Returns:** The window plus its position, or null when neither was given.
+
 #### `stripControlChars(s)`
 
 Strip C0 control chars (except tab, newline, CR) that break PostgreSQL JSONB
@@ -614,6 +795,25 @@ const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
 ]
 ```
 
+#### `MAX_BATCH_READ_BYTES`
+
+Total content bytes one batched `read_file` call returns, across all files.
+The per-file {@link MAX_READ_SIZE} still applies to each one.
+
+```typescript
+const MAX_BATCH_READ_BYTES: number
+```
+
+#### `MAX_BATCH_READ_FILES`
+
+Most files one batched `read_file` call returns. The cap exists so a survey
+of a large tree cannot swallow the turn's context in one result; the tool
+reports where it stopped so the model continues from there.
+
+```typescript
+const MAX_BATCH_READ_FILES: 25
+```
+
 #### `MAX_FIND_RESULTS`
 
 Max find results.
@@ -630,6 +830,23 @@ Max command output size (100KB per stream).
 const MAX_OUTPUT_SIZE: number
 ```
 
+#### `MAX_READ_RETURN_CHARS`
+
+The most one read_file call returns for ONE file when no window was asked
+for, in chars. Larger files come back as their first window with a note
+saying how to read the rest.
+
+MAX_READ_SIZE (5 MB) is a bound on what the tool will open, not on what it
+should hand a model: a single batched read that returned a 1.2 MB README
+put the next three provider calls at 366k tokens (~330k of them fresh)
+against a 120k-token context cap (X0 run x5, call 26). ~80 KB is ~20–25k
+tokens — a fifth of that cap, and more than any one file read usually
+needs.
+
+```typescript
+const MAX_READ_RETURN_CHARS: number
+```
+
 #### `MAX_READ_SIZE`
 
 Max file size for read_file (5MB).
@@ -638,6 +855,16 @@ Max file size for read_file (5MB).
 const MAX_READ_SIZE: number
 ```
 
+#### `MAX_SEARCH_CONTEXT_LINES`
+
+Most lines of surrounding context `search_files` will return per match.
+Bounded so a broad pattern with a generous context cannot pull a whole tree
+into one reply.
+
+```typescript
+const MAX_SEARCH_CONTEXT_LINES: 40
+```
+
 #### `MAX_SEARCH_RESULTS`
 
 Max search results.
@@ -685,6 +912,19 @@ Peer dependencies:
   rules via `blockCommand` (return an actionable error string to refuse — it is
   shown to the model verbatim) and enable `blockDangerousCommands` (default
   FALSE) where appropriate.
+- **`read_file` takes `paths` as well as `path`.** An agent that issues one
+  tool call per model round-trip pays a full round-trip per file, so a project
+  survey costs minutes; batched, the same reads cost one call each 25 files
+  (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
+  stopped). Each entry carries its own content or its own error, so one bad
+  path never fails the batch.
+- **A parameter under another name is not a broken tool.** Every tool's input
+  is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
+  snake_case), and a handler that throws returns an error naming the missing
+  parameter rather than a bare internal message — which a weak executor reads
+  as a broken tool and routes around, taking its verification with it. Use
+  `guardAITool` to give tools built elsewhere the same treatment, passing
+  `redactError` so a thrown message is masked by your own redactor.
 - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
   should not receive `write_file`/`exec_command`.
 - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches

package/dist/index.d.ts

@@ -23,6 +23,19 @@
  *   rules via `blockCommand` (return an actionable error string to refuse — it is
  *   shown to the model verbatim) and enable `blockDangerousCommands` (default
  *   FALSE) where appropriate.
+ * - **`read_file` takes `paths` as well as `path`.** An agent that issues one
+ *   tool call per model round-trip pays a full round-trip per file, so a project
+ *   survey costs minutes; batched, the same reads cost one call each 25 files
+ *   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
+ *   stopped). Each entry carries its own content or its own error, so one bad
+ *   path never fails the batch.
+ * - **A parameter under another name is not a broken tool.** Every tool's input
+ *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
+ *   snake_case), and a handler that throws returns an error naming the missing
+ *   parameter rather than a bare internal message — which a weak executor reads
+ *   as a broken tool and routes around, taking its verification with it. Use
+ *   `guardAITool` to give tools built elsewhere the same treatment, passing
+ *   `redactError` so a thrown message is masked by your own redactor.
  * - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
  *   should not receive `write_file`/`exec_command`.
  * - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches
@@ -85,6 +98,7 @@
 export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
+export * from './input-normalizer.js';
 export * from './schemas.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -23,6 +23,19 @@
  *   rules via `blockCommand` (return an actionable error string to refuse — it is
  *   shown to the model verbatim) and enable `blockDangerousCommands` (default
  *   FALSE) where appropriate.
+ * - **`read_file` takes `paths` as well as `path`.** An agent that issues one
+ *   tool call per model round-trip pays a full round-trip per file, so a project
+ *   survey costs minutes; batched, the same reads cost one call each 25 files
+ *   (`MAX_BATCH_READ_FILES` / `MAX_BATCH_READ_BYTES`, which report where they
+ *   stopped). Each entry carries its own content or its own error, so one bad
+ *   path never fails the batch.
+ * - **A parameter under another name is not a broken tool.** Every tool's input
+ *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
+ *   snake_case), and a handler that throws returns an error naming the missing
+ *   parameter rather than a bare internal message — which a weak executor reads
+ *   as a broken tool and routes around, taking its verification with it. Use
+ *   `guardAITool` to give tools built elsewhere the same treatment, passing
+ *   `redactError` so a thrown message is masked by your own redactor.
  * - **Scope the tool set per agent** with `include`/`exclude` — a read-only agent
  *   should not receive `write_file`/`exec_command`.
  * - Outputs are size-capped (`MAX_READ_SIZE`, `MAX_OUTPUT_SIZE`, …) and searches
@@ -85,6 +98,7 @@
 export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
+export * from './input-normalizer.js';
 export * from './schemas.js';
 export * from './system-prompt.js';
 export * from './tools.js';

package/dist/input-normalizer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Tool-input normalization: accept the parameter names a weak executor
+ * actually sends, and never let a missing one reach a handler as `undefined`.
+ *
+ * @module
+ */
+/** The JSON-Schema-ish shape every tool in this package declares. */
+export interface NormalizableSchema {
+    name: string;
+    parameters?: {
+        type?: string;
+        properties?: Record<string, {
+            type?: string;
+            description?: string;
+        }>;
+        required?: string[];
+    };
+}
+/** The result of normalizing one tool call's input. */
+export interface NormalizedInput {
+    /** The input to hand the handler, with aliases moved onto the declared names. */
+    input: Record<string, unknown>;
+    /** Declared-required parameters still absent after aliasing. */
+    missing: string[];
+    /** `alias→declared` pairs that were moved, for logging. */
+    aliased: string[];
+}
+/** Options shared by {@link guardToolExecute} and {@link guardAITool}. */
+export interface GuardOptions {
+    /**
+     * Redactor applied to a THROWN error's message before it is returned to the
+     * model. Defaults to this package's `redactSecrets`.
+     */
+    redactError?: (message: string) => string;
+}
+/**
+ * Move known aliases onto the declared parameter names and report what is still
+ * missing. Unknown keys are left in place — handlers ignore them, and dropping
+ * them would hide a model's intent from anything reading the call log.
+ *
+ * @param schema - The tool's declared schema.
+ * @param raw - Whatever the model sent as the tool input.
+ * @returns The normalized input plus the missing-required and aliased lists.
+ */
+export declare function normalizeToolInput(schema: NormalizableSchema, raw: unknown): NormalizedInput;
+/**
+ * The error a tool returns when a required parameter is still absent after
+ * aliasing. Model-facing, so it names the right parameter, what was actually
+ * sent, and the shape of a correct call — everything needed to fix it in one
+ * turn instead of concluding the tool is broken.
+ *
+ * @param schema - The tool's declared schema.
+ * @param input - The normalized input (used to list the keys that were sent).
+ * @param missing - The required parameters still absent.
+ * @returns A single-sentence-per-clause error string.
+ */
+export declare function missingParamError(schema: NormalizableSchema, input: Record<string, unknown>, missing: string[]): string;
+/**
+ * Wrap a tool handler so every call is normalized first and a handler that
+ * THROWS returns something the model can act on.
+ *
+ * The guard deliberately does NOT pre-empt the handler when a required
+ * parameter looks absent: several handlers accept a documented older shape
+ * (`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
+ * parameter with far better guidance than a generic message could (`edit_file`
+ * telling the model to re-read the file). It steps in only where the handler
+ * would otherwise crash — and when it does, a still-missing required parameter
+ * is the accurate diagnosis for that crash, so it is reported as one.
+ *
+ * @param schema - The tool's declared schema.
+ * @param impl - The raw handler.
+ * @returns A handler with the same signature, guarded.
+ */
+export declare function guardToolExecute(schema: NormalizableSchema, impl: (input: Record<string, unknown>, ...rest: never[]) => Promise<unknown>, options?: GuardOptions): (input: unknown, ...rest: never[]) => Promise<unknown>;
+/**
+ * Apply {@link guardToolExecute} to a ready-made tool object (the
+ * `@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
+ * execute }`), returning a copy whose `execute` is guarded.
+ *
+ * Use it at the point a consumer hands its full tool list to the model, so
+ * tools built outside this package get the same treatment as the ones built
+ * inside it.
+ *
+ * @param tool - The tool to guard.
+ * @returns A copy with a guarded `execute`.
+ */
+export declare function guardAITool<T extends {
+    name: string;
+    parameters?: unknown;
+    execute: (input: unknown, ...rest: never[]) => Promise<unknown>;
+}>(tool: T, options?: GuardOptions): T;
+//# sourceMappingURL=input-normalizer.d.ts.map

package/dist/input-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-normalizer.d.ts","sourceRoot":"","sources":["../src/input-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;QACpE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,CAAA;CACF;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,gEAAgE;IAChE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAiDD,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,OAAO,GAAG,eAAe,CAiD5F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAaR;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,EAC5E,OAAO,GAAE,YAAiB,GACzB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAsBxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,CAAC,SAAS;IACR,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAChE,EACD,IAAI,EAAE,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,CAAC,CAaxC"}

package/dist/input-normalizer.js

@@ -0,0 +1,191 @@
+/**
+ * Tool-input normalization: accept the parameter names a weak executor
+ * actually sends, and never let a missing one reach a handler as `undefined`.
+ *
+ * @module
+ */
+import { redactSecrets } from './utilities.js';
+/**
+ * Other names a model sends for a declared parameter, most likely first.
+ *
+ * Every entry here is a name a real run actually produced or a direct synonym
+ * of one. `cmd` is the one that cost the most: `exec_command` read only
+ * `input.command`, so a call sent as `{ cmd, timeout }` reached
+ * `checkBlockedCommand(undefined)` and died with `Cannot read properties of
+ * undefined (reading 'match')` — an internal TypeError, not a usable error. The
+ * executor read that as "the shell tool is failing consistently now", stopped
+ * verifying, and ended the turn reporting "All checks pass" while seven
+ * acceptance checks failed (X0 rehearsal 83).
+ */
+const PARAM_ALIASES = {
+    command: ['cmd', 'shell', 'script', 'bash', 'commandLine', 'command_line', 'run'],
+    path: ['file', 'filePath', 'file_path', 'filename', 'file_name', 'filepath', 'target'],
+    content: [
+        'contents',
+        'body',
+        'text',
+        'data',
+        'source',
+        'markdown',
+        'fileContent',
+        'file_content',
+    ],
+    pattern: ['query', 'regex', 'search', 'searchPattern', 'search_pattern', 'text'],
+    old_path: ['from', 'src', 'source', 'sourcePath', 'source_path', 'oldPath', 'old'],
+    new_path: ['to', 'dest', 'destination', 'destinationPath', 'destination_path', 'newPath', 'new'],
+    name: ['skill', 'skillName', 'skill_name', 'title', 'planName', 'plan_name'],
+    cwd: ['dir', 'directory', 'workdir', 'workingDirectory', 'working_directory'],
+    include: ['glob', 'filePattern', 'file_pattern'],
+};
+/** `old_path` ⇄ `oldPath`, so a casing slip is never a missing parameter. */
+function caseVariants(key) {
+    const camel = key.replace(/_([a-z])/g, (_m, c) => c.toUpperCase());
+    const snake = key.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+    return [camel, snake].filter((v) => v !== key);
+}
+/** Present means the key is there with a value that is not null/undefined. */
+function present(obj, key) {
+    return Object.hasOwn(obj, key) && obj[key] !== undefined && obj[key] !== null;
+}
+const warned = new Set();
+/**
+ * Move known aliases onto the declared parameter names and report what is still
+ * missing. Unknown keys are left in place — handlers ignore them, and dropping
+ * them would hide a model's intent from anything reading the call log.
+ *
+ * @param schema - The tool's declared schema.
+ * @param raw - Whatever the model sent as the tool input.
+ * @returns The normalized input plus the missing-required and aliased lists.
+ */
+export function normalizeToolInput(schema, raw) {
+    const input = typeof raw === 'object' && raw !== null && !Array.isArray(raw)
+        ? { ...raw }
+        : {};
+    const properties = schema.parameters?.properties ?? {};
+    const declared = Object.keys(properties);
+    const declaredSet = new Set(declared);
+    const aliased = [];
+    for (const key of declared) {
+        if (present(input, key))
+            continue;
+        const candidates = [...caseVariants(key), ...(PARAM_ALIASES[key] ?? [])];
+        for (const alias of candidates) {
+            // Never steal a name this same schema declares — `path` on rename_file
+            // would be ambiguous between old_path and new_path, so it stays unread.
+            if (declaredSet.has(alias))
+                continue;
+            if (!present(input, alias))
+                continue;
+            input[key] = input[alias];
+            aliased.push(`${alias}→${key}`);
+            break;
+        }
+    }
+    // A declared string that arrived as a number/boolean is stringified rather
+    // than handed to a handler that will call .match()/.split() on it.
+    for (const key of declared) {
+        if (properties[key]?.type !== 'string')
+            continue;
+        const value = input[key];
+        if (typeof value === 'number' || typeof value === 'boolean')
+            input[key] = String(value);
+    }
+    const required = schema.parameters?.required ?? [];
+    const missing = required.filter((key) => {
+        if (!present(input, key))
+            return true;
+        const value = input[key];
+        return typeof value === 'string' && value.trim() === '' && key !== 'content';
+    });
+    if (aliased.length > 0) {
+        const signature = `${schema.name}:${aliased.join(',')}`;
+        if (!warned.has(signature)) {
+            warned.add(signature);
+            console.warn(`[ai-tools] ${schema.name} input normalized (${aliased.join(', ')})`);
+        }
+    }
+    return { input, missing, aliased };
+}
+/**
+ * The error a tool returns when a required parameter is still absent after
+ * aliasing. Model-facing, so it names the right parameter, what was actually
+ * sent, and the shape of a correct call — everything needed to fix it in one
+ * turn instead of concluding the tool is broken.
+ *
+ * @param schema - The tool's declared schema.
+ * @param input - The normalized input (used to list the keys that were sent).
+ * @param missing - The required parameters still absent.
+ * @returns A single-sentence-per-clause error string.
+ */
+export function missingParamError(schema, input, missing) {
+    const properties = schema.parameters?.properties ?? {};
+    const sent = Object.keys(input);
+    const names = missing.map((k) => `"${k}"`).join(', ');
+    const example = Object.fromEntries((schema.parameters?.required ?? []).map((k) => [k, `<${properties[k]?.type ?? 'value'}>`]));
+    return (`${schema.name} needs ${missing.length === 1 ? 'the parameter' : 'the parameters'} ${names}. ` +
+        (sent.length > 0 ? `You sent: ${sent.join(', ')}. ` : 'You sent no parameters. ') +
+        `Call it as ${JSON.stringify(example)}. This is a parameter-name problem, not a broken tool — ` +
+        'retry the same call with the names above.');
+}
+/**
+ * Wrap a tool handler so every call is normalized first and a handler that
+ * THROWS returns something the model can act on.
+ *
+ * The guard deliberately does NOT pre-empt the handler when a required
+ * parameter looks absent: several handlers accept a documented older shape
+ * (`edit_file`'s top-level `old_string`/`new_string`) or answer a missing
+ * parameter with far better guidance than a generic message could (`edit_file`
+ * telling the model to re-read the file). It steps in only where the handler
+ * would otherwise crash — and when it does, a still-missing required parameter
+ * is the accurate diagnosis for that crash, so it is reported as one.
+ *
+ * @param schema - The tool's declared schema.
+ * @param impl - The raw handler.
+ * @returns A handler with the same signature, guarded.
+ */
+export function guardToolExecute(schema, impl, options = {}) {
+    // A thrown message is untrusted text (a connection string in a driver error,
+    // a key echoed by a failing command). The guard turns a throw into a RETURNED
+    // result, which leaves the consumer's thrown-error redaction path unused — so
+    // the message is redacted here, before it can reach the model, the SSE stream
+    // or the stored transcript. Defaults to this package's name-keyword redactor;
+    // pass a stronger one where the consumer has it.
+    const redactError = options.redactError ?? redactSecrets;
+    return async (raw, ...rest) => {
+        const { input, missing } = normalizeToolInput(schema, raw);
+        try {
+            return await impl(input, ...rest);
+        }
+        catch (e) {
+            if (missing.length > 0)
+                return { error: missingParamError(schema, input, missing) };
+            const message = redactError(e instanceof Error ? e.message : String(e));
+            return {
+                error: `${schema.name} failed: ${message}. Parameters sent: ${Object.keys(input).join(', ') || '(none)'}. ` +
+                    `This tool expects ${JSON.stringify(schema.parameters?.required ?? [])} — check them and retry.`,
+            };
+        }
+    };
+}
+/**
+ * Apply {@link guardToolExecute} to a ready-made tool object (the
+ * `@molecule/api-ai` `AITool` shape: `{ name, description, parameters,
+ * execute }`), returning a copy whose `execute` is guarded.
+ *
+ * Use it at the point a consumer hands its full tool list to the model, so
+ * tools built outside this package get the same treatment as the ones built
+ * inside it.
+ *
+ * @param tool - The tool to guard.
+ * @returns A copy with a guarded `execute`.
+ */
+export function guardAITool(tool, options = {}) {
+    const schema = {
+        name: tool.name,
+        parameters: tool.parameters,
+    };
+    return {
+        ...tool,
+        execute: guardToolExecute(schema, tool.execute, options),
+    };
+}

package/dist/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CA2O1C,CAAA"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAqT1C,CAAA"}