@morphllm/morphsdk 0.2.18 → 0.2.20

package/dist/modelrouter/index.d.ts

@@ -0,0 +1,2 @@
+export { AnthropicRouter, GeminiRouter, OpenAIRouter } from './core.js';
+export { ComplexityLevel, Provider, RouterConfig, RouterInput, RouterMode, RouterResult } from './types.js';

package/dist/modelrouter/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Model router types for intelligent model selection
+ */
+type ComplexityLevel = 'easy' | 'medium' | 'hard' | 'needs-info';
+type RouterMode = 'balanced' | 'aggressive';
+type Provider = 'openai' | 'anthropic' | 'gemini';
+interface RouterConfig {
+    /** Morph API key (defaults to MORPH_API_KEY env var) */
+    apiKey?: string;
+    /** Router API URL (defaults to https://api.morphllm.com) */
+    apiUrl?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Retry configuration */
+    retryConfig?: {
+        maxRetries?: number;
+        initialDelay?: number;
+        maxDelay?: number;
+        backoffMultiplier?: number;
+    };
+}
+interface RouterInput {
+    /** User input or task description */
+    input: string;
+    /** Routing mode: balanced (cheaper models) or aggressive (more capable models) */
+    mode?: RouterMode;
+}
+interface RouterResult {
+    /** Selected model name */
+    model: string;
+}
+
+export type { ComplexityLevel, Provider, RouterConfig, RouterInput, RouterMode, RouterResult };

package/dist/openai-BkKsS30n.d.ts

@@ -0,0 +1,111 @@
+import { ChatCompletionTool } from 'openai/resources/chat/completions';
+import { EditFileInput, EditFileConfig, EditFileResult } from './tools/fastapply/types.js';
+
+/**
+ * OpenAI SDK adapter for edit_file tool
+ */
+
+/**
+ * OpenAI-native tool definition for edit_file
+ *
+ * @example
+ * ```ts
+ * import OpenAI from 'openai';
+ * import { editFileTool } from 'morphsdk/tools/openai';
+ *
+ * const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+ *
+ * const response = await client.chat.completions.create({
+ *   model: "gpt-4o",
+ *   tools: [editFileTool],
+ *   messages: [{ role: "user", content: "Fix the bug in app.ts" }]
+ * });
+ * ```
+ */
+declare const editFileTool: ChatCompletionTool;
+/**
+ * Execute an edit_file tool call
+ *
+ * @param input - The tool input from GPT (parsed from tool_calls)
+ * @param config - Optional configuration
+ * @returns The result of the edit operation
+ *
+ * @example
+ * ```ts
+ * const args = JSON.parse(toolCall.function.arguments);
+ * const result = await execute(args);
+ * console.log('Changes applied:', result.udiff);
+ * ```
+ */
+declare function execute(input: EditFileInput, config?: EditFileConfig): Promise<EditFileResult>;
+/**
+ * Get the system prompt for edit_file usage
+ *
+ * Add this to your system message to guide GPT on using edit_file properly.
+ *
+ * @example
+ * ```ts
+ * const response = await client.chat.completions.create({
+ *   model: "gpt-4o",
+ *   messages: [
+ *     { role: "system", content: getSystemPrompt() },
+ *     { role: "user", content: "Fix bugs" }
+ *   ],
+ *   tools: [editFileTool]
+ * });
+ * ```
+ */
+declare function getSystemPrompt(): string;
+/**
+ * Format the result for passing back to GPT
+ *
+ * @param result - The edit result
+ * @returns Formatted string for tool message
+ */
+declare function formatResult(result: EditFileResult): string;
+/**
+ * Create a custom edit_file tool with configuration and methods
+ *
+ * @param config - Configuration options
+ * @returns Tool definition with execute and formatResult methods
+ *
+ * @example
+ * ```ts
+ * import OpenAI from 'openai';
+ * import { createEditFileTool } from 'morphsdk/tools/fastapply/openai';
+ *
+ * const tool = createEditFileTool({
+ *   baseDir: './src',
+ *   generateUdiff: true,
+ *   description: 'Custom tool description for your use case'
+ * });
+ *
+ * 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: 'Fix bug in app.ts' }]
+ * });
+ *
+ * // Execute and format
+ * const result = await tool.execute(toolCallArgs);
+ * const formatted = tool.formatResult(result);
+ * ```
+ */
+declare function createEditFileTool(config?: EditFileConfig): ChatCompletionTool & {
+    execute: (input: EditFileInput | string) => Promise<EditFileResult>;
+    formatResult: (result: EditFileResult) => string;
+    getSystemPrompt: () => string;
+};
+
+declare const openai_createEditFileTool: typeof createEditFileTool;
+declare const openai_editFileTool: typeof editFileTool;
+declare const openai_execute: typeof execute;
+declare const openai_formatResult: typeof formatResult;
+declare const openai_getSystemPrompt: typeof getSystemPrompt;
+declare namespace openai {
+  export { openai_createEditFileTool as createEditFileTool, editFileTool as default, openai_editFileTool as editFileTool, openai_execute as execute, openai_formatResult as formatResult, openai_getSystemPrompt as getSystemPrompt };
+}
+
+export { execute as a, createEditFileTool as c, editFileTool as e, formatResult as f, getSystemPrompt as g, openai as o };

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

@@ -0,0 +1,51 @@
+import { Tool } from '@anthropic-ai/sdk/resources/messages.mjs';
+import { BrowserConfig, BrowserTaskInput, BrowserTaskResult } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * Anthropic SDK adapter for browser automation tool
+ */
+
+/**
+ * Anthropic tool definition for browser automation
+ */
+declare const browserTool: Tool;
+/**
+ * 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 Anthropic from '@anthropic-ai/sdk';
+ * import { createBrowserTool } from 'morphsdk/tools/browser/anthropic';
+ *
+ * const tool = createBrowserTool({
+ *   apiKey: process.env.MORPH_API_KEY,
+ *   timeout: 180000
+ * });
+ *
+ * const client = new Anthropic();
+ *
+ * const response = await client.messages.create({
+ *   model: 'claude-sonnet-4-5-20250929',
+ *   tools: [tool], // tool itself is the Tool definition
+ *   messages: [{
+ *     role: 'user',
+ *     content: 'Test the checkout flow at https://3000-abc.e2b.dev'
+ *   }]
+ * });
+ *
+ * // Execute and format
+ * const result = await tool.execute(toolUseBlock.input);
+ * const formatted = tool.formatResult(result);
+ * ```
+ */
+declare function createBrowserTool(config?: BrowserConfig): Tool & {
+    execute: (input: BrowserTaskInput) => Promise<BrowserTaskResult>;
+    formatResult: (result: BrowserTaskResult) => string;
+    getSystemPrompt: () => string;
+};
+
+export { browserTool, createBrowserTool };

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

@@ -0,0 +1,196 @@
+import { BrowserConfig, BrowserTaskInput, BrowserTaskResult, BrowserTaskWithPromise, BrowserTaskInputWithSchema, BrowserTaskWithPromiseAndSchema, RecordingStatus, ErrorsResponse } from './types.js';
+import '../utils/resilience.js';
+
+/**
+ * Core implementation for browser automation tasks
+ */
+
+/**
+ * BrowserClient class for easier usage with instance configuration
+ */
+declare class BrowserClient {
+    private config;
+    constructor(config?: BrowserConfig);
+    /**
+     * Execute a browser automation task
+     */
+    execute(input: BrowserTaskInput): Promise<BrowserTaskResult>;
+    createTask(input: BrowserTaskInput): Promise<BrowserTaskWithPromise>;
+    createTask<T>(input: BrowserTaskInputWithSchema<T>): Promise<BrowserTaskWithPromiseAndSchema<T>>;
+    /**
+     * Execute task with recording and wait for video to be ready
+     */
+    executeWithRecording(input: BrowserTaskInput & {
+        record_video: true;
+    }): Promise<BrowserTaskResult & {
+        recording?: RecordingStatus;
+    }>;
+    /**
+     * Get recording status and URLs
+     */
+    getRecording(recordingId: string): Promise<RecordingStatus>;
+    /**
+     * Wait for recording to complete with automatic polling
+     */
+    waitForRecording(recordingId: string, options?: {
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<RecordingStatus>;
+    /**
+     * Get errors from recording with screenshots
+     */
+    getErrors(recordingId: string): Promise<ErrorsResponse>;
+    /**
+     * Check if browser worker service is healthy
+     */
+    checkHealth(): Promise<{
+        ok: boolean;
+        google_configured: boolean;
+        database_configured: boolean;
+        s3_configured: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Execute a natural language browser automation task
+ *
+ * @param input - Task parameters
+ * @param config - Optional configuration (apiKey, apiUrl to override default)
+ * @returns Task result with success status and findings
+ *
+ * @example
+ * ```typescript
+ * const result = await executeBrowserTask(
+ *   {
+ *     task: "Test checkout flow for buying a pineapple",
+ *     url: "https://3000-abc.e2b.dev",
+ *     max_steps: 20,
+ *     repo_id: "my-project",
+ *     commit_id: "uuid-here"
+ *   },
+ *   {
+ *     apiKey: process.env.MORPH_API_KEY,
+ *     // apiUrl: 'http://localhost:8001' // Override for local testing
+ *   }
+ * );
+ *
+ * if (result.success) {
+ *   console.log('Task completed:', result.result);
+ *   console.log('Replay:', result.replay_url);
+ * }
+ * ```
+ */
+declare function executeBrowserTask(input: BrowserTaskInput, config?: BrowserConfig): Promise<BrowserTaskResult>;
+/**
+ * Get recording status and video URL
+ *
+ * @param recordingId - Recording UUID from BrowserTaskResult
+ * @param config - Configuration with apiKey
+ * @returns Recording status with video URL when ready
+ *
+ * @example
+ * ```typescript
+ * const status = await getRecording('uuid-here', { apiKey: 'key' });
+ * if (status.status === 'COMPLETED' && status.video_url) {
+ *   console.log('Video ready:', status.video_url);
+ * }
+ * ```
+ */
+declare function getRecording(recordingId: string, config?: BrowserConfig): Promise<RecordingStatus>;
+/**
+ * Wait for recording to complete with automatic polling
+ *
+ * @param recordingId - Recording UUID
+ * @param config - Configuration with apiKey
+ * @param options - Polling options
+ * @returns Recording status when completed or errored
+ *
+ * @example
+ * ```typescript
+ * const result = await executeBrowserTask({ task: '...', record_video: true }, config);
+ * if (result.recording_id) {
+ *   const recording = await waitForRecording(result.recording_id, config, {
+ *     timeout: 60000,  // 1 minute
+ *     pollInterval: 2000  // Check every 2 seconds
+ *   });
+ *   console.log('Video URL:', recording.video_url);
+ * }
+ * ```
+ */
+declare function waitForRecording(recordingId: string, config?: BrowserConfig, options?: {
+    timeout?: number;
+    pollInterval?: number;
+}): Promise<RecordingStatus>;
+/**
+ * Execute task with recording and wait for video to be ready
+ *
+ * @param input - Task parameters with record_video=true
+ * @param config - Configuration with apiKey
+ * @returns Task result with ready video URL
+ *
+ * @example
+ * ```typescript
+ * const result = await executeWithRecording(
+ *   {
+ *     task: "Test checkout flow",
+ *     url: "https://example.com",
+ *     record_video: true,
+ *     repo_id: "my-project"
+ *   },
+ *   { apiKey: process.env.MORPH_API_KEY }
+ * );
+ *
+ * console.log('Task result:', result.result);
+ * console.log('Video URL:', result.recording?.video_url);
+ * ```
+ */
+declare function executeWithRecording(input: BrowserTaskInput & {
+    record_video: true;
+}, config?: BrowserConfig): Promise<BrowserTaskResult & {
+    recording?: RecordingStatus;
+}>;
+/**
+ * Get errors from recording with screenshots
+ *
+ * Screenshots are captured in real-time (500ms after error occurs) during the browser session.
+ *
+ * @param recordingId - Recording UUID from BrowserTaskResult
+ * @param config - Configuration with apiKey
+ * @returns Errors with real-time screenshots
+ *
+ * @example
+ * ```typescript
+ * const { errors, total_errors } = await getErrors('uuid-here', { apiKey: 'key' });
+ *
+ * console.log(`Found ${total_errors} errors`);
+ *
+ * errors.forEach(err => {
+ *   console.log(`[${err.type}] ${err.message}`);
+ *   if (err.url) console.log(`  URL: ${err.url}`);
+ *   if (err.screenshot_url) console.log(`  Screenshot: ${err.screenshot_url}`);
+ *
+ *   // Download screenshot
+ *   if (err.screenshot_url) {
+ *     const response = await fetch(err.screenshot_url);
+ *     const screenshot = await response.arrayBuffer();
+ *     // Save or process screenshot
+ *   }
+ * });
+ * ```
+ */
+declare function getErrors(recordingId: string, config?: BrowserConfig): Promise<ErrorsResponse>;
+/**
+ * Check if browser worker service is healthy
+ *
+ * @param config - Optional configuration
+ * @returns Health status
+ */
+declare function checkHealth(config?: BrowserConfig): Promise<{
+    ok: boolean;
+    google_configured: boolean;
+    database_configured: boolean;
+    s3_configured: boolean;
+    error?: string;
+}>;
+
+export { BrowserClient, checkHealth, executeBrowserTask, executeWithRecording, getErrors, getRecording, waitForRecording };

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

@@ -0,0 +1,72 @@
+export { BrowserClient, checkHealth, executeBrowserTask, executeWithRecording, getErrors, getRecording, waitForRecording } from './core.js';
+import { LiveSessionOptions, IframeOptions } from './types.js';
+export { BrowserConfig, BrowserError, BrowserModel, BrowserTaskInput, BrowserTaskInputWithSchema, BrowserTaskResult, BrowserTaskWithPromise, BrowserTaskWithPromiseAndSchema, ErrorsResponse, RecordingStatus } from './types.js';
+export { BROWSER_SYSTEM_PROMPT, BROWSER_TOOL_DESCRIPTION } from './prompts.js';
+import '../utils/resilience.js';
+
+/**
+ * Live session utilities for Morph browser sessions
+ *
+ * Provides helpers for embedding and sharing live browser sessions with WebRTC streaming.
+ */
+
+/**
+ * Preset configurations for common use cases
+ */
+declare const LIVE_PRESETS: {
+    /** Read-only monitoring (no interaction) */
+    readonly readonly: LiveSessionOptions;
+    /** Interactive control (human-in-the-loop) */
+    readonly interactive: LiveSessionOptions;
+    /** Watch-only without controls */
+    readonly monitoring: LiveSessionOptions;
+};
+/**
+ * Build a live session URL with query parameters
+ *
+ * @param debugUrl - Live session debug URL (e.g., from task.debugUrl)
+ * @param options - Live session configuration options
+ * @returns URL with query parameters for iframe embedding
+ *
+ * @example
+ * ```typescript
+ * const url = buildLiveUrl(task.debugUrl, { interactive: true });
+ * // Returns: https://example.com/sessions/abc?interactive=true
+ * ```
+ */
+declare function buildLiveUrl(debugUrl: string, options?: LiveSessionOptions): string;
+/**
+ * Build iframe HTML for embedding a live session
+ *
+ * @param debugUrl - Live session debug URL
+ * @param options - Iframe configuration including dimensions and session options
+ * @returns HTML iframe element as string
+ *
+ * @example
+ * ```typescript
+ * const iframe = buildLiveIframe(task.debugUrl, {
+ *   interactive: true,
+ *   width: '100%',
+ *   height: '600px'
+ * });
+ * ```
+ */
+declare function buildLiveIframe(debugUrl: string, options?: IframeOptions): string;
+/**
+ * Build complete embed code with HTML snippet
+ *
+ * @param debugUrl - Live session debug URL
+ * @param options - Iframe configuration
+ * @returns Multi-line HTML snippet ready to copy-paste
+ *
+ * @example
+ * ```typescript
+ * const code = buildEmbedCode(task.debugUrl, { interactive: false });
+ * console.log(code);
+ * // <!-- Embed Morph Live Session -->
+ * // <iframe src="..." style="..."></iframe>
+ * ```
+ */
+declare function buildEmbedCode(debugUrl: string, options?: IframeOptions): string;
+
+export { IframeOptions, LIVE_PRESETS, LiveSessionOptions, buildEmbedCode, buildLiveIframe, buildLiveUrl };

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

@@ -0,0 +1,69 @@
+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
+ *
+ * @param result - Browser task result
+ * @returns Formatted string 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 = "Execute natural language browser automation tasks using an AI-powered agent. The agent can navigate websites, interact with elements, fill forms, click buttons, and verify functionality.\n\nUse this tool to:\n- Test web applications end-to-end\n- Verify UI functionality\n- Automate user workflows\n- Extract information from web pages\n\nThe agent uses GPT-4o-mini to interpret your task and execute the necessary browser actions. It runs in a remote browser via Browserless.io, so it can access any publicly accessible URL.\n\nImportant:\n- Provide clear, specific task descriptions\n- Include the starting URL if navigating to a specific page\n- Use remote URLs (e.g., https://3000-xyz.e2b.dev) not localhost\n- Complex tasks may require more max_steps";
+declare const BROWSER_SYSTEM_PROMPT = "You have access to browser automation capabilities. When testing or interacting with web applications:\n\n1. Be specific about what you're testing or verifying\n2. Break complex tasks into clear steps\n3. Always provide the full URL including protocol (https://)\n4. For localhost apps, use the remote tunnel URL (e.g., e2b.dev URLs)\n5. Specify the number of steps needed - simple tasks use 5-10, complex flows use 15-30\n\nExample good tasks:\n- \"Go to https://3000-abc.e2b.dev and verify the landing page loads with a hero section\"\n- \"Test guest checkout: add a pineapple to cart, proceed to checkout, fill shipping info, and verify order summary\"\n- \"Navigate to the dashboard and click on the settings tab, then verify the API keys section is visible\"\n\nExample bad tasks:\n- \"test the app\" (too vague)\n- \"go to localhost:3000\" (use remote URL instead)\n- \"do everything\" (not specific enough)";
+
+export { BROWSER_SYSTEM_PROMPT, BROWSER_TOOL_DESCRIPTION };