goatchain 0.0.2 → 0.0.4

package/dist/tool/builtin/enterPlanMode.d.ts

@@ -0,0 +1,58 @@
+import type { CallToolResult, ToolInputSchema } from '../../types';
+import type { RiskLevel } from '../types';
+import { BaseTool } from '../base';
+/**
+ * Result of entering plan mode
+ */
+export interface EnterPlanModeResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Message indicating plan mode has been entered */
+    message: string;
+    /** Whether user approved entering plan mode */
+    approved?: boolean;
+}
+/**
+ * Arguments for the EnterPlanMode tool
+ */
+export interface EnterPlanModeArgs {
+    /** User approval collected by the permission component */
+    approved?: boolean;
+}
+/**
+ * Tool for entering plan mode before starting non-trivial implementation tasks.
+ *
+ * This tool allows the agent to transition into plan mode where it can:
+ * - Thoroughly explore the codebase using various tools
+ * - Understand existing patterns and architecture
+ * - Design an implementation approach
+ * - Present the plan to the user for approval
+ * - Use AskUserQuestion to clarify approaches if needed
+ *
+ * Getting user sign-off on the approach before writing code prevents wasted
+ * effort and ensures alignment.
+ *
+ * @example
+ * ```typescript
+ * const enterPlanModeTool = new EnterPlanModeTool()
+ * const result = await enterPlanModeTool.execute({})
+ * // Agent is now in plan mode and can explore before implementing
+ * ```
+ */
+export declare class EnterPlanModeTool extends BaseTool {
+    readonly name = "EnterPlanMode";
+    readonly riskLevel: RiskLevel;
+    readonly description = "Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.\n\n## When to Use This Tool\n\n**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:\n\n1. **New Feature Implementation**: Adding meaningful new functionality\n   - Example: \"Add a logout button\" - where should it go? What should happen on click?\n   - Example: \"Add form validation\" - what rules? What error messages?\n\n2. **Multiple Valid Approaches**: The task can be solved in several different ways\n   - Example: \"Add caching to the API\" - could use Redis, in-memory, file-based, etc.\n   - Example: \"Improve performance\" - many optimization strategies possible\n\n3. **Code Modifications**: Changes that affect existing behavior or structure\n   - Example: \"Update the login flow\" - what exactly should change?\n   - Example: \"Refactor this component\" - what's the target architecture?\n\n4. **Architectural Decisions**: The task requires choosing between patterns or technologies\n   - Example: \"Add real-time updates\" - WebSockets vs SSE vs polling\n   - Example: \"Implement state management\" - Redux vs Context vs custom solution\n\n5. **Multi-File Changes**: The task will likely touch more than 2-3 files\n   - Example: \"Refactor the authentication system\"\n   - Example: \"Add a new API endpoint with tests\"\n\n6. **Unclear Requirements**: You need to explore before understanding the full scope\n   - Example: \"Make the app faster\" - need to profile and identify bottlenecks\n   - Example: \"Fix the bug in checkout\" - need to investigate root cause\n\n7. **User Preferences Matter**: The implementation could reasonably go multiple ways\n   - If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead\n   - Plan mode lets you explore first, then present options with context\n\n## When NOT to Use This Tool\n\nOnly skip EnterPlanMode for simple tasks:\n- Single-line or few-line fixes (typos, obvious bugs, small tweaks)\n- Adding a single function with clear requirements\n- Tasks where the user has given very specific, detailed instructions\n- Pure research/exploration tasks (use the Task tool with explore agent instead)\n\n## What Happens in Plan Mode\n\nIn plan mode, you'll:\n1. Thoroughly explore the codebase using Glob, Grep, and Read tools\n2. Understand existing patterns and architecture\n3. Design an implementation approach\n4. Present your plan to the user for approval\n5. Use AskUserQuestion if you need to clarify approaches\n6. Exit plan mode with ExitPlanMode when ready to implement\n\n## Examples\n\n### GOOD - Use EnterPlanMode:\nUser: \"Add user authentication to the app\"\n- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)\n\nUser: \"Optimize the database queries\"\n- Multiple approaches possible, need to profile first, significant impact\n\nUser: \"Implement dark mode\"\n- Architectural decision on theme system, affects many components\n\nUser: \"Add a delete button to the user profile\"\n- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates\n\nUser: \"Update the error handling in the API\"\n- Affects multiple files, user should approve the approach\n\n### BAD - Don't use EnterPlanMode:\nUser: \"Fix the typo in the README\"\n- Straightforward, no planning needed\n\nUser: \"Add a console.log to debug this function\"\n- Simple, obvious implementation\n\nUser: \"What files handle routing?\"\n- Research task, not implementation planning\n\n## Important Notes\n\n- This tool REQUIRES user approval - they must consent to entering plan mode\n- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work\n- Users appreciate being consulted before significant changes are made to their codebase";
+    readonly parameters: ToolInputSchema;
+    /**
+     * Execute enter plan mode
+     *
+     * @param args - EnterPlanMode arguments
+     * @returns MCP-compliant CallToolResult indicating plan mode has been entered
+     */
+    execute(args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Validate and parse arguments
+     */
+    private validateArgs;
+}

package/dist/tool/builtin/exitPlanMode.d.ts

@@ -0,0 +1,48 @@
+import type { CallToolResult, ToolInputSchema } from '../../types';
+import type { RiskLevel } from '../types';
+import { BaseTool } from '../base';
+/**
+ * Result of exiting plan mode
+ */
+export interface ExitPlanModeResult {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Message indicating plan mode has been exited */
+    message: string;
+}
+/**
+ * Arguments for the ExitPlanMode tool
+ */
+export interface ExitPlanModeArgs {
+}
+/**
+ * Tool for exiting plan mode after completing the implementation plan.
+ *
+ * This tool is used when:
+ * - You have finished writing your plan to the plan file
+ * - The plan is clear and unambiguous
+ * - You are ready for user approval of the plan
+ *
+ * The tool signals completion of the planning phase and transitions
+ * to waiting for user review and approval.
+ *
+ * @example
+ * ```typescript
+ * const exitPlanModeTool = new ExitPlanModeTool()
+ * const result = await exitPlanModeTool.execute({})
+ * // Plan is now ready for user review
+ * ```
+ */
+export declare class ExitPlanModeTool extends BaseTool {
+    readonly name = "ExitPlanMode";
+    readonly riskLevel: RiskLevel;
+    readonly description = "Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.\n\n## How This Tool Works\n- You should have already written your plan to the plan file specified in the plan mode system message\n- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote\n- This tool simply signals that you're done planning and ready for the user to review and approve\n- The user will see the contents of your plan file when they review it\n\n## When to Use This Tool\nIMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.\n\n## Handling Ambiguity in Plans\nBefore using this tool, ensure your plan is clear and unambiguous. If there are multiple valid approaches or unclear requirements:\n1. Use the AskUserQuestion tool to clarify with the user\n2. Ask about specific implementation choices (e.g., architectural patterns, which library to use)\n3. Clarify any assumptions that could affect the implementation\n4. Edit your plan file to incorporate user feedback\n5. Only proceed with ExitPlanMode after resolving ambiguities and updating the plan file\n\n## Examples\n\n1. Initial task: \"Search for and understand the implementation of vim mode in the codebase\" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.\n2. Initial task: \"Help me implement yank mode for vim\" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.\n3. Initial task: \"Add a new feature to handle user authentication\" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.\n";
+    readonly parameters: ToolInputSchema;
+    /**
+     * Execute exit plan mode
+     *
+     * @param _args - ExitPlanMode arguments (empty)
+     * @returns MCP-compliant CallToolResult indicating plan mode has been exited
+     */
+    execute(_args: Record<string, unknown>): Promise<CallToolResult>;
+}

package/dist/tool/builtin/glob.d.ts

@@ -0,0 +1,70 @@
+import type { CallToolResult, ToolInputSchema } from '../../types';
+import { BaseTool } from '../base';
+/**
+ * Result of a glob operation
+ */
+export interface GlobResult {
+    /** List of matched file paths (sorted by modification time, newest first) */
+    files: string[];
+    /** Total number of matches found */
+    totalMatches: number;
+    /** Whether results were truncated */
+    truncated: boolean;
+}
+/**
+ * Arguments for the Glob tool
+ */
+export interface GlobArgs {
+    /** The glob pattern to match files against */
+    pattern: string;
+    /** The directory to search in (defaults to cwd) */
+    path?: string;
+}
+/**
+ * Tool for finding files matching glob patterns.
+ *
+ * This tool provides fast file pattern matching that works with any codebase size,
+ * returning matching file paths sorted by modification time.
+ *
+ * @example
+ * ```typescript
+ * const globTool = new GlobTool()
+ * const result = await globTool.execute({
+ *   pattern: '**\/*.ts',
+ *   path: './src'
+ * })
+ * ```
+ */
+export declare class GlobTool extends BaseTool {
+    readonly name = "Glob";
+    readonly description = "Fast file pattern matching tool that works with any codebase size.\n\nUsage notes:\n- Supports glob patterns like \"**/*.js\" or \"src/**/*.ts\"\n- Returns matching file paths sorted by modification time (newest first)\n- Use this tool when you need to find files by name patterns\n- You can call multiple tools in a single response for parallel searches\n\nSupported patterns:\n- `*` matches any sequence of characters except path separator\n- `**` matches any sequence of characters including path separator\n- `?` matches any single character\n- `{a,b}` matches either a or b\n- `[abc]` matches any character in brackets";
+    readonly parameters: ToolInputSchema;
+    /** Current working directory for search */
+    private cwd;
+    constructor(options?: {
+        cwd?: string;
+    });
+    /**
+     * Set the current working directory
+     */
+    setCwd(cwd: string): void;
+    /**
+     * Get the current working directory
+     */
+    getCwd(): string;
+    /**
+     * Execute glob pattern matching
+     *
+     * @param args - Glob arguments
+     * @returns MCP-compliant CallToolResult with matching files
+     */
+    execute(args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Validate and parse arguments
+     */
+    private validateArgs;
+    /**
+     * Recursively walk directory and collect matching files
+     */
+    private walkDirectory;
+}

package/dist/tool/builtin/grep.d.ts

@@ -0,0 +1,122 @@
+import type { CallToolResult, ToolInputSchema } from '../../types';
+import { BaseTool } from '../base';
+export declare function downloadRipgrep(version?: string): Promise<string | null>;
+export declare function ensureRipgrepBinary(version?: string): Promise<string | null>;
+export declare function getRipgrepPath(): Promise<string | null>;
+/**
+ * Output modes for grep results
+ */
+export type GrepOutputMode = 'content' | 'files_with_matches' | 'count';
+/**
+ * Result of a grep operation
+ */
+export interface GrepResult {
+    /** Command exit code */
+    exitCode: number | null;
+    /** Backend used for the search */
+    engine?: 'rg' | 'grep' | 'js';
+    /** Search output */
+    output: string;
+    /** Whether output was truncated */
+    truncated: boolean;
+    /** Whether search timed out */
+    timedOut: boolean;
+    /** Number of matches found (when available) */
+    matchCount?: number;
+}
+/**
+ * Arguments for the Grep tool
+ */
+export interface GrepArgs {
+    /** The regular expression pattern to search for */
+    'pattern': string;
+    /** File or directory to search in */
+    'path'?: string;
+    /** Glob pattern to filter files */
+    'glob'?: string;
+    /** Output mode */
+    'output_mode'?: GrepOutputMode;
+    /** Lines before match */
+    '-B'?: number;
+    /** Lines after match */
+    '-A'?: number;
+    /** Lines before and after match */
+    '-C'?: number;
+    /** Show line numbers */
+    '-n'?: boolean;
+    /** Case insensitive search */
+    '-i'?: boolean;
+    /** File type to search */
+    'type'?: string;
+    /** Limit output to first N lines/entries */
+    'head_limit'?: number;
+    /** Skip first N lines/entries */
+    'offset'?: number;
+    /** Enable multiline mode */
+    'multiline'?: boolean;
+}
+/**
+ * Tool for searching files using ripgrep.
+ *
+ * A powerful search tool built on ripgrep that supports regex patterns,
+ * multiple output modes, and various filtering options.
+ *
+ * @example
+ * ```typescript
+ * const grepTool = new GrepTool()
+ * const result = await grepTool.execute({
+ *   pattern: 'function\\s+\\w+',
+ *   path: './src',
+ *   type: 'ts'
+ * })
+ * ```
+ */
+export declare class GrepTool extends BaseTool {
+    readonly name = "Grep";
+    readonly description = "A powerful search tool built on ripgrep.\n\nUsage notes:\n- Supports full regex syntax (e.g., \"log.*Error\", \"function\\s+\\w+\")\n- Filter files with glob parameter (e.g., \"*.js\", \"**/*.tsx\") or type parameter (e.g., \"js\", \"py\", \"rust\")\n- Output modes: \"content\" shows matching lines, \"files_with_matches\" shows only file paths (default), \"count\" shows match counts\n- Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\\{\\}` to find `interface{}` in Go code)\n- Multiline matching: By default patterns match within single lines only. For cross-line patterns, use multiline: true\n- If ripgrep is not available, this tool falls back to a JS-based search (slower). You can opt into downloading a ripgrep binary via the GrepTool constructor option `allowDownload: true`.";
+    readonly parameters: ToolInputSchema;
+    /** Current working directory for search */
+    private cwd;
+    /** Path to ripgrep binary */
+    private rgPath;
+    /**
+     * If true, the tool may download a ripgrep binary when none is available.
+     *
+     * Default: false (falls back to a JS-based search instead).
+     */
+    private allowDownload;
+    constructor(options?: {
+        cwd?: string;
+        rgPath?: string;
+        allowDownload?: boolean;
+    });
+    /**
+     * Set the current working directory
+     */
+    setCwd(cwd: string): void;
+    /**
+     * Get the current working directory
+     */
+    getCwd(): string;
+    /**
+     * Execute grep search
+     *
+     * @param args - Grep arguments
+     * @returns MCP-compliant CallToolResult with search results
+     */
+    execute(args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Validate and parse arguments
+     */
+    private validateArgs;
+    /**
+     * Build ripgrep command arguments
+     */
+    private buildRgArgs;
+    /**
+     * Run ripgrep command
+     */
+    private runRipgrep;
+    private runJsSearch;
+    private runSystemGrep;
+}

package/dist/tool/builtin/index.d.ts

@@ -0,0 +1,30 @@
+export { AskUserTool } from './askUser';
+export type { AskUserArgs, AskUserResult, Question, QuestionOption } from './askUser';
+export { AstGrepReplaceTool } from './astGrepReplace';
+export type { AstGrepReplaceArgs, AstGrepReplaceResult } from './astGrepReplace';
+export { AstGrepSearchTool } from './astGrepSearch';
+export type { AstGrepMatch, AstGrepSearchArgs, AstGrepSearchResult } from './astGrepSearch';
+export { BashTool } from './bash';
+export type { BashArgs, BashResult } from './bash';
+export { EditTool } from './edit';
+export type { EditArgs, EditResult } from './edit';
+export { EnterPlanModeTool } from './enterPlanMode';
+export type { EnterPlanModeArgs, EnterPlanModeResult } from './enterPlanMode';
+export { ExitPlanModeTool } from './exitPlanMode';
+export type { ExitPlanModeArgs, ExitPlanModeResult } from './exitPlanMode';
+export { GlobTool } from './glob';
+export type { GlobArgs, GlobResult } from './glob';
+export { GrepTool } from './grep';
+export type { GrepArgs, GrepOutputMode, GrepResult } from './grep';
+export { ReadTool } from './read';
+export type { ReadArgs, ReadResult } from './read';
+export { TaskTool } from './task';
+export type { SubagentDefinition, TaskArgs, TaskExecutor, TaskResult } from './task';
+export { TodoPlanTool } from './todoPlan';
+export type { TodoPlanArgs, TodoPlanResult } from './todoPlan';
+export { TodoWriteTool } from './todoWrite';
+export type { TodoItem, TodoStatus, TodoWriteArgs, TodoWriteResult } from './todoWrite';
+export { WebSearchTool } from './webSearch';
+export type { SearchResultItem, WebSearchArgs, WebSearchResult } from './webSearch';
+export { WriteTool } from './write';
+export type { WriteArgs, WriteResult } from './write';

package/dist/tool/builtin/read.d.ts

@@ -0,0 +1,127 @@
+import type { CallToolResult, ToolInputSchema } from '../../types';
+import { BaseTool } from '../base';
+/**
+ * Result of a file read operation
+ */
+export interface ReadResult {
+    /** File content with line numbers */
+    content: string;
+    /** Total number of lines in file */
+    totalLines: number;
+    /** Number of lines returned */
+    linesReturned: number;
+    /** Starting line number (1-based) */
+    startLine: number;
+    /** Whether any lines were truncated */
+    truncated: boolean;
+    /** File size in bytes */
+    fileSize: number;
+    /** Whether this is a binary/image file */
+    isBinary: boolean;
+    /** MIME type if detected */
+    mimeType?: string;
+}
+/**
+ * Arguments for the Read tool
+ */
+export interface ReadArgs {
+    /** The absolute path to the file to read */
+    file_path: string;
+    /** The line number to start reading from (1-based) */
+    offset?: number;
+    /** The number of lines to read */
+    limit?: number;
+}
+/**
+ * Tool for reading files from the filesystem.
+ *
+ * This tool reads files with line number formatting, supporting
+ * offset/limit for large files and detecting binary content.
+ *
+ * @example
+ * ```typescript
+ * const readTool = new ReadTool()
+ * const result = await readTool.execute({
+ *   file_path: '/path/to/file.ts',
+ *   offset: 100,
+ *   limit: 50
+ * })
+ * ```
+ *
+ * @example Restrict reads to a specific directory
+ * ```typescript
+ * const readTool = new ReadTool({
+ *   cwd: '/app/output',
+ *   restrictToDirectory: true
+ * })
+ * // All paths will be resolved relative to /app/output
+ * // Absolute paths and path traversal (../) will be blocked
+ * ```
+ */
+export declare class ReadTool extends BaseTool {
+    readonly name = "Read";
+    /** Current working directory for resolving relative paths */
+    private _cwd;
+    /** Allowed directory for file operations (if set, restricts reads to this directory) */
+    private _allowedDirectory?;
+    constructor(options?: {
+        cwd?: string;
+        /** If set, restricts all file reads to this directory. Paths outside will be rejected. */
+        allowedDirectory?: string;
+    });
+    /**
+     * Dynamic description that includes allowed directory info if configured
+     */
+    get description(): string;
+    /**
+     * Dynamic parameters that include allowed directory info if configured
+     */
+    get parameters(): ToolInputSchema;
+    /**
+     * Set the current working directory
+     */
+    setCwd(cwd: string): void;
+    /**
+     * Get the current working directory
+     */
+    getCwd(): string;
+    /**
+     * Set the allowed directory for file operations
+     */
+    setAllowedDirectory(dir: string | undefined): void;
+    /**
+     * Get the allowed directory for file operations
+     */
+    getAllowedDirectory(): string | undefined;
+    /**
+     * Execute file read
+     *
+     * @param args - Read arguments
+     * @returns MCP-compliant CallToolResult with file content
+     */
+    execute(args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Validate and parse arguments
+     */
+    private validateArgs;
+    /**
+     * Handle binary file (images, PDFs, etc.)
+     */
+    private handleBinaryFile;
+    /**
+     * Handle Jupyter notebook file
+     */
+    private handleJupyterNotebook;
+    /**
+     * Handle text file
+     */
+    private handleTextFile;
+    /**
+     * Format output with line numbers and apply offset/limit
+     */
+    private formatOutput;
+    /**
+     * Format file size for display
+     */
+    private formatSize;
+}

package/dist/tool/builtin/skill.d.ts

@@ -0,0 +1,111 @@
+import type { CallToolResult, ToolInputSchema } from '../../types';
+import { BaseTool } from '../base';
+/**
+ * Definition of an available skill
+ */
+export interface SkillDefinition {
+    /** Unique name of the skill */
+    name: string;
+    /** Description of what the skill does */
+    description: string;
+    /** Additional metadata (extensible for future use) */
+    [key: string]: unknown;
+}
+/**
+ * Result of a skill execution
+ */
+export interface SkillResult {
+    /** Whether the skill execution was successful */
+    success: boolean;
+    /** The skill that was invoked */
+    skill: string;
+    /** Arguments passed to the skill */
+    args?: string;
+    /** Result data from the skill execution */
+    data?: unknown;
+    /** Error message if execution failed */
+    error?: string;
+}
+/**
+ * Arguments for the Skill tool
+ */
+export interface SkillArgs {
+    /** The skill name to invoke */
+    skill: string;
+    /** Optional arguments for the skill */
+    args?: string;
+}
+/**
+ * Skill executor function type
+ */
+export type SkillExecutor = (skill: string, args?: string) => Promise<unknown>;
+/**
+ * @experimental
+ * Tool for executing skills within a conversation.
+ *
+ * This tool allows the agent to invoke specialized skills that provide
+ * domain-specific capabilities. The available skills are configured
+ * at construction time.
+ *
+ * @example
+ * ```typescript
+ * const skillTool = new SkillTool({
+ *   skills: [
+ *     { name: 'pdf', description: 'PDF manipulation toolkit' },
+ *     { name: 'commit', description: 'Git commit helper' }
+ *   ],
+ *   executor: async (skill, args) => {
+ *     // Handle skill execution
+ *   }
+ * })
+ * ```
+ */
+export declare class SkillTool extends BaseTool {
+    readonly name = "Skill";
+    /** Dynamic description built from available skills */
+    readonly description: string;
+    readonly parameters: ToolInputSchema;
+    /** Available skills */
+    private skills;
+    /** Skill executor function */
+    private executor?;
+    constructor(options?: {
+        skills?: SkillDefinition[];
+        executor?: SkillExecutor;
+    });
+    /**
+     * Register a new skill
+     */
+    registerSkill(skill: SkillDefinition): void;
+    /**
+     * Unregister a skill
+     */
+    unregisterSkill(name: string): boolean;
+    /**
+     * Get all available skills
+     */
+    getSkills(): SkillDefinition[];
+    /**
+     * Check if a skill is available
+     */
+    hasSkill(name: string): boolean;
+    /**
+     * Set the skill executor
+     */
+    setExecutor(executor: SkillExecutor): void;
+    /**
+     * Execute a skill
+     *
+     * @param args - Skill arguments
+     * @returns MCP-compliant CallToolResult with skill execution result
+     */
+    execute(args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * Validate and parse arguments
+     */
+    private validateArgs;
+    /**
+     * Build description from available skills
+     */
+    private buildDescription;
+}