@morphllm/morphsdk 0.2.28 → 0.2.38

package/dist/tools/browser/openai.d.ts

@@ -0,0 +1,73 @@
+import { ChatCompletionTool } from 'openai/resources/chat/completions.mjs';
+import { BrowserTaskInput, BrowserConfig, BrowserTaskResult } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * OpenAI SDK adapter for browser automation tool
+ */
+
+/**
+ * OpenAI tool definition for browser automation
+ */
+declare const browserTool: ChatCompletionTool;
+/**
+ * Execute a browser task (for use in tool call handling)
+ *
+ * @param input - Tool input parameters (may be JSON string)
+ * @param config - Optional browser worker configuration
+ * @returns Task execution result
+ */
+declare function execute(input: BrowserTaskInput | string, config?: BrowserConfig): Promise<BrowserTaskResult>;
+/**
+ * Format browser task result for OpenAI tool result
+ *
+ * Returns a concise summary suitable for agent context. The full result object
+ * (with urls, errors, action_history, judgement, etc.) is available when calling
+ * execute() directly, but this formatted string omits those details to save tokens.
+ *
+ * @param result - Browser task result with full history data
+ * @returns Formatted string summary for tool result
+ */
+declare function formatResult(result: BrowserTaskResult): string;
+/**
+ * Get system prompt for browser automation
+ */
+declare function getSystemPrompt(): string;
+/**
+ * Create a configured browser tool with execute and formatResult methods
+ *
+ * @param config - Browser worker configuration
+ * @returns Tool definition with execute and formatResult methods
+ *
+ * @example
+ * ```typescript
+ * import OpenAI from 'openai';
+ * import { createBrowserTool } from 'morphsdk/tools/browser/openai';
+ *
+ * const tool = createBrowserTool({
+ *   apiUrl: 'https://browser-worker.example.com'
+ * });
+ *
+ * const client = new OpenAI();
+ *
+ * const response = await client.chat.completions.create({
+ *   model: 'gpt-4o',
+ *   tools: [tool], // tool itself is the ChatCompletionTool
+ *   messages: [{
+ *     role: 'user',
+ *     content: 'Test the checkout at https://3000-abc.e2b.dev'
+ *   }]
+ * });
+ *
+ * // Execute and format
+ * const result = await tool.execute(toolCallArgs);
+ * const formatted = tool.formatResult(result);
+ * ```
+ */
+declare function createBrowserTool(config?: BrowserConfig): ChatCompletionTool & {
+    execute: (input: BrowserTaskInput | string) => Promise<BrowserTaskResult>;
+    formatResult: (result: BrowserTaskResult) => string;
+    getSystemPrompt: () => string;
+};
+
+export { browserTool, createBrowserTool, execute, formatResult, getSystemPrompt };

package/dist/tools/browser/prompts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tool descriptions and prompts for AI models
+ */
+declare const BROWSER_TOOL_DESCRIPTION = "Test and verify your implemented code in a live browser. This tool executes natural language test instructions and returns a video recording plus detailed logs to help you debug issues.\n\n## When to Use\nUse this AFTER coding is complete to verify your implementation:\n- You've finished writing/modifying code and need to verify it works\n- You need to test user interactions end-to-end (clicks, forms, navigation)\n- You want to catch runtime errors, console warnings, or network failures\n- You need visual confirmation that UI elements render and behave correctly\n\n## What You Get Back\nThe tool returns debugging artifacts to help you identify and fix issues:\n- **Video recording**: Watch exactly what happened in the browser session\n- **Console logs**: All console.log, warnings, and errors with timestamps\n- **Network logs**: Failed requests, 404s, API errors with screenshots\n- **Error screenshots**: Visual snapshots captured when errors occur\n\n## How to Write Good Tests\nBe specific about the user journey you're testing:\n\u274C Bad: \"Test the login feature\"\n\u2705 Good: \"Navigate to /login, enter 'test@example.com' and 'password123', click the Login button, verify we reach the /dashboard page\"\n\nInclude verification steps:\n\u2705 \"Click the Add Item button, verify the item appears in the list\"\n\u2705 \"Submit the form, verify a success message is displayed\"\n\n## Iterating on Failures\n1. Run the test and review the video + logs\n2. Identify the specific issue (console error, failed request, wrong behavior)\n3. Fix the code based on the evidence\n4. Re-run the test to verify the fix\n5. Repeat until test passes\n\n## Requirements\n- **URL**: Must be publicly accessible (use tunnels like ngrok, Cloudflare, or deploy to staging)\n- **Timing**: Use this after implementation, not during coding\n- **Complexity**: Set max_steps higher (20-30) for multi-step user workflows";
+declare const BROWSER_SYSTEM_PROMPT = "You are an AI agent designed to automate browser tasks to accomplish the <user_request>. Respond with a valid JSON object in the format: {\"thinking\": \"Reason step-by-step about your current state, history, and the user request to decide your next goal and action. Analyze the browser state and screenshot to confirm the outcome of your last action.\", \"evaluation_previous_goal\": \"A concise, one-sentence evaluation of your last action's outcome (e.g., Success, Failure, or Uncertain).\", \"memory\": \"1-3 sentences summarizing key information and progress so far. This helps you track progress across multiple steps (e.g., items collected, pages visited).\", \"next_goal\": \"A clear, one-sentence description of your immediate next objective.\", \"action\": [{\"action_name\": {\"parameter\": \"value\"}}]}";
+
+export { BROWSER_SYSTEM_PROMPT, BROWSER_TOOL_DESCRIPTION };

package/dist/tools/browser/types.d.ts

@@ -0,0 +1,255 @@
+import { RetryConfig } from '../utils/resilience.js';
+
+/**
+ * Type definitions for browser automation tool
+ */
+
+/**
+ * Available browser automation models
+ */
+type BrowserModel = 'gemini-flash-latest' | 'morph-computer-use-v0';
+/**
+ * Configuration for the browser worker service
+ */
+interface BrowserConfig {
+    /** Browser worker API URL (default: https://browser.morphllm.com) */
+    apiUrl?: string;
+    /** Morph API key for authentication (required in production) */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 1000000) */
+    timeout?: number;
+    /** Retry configuration for API calls */
+    retryConfig?: RetryConfig;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Input parameters for browser automation task
+ */
+interface BrowserTaskInput {
+    /** Natural language description of what to do */
+    task: string;
+    /** Starting URL (e.g., https://3000-xyz.e2b.dev) */
+    url?: string;
+    /** Maximum number of browser actions to take (1-50, default: 10) */
+    max_steps?: number;
+    /** Model to use for task execution (default: morph-computer-use-v0) */
+    model?: BrowserModel;
+    /** Browserless region: 'sfo' (US West) or 'lon' (Europe) */
+    region?: 'sfo' | 'lon';
+    /** Enable stealth mode to avoid bot detection (default: true) */
+    stealth?: boolean;
+    /** Browser viewport width (default: 1280) */
+    viewport_width?: number;
+    /** Browser viewport height (default: 720) */
+    viewport_height?: number;
+    /** User-defined reference/tracking ID (e.g., "PR-1234", "jira-PROJ-567") */
+    external_id?: string;
+    /** Optional repository ID to associate with this session */
+    repo_id?: string;
+    /** Optional commit UUID to associate with this session */
+    commit_id?: string;
+    /** Record session video to S3 (default: false) */
+    record_video?: boolean;
+    /** Video width (default: 1280) */
+    video_width?: number;
+    /** Video height (default: 720) */
+    video_height?: number;
+    /** Serialized structured output schema (internal use) */
+    structured_output?: string;
+}
+/**
+ * Input with Zod schema for structured output
+ */
+interface BrowserTaskInputWithSchema<T> extends Omit<BrowserTaskInput, 'structured_output'> {
+    /** Zod schema for structured output */
+    schema: any;
+}
+/**
+ * Result from executing a browser task
+ */
+interface BrowserTaskResult {
+    /** Whether the task completed successfully */
+    success: boolean;
+    /** Task result or findings */
+    result?: string;
+    /** Error message if task failed */
+    error?: string;
+    /** Number of browser actions taken */
+    steps_taken?: number;
+    /** Total execution time in milliseconds */
+    execution_time_ms?: number;
+    /** All URLs visited during execution */
+    urls?: (string | null)[];
+    /** Names of all actions executed */
+    action_names?: string[];
+    /** Per-step errors (null for steps without errors) */
+    errors?: (string | null)[];
+    /** All model actions with parameters */
+    model_actions?: any[];
+    /** Whether agent marked task as done */
+    is_done?: boolean;
+    /** Truncated action history with essential fields */
+    action_history?: any[][];
+    /** All action results */
+    action_results?: any[];
+    /** Whether any errors occurred */
+    has_errors?: boolean;
+    /** Total number of steps executed */
+    number_of_steps?: number;
+    /** Judge validation result if available */
+    judgement?: {
+        reasoning?: string;
+        verdict: boolean;
+        failure_reason?: string;
+        impossible_task?: boolean;
+        reached_captcha?: boolean;
+    };
+    /** Whether judge validated the execution */
+    is_validated?: boolean;
+    /** UUID of saved replay record (if session replay enabled) */
+    replay_id?: string;
+    /** Browserless replay URL (if session replay enabled) */
+    replay_url?: string;
+    /** Recording ID (if record_video=true) */
+    recording_id?: string;
+    /** Recording status: PENDING, PROCESSING, COMPLETED, ERROR */
+    recording_status?: string;
+    /** Task ID for async task tracking */
+    task_id?: string;
+    /** Task status: pending, running, completed, failed */
+    status?: string;
+    /** Structured output (JSON string) */
+    output?: string;
+    /** Live session debug URL for real-time viewing (WebRTC streaming) */
+    debugUrl?: string;
+}
+/**
+ * Configuration for live session viewing
+ */
+interface LiveSessionOptions {
+    /** Enable or disable remote control (default: true for headful, varies for headless) */
+    interactive?: boolean;
+    /** UI theme: 'dark' or 'light' (headless only, default: 'dark') */
+    theme?: 'dark' | 'light';
+    /** Show or hide navigation controls (headless only, default: true) */
+    showControls?: boolean;
+    /** Focus view on specific page/tab ID (headless only) */
+    pageId?: string;
+    /** Display specific tab by index (headless only) */
+    pageIndex?: string;
+}
+/**
+ * Configuration for iframe generation
+ */
+interface IframeOptions extends LiveSessionOptions {
+    /** Iframe width (default: '100%') */
+    width?: string | number;
+    /** Iframe height (default: '600px') */
+    height?: string | number;
+    /** Additional inline styles */
+    style?: string;
+    /** CSS class name */
+    className?: string;
+}
+/**
+ * Task result with convenience methods for async execution
+ */
+interface BrowserTaskWithPromise extends BrowserTaskResult {
+    task_id: string;
+    /** Live URL to watch task execution in real-time */
+    liveUrl: string;
+    /** Wait for task completion */
+    complete: (pollConfig?: {
+        interval?: number;
+        timeout?: number;
+    }) => Promise<BrowserTaskResult>;
+    /** Get live session URL with optional parameters (Steel.dev) - throws if debugUrl not available */
+    getLiveUrl: (options?: LiveSessionOptions) => string;
+    /** Get iframe HTML for embedding live session - throws if debugUrl not available */
+    getLiveIframe: (optionsOrPreset?: string | IframeOptions) => string;
+    /** Get complete embed code snippet - throws if debugUrl not available */
+    getEmbedCode: () => string;
+}
+/**
+ * Task result with schema validation
+ */
+interface BrowserTaskWithPromiseAndSchema<T> extends BrowserTaskResult {
+    task_id: string;
+    /** Live URL to watch task execution in real-time */
+    liveUrl: string;
+    /** Parsed and validated output */
+    parsed: T | null;
+    /** Wait for task completion with schema validation */
+    complete: (pollConfig?: {
+        interval?: number;
+        timeout?: number;
+    }) => Promise<BrowserTaskResult & {
+        parsed: T | null;
+    }>;
+    /** Get live session URL with optional parameters - throws if debugUrl not available */
+    getLiveUrl: (options?: LiveSessionOptions) => string;
+    /** Get iframe HTML for embedding live session - throws if debugUrl not available */
+    getLiveIframe: (optionsOrPreset?: string | IframeOptions) => string;
+    /** Get complete embed code snippet - throws if debugUrl not available */
+    getEmbedCode: () => string;
+}
+/**
+ * Recording status and metadata
+ */
+interface RecordingStatus {
+    /** Recording ID */
+    id: string;
+    /** Current status */
+    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'ERROR';
+    /** Presigned S3 URL for rrweb replay JSON (interactive DOM replay) */
+    replay_url?: string;
+    /** Presigned S3 URL for network logs (NDJSON format) */
+    network_url?: string;
+    /** Presigned S3 URL for console logs (NDJSON format) */
+    console_url?: string;
+    /** Presigned S3 URL for native browser video (WebM or MP4 format, real-time recording) */
+    video_url?: string;
+    /** Total rrweb events captured */
+    total_events?: number;
+    /** Total bytes of all files */
+    file_size?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Error message if status=ERROR */
+    error?: string;
+    /** When recording was created */
+    created_at: string;
+}
+/**
+ * Browser error with screenshot captured at error time
+ */
+interface BrowserError {
+    /** Error type: console error or network error */
+    type: 'console' | 'network';
+    /** Error message */
+    message: string;
+    /** URL where error occurred */
+    url?: string;
+    /** CDP timestamp in seconds since browser start */
+    timestamp: number;
+    /** Presigned S3 URL to screenshot JPEG (captured 500ms after error) */
+    screenshot_url?: string;
+    /** When screenshot was captured (Unix timestamp) */
+    captured_at?: number;
+    /** HTTP status code (for network errors) */
+    status?: number;
+}
+/**
+ * Response from getErrors()
+ */
+interface ErrorsResponse {
+    /** Recording ID */
+    recording_id: string;
+    /** Total number of errors */
+    total_errors: number;
+    /** Errors with real-time screenshots */
+    errors: BrowserError[];
+}
+
+export type { BrowserConfig, BrowserError, BrowserModel, BrowserTaskInput, BrowserTaskInputWithSchema, BrowserTaskResult, BrowserTaskWithPromise, BrowserTaskWithPromiseAndSchema, ErrorsResponse, IframeOptions, LiveSessionOptions, RecordingStatus };

package/dist/tools/browser/vercel.d.ts

@@ -0,0 +1,69 @@
+import * as ai from 'ai';
+import { BrowserConfig } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * Create Vercel AI SDK tool for browser automation
+ *
+ * @param config - Optional browser worker configuration
+ * @returns Vercel AI SDK tool
+ *
+ * @example
+ * ```typescript
+ * import { generateText } from 'ai';
+ * import { anthropic } from '@ai-sdk/anthropic';
+ * import { createBrowserTool } from 'morphsdk/tools/browser/vercel';
+ *
+ * const browserTool = createBrowserTool({
+ *   apiUrl: 'https://browser-worker.example.com'
+ * });
+ *
+ * const result = await generateText({
+ *   model: anthropic('claude-sonnet-4-5-20250929'),
+ *   tools: { browserTask: browserTool },
+ *   prompt: 'Test the checkout flow at https://3000-abc.e2b.dev',
+ *   maxSteps: 5
+ * });
+ * ```
+ */
+declare function createBrowserTool(config?: BrowserConfig): ai.Tool<{
+    task: string;
+    max_steps: number;
+    region: "sfo" | "lon";
+    url?: string | undefined;
+}, {
+    success: boolean;
+    result: string | undefined;
+    steps_taken: number | undefined;
+    execution_time_ms: number | undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string | undefined;
+    result?: undefined;
+    steps_taken?: undefined;
+    execution_time_ms?: undefined;
+}>;
+/**
+ * Default browser tool for Vercel AI SDK
+ */
+declare const browserTool: ai.Tool<{
+    task: string;
+    max_steps: number;
+    region: "sfo" | "lon";
+    url?: string | undefined;
+}, {
+    success: boolean;
+    result: string | undefined;
+    steps_taken: number | undefined;
+    execution_time_ms: number | undefined;
+    error?: undefined;
+} | {
+    success: boolean;
+    error: string | undefined;
+    result?: undefined;
+    steps_taken?: undefined;
+    execution_time_ms?: undefined;
+}>;
+
+export { browserTool, createBrowserTool };

package/dist/tools/codebase_search/anthropic.d.ts

@@ -0,0 +1,40 @@
+import { Tool } from '@anthropic-ai/sdk/resources/messages';
+import { CodebaseSearchConfig, CodebaseSearchInput, CodebaseSearchResult } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * Anthropic SDK adapter for codebase_search tool
+ */
+
+/**
+ * Create Anthropic-native codebase_search tool with execute and formatResult methods
+ *
+ * @param config - Configuration with repoId
+ * @returns Anthropic Tool definition with execute and formatResult methods
+ *
+ * @example
+ * ```ts
+ * import Anthropic from '@anthropic-ai/sdk';
+ * import { createCodebaseSearchTool } from 'morphsdk/tools/anthropic';
+ *
+ * const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+ * const tool = createCodebaseSearchTool({ repoId: 'my-project' });
+ *
+ * const response = await client.messages.create({
+ *   model: "claude-sonnet-4-5-20250929",
+ *   tools: [tool], // tool itself is the Tool definition
+ *   messages: [{ role: "user", content: "Find authentication code" }]
+ * });
+ *
+ * // Execute tool and format result
+ * const result = await tool.execute(toolUseBlock.input);
+ * const formatted = tool.formatResult(result);
+ * ```
+ */
+declare function createCodebaseSearchTool(config: CodebaseSearchConfig): Tool & {
+    execute: (input: CodebaseSearchInput) => Promise<CodebaseSearchResult>;
+    formatResult: (result: CodebaseSearchResult) => string;
+    getSystemPrompt: () => string;
+};
+
+export { createCodebaseSearchTool };

package/dist/tools/codebase_search/core.d.ts

@@ -0,0 +1,40 @@
+import { CodebaseSearchResult, CodebaseSearchInput, CodebaseSearchConfig } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * Core implementation for codebase search
+ * Calls Morph rerank service for two-stage semantic search
+ */
+
+/**
+ * CodebaseSearch client for programmatic semantic search
+ */
+declare class CodebaseSearchClient {
+    private config;
+    constructor(config?: {
+        apiKey?: string;
+        debug?: boolean;
+        timeout?: number;
+        retryConfig?: any;
+    });
+    /**
+     * Execute a semantic code search
+     *
+     * @param input - Search parameters including query, repoId, and target directories
+     * @param overrides - Optional config overrides for this operation
+     * @returns Search results with ranked code matches
+     */
+    search(input: {
+        query: string;
+        repoId: string;
+        target_directories?: string[];
+        explanation?: string;
+        limit?: number;
+    }, overrides?: any): Promise<CodebaseSearchResult>;
+}
+/**
+ * Execute semantic code search
+ */
+declare function executeCodebaseSearch(input: CodebaseSearchInput, config: CodebaseSearchConfig): Promise<CodebaseSearchResult>;
+
+export { CodebaseSearchClient, executeCodebaseSearch };

package/dist/tools/codebase_search/index.d.ts

@@ -0,0 +1,10 @@
+export { executeCodebaseSearch } from './core.js';
+export { CODEBASE_SEARCH_DESCRIPTION, CODEBASE_SEARCH_SYSTEM_PROMPT } from './prompts.js';
+export { CodeSearchResult, CodebaseSearchConfig, CodebaseSearchInput, CodebaseSearchResult, SearchStats } from './types.js';
+export { createCodebaseSearchTool as anthropicCodebaseSearchTool } from './anthropic.js';
+export { createCodebaseSearchTool as openaiCodebaseSearchTool } from './openai.js';
+export { createCodebaseSearchTool as vercelCodebaseSearchTool } from './vercel.js';
+import '../utils/resilience.js';
+import '@anthropic-ai/sdk/resources/messages';
+import 'openai/resources/chat/completions';
+import 'ai';

package/dist/tools/codebase_search/openai.d.ts

@@ -0,0 +1,87 @@
+import { ChatCompletionTool } from 'openai/resources/chat/completions';
+import { CodebaseSearchConfig, CodebaseSearchInput, CodebaseSearchResult } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * OpenAI SDK adapter for codebase_search tool
+ */
+
+/**
+ * Direct codebase_search tool definition
+ * Use this when you want to pass config at execute time
+ */
+declare const codebaseSearchTool: ChatCompletionTool;
+/**
+ * Create OpenAI-native codebase_search tool with execute and formatResult methods
+ *
+ * @param config - Configuration with repoId
+ * @returns OpenAI ChatCompletionTool definition with methods
+ *
+ * @example
+ * ```ts
+ * import OpenAI from 'openai';
+ * import { createCodebaseSearchTool } from 'morphsdk/tools/openai';
+ *
+ * const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ * const tool = createCodebaseSearchTool({ repoId: 'my-project' });
+ *
+ * const response = await client.chat.completions.create({
+ *   model: "gpt-4o",
+ *   tools: [tool], // tool itself is the ChatCompletionTool
+ *   messages: [{ role: "user", content: "Find authentication code" }]
+ * });
+ *
+ * // Execute and format
+ * const result = await tool.execute(toolCallArgs);
+ * const formatted = tool.formatResult(result);
+ * ```
+ */
+declare function createCodebaseSearchTool(config: CodebaseSearchConfig): ChatCompletionTool & {
+    execute: (input: CodebaseSearchInput | string) => Promise<CodebaseSearchResult>;
+    formatResult: (result: CodebaseSearchResult) => string;
+    getSystemPrompt: () => string;
+};
+/**
+ * Execute codebase_search tool call
+ *
+ * @param input - Tool input from GPT (parsed from tool_calls)
+ * @param config - Configuration with repoId (REQUIRED)
+ * @returns Search results
+ *
+ * @example
+ * ```ts
+ * // Handle tool calls from GPT:
+ * if (response.choices[0].message.tool_calls) {
+ *   for (const toolCall of response.choices[0].message.tool_calls) {
+ *     const args = JSON.parse(toolCall.function.arguments);
+ *     const result = await execute(args, { repoId: 'my-project' });
+ *     console.log(`Found ${result.results.length} matches`);
+ *   }
+ * }
+ * ```
+ */
+declare function execute(input: CodebaseSearchInput, config: CodebaseSearchConfig): Promise<CodebaseSearchResult>;
+/**
+ * Format search results for GPT
+ *
+ * @param result - Search result from endpoint
+ * @returns Formatted string for tool message
+ */
+declare function formatResult(result: CodebaseSearchResult): string;
+/**
+ * Get the system prompt for codebase_search usage
+ *
+ * @returns System prompt to guide GPT
+ */
+declare function getSystemPrompt(): string;
+/**
+ * Default export for convenience
+ */
+declare const _default: {
+    createCodebaseSearchTool: typeof createCodebaseSearchTool;
+    execute: typeof execute;
+    formatResult: typeof formatResult;
+    getSystemPrompt: typeof getSystemPrompt;
+};
+
+export { codebaseSearchTool, createCodebaseSearchTool, _default as default, execute, formatResult, getSystemPrompt };

package/dist/tools/codebase_search/prompts.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tool descriptions and system prompts for codebase search
+ */
+declare const CODEBASE_SEARCH_DESCRIPTION = "Semantic search that finds code by meaning, not exact text.\n\nUse this to explore unfamiliar codebases or ask \"how/where/what\" questions:\n- \"How does X work?\" - Find implementation details\n- \"Where is Y handled?\" - Locate specific functionality\n- \"What happens when Z?\" - Understand flow\n\nThe tool uses two-stage retrieval (embedding similarity + reranking) to find the most semantically relevant code chunks.\n\nReturns code chunks with file paths, line ranges, and full content ranked by relevance.";
+declare const CODEBASE_SEARCH_SYSTEM_PROMPT = "You have access to the codebase_search tool that performs semantic code search.\n\nWhen searching:\n- Use natural language queries describing what you're looking for\n- Be specific about functionality, not variable names\n- Use target_directories to narrow search if you know the area\n- Results are ranked by relevance (rerank score is most important)\n\nThe tool returns:\n- File paths with symbol names (e.g. \"src/auth.ts::AuthService@L1-L17\")\n- Line ranges for precise navigation\n- Full code content for each match\n- Dual relevance scores: embedding similarity + rerank score\n\nUse results to understand code or answer questions. The content is provided in full - avoid re-reading unless you need more context.";
+
+export { CODEBASE_SEARCH_DESCRIPTION, CODEBASE_SEARCH_SYSTEM_PROMPT };

package/dist/tools/codebase_search/types.d.ts

@@ -0,0 +1,50 @@
+import { RetryConfig } from '../utils/resilience.js';
+
+/**
+ * Type definitions for codebase search tool
+ */
+
+interface CodebaseSearchConfig {
+    repoId: string;
+    /** Optional branch name (e.g., 'main', 'develop'). Uses latest commit for that branch. */
+    branch?: string;
+    /** Optional commit hash. If specified, uses this exact commit. Takes precedence over branch. */
+    commitHash?: string;
+    searchUrl?: string;
+    apiKey?: string;
+    /** Timeout for search requests in ms (default: 30000) */
+    timeout?: number;
+    /** Retry configuration for API calls */
+    retryConfig?: RetryConfig;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface CodebaseSearchInput {
+    query: string;
+    target_directories?: string[];
+    explanation?: string;
+    limit?: number;
+}
+interface CodeSearchResult {
+    filepath: string;
+    symbolPath: string;
+    content: string;
+    language: string;
+    startLine: number;
+    endLine: number;
+    embeddingSimilarity: number;
+    rerankScore: number;
+}
+interface SearchStats {
+    totalResults: number;
+    candidatesRetrieved: number;
+    searchTimeMs: number;
+}
+interface CodebaseSearchResult {
+    success: boolean;
+    results: CodeSearchResult[];
+    stats: SearchStats;
+    error?: string;
+}
+
+export type { CodeSearchResult, CodebaseSearchConfig, CodebaseSearchInput, CodebaseSearchResult, SearchStats };