@kb-labs/agent-tools 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,729 @@
+import * as _kb_labs_agent_contracts from '@kb-labs/agent-contracts';
+import { RepositoryModel, SpawnAgentRequest, AsyncTask, SpawnAgentResult, KernelState, EvidenceRequirements, ToolCapability, ToolDefinition, ToolResult, ToolResultArtifact } from '@kb-labs/agent-contracts';
+import { ICache } from '@kb-labs/core-platform';
+
+/**
+ * IWorkspaceProvider — abstraction for workspace operations.
+ *
+ * When agent runs on Platform but workspace is on Workspace Agent,
+ * this interface proxies fs/search/git/shell operations through Gateway.
+ *
+ * When agent runs locally (same machine as workspace), LocalWorkspaceProvider
+ * delegates to native fs/child_process (current behavior).
+ *
+ * Tools check `context.workspaceProvider`:
+ * - If set → use provider methods (remote or local)
+ * - If not set → use native fs directly (backwards compatible)
+ *
+ * @see ADR-0017: Workspace Agent Architecture (Phase 3)
+ */
+interface FileReadResult {
+    content: string;
+    totalLines: number;
+    truncated: boolean;
+}
+interface FileStatResult {
+    size: number;
+    isFile: boolean;
+    isDir: boolean;
+    mtime: number;
+}
+interface GrepMatch {
+    file: string;
+    line: number;
+    content: string;
+}
+interface GrepResult {
+    matches: GrepMatch[];
+    truncated: boolean;
+    totalMatches: number;
+}
+interface GlobResult {
+    files: string[];
+    truncated: boolean;
+    totalFiles: number;
+}
+interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface IWorkspaceProvider {
+    /** Read file content with offset/limit */
+    readFile(path: string, offset?: number, limit?: number): Promise<FileReadResult>;
+    /** Write file content */
+    writeFile(path: string, content: string): Promise<void>;
+    /** List directory contents */
+    listDir(path: string, limit?: number): Promise<string[]>;
+    /** Get file/dir stats */
+    stat(path: string): Promise<FileStatResult>;
+    /** Check if path exists */
+    exists(path: string): Promise<boolean>;
+    /** Search file contents (grep) */
+    grep(pattern: string, directory: string, options?: {
+        includes?: string[];
+        excludes?: string[];
+        maxResults?: number;
+        contextLines?: number;
+    }): Promise<GrepResult>;
+    /** Find files by glob pattern */
+    glob(pattern: string, directory: string, options?: {
+        excludes?: string[];
+        maxResults?: number;
+    }): Promise<GlobResult>;
+    /** Execute shell command */
+    shellExec(command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+    }): Promise<ShellResult>;
+}
+
+/**
+ * Tool types and interfaces
+ */
+
+/**
+ * Tool executor function
+ */
+type ToolExecutor = (input: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
+/**
+ * Tool registration
+ */
+interface Tool {
+    definition: ToolDefinition;
+    executor: ToolExecutor;
+}
+interface ToolPolicy {
+    id: string;
+    allows(toolName: string, context: ToolContext): boolean;
+    allowsCapability?(capability: ToolCapability, context: ToolContext, toolName: string): boolean;
+}
+interface ToolExecutionEnvelope {
+    result: ToolResult;
+    artifact: ToolResultArtifact;
+}
+interface SessionMemoryBridge {
+    loadKernelState(): Promise<KernelState | null>;
+    recordConstraint(content: string): Promise<KernelState>;
+    recordCorrection(input: {
+        content: string;
+        invalidates?: string[];
+        asConstraint?: boolean;
+    }): Promise<KernelState>;
+}
+interface ToolResponseRequirements {
+    requirements: EvidenceRequirements;
+    rationale: string;
+}
+/**
+ * Interface for ArchiveMemory (Tier 2: Cold Storage).
+ * Defined here to avoid circular dependency: agent-tools cannot import agent-core.
+ */
+interface IArchiveMemory {
+    recallByFilePath(filePath: string): {
+        fullOutput: string;
+        iteration: number;
+        toolName: string;
+    } | null;
+    recallByToolName(toolName: string, limit?: number): Array<{
+        fullOutput: string;
+        iteration: number;
+        toolName: string;
+        filePath?: string;
+    }>;
+    recallByIteration(iteration: number): Array<{
+        fullOutput: string;
+        iteration: number;
+        toolName: string;
+        filePath?: string;
+    }>;
+    search(keyword: string, limit?: number): Array<{
+        fullOutput: string;
+        toolName: string;
+        iteration: number;
+        filePath?: string;
+    }>;
+    getArchivedFilePaths(): string[];
+    hasFile(filePath: string): boolean;
+    getSummaryHint(): string;
+}
+/**
+ * Tool context (working directory, etc.)
+ */
+interface ToolContext {
+    workingDir: string;
+    repositoryModel?: RepositoryModel;
+    currentTask?: string;
+    sessionId?: string;
+    verbose?: boolean;
+    /** Shared platform cache adapter (optional) */
+    cache?: ICache;
+    /** Files that were read in this session (for edit protection) */
+    filesRead?: Set<string>;
+    /** File content hashes from when files were read (for change detection) */
+    filesReadHash?: Map<string, string>;
+    /** Agent ID for attribution */
+    agentId?: string;
+    /** Archive memory for cold storage recall (Tier 2) */
+    archiveMemory?: IArchiveMemory;
+    /**
+     * If set, only tools whose names are in this set will be registered.
+     * Used by plan mode to restrict both the plan-writer and any sub-agents
+     * it spawns to read-only tools — without touching AgentConfig.
+     */
+    allowedTools?: Set<string>;
+    /** Async task manager for sub-agent delegation (submit/status/collect). */
+    taskManager?: ITaskManager;
+    /**
+     * Set to true by plan_validate tool when the plan passes the quality gate.
+     * Checked by report tool in plan mode — report is blocked until this is set.
+     */
+    planValidationPassed?: boolean;
+    /**
+     * Workspace provider for remote fs/search/shell operations (Cursor-model).
+     * When set, workspace tools proxy through this provider instead of native fs.
+     * When not set, tools use native fs directly (backwards compatible).
+     *
+     * @see ADR-0017: Workspace Agent Architecture (Phase 3)
+     */
+    workspaceProvider?: IWorkspaceProvider;
+    /** Canonical session memory bridge backed by kernel/store artifacts. */
+    sessionMemory?: SessionMemoryBridge;
+    /** Optional resolver for answer-time evidence requirements. */
+    responseRequirementsResolver?: (input: {
+        task?: string;
+        answer: string;
+        kernel: KernelState | null;
+    }) => Promise<ToolResponseRequirements> | ToolResponseRequirements;
+    /** Optional capability map for internal or external tool providers. */
+    toolCapabilitiesByName?: Map<string, ToolCapability[]>;
+}
+/**
+ * Interface for async task management.
+ * Defined here to avoid circular dependency: agent-tools cannot import agent-core.
+ * Implemented by TaskMiddleware in agent-core.
+ */
+interface ITaskManager {
+    submit(description: string, request: SpawnAgentRequest): Promise<AsyncTask>;
+    getStatus(taskId?: string): AsyncTask | AsyncTask[] | null;
+    collect(taskId: string): Promise<SpawnAgentResult>;
+}
+
+declare class ToolRegistry {
+    private tools;
+    private context;
+    constructor(context: ToolContext);
+    /**
+     * Register a tool
+     */
+    register(tool: Tool): void;
+    /**
+     * Get tool by name
+     */
+    get(name: string): Tool | undefined;
+    /**
+     * Get all tool definitions for LLM
+     */
+    getDefinitions(): _kb_labs_agent_contracts.ToolDefinition[];
+    /**
+     * Execute a tool with automatic required-argument validation.
+     * Returns a structured error if required args are missing/null/undefined,
+     * so the agent understands what went wrong and can correct its call.
+     */
+    execute(name: string, input: Record<string, unknown>): Promise<_kb_labs_agent_contracts.ToolResult>;
+    /**
+     * Get sorted list of registered tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Get context
+     */
+    getContext(): ToolContext;
+}
+
+declare class ToolGateway {
+    private readonly context;
+    private readonly policies;
+    private readonly registry;
+    constructor(context: ToolContext, policies?: ToolPolicy[]);
+    getDefinitions(): _kb_labs_agent_contracts.ToolDefinition[];
+    getToolNames(): string[];
+    execute(name: string, input: Record<string, unknown>): Promise<ToolExecutionEnvelope>;
+    private isAllowed;
+    private getToolCapabilities;
+}
+
+/**
+ * Filesystem tools for agent operations
+ *
+ * Features:
+ * - Atomic operations with offset/limit for large files
+ * - Path traversal protection
+ * - Clear error messages for agent understanding
+ * - Size limits to prevent context overflow
+ */
+
+/**
+ * Read file contents with optional line range
+ */
+declare function createFsReadTool(context: ToolContext): Tool;
+/**
+ * Write content to a file
+ */
+declare function createFsWriteTool(context: ToolContext): Tool;
+/**
+ * Edit file by replacing a range of lines
+ */
+declare function createFsPatchTool(context: ToolContext): Tool;
+/**
+ * Edit a file by matching text content and replacing it.
+ * More reliable than line-number-based fs_patch because LLMs
+ * can copy exact text from fs_read output.
+ */
+declare function createFsReplaceTool(context: ToolContext): Tool;
+/**
+ * List files in a directory
+ */
+declare function createFsListTool(context: ToolContext): Tool;
+
+/**
+ * Mass replace tool for batch text replacement across multiple files
+ *
+ * Features:
+ * - Supports literal string or regex patterns
+ * - Glob-based file selection
+ * - File history tracking for rollback
+ * - Dry-run mode for preview
+ * - Safe: validates paths, checks file sizes
+ */
+
+declare function createMassReplaceTool(context: ToolContext): Tool;
+
+/**
+ * Search tools for finding files and content
+ */
+
+/**
+ * Search for files by pattern (glob)
+ */
+declare function createGlobSearchTool(context: ToolContext): Tool;
+/**
+ * Search for text in files (grep)
+ */
+declare function createGrepSearchTool(context: ToolContext): Tool;
+/**
+ * List files in directory
+ */
+declare function createListFilesTool(context: ToolContext): Tool;
+/**
+ * Find files containing specific code pattern (semantic search)
+ * Language-agnostic - works with any programming language
+ */
+declare function createFindDefinitionTool(context: ToolContext): Tool;
+/**
+ * Count lines of code - language agnostic
+ */
+declare function createCodeStatsTool(context: ToolContext): Tool;
+
+/**
+ * Memory tools for persistent context and session management
+ *
+ * ARCHITECTURE:
+ * - Shared memory (.kb/memory/shared/) - persistent across sessions
+ *   - preferences: user preferences (e.g., "use TypeScript strict mode")
+ *   - constraints: project rules (e.g., "never modify /legacy/")
+ *
+ * - Session memory (.kb/memory/session-xxx/) - handled by FileMemory
+ *   - corrections: user corrections for current session
+ *   - findings: agent discoveries
+ *   - blockers: current blockers
+ */
+
+/**
+ * Get shared memory (preferences, constraints, project context)
+ */
+declare function createMemoryGetTool(context: ToolContext): Tool;
+/**
+ * Add user preference to shared memory (persistent)
+ */
+declare function createMemoryPreferenceTool(context: ToolContext): Tool;
+/**
+ * Add constraint to shared memory (persistent)
+ */
+declare function createMemoryConstraintTool(context: ToolContext): Tool;
+/**
+ * Add user correction to session memory
+ * Session-scoped - only valid for current session
+ */
+declare function createMemoryCorrectionTool(context: ToolContext): Tool;
+/**
+ * Add finding to session memory
+ */
+declare function createMemoryFindingTool(context: ToolContext): Tool;
+/**
+ * Add blocker to session memory
+ */
+declare function createMemoryBlockerTool(context: ToolContext): Tool;
+/**
+ * Save session summary (shared)
+ */
+declare function createSessionSaveTool(context: ToolContext): Tool;
+
+/**
+ * archive_recall tool - Retrieve full content from previously-read files
+ * or tool outputs WITHOUT re-reading them.
+ *
+ * This is the agent's interface to Tier 2 (Cold Storage / ArchiveMemory).
+ */
+
+declare function createArchiveRecallTool(context: ToolContext): Tool;
+
+/**
+ * TODO tools for task planning and progress tracking
+ */
+
+/**
+ * Create TODO list with tasks
+ */
+declare function createTodoCreateTool(context: ToolContext): Tool;
+/**
+ * Update TODO item status
+ */
+declare function createTodoUpdateTool(context: ToolContext): Tool;
+/**
+ * Get TODO list status
+ */
+declare function createTodoGetTool(context: ToolContext): Tool;
+
+/**
+ * plan_validate tool — LLM-based plan quality gate.
+ *
+ * Called by the plan-writer agent after drafting a plan to get structured
+ * feedback before reporting it as ready. The LLM evaluator receives:
+ *   - The original user task (so it can judge relevance)
+ *   - The full plan markdown
+ *   - The requested evaluation tier (default: small)
+ *
+ * Returns a human+agent-readable string with:
+ *   - passed: yes/no
+ *   - score: 0.0–1.0
+ *   - Per-dimension breakdown (specificity, actionability, completeness, verification)
+ *   - Concrete, actionable feedback for each failing dimension
+ *
+ * The agent uses this output to decide:
+ *   1. passed=yes → call report() with the plan
+ *   2. passed=no  → revise the plan based on feedback and call plan_validate again
+ *   3. After 3 failed attempts → call ask_user() with the plan + issues
+ */
+
+declare function createPlanValidateTool(context: ToolContext): Tool;
+
+/**
+ * plan_write tool — write/update the session plan file on disk.
+ *
+ * Enables iterative plan building: agent writes plan incrementally during
+ * exploration, rather than generating everything at the end in one shot.
+ * The plan survives context compaction because it lives on disk.
+ *
+ * Plan file location: .kb/agents/sessions/{sessionId}/plan.md
+ * (resolved from context.sessionId and context.workingDir)
+ */
+
+declare function createPlanWriteTool(context: ToolContext): Tool;
+
+/**
+ * Shell execution tool
+ */
+
+/**
+ * Execute shell command
+ */
+declare function createShellExecTool(context: ToolContext): Tool;
+
+/**
+ * Async task tools — fire-and-forget sub-agent operations.
+ *
+ * - task_submit:  Start a sub-agent in the background, get a task ID immediately
+ * - task_status:  Check status of one or all async tasks
+ * - task_collect: Wait for a specific task to complete and get its result
+ */
+
+/**
+ * Submit an async task (fire-and-forget sub-agent).
+ */
+declare function createTaskSubmitTool(context: ToolContext): Tool;
+/**
+ * Check status of async tasks.
+ */
+declare function createTaskStatusTool(context: ToolContext): Tool;
+/**
+ * Wait for a specific async task to complete and get its full result.
+ */
+declare function createTaskCollectTool(context: ToolContext): Tool;
+
+/**
+ * User interaction tools
+ */
+
+/**
+ * Ask user a question (interactive mode only)
+ */
+declare function createAskUserTool(_context: ToolContext): Tool;
+
+/**
+ * Reporting tools - for sub-agents to communicate with parent agent
+ */
+
+/**
+ * Ask parent agent for help when stuck or uncertain.
+ * Sub-agents use this to escalate to the main agent for guidance.
+ */
+declare function createAskParentTool(_context: ToolContext): Tool;
+/**
+ * Report findings and exit. Used by agents to provide synthesized answer
+ * and signal early exit when task is complete.
+ */
+declare function createReportTool(context: ToolContext): Tool;
+
+/**
+ * Tool registration and exports
+ *
+ * Tools are organized by category:
+ *   filesystem/  — fs_read, fs_write, fs_patch, fs_replace, fs_list, mass_replace
+ *   search/      — glob_search, grep_search, find_definition, code_stats
+ *   memory/      — memory_*, archive_recall, session_save
+ *   planning/    — plan_validate, plan_write, todo_*
+ *   execution/   — shell_exec, task_submit/status/collect
+ *   interaction/ — ask_user, ask_parent, report
+ *   shared/      — tool-error (utilities)
+ */
+
+/**
+ * Create and register all tools
+ */
+declare function createToolRegistry(context: ToolContext): ToolRegistry;
+
+/**
+ * Centralized configuration constants for agent tools.
+ *
+ * All magic numbers and default values live here — tool implementations
+ * import from this module instead of defining inline constants.
+ */
+declare const FILESYSTEM_CONFIG: {
+    /** Hard cap on file size to read (500KB) — prevents context overflow */
+    readonly maxFileSize: 500000;
+    /** Hard cap on lines returned per read — prevents context overflow */
+    readonly maxLinesPerRead: 2000;
+    /** Default lines to return when not specified — read whole file up to maxLinesPerRead */
+    readonly defaultLines: 2000;
+    /** Hard cap on content size for write operations (1MB) */
+    readonly maxWriteSize: 1000000;
+    /** Default limit for directory listing */
+    readonly defaultListLimit: 50;
+    /** Maximum limit for directory listing */
+    readonly maxListLimit: 200;
+    /** Max output characters before trimming (prevents context explosion) */
+    readonly maxOutputChars: 12000;
+};
+declare const SEARCH_CONFIG: {
+    /** Timeout for search commands (15s) — fail fast, don't burn iterations */
+    readonly timeoutMs: 15000;
+    /** Max stdout buffer for search commands (8MB) */
+    readonly maxBuffer: number;
+    /** Default result limit — enough for actionable results */
+    readonly defaultResultLimit: 50;
+    /** Maximum result limit */
+    readonly maxResultLimit: 200;
+    /** Max output characters before trimming */
+    readonly maxOutputChars: 8000;
+    /**
+     * Directories excluded from search by default.
+     * These are never useful for code understanding and often huge.
+     * Pass exclude=[] to override entirely, or exclude=[...custom] to replace the list.
+     */
+    readonly defaultExcludes: string[];
+};
+declare const SHELL_CONFIG: {
+    /** Max stdout buffer — aligned with SEARCH_CONFIG (16MB) */
+    readonly maxBuffer: number;
+};
+declare const TODO_CONFIG: {
+    /** Cache key prefix for todo lists */
+    readonly cachePrefix: "agent:todo:";
+    /** TTL for cached todo lists (7 days) */
+    readonly cacheTtlMs: number;
+};
+declare const DELEGATION_CONFIG: {
+    /** Default max iterations for spawned sub-agents (safety net — token budget is primary control) */
+    readonly defaultMaxIterations: 100;
+    /** Default budget fraction (50% of parent remaining — sub-agents need real budget) */
+    readonly defaultBudgetFraction: 0.5;
+};
+/**
+ * Sub-agent tool allowlists and iteration defaults per preset.
+ *
+ * Single source of truth: lives in agent-tools because it knows tool names.
+ * agent-core receives these as `allowedTools: string[]` data via SpawnAgentRequest
+ * (no import from agent-tools needed — correct dependency direction).
+ */
+declare const SUB_AGENT_PRESETS: {
+    /** Read-only exploration and evidence gathering. */
+    readonly research: {
+        readonly tools: Set<string>;
+        readonly maxIterations: 50;
+    };
+    /** Full read/write capabilities for implementation tasks. */
+    readonly execute: {
+        readonly tools: Set<string>;
+        readonly maxIterations: 100;
+    };
+    /** Code review and verification: read + shell (linters, tests). */
+    readonly review: {
+        readonly tools: Set<string>;
+        readonly maxIterations: 50;
+    };
+    /**
+     * Adversarial verification: independent agent that checks another agent's work.
+     * Has read + shell access to run tests, check imports, verify builds.
+     * Reports PASS/FAIL verdict with evidence.
+     */
+    readonly verification: {
+        readonly tools: Set<string>;
+        readonly maxIterations: 25;
+    };
+};
+declare const MASS_REPLACE_CONFIG: {
+    /** Hard cap on file size to process (1MB) — same as maxWriteSize */
+    readonly maxFileSize: 1000000;
+    /** Maximum number of files to process in one operation */
+    readonly maxFiles: 100;
+};
+/**
+ * Tools available in plan mode — read-only exploration + async task delegation.
+ * Used as `allowedTools` in ToolContext for both the plan-writer and any
+ * research sub-agents it spawns via task_submit. Single source of truth:
+ * lives in agent-tools so both agent-core and tests can import it without
+ * creating a circular dependency.
+ */
+declare const PLAN_READ_ONLY_TOOL_NAMES: Set<string>;
+/**
+ * Source file extensions grouped by language.
+ * Use ALL_SOURCE_EXTENSIONS or the helper functions for CLI flags.
+ */
+declare const SOURCE_FILE_EXTENSIONS: {
+    readonly typescript: readonly ["ts", "tsx"];
+    readonly javascript: readonly ["js", "jsx"];
+    readonly python: readonly ["py"];
+    readonly csharp: readonly ["cs"];
+    readonly java: readonly ["java"];
+    readonly go: readonly ["go"];
+    readonly rust: readonly ["rs"];
+    readonly ruby: readonly ["rb"];
+    readonly php: readonly ["php"];
+    readonly swift: readonly ["swift"];
+    readonly kotlin: readonly ["kt"];
+    readonly scala: readonly ["scala"];
+    readonly cpp: readonly ["cpp", "c", "h", "cc", "cxx"];
+};
+/** Flat list of all source file extensions */
+declare const ALL_SOURCE_EXTENSIONS: readonly string[];
+/**
+ * Build `--include="*.ext"` flags for ripgrep / grep.
+ * @example toRgIncludes(ALL_SOURCE_EXTENSIONS)
+ * // → '--include="*.ts" --include="*.tsx" ...'
+ */
+declare function toRgIncludes(exts: readonly string[]): string;
+/**
+ * Build `-name "*.ext"` flags for `find` (joined with ` -o `).
+ * @example toFindNames(ALL_SOURCE_EXTENSIONS)
+ * // → '-name "*.ts" -o -name "*.tsx" ...'
+ */
+declare function toFindNames(exts: readonly string[]): string;
+
+/**
+ * Shared utilities for agent tool implementations.
+ */
+/**
+ * Normalize offset and limit parameters from tool input.
+ *
+ * Handles NaN, negative values, and enforces configured max/default limits.
+ * Previously duplicated in filesystem.ts and search.ts.
+ *
+ * @example
+ * const { offset, limit } = normalizeOffsetLimit(input, {
+ *   defaultLimit: FILESYSTEM_CONFIG.defaultLines,
+ *   maxLimit: FILESYSTEM_CONFIG.maxLinesPerRead,
+ * });
+ */
+declare function normalizeOffsetLimit(input: Record<string, unknown>, config: {
+    defaultLimit: number;
+    maxLimit: number;
+}): {
+    offset: number;
+    limit: number;
+};
+/**
+ * Validate that a file path stays within the working directory.
+ *
+ * Resolves symlinks to prevent symlink-based traversal bypasses.
+ * Uses path.relative() which is more robust than startsWith().
+ *
+ * Previously duplicated in filesystem.ts and mass-replace.ts.
+ */
+declare function validatePath(workingDir: string, filePath: string): {
+    valid: boolean;
+    resolved: string;
+    error?: string;
+};
+/**
+ * Suggest a similar directory when the requested one doesn't exist.
+ *
+ * Handles common agent mistakes like nested paths (e.g. "foo/bar" when "foo-bar/" exists).
+ * Returns null if no good suggestion found.
+ */
+declare function suggestDirectory(workingDir: string, requestedDir: string): string | null;
+
+/**
+ * RemoteWorkspaceProvider — proxies workspace operations to Workspace Agent via Gateway.
+ *
+ * Used when Agent Runner runs on Platform but needs to access files
+ * on a remote Workspace Agent (Cursor-model: "brain" on server, "hands" on client).
+ *
+ * Uses Gateway dispatcher to send capability calls to connected Workspace Agent.
+ *
+ * @see ADR-0017: Workspace Agent Architecture (Phase 3)
+ */
+
+/** Gateway dispatcher call function (injected, avoids direct dependency on Gateway) */
+type DispatchFn = (adapter: string, method: string, args: unknown[]) => Promise<unknown>;
+interface RemoteWorkspaceProviderOptions {
+    /** Function to dispatch capability calls via Gateway */
+    dispatch: DispatchFn;
+}
+declare class RemoteWorkspaceProvider implements IWorkspaceProvider {
+    private readonly opts;
+    constructor(opts: RemoteWorkspaceProviderOptions);
+    readFile(path: string, offset?: number, limit?: number): Promise<FileReadResult>;
+    writeFile(path: string, content: string): Promise<void>;
+    listDir(path: string, limit?: number): Promise<string[]>;
+    stat(path: string): Promise<FileStatResult>;
+    exists(path: string): Promise<boolean>;
+    grep(pattern: string, directory: string, options?: {
+        includes?: string[];
+        excludes?: string[];
+        maxResults?: number;
+        contextLines?: number;
+    }): Promise<GrepResult>;
+    glob(pattern: string, directory: string, options?: {
+        excludes?: string[];
+        maxResults?: number;
+    }): Promise<GlobResult>;
+    shellExec(command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+    }): Promise<ShellResult>;
+}
+
+export { ALL_SOURCE_EXTENSIONS, DELEGATION_CONFIG, type DispatchFn, FILESYSTEM_CONFIG, type FileReadResult, type FileStatResult, type GlobResult, type GrepMatch, type GrepResult, type IArchiveMemory, type ITaskManager, type IWorkspaceProvider, MASS_REPLACE_CONFIG, PLAN_READ_ONLY_TOOL_NAMES, RemoteWorkspaceProvider, SEARCH_CONFIG, SHELL_CONFIG, SOURCE_FILE_EXTENSIONS, SUB_AGENT_PRESETS, type SessionMemoryBridge, type ShellResult, TODO_CONFIG, type Tool, type ToolContext, type ToolExecutionEnvelope, type ToolExecutor, ToolGateway, type ToolPolicy, ToolRegistry, type ToolResponseRequirements, createArchiveRecallTool, createAskParentTool, createAskUserTool, createCodeStatsTool, createFindDefinitionTool, createFsListTool, createFsPatchTool, createFsReadTool, createFsReplaceTool, createFsWriteTool, createGlobSearchTool, createGrepSearchTool, createListFilesTool, createMassReplaceTool, createMemoryBlockerTool, createMemoryConstraintTool, createMemoryCorrectionTool, createMemoryFindingTool, createMemoryGetTool, createMemoryPreferenceTool, createPlanValidateTool, createPlanWriteTool, createReportTool, createSessionSaveTool, createShellExecTool, createTaskCollectTool, createTaskStatusTool, createTaskSubmitTool, createTodoCreateTool, createTodoGetTool, createTodoUpdateTool, createToolRegistry, normalizeOffsetLimit, suggestDirectory, toFindNames, toRgIncludes, validatePath };