@molecule/api-ai-tools 1.0.9 → 1.1.0

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;AA6BnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CA8rCxF"}