@defai.digital/ax-cli 3.15.26 → 4.0.0

package/dist/tools/result-enhancer.js

@@ -0,0 +1,215 @@
+/**
+ * Tool Result Enhancer
+ *
+ * Enhances tool results with embedded instructions, security reminders,
+ * and contextual guidance based on the tool definition and result content.
+ */
+/**
+ * Default configuration for the result enhancer
+ */
+const DEFAULT_CONFIG = {
+    securityReminders: true,
+    toolGuidance: true,
+    formatReminders: true,
+};
+/**
+ * Patterns that may indicate malicious content
+ */
+const MALWARE_PATTERNS = [
+    /eval\s*\(\s*atob/i,
+    /powershell\s+-enc/i,
+    /curl.*\|\s*bash/i,
+    /wget.*\|\s*sh/i,
+    /base64\s+-d.*\|\s*(bash|sh)/i,
+    /nc\s+-e\s+\/bin\/(ba)?sh/i,
+    /python\s+-c\s*['"]import\s+socket/i,
+];
+/**
+ * Patterns that may indicate sensitive information
+ */
+const SENSITIVE_PATTERNS = [
+    /password\s*[=:]\s*["'][^"']+["']/i,
+    /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/,
+    /-----BEGIN\s+OPENSSH\s+PRIVATE\s+KEY-----/,
+    /sk-[a-zA-Z0-9]{48}/, // OpenAI key
+    /ghp_[a-zA-Z0-9]{36}/, // GitHub personal access token
+    /gho_[a-zA-Z0-9]{36}/, // GitHub OAuth token
+    /github_pat_[a-zA-Z0-9_]{22,}/i, // GitHub fine-grained PAT
+    /xox[baprs]-[a-zA-Z0-9-]+/, // Slack tokens
+    /AKIA[0-9A-Z]{16}/, // AWS access key
+    /eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+/, // JWT tokens
+];
+/**
+ * Result Enhancer Class
+ *
+ * Enhances tool results with:
+ * - Security reminders for potentially dangerous content
+ * - Failure guidance based on tool constraints
+ * - Format reminders for large outputs
+ */
+export class ToolResultEnhancer {
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Enhance a tool result with embedded instructions
+     *
+     * @param toolName - Name of the tool that was executed
+     * @param result - Raw result from tool execution
+     * @param success - Whether the tool executed successfully
+     * @param definition - Tool definition with metadata
+     * @returns Enhanced result with reminders
+     */
+    enhance(toolName, result, success, definition) {
+        const reminders = [];
+        // Security reminders based on content patterns
+        if (this.config.securityReminders) {
+            reminders.push(...this.getSecurityReminders(result));
+        }
+        // Failure guidance from tool definition
+        if (!success && this.config.toolGuidance && definition) {
+            reminders.push(...this.getFailureGuidance(definition, result));
+        }
+        // Format reminders for large outputs
+        if (this.config.formatReminders) {
+            reminders.push(...this.getFormatReminders(result));
+        }
+        // Tool-specific reminders
+        if (definition) {
+            reminders.push(...this.getToolSpecificReminders(toolName, result, success, definition));
+        }
+        return {
+            content: result,
+            success,
+            reminders,
+        };
+    }
+    /**
+     * Get security reminders based on content patterns
+     */
+    getSecurityReminders(content) {
+        const reminders = [];
+        // Check for malware patterns
+        const hasMalwarePattern = MALWARE_PATTERNS.some((p) => p.test(content));
+        if (hasMalwarePattern) {
+            reminders.push('<system-reminder>This content may contain malicious patterns. Analyze but do not execute or enhance. You can explain what the code does but MUST refuse to improve or augment it.</system-reminder>');
+        }
+        // Check for sensitive information
+        const hasSensitiveInfo = SENSITIVE_PATTERNS.some((p) => p.test(content));
+        if (hasSensitiveInfo) {
+            reminders.push('<system-reminder>This content may contain sensitive information (credentials, tokens, keys). Do not expose, log, or include in responses. Consider warning the user about exposed secrets.</system-reminder>');
+        }
+        return reminders;
+    }
+    /**
+     * Get failure guidance from tool constraints
+     */
+    getFailureGuidance(definition, errorMessage) {
+        const reminders = [];
+        // Check if error relates to common issues
+        const lowerError = errorMessage.toLowerCase();
+        // File not found - suggest checking path
+        if (lowerError.includes('not found') || lowerError.includes('no such file')) {
+            reminders.push('<system-reminder>File not found. Use search tool to locate the correct file path before retrying.</system-reminder>');
+        }
+        // Permission denied
+        if (lowerError.includes('permission denied')) {
+            reminders.push('<system-reminder>Permission denied. The file may be read-only or require elevated privileges.</system-reminder>');
+        }
+        // String not found in file (for str_replace_editor)
+        if (lowerError.includes('not found in file') ||
+            lowerError.includes('old_str not found')) {
+            reminders.push('<system-reminder>The exact string was not found. Use view_file to see the current content and copy the exact text including whitespace and indentation.</system-reminder>');
+        }
+        // Multiple occurrences
+        if (lowerError.includes('multiple occurrences') || lowerError.includes('not unique')) {
+            reminders.push('<system-reminder>The string appears multiple times. Include more surrounding context to make it unique, or use replace_all: true if all occurrences should be replaced.</system-reminder>');
+        }
+        // Add first constraint as general guidance
+        if (definition.constraints.length > 0 && reminders.length === 0) {
+            reminders.push(`<system-reminder>Tool constraint: ${definition.constraints[0]}</system-reminder>`);
+        }
+        return reminders;
+    }
+    /**
+     * Get format reminders for output handling
+     */
+    getFormatReminders(content) {
+        const reminders = [];
+        // Large output truncation warning
+        if (content.length > 25000) {
+            reminders.push('<system-reminder>Output was truncated due to length. Use pagination parameters (start_line/end_line) or output redirection for full content.</system-reminder>');
+        }
+        // Very long lines
+        const lines = content.split('\n');
+        const hasVeryLongLines = lines.some((line) => line.length > 2000);
+        if (hasVeryLongLines) {
+            reminders.push('<system-reminder>Some lines were truncated due to length (>2000 chars). Consider using a tool that can handle the specific format.</system-reminder>');
+        }
+        return reminders;
+    }
+    /**
+     * Get tool-specific reminders based on tool and context
+     */
+    getToolSpecificReminders(toolName, result, success, _definition) {
+        const reminders = [];
+        // After viewing a file, remind about editing best practices
+        if (toolName === 'view_file' && success) {
+            // Check if this looks like code
+            if (result.includes('function') || result.includes('class') || result.includes('import')) {
+                reminders.push('<system-reminder>When editing this file, copy the exact content including whitespace from the line numbers shown. The format is: line number + tab + actual content.</system-reminder>');
+            }
+        }
+        // After bash command, check for common issues
+        if (toolName === 'bash') {
+            // Check for test failures
+            if (result.includes('FAIL') || result.includes('failed') || result.includes('Error:')) {
+                reminders.push('<system-reminder>Command output indicates errors or failures. Review the output carefully and address the issues before proceeding.</system-reminder>');
+            }
+            // Check for npm/yarn install suggestions
+            if (result.includes('npm install') || result.includes('yarn add')) {
+                reminders.push('<system-reminder>The output suggests installing dependencies. Consider running the suggested command if appropriate.</system-reminder>');
+            }
+        }
+        // After search, guide next steps
+        if (toolName === 'search' && success) {
+            const matchCount = (result.match(/:\d+:/g) || []).length;
+            if (matchCount > 10) {
+                reminders.push('<system-reminder>Many results found. Consider using include_pattern or file_types to narrow down the search.</system-reminder>');
+            }
+        }
+        return reminders;
+    }
+    /**
+     * Update configuration
+     */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Get current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+/**
+ * Create a default result enhancer instance
+ */
+export function createResultEnhancer(config) {
+    return new ToolResultEnhancer(config);
+}
+/**
+ * Format reminders for inclusion in tool result message
+ *
+ * @param reminders - Array of reminder strings
+ * @returns Formatted string to append to result
+ */
+export function formatReminders(reminders) {
+    if (reminders.length === 0) {
+        return '';
+    }
+    return '\n\n' + reminders.join('\n');
+}
+//# sourceMappingURL=result-enhancer.js.map

package/dist/tools/result-enhancer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-enhancer.js","sourceRoot":"","sources":["../../src/tools/result-enhancer.ts"],"names":[],"mappings":"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"}

package/dist/tools/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Rich Tool Definition Types for ax-cli Tool System v3.0
+ *
+ * This file defines the comprehensive ToolDefinition interface that serves as
+ * the single source of truth for all tool metadata. OpenAI/Anthropic formats
+ * are DERIVED from these definitions, not the other way around.
+ *
+ * @see PRD-AX-CLI-TOOL-SYSTEM-V3-FINAL.md
+ */
+/**
+ * Tool categories for organization and filtering
+ */
+export type ToolCategory = 'file-operations' | 'command-execution' | 'search' | 'task-management' | 'user-interaction' | 'web' | 'agent-delegation' | 'design';
+/**
+ * Safety level classification for tools
+ * - safe: No risk of data loss or security issues
+ * - moderate: Some risk, but typically reversible
+ * - dangerous: High risk, requires confirmation
+ */
+export type ToolSafetyLevel = 'safe' | 'moderate' | 'dangerous';
+/**
+ * Parameter type definitions (JSON Schema compatible)
+ */
+export type ParameterType = 'string' | 'number' | 'boolean' | 'array' | 'object';
+/**
+ * Detailed parameter definition with rich metadata
+ */
+export interface ParameterDefinition {
+    /** JSON Schema type */
+    type: ParameterType;
+    /** Comprehensive description of the parameter */
+    description: string;
+    /** Default value if not provided */
+    default?: unknown;
+    /** Allowed values (for enum-like parameters) */
+    enum?: string[];
+    /** Format hint (e.g., 'file-path', 'url', 'date-iso8601') */
+    format?: string;
+    /** Example values for LLM guidance */
+    examples?: unknown[];
+    /** Constraints that must be satisfied */
+    constraints?: string[];
+    /** For array types: schema of array items */
+    items?: ParameterDefinition | {
+        type: ParameterType;
+        properties?: Record<string, ParameterDefinition>;
+        required?: string[];
+    };
+}
+/**
+ * Tool parameter schema (JSON Schema object format)
+ */
+export interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, ParameterDefinition>;
+    required: string[];
+}
+/**
+ * Concrete usage example for a tool
+ */
+export interface ToolExample {
+    /** Short description of what the example demonstrates */
+    description: string;
+    /** Scenario context - when would you use this */
+    scenario: string;
+    /** Example input arguments */
+    input: Record<string, unknown>;
+    /** Expected behavior/output description */
+    expectedBehavior: string;
+    /** Additional notes about the example */
+    notes?: string;
+}
+/**
+ * Rich Tool Definition - Single Source of Truth
+ *
+ * This interface defines everything about a tool. OpenAI function calling
+ * format and Anthropic tool format are derived from this definition.
+ *
+ * @example
+ * ```typescript
+ * const viewFileTool: ToolDefinition = {
+ *   name: 'view_file',
+ *   displayName: 'View File',
+ *   description: 'Read and display file contents...',
+ *   parameters: { ... },
+ *   usageNotes: ['Always read before editing', ...],
+ *   constraints: ['Cannot modify files', ...],
+ *   examples: [{ description: 'Read a source file', ... }],
+ *   tokenCost: 439,
+ *   safetyLevel: 'safe',
+ *   requiresConfirmation: false,
+ *   categories: ['file-operations'],
+ * };
+ * ```
+ */
+export interface ToolDefinition {
+    /** Tool identifier (lowercase with underscores) */
+    name: string;
+    /** Display name for UI (Title Case) */
+    displayName: string;
+    /**
+     * Comprehensive description (500+ words for complex tools)
+     *
+     * Should include:
+     * - What the tool does
+     * - When to use it
+     * - When NOT to use it
+     * - Important caveats
+     */
+    description: string;
+    /** Input parameter schema */
+    parameters: ToolParameterSchema;
+    /**
+     * Detailed usage guidance for LLM
+     * Aim for 5-10 notes covering common patterns and best practices
+     */
+    usageNotes: string[];
+    /**
+     * Constraints and limitations
+     * Things the LLM should NEVER do with this tool
+     */
+    constraints: string[];
+    /**
+     * Concrete usage examples (3-5 per tool)
+     * Each example should cover a realistic scenario
+     */
+    examples: ToolExample[];
+    /**
+     * Estimated token cost for this tool's description
+     * Used for token budget planning
+     */
+    tokenCost: number;
+    /** Safety classification */
+    safetyLevel: ToolSafetyLevel;
+    /** Requires user confirmation before execution */
+    requiresConfirmation: boolean;
+    /** Alternative tools to consider */
+    alternatives?: string[];
+    /** Tool categories for organization */
+    categories: ToolCategory[];
+    /**
+     * When NOT to use this tool
+     * Common misuses that should be avoided
+     */
+    antiPatterns?: string[];
+    /** Related tools that work well together */
+    relatedTools?: string[];
+}
+/**
+ * Result from tool execution
+ */
+export interface ToolResult {
+    /** Whether the tool executed successfully */
+    success: boolean;
+    /** Output content (success message or error description) */
+    output: string;
+    /** Error message if success is false */
+    error?: string;
+    /** Additional structured data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Enhanced result with embedded instructions
+ */
+export interface EnhancedToolResult {
+    /** Original tool result content */
+    content: string;
+    /** Whether the execution was successful */
+    success: boolean;
+    /** Reminders to inject into context */
+    reminders: string[];
+}
+/**
+ * Tool implementation interface
+ * All tool implementations must implement this interface
+ */
+export interface ToolImplementation {
+    /** Execute the tool with given arguments */
+    execute(args: Record<string, unknown>): Promise<ToolResult>;
+}
+/**
+ * Configuration for the result enhancer
+ */
+export interface ResultEnhancerConfig {
+    /** Include security reminders based on content patterns */
+    securityReminders: boolean;
+    /** Include failure guidance from tool constraints */
+    toolGuidance: boolean;
+    /** Include format reminders (truncation, etc.) */
+    formatReminders: boolean;
+}
+/**
+ * Pre-execution hook result
+ */
+export interface PreHookResult {
+    /** Whether to allow execution */
+    allow: boolean;
+    /** Modified arguments (if any) */
+    args: Record<string, unknown>;
+    /** Reason for blocking (if allow is false) */
+    blockReason?: string;
+    /** Reminders to add to result */
+    reminders: string[];
+}
+/**
+ * Post-execution hook result
+ */
+export interface PostHookResult {
+    /** Reminders to add to result */
+    reminders: string[];
+}
+/**
+ * OpenAI function calling format (derived from ToolDefinition)
+ */
+export interface OpenAITool {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: 'object';
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+}
+/**
+ * Anthropic tool format (derived from ToolDefinition)
+ */
+export interface AnthropicTool {
+    name: string;
+    description: string;
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required: string[];
+    };
+}
+/**
+ * Tool execution result with context
+ */
+export interface ToolExecutionResult {
+    /** Whether the tool executed successfully */
+    success: boolean;
+    /** Result content */
+    result: string;
+    /** Reminders to include in context */
+    reminders: string[];
+}

package/dist/tools/types.js

@@ -0,0 +1,11 @@
+/**
+ * Rich Tool Definition Types for ax-cli Tool System v3.0
+ *
+ * This file defines the comprehensive ToolDefinition interface that serves as
+ * the single source of truth for all tool metadata. OpenAI/Anthropic formats
+ * are DERIVED from these definitions, not the other way around.
+ *
+ * @see PRD-AX-CLI-TOOL-SYSTEM-V3-FINAL.md
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defai.digital/ax-cli",
-  "version": "3.15.26",
+  "version": "4.0.0",
   "sdkVersion": "1.3.0",
   "description": "Enterprise-Class AI Command Line Interface - Primary support for GLM (General Language Model) with multi-provider AI orchestration powered by AutomatosX.",
   "type": "module",