@molecule/api-ai-tools 1.0.9 → 1.2.0

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"}

package/dist/schemas.js

@@ -24,16 +24,39 @@ export const TOOL_SCHEMAS = {
     },
     read_file: {
         name: 'read_file',
-        description: 'Read the full content of a file as text. Always read a file before editing it.',
+        description: 'Read the full content of one file, or of SEVERAL files in a single call. Always read a ' +
+            'file before editing it. When you need more than one file — surveying a project, ' +
+            'gathering the files behind one feature — pass them all as `paths` in ONE call rather ' +
+            'than calling this tool once per file: same content, a fraction of the time. ' +
+            'For a @molecule package\u2019s docs call read_molecule_doc instead — one call, the whole ' +
+            'document. A file under 80 KB comes back whole; do not page through it with offset/limit.',
         parameters: {
             type: 'object',
             properties: {
                 path: {
                     type: 'string',
-                    description: 'Path to the file to read (relative or absolute).',
+                    description: 'Path to a single file to read (relative or absolute).',
+                },
+                paths: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Paths to SEVERAL files to read in one call — preferred whenever you want more ' +
+                        'than one file. Returns `files`, one entry per path in the order given, each ' +
+                        "with that file's content or its own error.",
+                },
+                offset: {
+                    type: 'number',
+                    description: 'First line to return, 1-based. NEGATIVE counts from the end, so `offset: -30` ' +
+                        'is the last 30 lines. Use with `limit` to read PART of a large file instead of ' +
+                        'all of it — never pipe a file through head/tail in the shell.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'How many lines to return from `offset`. The result reports `offset`, `lines` ' +
+                        'and `totalLines` so you can ask for the next window.',
                 },
             },
-            required: ['path'],
+            required: [],
         },
     },
     write_file: {
@@ -104,6 +127,12 @@ export const TOOL_SCHEMAS = {
                     type: 'string',
                     description: "File glob pattern to filter files (e.g. '*.ts', '*.tsx'). Optional.",
                 },
+                contextLines: {
+                    type: 'number',
+                    description: 'Lines of surrounding context to return with each match, like `grep -C`. Each ' +
+                        'result carries `match: true` for the matching line and `false` for context. ' +
+                        'Use this instead of grepping through the shell.',
+                },
             },
             required: ['pattern'],
         },
@@ -174,7 +203,9 @@ export const TOOL_SCHEMAS = {
     },
     exec_command: {
         name: 'exec_command',
-        description: 'Run a shell command and return its output. Use for build checks, npm commands, verification, etc.',
+        description: 'Run a shell command and return its output. Use for build checks, npm commands, verification, etc. ' +
+            'Pass `run_in_background` for anything long-running: it returns a handle at once instead of ' +
+            'being cut off at the time limit.',
         parameters: {
             type: 'object',
             properties: {
@@ -186,10 +217,44 @@ export const TOOL_SCHEMAS = {
                     type: 'string',
                     description: 'Working directory. Defaults to project root.',
                 },
+                timeout: {
+                    type: 'number',
+                    description: "Optional time budget in milliseconds. Clamped to this tool's ceiling — ask for more and the ceiling applies and is reported, so split the work into smaller commands instead of re-running the same long one.",
+                },
+                run_in_background: {
+                    type: 'boolean',
+                    description: 'Start the command DETACHED and return immediately with a handle instead of waiting. ' +
+                        'Use it for anything that may outrun the ceiling — a full test suite, a production ' +
+                        'build, a long install. The result gives a log path to read with read_file and an ' +
+                        'exit-code file that appears when it finishes. Do the next piece of work while it ' +
+                        'runs; when you need its result, call wait_for_task (one call, no polling).',
+                },
             },
             required: ['command'],
         },
     },
+    wait_for_task: {
+        name: 'wait_for_task',
+        description: 'Wait for a command started with `run_in_background` and return its output and exit ' +
+            'code. Blocks until it finishes or the time budget runs out, then returns — one call, ' +
+            'no polling. Use it the moment you need that result to continue; never `sleep` and ' +
+            'read the log by hand. If it is still running when the budget ends, the result says so ' +
+            'and you can call it again.',
+        parameters: {
+            type: 'object',
+            properties: {
+                taskId: {
+                    type: 'string',
+                    description: 'The `taskId` the background command returned.',
+                },
+                timeout: {
+                    type: 'number',
+                    description: 'Optional time budget in milliseconds. Clamped to this tool’s ceiling.',
+                },
+            },
+            required: ['taskId'],
+        },
+    },
     save_plan: {
         name: 'save_plan',
         description: 'Save an implementation plan as a markdown file in .agents/plans/.',

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsBnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA2zBxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAY9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA+BnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA0tCxF"}