@compilr-dev/agents 0.3.15 → 0.3.17

package/LICENSE

@@ -0,0 +1,108 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Abbreviation: FSL-1.1-MIT
+
+Notice
+
+Copyright 2026 Carmelo Scozzola
+
+Terms and Conditions
+
+Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -13,7 +13,7 @@
 > Lightweight multi-LLM agent library for building CLI AI assistants
 
 [![npm version](https://img.shields.io/npm/v/@compilr-dev/agents.svg)](https://www.npmjs.com/package/@compilr-dev/agents)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
 
 > [!WARNING]
 > This package is in beta. APIs may change between minor versions.
@@ -1314,7 +1314,7 @@ const agent = new Agent({ provider, tracing });
 
 ## License
 
-MIT - See [LICENSE](LICENSE) for details.
+[FSL-1.1-MIT](https://fsl.software/) - See [LICENSE](LICENSE) for details. Converts to MIT after 2 years per version.
 
 ---
 

package/dist/episodes/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Work history tracking with effort estimation.
  */
-export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, EpisodeStore, } from './types.js';
+export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, WorkAtRisk, EpisodeStore, } from './types.js';
 export { estimateEffort, DEFAULT_WEIGHTS, EFFORT_ORDER } from './effort.js';

package/dist/episodes/types.d.ts

@@ -127,6 +127,20 @@ export interface ProjectWorkSummary {
     /** Episodes since the last git commit */
     uncommittedWork: WorkEpisode[];
 }
+/**
+ * Summary of work that would be at risk from a destructive operation.
+ * Used by guardrails and rehearsal to warn agents before they destroy work.
+ */
+export interface WorkAtRisk {
+    /** Episodes involving the affected files */
+    episodes: WorkEpisode[];
+    /** Maximum effort across at-risk episodes */
+    totalEffort: Effort;
+    /** Agents who did the work (e.g., ['default (abc123)', 'backend (xyz999)']) */
+    agentAttribution: string[];
+    /** Human-readable warning message */
+    warningMessage: string;
+}
 /**
  * Persistence interface for work episodes.
  * Write methods may be async (for file I/O), read methods are synchronous

package/dist/index.d.ts

@@ -67,4 +67,4 @@ export type { RateLimiterConfig, RateLimiterStats, RetryConfig, RateLimitRetryCo
 export { RehearsalManager, createRehearsalManager, GitRehearsalAnalyzer, createGitAnalyzer, FileRehearsalAnalyzer, createFileAnalyzer, } from './rehearsal/index.js';
 export type { ImpactSeverity, RehearsalRecommendation, OperationCategory, AffectedFile, RehearsalImpact, RehearsalResult, RehearsalContext, RehearsalAnalyzer, RehearsalManagerOptions, RehearsalEventType, RehearsalEvent, RehearsalEventHandler, } from './rehearsal/index.js';
 export { estimateEffort, DEFAULT_WEIGHTS, EFFORT_ORDER } from './episodes/index.js';
-export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, EpisodeStore, } from './episodes/index.js';
+export type { Effort, WorkEpisode, EffortSignals, EffortWeights, EffortSummary, ProjectWorkSummary, WorkAtRisk, EpisodeStore, } from './episodes/index.js';

package/dist/rehearsal/types.d.ts

@@ -5,6 +5,7 @@
  * before they are executed. This is a novel safety feature that goes beyond
  * simple dry-run by actually analyzing what would be affected.
  */
+import type { WorkAtRisk } from '../episodes/types.js';
 /**
  * Severity level of the operation's potential impact
  */
@@ -120,6 +121,10 @@ export interface RehearsalResult {
      * Suggested safer alternatives (if any)
      */
     alternatives?: string[];
+    /**
+     * Work episodes at risk from this operation (populated by episodic memory)
+     */
+    workAtRisk?: WorkAtRisk;
     /**
      * Time taken to perform the analysis (ms)
      */

package/dist/tools/builtin/ask-user-simple.js

@@ -75,10 +75,8 @@ async function askSimpleWithReadline(question, options, defaultValue) {
  */
 export const askUserSimpleTool = defineTool({
     name: 'ask_user_simple',
-    description: 'Ask a single simple question with string options. ' +
-        'Use this instead of ask_user when you only need one question. ' +
-        'Provide 2-4 clear, concise options. ' +
-        'The user can select by number or by typing the option text.',
+    // Original: 'Ask a single simple question with string options. Use this instead of ask_user when you only need one question. Provide 2-4 clear, concise options. The user can select by number or by typing the option text.'
+    description: 'Ask a single question with 2-4 string options.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/builtin/ask-user.js

@@ -90,10 +90,8 @@ async function askWithReadline(questions) {
  */
 export const askUserTool = defineTool({
     name: 'ask_user',
-    description: 'Ask the user one or more questions with predefined options. ' +
-        'Use this to gather preferences, make decisions, or get user input during workflows. ' +
-        'Each question should have 2-4 clear options. ' +
-        'Prefer ask_user_simple for single simple questions.',
+    // Original: 'Ask the user one or more questions with predefined options. Use this to gather preferences, make decisions, or get user input during workflows. Each question should have 2-4 clear options. Prefer ask_user_simple for single simple questions.'
+    description: 'Ask 1-4 questions with predefined options. Prefer ask_user_simple for single questions.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/builtin/backlog.js

@@ -86,9 +86,8 @@ function generateItemId(type, items) {
  */
 export const backlogReadTool = defineTool({
     name: 'backlog_read',
-    description: 'Read backlog items from the project. ' +
-        'Use filters to narrow results. Use id parameter to get a specific item. ' +
-        'Returns items sorted by priority (critical first) then by creation date.',
+    // Original: 'Read backlog items from the project. Use filters to narrow results. Use id parameter to get a specific item. Returns items sorted by priority (critical first) then by creation date.'
+    description: 'Read backlog items, sorted by priority then creation date.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -189,9 +188,8 @@ export const backlogReadTool = defineTool({
  */
 export const backlogWriteTool = defineTool({
     name: 'backlog_write',
-    description: 'Create, update, or delete backlog items. ' +
-        'Actions: add (new item), update (modify existing), delete (remove), replace (full list). ' +
-        'IDs are auto-generated for new items based on type (e.g., FEAT-001, BUG-002).',
+    // Original: 'Create, update, or delete backlog items. Actions: add (new item), update (modify existing), delete (remove), replace (full list). IDs are auto-generated for new items based on type (e.g., FEAT-001, BUG-002).'
+    description: 'Create, update, or delete backlog items.',
     inputSchema: {
         type: 'object',
         properties: {

package/dist/tools/builtin/bash-output.js

@@ -8,9 +8,8 @@ import { getDefaultShellManager } from './shell-manager.js';
  */
 export const bashOutputTool = defineTool({
     name: 'bash_output',
-    description: 'Retrieve output from a running or completed background bash shell. ' +
-        'Returns only new output since the last check. ' +
-        'Use this to monitor long-running commands started with run_in_background.',
+    // Original: 'Retrieve output from a running or completed background bash shell. Returns only new output since the last check. Use this to monitor long-running commands started with run_in_background.'
+    description: 'Retrieve output from a background bash shell.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -67,24 +66,8 @@ export function createBashOutputTool(options) {
     const manager = options?.shellManager ?? getDefaultShellManager();
     return defineTool({
         name: 'bash_output',
-        description: 'Retrieve output from a running or completed background bash shell. ' +
-            'Returns only new output since the last check. ' +
-            'Use this to monitor long-running commands started with run_in_background.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                bash_id: {
-                    type: 'string',
-                    description: 'The ID of the background shell to retrieve output from',
-                },
-                filter: {
-                    type: 'string',
-                    description: 'Optional regular expression to filter output lines. ' +
-                        'Only lines matching this regex will be included.',
-                },
-            },
-            required: ['bash_id'],
-        },
+        description: bashOutputTool.definition.description,
+        inputSchema: bashOutputTool.definition.inputSchema,
         execute: (input) => Promise.resolve(executeBashOutput(input, manager)),
     });
 }

package/dist/tools/builtin/bash.js

@@ -78,9 +78,9 @@ function truncateOutput(output, maxSize) {
  */
 export const bashTool = defineTool({
     name: 'bash',
-    description: 'Execute a shell command and return its output. ' +
-        'Commands run in bash shell. Use for system operations, git commands, npm, etc. ' +
-        'Set run_in_background=true for long-running commands, then use bash_output to monitor.',
+    // Original: 'Execute a shell command and return its output. Commands run in bash shell. Use for system operations, git commands, npm, etc. Set run_in_background=true for long-running commands, then use bash_output to monitor.'
+    description: 'Execute a shell command. ' +
+        'For long-running commands, set run_in_background and poll with bash_output.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -94,7 +94,8 @@ export const bashTool = defineTool({
             },
             timeout: {
                 type: 'number',
-                description: 'Timeout in milliseconds (default: 60000). Ignored for background commands.',
+                description: 'Timeout in milliseconds. Ignored for background commands.',
+                default: 60000,
             },
             env: {
                 type: 'object',
@@ -479,39 +480,8 @@ function isExecError(error) {
 export function createBashTool(options) {
     return defineTool({
         name: 'bash',
-        description: 'Execute a shell command and return its output. ' +
-            'Commands run in bash shell. Use for system operations, git commands, npm, etc. ' +
-            'Set run_in_background=true for long-running commands, then use bash_output to monitor.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                command: {
-                    type: 'string',
-                    description: 'The shell command to execute',
-                },
-                cwd: {
-                    type: 'string',
-                    description: 'Working directory for the command',
-                },
-                timeout: {
-                    type: 'number',
-                    description: 'Timeout in milliseconds (default: 60000). Ignored for background commands.',
-                },
-                env: {
-                    type: 'object',
-                    description: 'Additional environment variables',
-                },
-                run_in_background: {
-                    type: 'boolean',
-                    description: 'Run command in background and return shell ID. Use bash_output to get results.',
-                },
-                description: {
-                    type: 'string',
-                    description: 'Brief description of what this command does',
-                },
-            },
-            required: ['command'],
-        },
+        description: bashTool.definition.description,
+        inputSchema: bashTool.definition.inputSchema,
         execute: async (input, context) => {
             const { cwd: defaultCwd, timeout: defaultTimeout = DEFAULT_TIMEOUT, maxOutputSize = DEFAULT_MAX_OUTPUT_SIZE, blockedCommands = [], restrictToAllowed = false, allowedCommands = [], shell = '/bin/bash', shellManager, fifoMode = 'warn', } = options ?? {};
             const command = input.command.trim();

package/dist/tools/builtin/edit.js

@@ -157,35 +157,8 @@ function truncate(str, maxLength) {
 export function createEditTool(options) {
     return defineTool({
         name: 'edit',
-        description: 'Perform exact string replacements in files. ' +
-            'By default, the old_string must be unique in the file. ' +
-            'Use replaceAll to replace all occurrences.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                filePath: {
-                    type: 'string',
-                    description: 'Path to the file to edit',
-                },
-                oldString: {
-                    type: 'string',
-                    description: 'The text to search for and replace',
-                },
-                newString: {
-                    type: 'string',
-                    description: 'The replacement text',
-                },
-                replaceAll: {
-                    type: 'boolean',
-                    description: 'Replace all occurrences instead of requiring uniqueness',
-                },
-                createIfMissing: {
-                    type: 'boolean',
-                    description: 'Create the file with newString content if it does not exist',
-                },
-            },
-            required: ['filePath', 'oldString', 'newString'],
-        },
+        description: editTool.definition.description,
+        inputSchema: editTool.definition.inputSchema,
         execute: async (input) => {
             let targetPath = input.filePath;
             // Resolve relative paths

package/dist/tools/builtin/glob.js

@@ -34,9 +34,8 @@ const DEFAULT_EXCLUDE_DIRS = [
 export const globTool = defineTool({
     name: 'glob',
     readonly: true,
-    description: 'Find files matching glob patterns. ' +
-        'Supports common patterns like **/*.ts for recursive matching. ' +
-        'Returns a list of matching file paths.',
+    // Original: 'Find files matching glob patterns. Supports common patterns like **/*.ts for recursive matching. Returns a list of matching file paths.'
+    description: 'Find files matching glob patterns.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -50,7 +49,7 @@ export const globTool = defineTool({
             },
             includeHidden: {
                 type: 'boolean',
-                description: 'Include hidden files/directories (default: false)',
+                description: 'Include hidden files/directories',
             },
             onlyDirectories: {
                 type: 'boolean',
@@ -58,7 +57,8 @@ export const globTool = defineTool({
             },
             onlyFiles: {
                 type: 'boolean',
-                description: 'Only match files (default: true)',
+                description: 'Only match files',
+                default: true,
             },
             maxDepth: {
                 type: 'number',
@@ -66,7 +66,8 @@ export const globTool = defineTool({
             },
             maxResults: {
                 type: 'number',
-                description: 'Maximum number of results (default: 1000)',
+                description: 'Maximum number of results',
+                default: 1000,
             },
             absolute: {
                 type: 'boolean',
@@ -224,52 +225,8 @@ export function createGlobTool(options) {
     return defineTool({
         name: 'glob',
         readonly: true,
-        description: 'Find files matching glob patterns. ' +
-            'Supports common patterns like **/*.ts for recursive matching. ' +
-            'Returns a list of matching file paths.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                pattern: {
-                    type: 'string',
-                    description: 'Glob pattern (e.g., "**/*.ts", "src/**/*.js", "*.md")',
-                },
-                path: {
-                    type: 'string',
-                    description: 'Base directory to search in (default: current directory)',
-                },
-                includeHidden: {
-                    type: 'boolean',
-                    description: 'Include hidden files/directories (default: false)',
-                },
-                onlyDirectories: {
-                    type: 'boolean',
-                    description: 'Only match directories',
-                },
-                onlyFiles: {
-                    type: 'boolean',
-                    description: 'Only match files (default: true)',
-                },
-                maxDepth: {
-                    type: 'number',
-                    description: 'Maximum directory depth to traverse',
-                },
-                maxResults: {
-                    type: 'number',
-                    description: 'Maximum number of results (default: 1000)',
-                },
-                absolute: {
-                    type: 'boolean',
-                    description: 'Return absolute paths instead of relative',
-                },
-                excludeDirs: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Directory names to exclude (default: node_modules, .git, dist, build, etc.)',
-                },
-            },
-            required: ['pattern'],
-        },
+        description: globTool.definition.description,
+        inputSchema: globTool.definition.inputSchema,
         execute: async (input) => {
             let searchPath = input.path ?? '.';
             // Resolve relative paths

package/dist/tools/builtin/grep.js

@@ -35,9 +35,8 @@ const DEFAULT_EXCLUDE_DIRS = [
 export const grepTool = defineTool({
     name: 'grep',
     readonly: true,
-    description: 'Search for patterns in files using regular expressions. ' +
-        'Can search a single file or recursively through directories. ' +
-        'Returns matching lines with optional context.',
+    // Original: 'Search for patterns in files using regular expressions. Can search a single file or recursively through directories. Returns matching lines with optional context.'
+    description: 'Search for regex patterns in files or directories.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -51,11 +50,13 @@ export const grepTool = defineTool({
             },
             ignoreCase: {
                 type: 'boolean',
-                description: 'Case insensitive search (default: false)',
+                description: 'Case insensitive search',
+                default: false,
             },
             lineNumbers: {
                 type: 'boolean',
-                description: 'Include line numbers in output (default: true)',
+                description: 'Include line numbers in output',
+                default: true,
             },
             before: {
                 type: 'number',
@@ -80,11 +81,13 @@ export const grepTool = defineTool({
             },
             maxMatches: {
                 type: 'number',
-                description: 'Maximum number of matches to return (default: 100)',
+                description: 'Maximum number of matches to return',
+                default: 100,
             },
             recursive: {
                 type: 'boolean',
-                description: 'Search recursively in directories (default: true)',
+                description: 'Search recursively in directories',
+                default: true,
             },
         },
         required: ['pattern', 'path'],
@@ -321,65 +324,8 @@ export function createGrepTool(options) {
     return defineTool({
         name: 'grep',
         readonly: true,
-        description: 'Search for patterns in files using regular expressions. ' +
-            'Can search a single file or recursively through directories. ' +
-            'Returns matching lines with optional context.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                pattern: {
-                    type: 'string',
-                    description: 'Regular expression pattern to search for',
-                },
-                path: {
-                    type: 'string',
-                    description: 'Path to file or directory to search in',
-                },
-                ignoreCase: {
-                    type: 'boolean',
-                    description: 'Case insensitive search (default: false)',
-                },
-                lineNumbers: {
-                    type: 'boolean',
-                    description: 'Include line numbers in output (default: true)',
-                },
-                before: {
-                    type: 'number',
-                    description: 'Number of context lines before match',
-                },
-                after: {
-                    type: 'number',
-                    description: 'Number of context lines after match',
-                },
-                filesOnly: {
-                    type: 'boolean',
-                    description: 'Only return filenames with matches',
-                },
-                includeHidden: {
-                    type: 'boolean',
-                    description: 'Include hidden files/directories',
-                },
-                extensions: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'File extensions to include (e.g., [".ts", ".js"])',
-                },
-                maxMatches: {
-                    type: 'number',
-                    description: 'Maximum number of matches to return (default: 100)',
-                },
-                recursive: {
-                    type: 'boolean',
-                    description: 'Search recursively in directories (default: true)',
-                },
-                excludeDirs: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Directory names to exclude (default: node_modules, .git, dist, build, etc.)',
-                },
-            },
-            required: ['pattern', 'path'],
-        },
+        description: grepTool.definition.description,
+        inputSchema: grepTool.definition.inputSchema,
         execute: async (input) => {
             let searchPath = input.path;
             // Resolve relative paths

package/dist/tools/builtin/kill-shell.js

@@ -8,8 +8,8 @@ import { getDefaultShellManager } from './shell-manager.js';
  */
 export const killShellTool = defineTool({
     name: 'kill_shell',
-    description: 'Kill a running background bash shell by its ID. ' +
-        'Use this to terminate long-running commands that are no longer needed.',
+    // Original: 'Kill a running background bash shell by its ID. Use this to terminate long-running commands that are no longer needed.'
+    description: 'Terminate a background bash shell by ID.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -63,18 +63,8 @@ export function createKillShellTool(options) {
     const manager = options?.shellManager ?? getDefaultShellManager();
     return defineTool({
         name: 'kill_shell',
-        description: 'Kill a running background bash shell by its ID. ' +
-            'Use this to terminate long-running commands that are no longer needed.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                shell_id: {
-                    type: 'string',
-                    description: 'The ID of the background shell to kill',
-                },
-            },
-            required: ['shell_id'],
-        },
+        description: killShellTool.definition.description,
+        inputSchema: killShellTool.definition.inputSchema,
         execute: (input) => Promise.resolve(executeKillShell(input, manager)),
     });
 }

package/dist/tools/builtin/read-file.js

@@ -19,8 +19,8 @@ const DEFAULT_MAX_CONTENT_SIZE = 100 * 1024;
 export const readFileTool = defineTool({
     name: 'read_file',
     readonly: true,
-    description: 'Read the contents of a file. Returns the file content as text. ' +
-        'Use maxLines and startLine to read specific portions of large files.',
+    // Original: 'Read the contents of a file. Returns the file content as text. Use maxLines and startLine to read specific portions of large files.'
+    description: 'Read file contents. Use maxLines/startLine for large files.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -30,7 +30,8 @@ export const readFileTool = defineTool({
             },
             encoding: {
                 type: 'string',
-                description: 'File encoding (default: utf-8)',
+                description: 'File encoding',
+                default: 'utf-8',
             },
             maxLines: {
                 type: 'number',
@@ -139,30 +140,8 @@ export function createReadFileTool(options) {
     return defineTool({
         name: 'read_file',
         readonly: true,
-        description: 'Read the contents of a file. Returns the file content as text. ' +
-            'Use maxLines and startLine to read specific portions of large files.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Absolute or relative path to the file',
-                },
-                encoding: {
-                    type: 'string',
-                    description: 'File encoding (default: utf-8)',
-                },
-                maxLines: {
-                    type: 'number',
-                    description: 'Maximum number of lines to read',
-                },
-                startLine: {
-                    type: 'number',
-                    description: 'Line number to start reading from (1-indexed)',
-                },
-            },
-            required: ['path'],
-        },
+        description: readFileTool.definition.description,
+        inputSchema: readFileTool.definition.inputSchema,
         execute: async (input) => {
             const { baseDir, allowedExtensions, maxFileSize, maxContentSize, truncateIfLarge } = options ?? {};
             let filePath = input.path;

package/dist/tools/builtin/recall-result.js

@@ -12,9 +12,8 @@ export function createRecallResultTool(options) {
     const { store, onEvent } = options;
     return defineTool({
         name: 'recall_full_result',
-        description: 'Retrieve the full output of a previously delegated tool result. ' +
-            'Use when a summary is insufficient and you need the complete data. ' +
-            'Results expire after 10 minutes.',
+        // Original: 'Retrieve the full output of a previously delegated tool result. Use when a summary is insufficient and you need the complete data. Results expire after 10 minutes.'
+        description: 'Retrieve full output of a delegated tool result. Results expire after 10 minutes.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/tools/builtin/suggest.js

@@ -15,11 +15,8 @@ import { defineTool, createSuccessResult } from '../define.js';
  */
 export const suggestTool = defineTool({
     name: 'suggest',
-    description: 'Suggest a next action for the user. The suggestion appears as ghost text in the input prompt. ' +
-        'Use this after completing a task to guide the user toward a logical next step. ' +
-        'Good suggestions are actionable, specific, and follow naturally from what you just did. ' +
-        'Examples: "run npm test to verify the fix", "review the changes in src/index.ts", ' +
-        '"commit the changes with git commit". Only suggest when there is a clear, helpful next step.',
+    // Original: 'Suggest a next action for the user. The suggestion appears as ghost text in the input prompt. Use this after completing a task to guide the user toward a logical next step. Good suggestions are actionable, specific, and follow naturally from what you just did. Examples: "run npm test to verify the fix", "review the changes in src/index.ts", "commit the changes with git commit". Only suggest when there is a clear, helpful next step.'
+    description: 'Suggest a next action as ghost text in the input prompt. Use after completing a task.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -61,25 +58,8 @@ export function createSuggestTool(options = {}) {
     const { onSuggest } = options;
     return defineTool({
         name: 'suggest',
-        description: 'Suggest a next action for the user. The suggestion appears as ghost text in the input prompt. ' +
-            'Use this after completing a task to guide the user toward a logical next step. ' +
-            'Good suggestions are actionable, specific, and follow naturally from what you just did. ' +
-            'Examples: "run npm test to verify the fix", "review the changes in src/index.ts", ' +
-            '"commit the changes with git commit". Only suggest when there is a clear, helpful next step.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                action: {
-                    type: 'string',
-                    description: 'The suggested action or command for the user to take next',
-                },
-                reason: {
-                    type: 'string',
-                    description: 'Brief explanation of why this action is suggested (optional)',
-                },
-            },
-            required: ['action'],
-        },
+        description: suggestTool.definition.description,
+        inputSchema: suggestTool.definition.inputSchema,
         execute: (input) => {
             // Emit the suggest event if handler is configured
             if (onSuggest) {

package/dist/tools/builtin/todo.js

@@ -158,10 +158,9 @@ const defaultStore = new TodoStore();
  */
 export const todoWriteTool = defineTool({
     name: 'todo_write',
-    description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
-        'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
-        'Provide the complete list to replace current todos. ' +
-        'Use blockedBy to declare task dependencies (1-based positions in the array).',
+    // Original: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - NOT persistent backlog items. For persistent project backlog, use workitem_* tools. Provide the complete list to replace current todos. Use blockedBy to declare task dependencies (1-based positions in the array).'
+    description: 'Replace the session todo list (ephemeral, shown in footer). ' +
+        'For persistent backlog, use workitem_* tools.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -229,8 +228,8 @@ export const todoWriteTool = defineTool({
 export const todoReadTool = defineTool({
     name: 'todo_read',
     readonly: true,
-    description: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - ' +
-        'for persistent project backlog, use workitem_query. Optionally filter by status or owner.',
+    // Original: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - for persistent project backlog, use workitem_query. Optionally filter by status or owner.'
+    description: 'Get the session todo list. For persistent backlog, use workitem_query.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -241,7 +240,8 @@ export const todoReadTool = defineTool({
             },
             includeCompleted: {
                 type: 'boolean',
-                description: 'Include completed tasks (default: true)',
+                description: 'Include completed tasks',
+                default: true,
             },
             owner: {
                 type: 'string',
@@ -291,9 +291,7 @@ export function createTodoTools(store) {
     const todoStore = store ?? new TodoStore();
     const todoWrite = defineTool({
         name: 'todo_write',
-        description: 'Update the SESSION todo list (shown in CLI footer). These are ephemeral tasks for the current session only - ' +
-            'NOT persistent backlog items. For persistent project backlog, use workitem_* tools. ' +
-            'Use blockedBy to declare task dependencies (1-based positions in the array).',
+        description: todoWriteTool.definition.description,
         inputSchema: {
             type: 'object',
             properties: {
@@ -342,8 +340,7 @@ export function createTodoTools(store) {
     const todoRead = defineTool({
         name: 'todo_read',
         readonly: true,
-        description: 'Get the SESSION todo list (shown in CLI footer). These are ephemeral session tasks - ' +
-            'for persistent project backlog, use workitem_query.',
+        description: todoReadTool.definition.description,
         inputSchema: {
             type: 'object',
             properties: {
@@ -395,7 +392,8 @@ export function createTodoTools(store) {
     });
     const todoClaim = defineTool({
         name: 'todo_claim',
-        description: 'Claim an unassigned SESSION todo (from CLI footer). For persistent backlog items, use workitem_claim.',
+        // Original: 'Claim an unassigned SESSION todo (from CLI footer). For persistent backlog items, use workitem_claim.'
+        description: 'Claim an unassigned session todo. For persistent items, use workitem_claim.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -436,8 +434,8 @@ export function createTodoTools(store) {
     });
     const todoHandoff = defineTool({
         name: 'todo_handoff',
-        description: 'Hand off a SESSION todo (from CLI footer) to another agent. ' +
-            'For persistent backlog items, use workitem_handoff.',
+        // Original: 'Hand off a SESSION todo (from CLI footer) to another agent. For persistent backlog items, use workitem_handoff.'
+        description: 'Hand off a session todo to another agent. For persistent items, use workitem_handoff.',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/tools/builtin/web-fetch.js

@@ -18,9 +18,8 @@ const DEFAULT_MAX_SIZE = 100 * 1024;
 export const webFetchTool = defineTool({
     name: 'web_fetch',
     readonly: true,
-    description: 'Fetch content from a URL. Returns the page content as text. ' +
-        'Use for retrieving documentation, API responses, or web pages. ' +
-        'HTTP URLs are automatically upgraded to HTTPS.',
+    // Original: 'Fetch content from a URL. Returns the page content as text. Use for retrieving documentation, API responses, or web pages. HTTP URLs are automatically upgraded to HTTPS.'
+    description: 'Fetch content from a URL and return as text.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -35,11 +34,13 @@ export const webFetchTool = defineTool({
             },
             timeout: {
                 type: 'number',
-                description: 'Request timeout in milliseconds (default: 30000)',
+                description: 'Request timeout in milliseconds',
+                default: 30000,
             },
             maxSize: {
                 type: 'number',
-                description: 'Maximum content size to return in bytes (default: 102400)',
+                description: 'Maximum content size to return in bytes',
+                default: 102400,
             },
         },
         required: ['url'],
@@ -170,9 +171,7 @@ export function createWebFetchTool(options) {
     return defineTool({
         name: 'web_fetch',
         readonly: true,
-        description: 'Fetch content from a URL. Returns the page content as text. ' +
-            'Use for retrieving documentation, API responses, or web pages. ' +
-            'HTTP URLs are automatically upgraded to HTTPS.',
+        description: webFetchTool.definition.description,
         inputSchema: {
             type: 'object',
             properties: {
@@ -187,11 +186,13 @@ export function createWebFetchTool(options) {
                 },
                 timeout: {
                     type: 'number',
-                    description: `Request timeout in milliseconds (default: ${String(defaultTimeout)})`,
+                    description: 'Request timeout in milliseconds',
+                    default: defaultTimeout,
                 },
                 maxSize: {
                     type: 'number',
-                    description: `Maximum content size to return in bytes (default: ${String(defaultMaxSize)})`,
+                    description: 'Maximum content size to return in bytes',
+                    default: defaultMaxSize,
                 },
             },
             required: ['url'],

package/dist/tools/builtin/write-file.js

@@ -10,8 +10,8 @@ import { isNodeError, isExtensionAllowed } from './utils.js';
  */
 export const writeFileTool = defineTool({
     name: 'write_file',
-    description: 'Write content to a file. Creates the file if it does not exist. ' +
-        'Use append: true to add to existing content instead of overwriting.',
+    // Original: 'Write content to a file. Creates the file if it does not exist. Use append: true to add to existing content instead of overwriting.'
+    description: 'Write content to a file, creating it if needed.',
     inputSchema: {
         type: 'object',
         properties: {
@@ -25,15 +25,18 @@ export const writeFileTool = defineTool({
             },
             encoding: {
                 type: 'string',
-                description: 'File encoding (default: utf-8)',
+                description: 'File encoding',
+                default: 'utf-8',
             },
             createDirs: {
                 type: 'boolean',
-                description: 'Create parent directories if needed (default: true)',
+                description: 'Create parent directories if needed',
+                default: true,
             },
             append: {
                 type: 'boolean',
-                description: 'Append to file instead of overwriting (default: false)',
+                description: 'Append to file instead of overwriting',
+                default: false,
             },
         },
         required: ['path', 'content'],
@@ -86,34 +89,8 @@ async function executeWriteFile(input) {
 export function createWriteFileTool(options) {
     return defineTool({
         name: 'write_file',
-        description: 'Write content to a file. Creates the file if it does not exist. ' +
-            'Use append: true to add to existing content instead of overwriting.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'Absolute or relative path to the file',
-                },
-                content: {
-                    type: 'string',
-                    description: 'Content to write to the file',
-                },
-                encoding: {
-                    type: 'string',
-                    description: 'File encoding (default: utf-8)',
-                },
-                createDirs: {
-                    type: 'boolean',
-                    description: 'Create parent directories if needed (default: true)',
-                },
-                append: {
-                    type: 'boolean',
-                    description: 'Append to file instead of overwriting (default: false)',
-                },
-            },
-            required: ['path', 'content'],
-        },
+        description: writeFileTool.definition.description,
+        inputSchema: writeFileTool.definition.inputSchema,
         execute: async (input) => {
             const { baseDir, allowedExtensions, maxContentSize = 10 * 1024 * 1024, blockedPaths = [], } = options ?? {};
             let filePath = input.path;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",
@@ -43,7 +43,7 @@
     "anthropic"
   ],
   "author": "Carmelo Scozzola",
-  "license": "MIT",
+  "license": "FSL-1.1-MIT",
   "bugs": {
     "url": "https://github.com/compilr-dev/agents/issues"
   },