@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.1

package/dist/esm/lib/v3/llm/aisdk.js

@@ -0,0 +1,348 @@
+import { generateObject, generateText, NoObjectGeneratedError, } from "ai";
+import { v7 as uuidv7 } from "uuid";
+import { LLMClient } from "./LLMClient.js";
+import { SessionFileLogger, formatLlmPromptPreview } from "../flowLogger.js";
+import { toJsonSchema } from "../zodCompat.js";
+export class AISdkClient extends LLMClient {
+    type = "aisdk";
+    model;
+    logger;
+    constructor({ model, logger, }) {
+        super(model.modelId);
+        this.model = model;
+        this.logger = logger;
+    }
+    getLanguageModel() {
+        return this.model;
+    }
+    async createChatCompletion({ options, }) {
+        this.logger?.({
+            category: "aisdk",
+            message: "creating chat completion",
+            level: 2,
+            auxiliary: {
+                options: {
+                    value: JSON.stringify({
+                        ...options,
+                        image: undefined,
+                        messages: options.messages.map((msg) => ({
+                            ...msg,
+                            content: Array.isArray(msg.content)
+                                ? msg.content.map((c) => "image_url" in c
+                                    ? { ...c, image_url: { url: "[IMAGE_REDACTED]" } }
+                                    : c)
+                                : msg.content,
+                        })),
+                    }),
+                    type: "object",
+                },
+                modelName: {
+                    value: this.model.modelId,
+                    type: "string",
+                },
+            },
+        });
+        const formattedMessages = options.messages.map((message) => {
+            if (Array.isArray(message.content)) {
+                if (message.role === "system") {
+                    const systemMessage = {
+                        role: "system",
+                        content: message.content
+                            .map((c) => ("text" in c ? c.text : ""))
+                            .join("\n"),
+                    };
+                    return systemMessage;
+                }
+                const contentParts = message.content.map((content) => {
+                    if ("image_url" in content) {
+                        const imageContent = {
+                            type: "image",
+                            image: content.image_url.url,
+                        };
+                        return imageContent;
+                    }
+                    else {
+                        const textContent = {
+                            type: "text",
+                            text: content.text,
+                        };
+                        return textContent;
+                    }
+                });
+                if (message.role === "user") {
+                    const userMessage = {
+                        role: "user",
+                        content: contentParts,
+                    };
+                    return userMessage;
+                }
+                else {
+                    const textOnlyParts = contentParts.map((part) => ({
+                        type: "text",
+                        text: part.type === "image" ? "[Image]" : part.text,
+                    }));
+                    const assistantMessage = {
+                        role: "assistant",
+                        content: textOnlyParts,
+                    };
+                    return assistantMessage;
+                }
+            }
+            return {
+                role: message.role,
+                content: message.content,
+            };
+        });
+        let objectResponse;
+        const isGPT5 = this.model.modelId.includes("gpt-5");
+        const isCodex = this.model.modelId.includes("codex");
+        const usesLowReasoningEffort = (this.model.modelId.includes("gpt-5.1") ||
+            this.model.modelId.includes("gpt-5.2")) &&
+            !isCodex;
+        const isDeepSeek = this.model.modelId.includes("deepseek");
+        // Kimi models only support temperature=1
+        const isKimi = this.model.modelId.includes("kimi");
+        const temperature = isKimi ? 1 : options.temperature;
+        if (options.response_model) {
+            // Log LLM request for generateObject (extract)
+            const llmRequestId = uuidv7();
+            const promptPreview = formatLlmPromptPreview(options.messages, {
+                hasSchema: true,
+            });
+            SessionFileLogger.logLlmRequest({
+                requestId: llmRequestId,
+                model: this.model.modelId,
+                operation: "generateObject",
+                prompt: promptPreview,
+            });
+            // For models that don't support native structured outputs, add a prompt instruction
+            if (isDeepSeek || isKimi) {
+                const parsedSchema = JSON.stringify(toJsonSchema(options.response_model.schema));
+                formattedMessages.push({
+                    role: "user",
+                    content: `Respond in this zod schema format:\n${parsedSchema}\n
+You must respond in JSON format. respond WITH JSON. Do not include any other text, formatting or markdown in your output. Do not include \`\`\` or \`\`\`json in your response. Only the JSON object itself.`,
+                });
+            }
+            try {
+                objectResponse = await generateObject({
+                    model: this.model,
+                    messages: formattedMessages,
+                    schema: options.response_model.schema,
+                    temperature,
+                    providerOptions: isGPT5
+                        ? {
+                            openai: {
+                                textVerbosity: isCodex ? "medium" : "low", // codex models only support 'medium'
+                                reasoningEffort: isCodex
+                                    ? "medium"
+                                    : usesLowReasoningEffort
+                                        ? "low"
+                                        : "minimal",
+                            },
+                        }
+                        : undefined,
+                });
+            }
+            catch (err) {
+                // Log error response to maintain request/response pairing
+                SessionFileLogger.logLlmResponse({
+                    requestId: llmRequestId,
+                    model: this.model.modelId,
+                    operation: "generateObject",
+                    output: `[error: ${err instanceof Error ? err.message : "unknown"}]`,
+                });
+                if (NoObjectGeneratedError.isInstance(err)) {
+                    this.logger?.({
+                        category: "AISDK error",
+                        message: err.message,
+                        level: 0,
+                        auxiliary: {
+                            cause: {
+                                value: JSON.stringify(err.cause ?? {}),
+                                type: "object",
+                            },
+                            text: {
+                                value: err.text ?? "",
+                                type: "string",
+                            },
+                            response: {
+                                value: JSON.stringify(err.response ?? {}),
+                                type: "object",
+                            },
+                            usage: {
+                                value: JSON.stringify(err.usage ?? {}),
+                                type: "object",
+                            },
+                            finishReason: {
+                                value: err.finishReason ?? "unknown",
+                                type: "string",
+                            },
+                            requestId: {
+                                value: options.requestId,
+                                type: "string",
+                            },
+                        },
+                    });
+                    throw err;
+                }
+                throw err;
+            }
+            const result = {
+                data: objectResponse.object,
+                usage: {
+                    prompt_tokens: objectResponse.usage.inputTokens ?? 0,
+                    completion_tokens: objectResponse.usage.outputTokens ?? 0,
+                    reasoning_tokens: objectResponse.usage.reasoningTokens ?? 0,
+                    cached_input_tokens: objectResponse.usage.cachedInputTokens ?? 0,
+                    total_tokens: objectResponse.usage.totalTokens ?? 0,
+                },
+            };
+            // Log LLM response for generateObject
+            SessionFileLogger.logLlmResponse({
+                requestId: llmRequestId,
+                model: this.model.modelId,
+                operation: "generateObject",
+                output: JSON.stringify(objectResponse.object),
+                inputTokens: objectResponse.usage.inputTokens,
+                outputTokens: objectResponse.usage.outputTokens,
+            });
+            this.logger?.({
+                category: "aisdk",
+                message: "response",
+                level: 1,
+                auxiliary: {
+                    response: {
+                        value: JSON.stringify({
+                            object: objectResponse.object,
+                            usage: objectResponse.usage,
+                            finishReason: objectResponse.finishReason,
+                            // Omit request and response properties that might contain images
+                        }),
+                        type: "object",
+                    },
+                    requestId: {
+                        value: options.requestId,
+                        type: "string",
+                    },
+                },
+            });
+            return result;
+        }
+        const tools = {};
+        if (options.tools && options.tools.length > 0) {
+            for (const tool of options.tools) {
+                tools[tool.name] = {
+                    description: tool.description,
+                    inputSchema: tool.parameters,
+                };
+            }
+        }
+        // Log LLM request for generateText (act/observe)
+        const llmRequestId = uuidv7();
+        const toolCount = Object.keys(tools).length;
+        const promptPreview = formatLlmPromptPreview(options.messages, {
+            toolCount,
+        });
+        SessionFileLogger.logLlmRequest({
+            requestId: llmRequestId,
+            model: this.model.modelId,
+            operation: "generateText",
+            prompt: promptPreview,
+        });
+        let textResponse;
+        try {
+            textResponse = await generateText({
+                model: this.model,
+                messages: formattedMessages,
+                tools: Object.keys(tools).length > 0 ? tools : undefined,
+                toolChoice: Object.keys(tools).length > 0
+                    ? options.tool_choice === "required"
+                        ? "required"
+                        : options.tool_choice === "none"
+                            ? "none"
+                            : "auto"
+                    : undefined,
+                temperature,
+            });
+        }
+        catch (err) {
+            // Log error response to maintain request/response pairing
+            SessionFileLogger.logLlmResponse({
+                requestId: llmRequestId,
+                model: this.model.modelId,
+                operation: "generateText",
+                output: `[error: ${err instanceof Error ? err.message : "unknown"}]`,
+            });
+            throw err;
+        }
+        // Transform AI SDK response to match LLMResponse format expected by operator handler
+        const transformedToolCalls = (textResponse.toolCalls || []).map((toolCall) => ({
+            id: toolCall.toolCallId ||
+                `call_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+            type: "function",
+            function: {
+                name: toolCall.toolName,
+                arguments: JSON.stringify(toolCall.input),
+            },
+        }));
+        const result = {
+            id: `chatcmpl_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+            object: "chat.completion",
+            created: Math.floor(Date.now() / 1000),
+            model: this.model.modelId,
+            choices: [
+                {
+                    index: 0,
+                    message: {
+                        role: "assistant",
+                        content: textResponse.text || null,
+                        tool_calls: transformedToolCalls,
+                    },
+                    finish_reason: textResponse.finishReason || "stop",
+                },
+            ],
+            usage: {
+                prompt_tokens: textResponse.usage.inputTokens ?? 0,
+                completion_tokens: textResponse.usage.outputTokens ?? 0,
+                reasoning_tokens: textResponse.usage.reasoningTokens ?? 0,
+                cached_input_tokens: textResponse.usage.cachedInputTokens ?? 0,
+                total_tokens: textResponse.usage.totalTokens ?? 0,
+            },
+        };
+        // Log LLM response for generateText
+        SessionFileLogger.logLlmResponse({
+            requestId: llmRequestId,
+            model: this.model.modelId,
+            operation: "generateText",
+            output: textResponse.text ||
+                (transformedToolCalls.length > 0
+                    ? `[${transformedToolCalls.length} tool calls]`
+                    : ""),
+            inputTokens: textResponse.usage.inputTokens,
+            outputTokens: textResponse.usage.outputTokens,
+        });
+        this.logger?.({
+            category: "aisdk",
+            message: "response",
+            level: 2,
+            auxiliary: {
+                response: {
+                    value: JSON.stringify({
+                        text: textResponse.text,
+                        usage: textResponse.usage,
+                        finishReason: textResponse.finishReason,
+                        // Omit request and response properties that might contain images
+                    }),
+                    type: "object",
+                },
+                requestId: {
+                    value: options.requestId,
+                    type: "string",
+                },
+            },
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=aisdk.js.map

package/dist/esm/lib/v3/llm/aisdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aisdk.js","sourceRoot":"","sources":["../../../../../lib/v3/llm/aisdk.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  CoreAssistantMessage,\n  ModelMessage,\n  CoreSystemMessage,\n  CoreUserMessage,\n  generateObject,\n  generateText,\n  ImagePart,\n  NoObjectGeneratedError,\n  TextPart,\n  ToolSet,\n  Tool,\n} from \"ai\";\nimport type { LanguageModelV2 } from \"@ai-sdk/provider\";\nimport { ChatCompletion } from \"openai/resources\";\nimport { v7 as uuidv7 } from \"uuid\";\nimport { LogLine } from \"../types/public/logs.js\";\nimport { AvailableModel } from \"../types/public/model.js\";\nimport { CreateChatCompletionOptions, LLMClient } from \"./LLMClient.js\";\nimport { SessionFileLogger, formatLlmPromptPreview } from \"../flowLogger.js\";\nimport { toJsonSchema } from \"../zodCompat.js\";\n\nexport class AISdkClient extends LLMClient {\n  public type = \"aisdk\" as const;\n  private model: LanguageModelV2;\n  private logger?: (message: LogLine) => void;\n\n  constructor({\n    model,\n    logger,\n  }: {\n    model: LanguageModelV2;\n    logger?: (message: LogLine) => void;\n  }) {\n    super(model.modelId as AvailableModel);\n    this.model = model;\n    this.logger = logger;\n  }\n\n  public getLanguageModel(): LanguageModelV2 {\n    return this.model;\n  }\n\n  async createChatCompletion<T = ChatCompletion>({\n    options,\n  }: CreateChatCompletionOptions): Promise<T> {\n    this.logger?.({\n      category: \"aisdk\",\n      message: \"creating chat completion\",\n      level: 2,\n      auxiliary: {\n        options: {\n          value: JSON.stringify({\n            ...options,\n            image: undefined,\n            messages: options.messages.map((msg) => ({\n              ...msg,\n              content: Array.isArray(msg.content)\n                ? msg.content.map((c) =>\n                    \"image_url\" in c\n                      ? { ...c, image_url: { url: \"[IMAGE_REDACTED]\" } }\n                      : c,\n                  )\n                : msg.content,\n            })),\n          }),\n          type: \"object\",\n        },\n        modelName: {\n          value: this.model.modelId,\n          type: \"string\",\n        },\n      },\n    });\n\n    const formattedMessages: ModelMessage[] = options.messages.map(\n      (message) => {\n        if (Array.isArray(message.content)) {\n          if (message.role === \"system\") {\n            const systemMessage: CoreSystemMessage = {\n              role: \"system\",\n              content: message.content\n                .map((c) => (\"text\" in c ? c.text : \"\"))\n                .join(\"\\n\"),\n            };\n            return systemMessage;\n          }\n\n          const contentParts = message.content.map((content) => {\n            if (\"image_url\" in content) {\n              const imageContent: ImagePart = {\n                type: \"image\",\n                image: content.image_url.url,\n              };\n              return imageContent;\n            } else {\n              const textContent: TextPart = {\n                type: \"text\",\n                text: content.text,\n              };\n              return textContent;\n            }\n          });\n\n          if (message.role === \"user\") {\n            const userMessage: CoreUserMessage = {\n              role: \"user\",\n              content: contentParts,\n            };\n            return userMessage;\n          } else {\n            const textOnlyParts = contentParts.map((part) => ({\n              type: \"text\" as const,\n              text: part.type === \"image\" ? \"[Image]\" : part.text,\n            }));\n            const assistantMessage: CoreAssistantMessage = {\n              role: \"assistant\",\n              content: textOnlyParts,\n            };\n            return assistantMessage;\n          }\n        }\n\n        return {\n          role: message.role,\n          content: message.content,\n        };\n      },\n    );\n\n    let objectResponse: Awaited<ReturnType<typeof generateObject>>;\n    const isGPT5 = this.model.modelId.includes(\"gpt-5\");\n    const isCodex = this.model.modelId.includes(\"codex\");\n    const usesLowReasoningEffort =\n      (this.model.modelId.includes(\"gpt-5.1\") ||\n        this.model.modelId.includes(\"gpt-5.2\")) &&\n      !isCodex;\n    const isDeepSeek = this.model.modelId.includes(\"deepseek\");\n    // Kimi models only support temperature=1\n    const isKimi = this.model.modelId.includes(\"kimi\");\n    const temperature = isKimi ? 1 : options.temperature;\n\n    if (options.response_model) {\n      // Log LLM request for generateObject (extract)\n      const llmRequestId = uuidv7();\n      const promptPreview = formatLlmPromptPreview(options.messages, {\n        hasSchema: true,\n      });\n      SessionFileLogger.logLlmRequest({\n        requestId: llmRequestId,\n        model: this.model.modelId,\n        operation: \"generateObject\",\n        prompt: promptPreview,\n      });\n\n      // For models that don't support native structured outputs, add a prompt instruction\n      if (isDeepSeek || isKimi) {\n        const parsedSchema = JSON.stringify(\n          toJsonSchema(options.response_model.schema),\n        );\n\n        formattedMessages.push({\n          role: \"user\",\n          content: `Respond in this zod schema format:\\n${parsedSchema}\\n\nYou must respond in JSON format. respond WITH JSON. Do not include any other text, formatting or markdown in your output. Do not include \\`\\`\\` or \\`\\`\\`json in your response. Only the JSON object itself.`,\n        });\n      }\n\n      try {\n        objectResponse = await generateObject({\n          model: this.model,\n          messages: formattedMessages,\n          schema: options.response_model.schema,\n          temperature,\n          providerOptions: isGPT5\n            ? {\n                openai: {\n                  textVerbosity: isCodex ? \"medium\" : \"low\", // codex models only support 'medium'\n                  reasoningEffort: isCodex\n                    ? \"medium\"\n                    : usesLowReasoningEffort\n                      ? \"low\"\n                      : \"minimal\",\n                },\n              }\n            : undefined,\n        });\n      } catch (err) {\n        // Log error response to maintain request/response pairing\n        SessionFileLogger.logLlmResponse({\n          requestId: llmRequestId,\n          model: this.model.modelId,\n          operation: \"generateObject\",\n          output: `[error: ${err instanceof Error ? err.message : \"unknown\"}]`,\n        });\n\n        if (NoObjectGeneratedError.isInstance(err)) {\n          this.logger?.({\n            category: \"AISDK error\",\n            message: err.message,\n            level: 0,\n            auxiliary: {\n              cause: {\n                value: JSON.stringify(err.cause ?? {}),\n                type: \"object\",\n              },\n              text: {\n                value: err.text ?? \"\",\n                type: \"string\",\n              },\n              response: {\n                value: JSON.stringify(err.response ?? {}),\n                type: \"object\",\n              },\n              usage: {\n                value: JSON.stringify(err.usage ?? {}),\n                type: \"object\",\n              },\n              finishReason: {\n                value: err.finishReason ?? \"unknown\",\n                type: \"string\",\n              },\n              requestId: {\n                value: options.requestId,\n                type: \"string\",\n              },\n            },\n          });\n\n          throw err;\n        }\n        throw err;\n      }\n\n      const result = {\n        data: objectResponse.object,\n        usage: {\n          prompt_tokens: objectResponse.usage.inputTokens ?? 0,\n          completion_tokens: objectResponse.usage.outputTokens ?? 0,\n          reasoning_tokens: objectResponse.usage.reasoningTokens ?? 0,\n          cached_input_tokens: objectResponse.usage.cachedInputTokens ?? 0,\n          total_tokens: objectResponse.usage.totalTokens ?? 0,\n        },\n      } as T;\n\n      // Log LLM response for generateObject\n      SessionFileLogger.logLlmResponse({\n        requestId: llmRequestId,\n        model: this.model.modelId,\n        operation: \"generateObject\",\n        output: JSON.stringify(objectResponse.object),\n        inputTokens: objectResponse.usage.inputTokens,\n        outputTokens: objectResponse.usage.outputTokens,\n      });\n\n      this.logger?.({\n        category: \"aisdk\",\n        message: \"response\",\n        level: 1,\n        auxiliary: {\n          response: {\n            value: JSON.stringify({\n              object: objectResponse.object,\n              usage: objectResponse.usage,\n              finishReason: objectResponse.finishReason,\n              // Omit request and response properties that might contain images\n            }),\n            type: \"object\",\n          },\n          requestId: {\n            value: options.requestId,\n            type: \"string\",\n          },\n        },\n      });\n\n      return result;\n    }\n\n    const tools: ToolSet = {};\n    if (options.tools && options.tools.length > 0) {\n      for (const tool of options.tools) {\n        tools[tool.name] = {\n          description: tool.description,\n          inputSchema: tool.parameters,\n        } as Tool;\n      }\n    }\n\n    // Log LLM request for generateText (act/observe)\n    const llmRequestId = uuidv7();\n    const toolCount = Object.keys(tools).length;\n    const promptPreview = formatLlmPromptPreview(options.messages, {\n      toolCount,\n    });\n    SessionFileLogger.logLlmRequest({\n      requestId: llmRequestId,\n      model: this.model.modelId,\n      operation: \"generateText\",\n      prompt: promptPreview,\n    });\n\n    let textResponse: Awaited<ReturnType<typeof generateText>>;\n    try {\n      textResponse = await generateText({\n        model: this.model,\n        messages: formattedMessages,\n        tools: Object.keys(tools).length > 0 ? tools : undefined,\n        toolChoice:\n          Object.keys(tools).length > 0\n            ? options.tool_choice === \"required\"\n              ? \"required\"\n              : options.tool_choice === \"none\"\n                ? \"none\"\n                : \"auto\"\n            : undefined,\n        temperature,\n      });\n    } catch (err) {\n      // Log error response to maintain request/response pairing\n      SessionFileLogger.logLlmResponse({\n        requestId: llmRequestId,\n        model: this.model.modelId,\n        operation: \"generateText\",\n        output: `[error: ${err instanceof Error ? err.message : \"unknown\"}]`,\n      });\n      throw err;\n    }\n\n    // Transform AI SDK response to match LLMResponse format expected by operator handler\n    const transformedToolCalls = (textResponse.toolCalls || []).map(\n      (toolCall) => ({\n        id:\n          toolCall.toolCallId ||\n          `call_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,\n        type: \"function\",\n        function: {\n          name: toolCall.toolName,\n          arguments: JSON.stringify(toolCall.input),\n        },\n      }),\n    );\n\n    const result = {\n      id: `chatcmpl_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,\n      object: \"chat.completion\",\n      created: Math.floor(Date.now() / 1000),\n      model: this.model.modelId,\n      choices: [\n        {\n          index: 0,\n          message: {\n            role: \"assistant\",\n            content: textResponse.text || null,\n            tool_calls: transformedToolCalls,\n          },\n          finish_reason: textResponse.finishReason || \"stop\",\n        },\n      ],\n      usage: {\n        prompt_tokens: textResponse.usage.inputTokens ?? 0,\n        completion_tokens: textResponse.usage.outputTokens ?? 0,\n        reasoning_tokens: textResponse.usage.reasoningTokens ?? 0,\n        cached_input_tokens: textResponse.usage.cachedInputTokens ?? 0,\n        total_tokens: textResponse.usage.totalTokens ?? 0,\n      },\n    } as T;\n\n    // Log LLM response for generateText\n    SessionFileLogger.logLlmResponse({\n      requestId: llmRequestId,\n      model: this.model.modelId,\n      operation: \"generateText\",\n      output:\n        textResponse.text ||\n        (transformedToolCalls.length > 0\n          ? `[${transformedToolCalls.length} tool calls]`\n          : \"\"),\n      inputTokens: textResponse.usage.inputTokens,\n      outputTokens: textResponse.usage.outputTokens,\n    });\n\n    this.logger?.({\n      category: \"aisdk\",\n      message: \"response\",\n      level: 2,\n      auxiliary: {\n        response: {\n          value: JSON.stringify({\n            text: textResponse.text,\n            usage: textResponse.usage,\n            finishReason: textResponse.finishReason,\n            // Omit request and response properties that might contain images\n          }),\n          type: \"object\",\n        },\n        requestId: {\n          value: options.requestId,\n          type: \"string\",\n        },\n      },\n    });\n\n    return result;\n  }\n}\n"]}

package/dist/esm/lib/v3/logger.d.ts

@@ -0,0 +1,9 @@
+import type { LogLine } from "./types/public/logs.js";
+export declare function bindInstanceLogger(instanceId: string, logger: (line: LogLine) => void): void;
+export declare function unbindInstanceLogger(instanceId: string): void;
+export declare function withInstanceLogContext<T>(instanceId: string, fn: () => T): T;
+/**
+ * Routes logs to the appropriate instance logger based on AsyncLocalStorage context.
+ * Falls back to console output if no instance context is available.
+ */
+export declare function v3Logger(line: LogLine): void;

package/dist/esm/lib/v3/logger.js

@@ -0,0 +1,96 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * Stagehand V3 Logging
+ *
+ * Design goals:
+ * - Support concurrent V3 instances with independent logger configuration
+ * - Each V3 instance has its own StagehandLogger (handles usePino, verbose, externalLogger)
+ * - Provide AsyncLocalStorage-based routing for backward compatibility with handler code
+ * - Prevent cross-talk between concurrent instances
+ *
+ * How it works:
+ * - Each V3 instance creates a StagehandLogger in its constructor (per-instance config)
+ * - bindInstanceLogger()/unbindInstanceLogger(): registers logger callback per instance ID
+ * - withInstanceLogContext(): establishes AsyncLocalStorage context for an async operation
+ * - v3Logger(): routes logs using AsyncLocalStorage with console fallback
+ *
+ * ⚠️ CONTEXT LOSS SCENARIOS:
+ * 1. setTimeout/setInterval callbacks lose context (runs outside AsyncLocalStorage scope)
+ * 2. Event emitters (EventEmitter.on) lose context (callback invoked outside scope)
+ * 3. Fire-and-forget promises (void promise) lose context if they don't complete synchronously
+ * 4. Third-party library callbacks may lose context depending on implementation
+ *
+ * WORKAROUND for context loss:
+ * - Use explicit logger parameter instead of v3Logger()
+ * - Wrap callback in withInstanceLogContext() manually
+ * - Or let logs fall back to console (acceptable for edge cases)
+ */
+// Per-instance routing using AsyncLocalStorage
+const logContext = new AsyncLocalStorage();
+const instanceLoggers = new Map();
+export function bindInstanceLogger(instanceId, logger) {
+    instanceLoggers.set(instanceId, logger);
+}
+export function unbindInstanceLogger(instanceId) {
+    instanceLoggers.delete(instanceId);
+}
+export function withInstanceLogContext(instanceId, fn) {
+    return logContext.run(instanceId, fn);
+}
+/**
+ * Routes logs to the appropriate instance logger based on AsyncLocalStorage context.
+ * Falls back to console output if no instance context is available.
+ */
+export function v3Logger(line) {
+    const id = logContext.getStore();
+    if (id) {
+        const fn = instanceLoggers.get(id);
+        if (fn) {
+            const enriched = {
+                ...line,
+                auxiliary: {
+                    ...(line.auxiliary || {}),
+                },
+            };
+            try {
+                fn(enriched);
+                return;
+            }
+            catch {
+                // fallback to console below
+            }
+        }
+    }
+    // Fallback: log to console when no instance context
+    const ts = line.timestamp ?? new Date().toISOString();
+    const lvl = line.level ?? 1;
+    const levelStr = lvl === 0 ? "ERROR" : lvl === 2 ? "DEBUG" : "INFO";
+    let output = `[${ts}] ${levelStr}: ${line.message}`;
+    if (line.auxiliary) {
+        for (const [key, { value, type }] of Object.entries(line.auxiliary)) {
+            let formattedValue = value;
+            if (type === "object") {
+                try {
+                    formattedValue = JSON.stringify(JSON.parse(value), null, 2)
+                        .split("\n")
+                        .map((line, i) => (i === 0 ? line : `    ${line}`))
+                        .join("\n");
+                }
+                catch {
+                    formattedValue = value;
+                }
+            }
+            output += `\n    ${key}: ${formattedValue}`;
+        }
+    }
+    if (lvl === 0) {
+        console.error(output);
+    }
+    else if (lvl === 2) {
+        (console.debug ?? console.log)(output);
+    }
+    else {
+        console.log(output);
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/esm/lib/v3/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../../lib/v3/logger.ts"],"names":[],"mappings":"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","sourcesContent":["import type { LogLine } from \"./types/public/logs.js\";\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\n/**\n * Stagehand V3 Logging\n *\n * Design goals:\n * - Support concurrent V3 instances with independent logger configuration\n * - Each V3 instance has its own StagehandLogger (handles usePino, verbose, externalLogger)\n * - Provide AsyncLocalStorage-based routing for backward compatibility with handler code\n * - Prevent cross-talk between concurrent instances\n *\n * How it works:\n * - Each V3 instance creates a StagehandLogger in its constructor (per-instance config)\n * - bindInstanceLogger()/unbindInstanceLogger(): registers logger callback per instance ID\n * - withInstanceLogContext(): establishes AsyncLocalStorage context for an async operation\n * - v3Logger(): routes logs using AsyncLocalStorage with console fallback\n *\n * ⚠️ CONTEXT LOSS SCENARIOS:\n * 1. setTimeout/setInterval callbacks lose context (runs outside AsyncLocalStorage scope)\n * 2. Event emitters (EventEmitter.on) lose context (callback invoked outside scope)\n * 3. Fire-and-forget promises (void promise) lose context if they don't complete synchronously\n * 4. Third-party library callbacks may lose context depending on implementation\n *\n * WORKAROUND for context loss:\n * - Use explicit logger parameter instead of v3Logger()\n * - Wrap callback in withInstanceLogContext() manually\n * - Or let logs fall back to console (acceptable for edge cases)\n */\n\n// Per-instance routing using AsyncLocalStorage\nconst logContext = new AsyncLocalStorage<string>();\nconst instanceLoggers = new Map<string, (line: LogLine) => void>();\n\nexport function bindInstanceLogger(\n  instanceId: string,\n  logger: (line: LogLine) => void,\n): void {\n  instanceLoggers.set(instanceId, logger);\n}\n\nexport function unbindInstanceLogger(instanceId: string): void {\n  instanceLoggers.delete(instanceId);\n}\n\nexport function withInstanceLogContext<T>(instanceId: string, fn: () => T): T {\n  return logContext.run(instanceId, fn);\n}\n\n/**\n * Routes logs to the appropriate instance logger based on AsyncLocalStorage context.\n * Falls back to console output if no instance context is available.\n */\nexport function v3Logger(line: LogLine): void {\n  const id = logContext.getStore();\n  if (id) {\n    const fn = instanceLoggers.get(id);\n    if (fn) {\n      const enriched: LogLine = {\n        ...line,\n        auxiliary: {\n          ...(line.auxiliary || {}),\n        },\n      };\n      try {\n        fn(enriched);\n        return;\n      } catch {\n        // fallback to console below\n      }\n    }\n  }\n\n  // Fallback: log to console when no instance context\n  const ts = line.timestamp ?? new Date().toISOString();\n  const lvl = line.level ?? 1;\n  const levelStr = lvl === 0 ? \"ERROR\" : lvl === 2 ? \"DEBUG\" : \"INFO\";\n  let output = `[${ts}] ${levelStr}: ${line.message}`;\n\n  if (line.auxiliary) {\n    for (const [key, { value, type }] of Object.entries(line.auxiliary)) {\n      let formattedValue = value;\n      if (type === \"object\") {\n        try {\n          formattedValue = JSON.stringify(JSON.parse(value), null, 2)\n            .split(\"\\n\")\n            .map((line, i) => (i === 0 ? line : `    ${line}`))\n            .join(\"\\n\");\n        } catch {\n          formattedValue = value;\n        }\n      }\n      output += `\\n    ${key}: ${formattedValue}`;\n    }\n  }\n\n  if (lvl === 0) {\n    console.error(output);\n  } else if (lvl === 2) {\n    (console.debug ?? console.log)(output);\n  } else {\n    console.log(output);\n  }\n}\n"]}

package/dist/esm/lib/v3/mcp/connection.d.ts

@@ -0,0 +1,11 @@
+import { Client, ClientOptions } from "@modelcontextprotocol/sdk/client/index.js";
+export interface ConnectToMCPServerOptions {
+    serverUrl: string | URL;
+    clientOptions?: ClientOptions;
+}
+export interface StdioServerConfig {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export declare const connectToMCPServer: (serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions) => Promise<Client>;

package/dist/esm/lib/v3/mcp/connection.js

@@ -0,0 +1,49 @@
+import { Client, } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { MCPConnectionError } from "../types/public/sdkErrors.js";
+export const connectToMCPServer = async (serverConfig) => {
+    try {
+        let transport;
+        let clientOptions;
+        // Check if it's a stdio config (has 'command' property)
+        if (typeof serverConfig === "object" && "command" in serverConfig) {
+            transport = new StdioClientTransport(serverConfig);
+        }
+        else {
+            // Handle URL-based connection
+            let serverUrl;
+            if (typeof serverConfig === "string" || serverConfig instanceof URL) {
+                serverUrl = serverConfig;
+            }
+            else {
+                serverUrl = serverConfig.serverUrl;
+                clientOptions = serverConfig
+                    .clientOptions;
+            }
+            transport = new StreamableHTTPClientTransport(new URL(serverUrl));
+        }
+        const client = new Client({
+            name: "Stagehand",
+            version: "1.0.0",
+            ...clientOptions,
+        });
+        await client.connect(transport);
+        try {
+            await client.ping();
+        }
+        catch (pingError) {
+            await client.close();
+            throw new MCPConnectionError(serverConfig.toString(), pingError);
+        }
+        return client;
+    }
+    catch (error) {
+        // Handle any errors during transport/client creation or connection
+        if (error instanceof MCPConnectionError) {
+            throw error; // Re-throw our custom error
+        }
+        throw new MCPConnectionError(serverConfig.toString(), error);
+    }
+};
+//# sourceMappingURL=connection.js.map

package/dist/esm/lib/v3/mcp/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../../../../lib/v3/mcp/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,GAEP,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAalE,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,YAA0E,EACzD,EAAE;IACnB,IAAI,CAAC;QACH,IAAI,SAAS,CAAC;QACd,IAAI,aAAwC,CAAC;QAE7C,wDAAwD;QACxD,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;YAClE,SAAS,GAAG,IAAI,oBAAoB,CAAC,YAAY,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,8BAA8B;YAC9B,IAAI,SAAuB,CAAC;YAE5B,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,YAAY,GAAG,EAAE,CAAC;gBACpE,SAAS,GAAG,YAAY,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,SAAS,GAAI,YAA0C,CAAC,SAAS,CAAC;gBAClE,aAAa,GAAI,YAA0C;qBACxD,aAAa,CAAC;YACnB,CAAC;YAED,SAAS,GAAG,IAAI,6BAA6B,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;YACxB,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,OAAO;YAChB,GAAG,aAAa;SACjB,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEhC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC;QACnE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mEAAmE;QACnE,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;YACxC,MAAM,KAAK,CAAC,CAAC,4BAA4B;QAC3C,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC,CAAC","sourcesContent":["import {\n  Client,\n  ClientOptions,\n} from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StreamableHTTPClientTransport } from \"@modelcontextprotocol/sdk/client/streamableHttp.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\nimport { MCPConnectionError } from \"../types/public/sdkErrors.js\";\n\nexport interface ConnectToMCPServerOptions {\n  serverUrl: string | URL;\n  clientOptions?: ClientOptions;\n}\n\nexport interface StdioServerConfig {\n  command: string;\n  args?: string[];\n  env?: Record<string, string>;\n}\n\nexport const connectToMCPServer = async (\n  serverConfig: string | URL | StdioServerConfig | ConnectToMCPServerOptions,\n): Promise<Client> => {\n  try {\n    let transport;\n    let clientOptions: ClientOptions | undefined;\n\n    // Check if it's a stdio config (has 'command' property)\n    if (typeof serverConfig === \"object\" && \"command\" in serverConfig) {\n      transport = new StdioClientTransport(serverConfig);\n    } else {\n      // Handle URL-based connection\n      let serverUrl: string | URL;\n\n      if (typeof serverConfig === \"string\" || serverConfig instanceof URL) {\n        serverUrl = serverConfig;\n      } else {\n        serverUrl = (serverConfig as ConnectToMCPServerOptions).serverUrl;\n        clientOptions = (serverConfig as ConnectToMCPServerOptions)\n          .clientOptions;\n      }\n\n      transport = new StreamableHTTPClientTransport(new URL(serverUrl));\n    }\n\n    const client = new Client({\n      name: \"Stagehand\",\n      version: \"1.0.0\",\n      ...clientOptions,\n    });\n\n    await client.connect(transport);\n\n    try {\n      await client.ping();\n    } catch (pingError) {\n      await client.close();\n      throw new MCPConnectionError(serverConfig.toString(), pingError);\n    }\n\n    return client;\n  } catch (error) {\n    // Handle any errors during transport/client creation or connection\n    if (error instanceof MCPConnectionError) {\n      throw error; // Re-throw our custom error\n    }\n    throw new MCPConnectionError(serverConfig.toString(), error);\n  }\n};\n"]}

package/dist/esm/lib/v3/mcp/utils.d.ts

@@ -0,0 +1,3 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ToolSet } from "ai";
+export declare const resolveTools: (clients: (Client | string)[], userTools: ToolSet) => Promise<ToolSet>;

package/dist/esm/lib/v3/mcp/utils.js

@@ -0,0 +1,36 @@
+import { jsonSchemaToZod } from "../../utils.js";
+import { connectToMCPServer } from "./connection.js";
+export const resolveTools = async (clients, userTools) => {
+    const tools = { ...userTools };
+    for (const client of clients) {
+        let clientInstance;
+        if (typeof client === "string") {
+            clientInstance = await connectToMCPServer(client);
+        }
+        else {
+            clientInstance = client;
+        }
+        let nextCursor = undefined;
+        do {
+            const clientTools = await clientInstance.listTools({
+                cursor: nextCursor,
+            });
+            for (const tool of clientTools.tools) {
+                tools[tool.name] = {
+                    description: tool.description,
+                    inputSchema: jsonSchemaToZod(tool.inputSchema),
+                    execute: async (input) => {
+                        const result = await clientInstance.callTool({
+                            name: tool.name,
+                            arguments: input,
+                        });
+                        return result;
+                    },
+                };
+            }
+            nextCursor = clientTools.nextCursor;
+        } while (nextCursor);
+    }
+    return tools;
+};
+//# sourceMappingURL=utils.js.map

package/dist/esm/lib/v3/mcp/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../../lib/v3/mcp/utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,OAA4B,EAC5B,SAAkB,EACA,EAAE;IACpB,MAAM,KAAK,GAAY,EAAE,GAAG,SAAS,EAAE,CAAC;IAExC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,cAAsB,CAAC;QAC3B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,cAAc,GAAG,MAAM,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,cAAc,GAAG,MAAM,CAAC;QAC1B,CAAC;QAED,IAAI,UAAU,GAAuB,SAAS,CAAC;QAE/C,GAAG,CAAC;YACF,MAAM,WAAW,GAAG,MAAM,cAAc,CAAC,SAAS,CAAC;gBACjD,MAAM,EAAE,UAAU;aACnB,CAAC,CAAC;YAEH,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;oBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,WAAyB,CAAC;oBAC5D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;wBACvB,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC;4BAC3C,IAAI,EAAE,IAAI,CAAC,IAAI;4BACf,SAAS,EAAE,KAAK;yBACjB,CAAC,CAAC;wBACH,OAAO,MAAM,CAAC;oBAChB,CAAC;iBACF,CAAC;YACJ,CAAC;YACD,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC;QACtC,CAAC,QAAQ,UAAU,EAAE;IACvB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC,CAAC","sourcesContent":["import { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { ToolSet } from \"ai\";\nimport { JsonSchema, jsonSchemaToZod } from \"../../utils.js\";\nimport { connectToMCPServer } from \"./connection.js\";\n\nexport const resolveTools = async (\n  clients: (Client | string)[],\n  userTools: ToolSet,\n): Promise<ToolSet> => {\n  const tools: ToolSet = { ...userTools };\n\n  for (const client of clients) {\n    let clientInstance: Client;\n    if (typeof client === \"string\") {\n      clientInstance = await connectToMCPServer(client);\n    } else {\n      clientInstance = client;\n    }\n\n    let nextCursor: string | undefined = undefined;\n\n    do {\n      const clientTools = await clientInstance.listTools({\n        cursor: nextCursor,\n      });\n\n      for (const tool of clientTools.tools) {\n        tools[tool.name] = {\n          description: tool.description,\n          inputSchema: jsonSchemaToZod(tool.inputSchema as JsonSchema),\n          execute: async (input) => {\n            const result = await clientInstance.callTool({\n              name: tool.name,\n              arguments: input,\n            });\n            return result;\n          },\n        };\n      }\n      nextCursor = clientTools.nextCursor;\n    } while (nextCursor);\n  }\n\n  return tools;\n};\n"]}

package/dist/esm/lib/v3/shutdown/cleanupLocal.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared cleanup logic for locally launched Chrome.
+ *
+ * Used by both `V3.close()` (normal shutdown) and the supervisor process
+ * (crash cleanup). The caller provides a `killChrome` callback since the
+ * kill mechanism differs: chrome-launcher's `chrome.kill()` in-process
+ * vs raw `process.kill(pid)` from the supervisor.
+ */
+export declare function cleanupLocalBrowser(opts: {
+    killChrome?: () => Promise<void> | void;
+    userDataDir?: string;
+    createdTempProfile?: boolean;
+    preserveUserDataDir?: boolean;
+}): Promise<void>;