opensteer 0.4.11 → 0.4.13

package/dist/cli/server.cjs

@@ -110,6 +110,15 @@ function resolveProviderInfo(modelStr) {
   }
   return { pkg: "@ai-sdk/openai", providerFn: "openai" };
 }
+function stripProviderPrefix(modelStr) {
+  const slash = modelStr.indexOf("/");
+  if (slash <= 0) return modelStr;
+  const provider = modelStr.slice(0, slash).toLowerCase();
+  if (provider === "openai" || provider === "anthropic" || provider === "google" || provider === "xai" || provider === "groq") {
+    return modelStr.slice(slash + 1);
+  }
+  return modelStr;
+}
 async function getModelProvider(modelStr) {
   const { pkg, providerFn } = resolveProviderInfo(modelStr);
   let mod;
@@ -126,7 +135,7 @@ async function getModelProvider(modelStr) {
       `Provider '${providerFn}' not found in '${pkg}'. Ensure you have the latest version installed.`
     );
   }
-  const modelId = modelStr.startsWith("groq/") ? modelStr.slice("groq/".length) : modelStr;
+  const modelId = stripProviderPrefix(modelStr);
   return provider(modelId);
 }
 var PROVIDER_MAP;
@@ -134,6 +143,10 @@ var init_model = __esm({
   "src/ai/model.ts"() {
     "use strict";
     PROVIDER_MAP = {
+      "openai/": { pkg: "@ai-sdk/openai", providerFn: "openai" },
+      "anthropic/": { pkg: "@ai-sdk/anthropic", providerFn: "anthropic" },
+      "google/": { pkg: "@ai-sdk/google", providerFn: "google" },
+      "xai/": { pkg: "@ai-sdk/xai", providerFn: "xai" },
       "gpt-": { pkg: "@ai-sdk/openai", providerFn: "openai" },
       "o1-": { pkg: "@ai-sdk/openai", providerFn: "openai" },
       "o3-": { pkg: "@ai-sdk/openai", providerFn: "openai" },
@@ -7797,7 +7810,8 @@ var CloudCdpClient = class {
       const message = error instanceof Error ? error.message : "Failed to connect to cloud CDP endpoint.";
       throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
     }
-    const context = browser.contexts()[0];
+    const contexts = browser.contexts();
+    const context = contexts[0];
     if (!context) {
       await browser.close();
       throw new OpensteerCloudError(
@@ -7805,10 +7819,41 @@ var CloudCdpClient = class {
         "Cloud browser returned no context."
       );
     }
+    const preferred = selectPreferredContextPage(browser, contexts);
+    if (preferred) {
+      return preferred;
+    }
     const page = context.pages()[0] || await context.newPage();
     return { browser, context, page };
   }
 };
+function selectPreferredContextPage(browser, contexts) {
+  let aboutBlankCandidate = null;
+  for (const context of contexts) {
+    for (const page of context.pages()) {
+      const url = safePageUrl(page);
+      if (!isInternalOrEmptyUrl(url)) {
+        return { browser, context, page };
+      }
+      if (!aboutBlankCandidate && url === "about:blank") {
+        aboutBlankCandidate = { browser, context, page };
+      }
+    }
+  }
+  return aboutBlankCandidate;
+}
+function safePageUrl(page) {
+  try {
+    return page.url();
+  } catch {
+    return "";
+  }
+}
+function isInternalOrEmptyUrl(url) {
+  if (!url) return true;
+  if (url === "about:blank") return true;
+  return url.startsWith("chrome://") || url.startsWith("devtools://") || url.startsWith("edge://");
+}
 function withTokenQuery2(wsUrl, token) {
   const url = new URL(wsUrl);
   url.searchParams.set("token", token);
@@ -8070,7 +8115,7 @@ function toCloudErrorCode(code) {
 }
 
 // src/cloud/runtime.ts
-var DEFAULT_CLOUD_BASE_URL = "https://remote.opensteer.com";
+var DEFAULT_CLOUD_BASE_URL = "https://api.opensteer.com";
 function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key") {
   const normalizedBaseUrl = normalizeCloudBaseUrl(baseUrl);
   return {
@@ -8102,187 +8147,2006 @@ function readCloudActionDescription(payload) {
   return normalized.length ? normalized : void 0;
 }
 
-// src/opensteer.ts
-var CLOUD_INTERACTION_METHODS = /* @__PURE__ */ new Set([
-  "click",
-  "dblclick",
-  "rightclick",
-  "hover",
-  "input",
-  "select",
-  "scroll",
-  "uploadFile"
+// src/agent/errors.ts
+var OpensteerAgentError = class extends Error {
+  constructor(message, cause) {
+    super(message, { cause });
+    this.name = "OpensteerAgentError";
+  }
+};
+var OpensteerAgentConfigError = class extends OpensteerAgentError {
+  constructor(message) {
+    super(message);
+    this.name = "OpensteerAgentConfigError";
+  }
+};
+var OpensteerAgentProviderError = class extends OpensteerAgentError {
+  constructor(message) {
+    super(message);
+    this.name = "OpensteerAgentProviderError";
+  }
+};
+var OpensteerAgentExecutionError = class extends OpensteerAgentError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "OpensteerAgentExecutionError";
+  }
+};
+var OpensteerAgentBusyError = class extends OpensteerAgentError {
+  constructor() {
+    super("An OpenSteer agent execution is already in progress on this instance.");
+    this.name = "OpensteerAgentBusyError";
+  }
+};
+var OpensteerAgentActionError = class extends OpensteerAgentError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "OpensteerAgentActionError";
+  }
+};
+var OpensteerAgentApiError = class extends OpensteerAgentError {
+  status;
+  provider;
+  constructor(provider, message, status, cause) {
+    super(message, cause);
+    this.name = "OpensteerAgentApiError";
+    this.provider = provider;
+    this.status = status;
+  }
+};
+
+// src/agent/model.ts
+var SUPPORTED_CUA_PROVIDERS = /* @__PURE__ */ new Set([
+  "openai",
+  "anthropic",
+  "google"
 ]);
-var Opensteer = class _Opensteer {
-  config;
-  aiResolve;
-  aiExtract;
-  namespace;
-  storage;
-  pool;
-  cloud;
-  browser = null;
-  pageRef = null;
-  contextRef = null;
-  ownsBrowser = false;
-  snapshotCache = null;
-  constructor(config = {}) {
-    const resolved = resolveConfig(config);
-    const cloudSelection = resolveCloudSelection({
-      cloud: resolved.cloud
-    });
-    const model = resolved.model;
-    this.config = resolved;
-    this.aiResolve = this.createLazyResolveCallback(model);
-    this.aiExtract = this.createLazyExtractCallback(model);
-    const rootDir = resolved.storage?.rootDir || process.cwd();
-    this.namespace = resolveNamespace(resolved, rootDir);
-    this.storage = new LocalSelectorStorage(rootDir, this.namespace);
-    this.pool = new BrowserPool(resolved.browser || {});
-    if (cloudSelection.cloud) {
-      const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
-      const apiKey = cloudConfig?.apiKey?.trim();
-      if (!apiKey) {
-        throw new Error(
-          "Cloud mode requires a non-empty API key via cloud.apiKey or OPENSTEER_API_KEY."
-        );
-      }
-      this.cloud = createCloudRuntimeState(
-        apiKey,
-        cloudConfig?.baseUrl,
-        cloudConfig?.authScheme
-      );
-    } else {
-      this.cloud = null;
-    }
+function resolveCuaModelConfig(args) {
+  const env = args.env || process.env;
+  const source = resolveModelSource(args.agentConfig.model, args.fallbackModel);
+  const parsed = parseProviderModel(source.modelName);
+  if (!SUPPORTED_CUA_PROVIDERS.has(parsed.provider)) {
+    throw new OpensteerAgentProviderError(
+      `Unsupported CUA provider "${parsed.provider}". Supported providers: openai, anthropic, google.`
+    );
   }
-  createLazyResolveCallback(model) {
-    let resolverPromise = null;
-    return async (...args) => {
-      try {
-        if (!resolverPromise) {
-          resolverPromise = Promise.resolve().then(() => (init_resolver(), resolver_exports)).then(
-            (m) => m.createResolveCallback(model)
-          );
-        }
-        const resolver = await resolverPromise;
-        return resolver(...args);
-      } catch (err) {
-        resolverPromise = null;
-        throw err;
-      }
+  const apiKey = resolveProviderApiKey(parsed.provider, source.options.apiKey, env);
+  return {
+    provider: parsed.provider,
+    fullModelName: `${parsed.provider}/${parsed.modelName}`,
+    providerModelName: parsed.modelName,
+    apiKey,
+    baseUrl: normalizeOptional(source.options.baseUrl),
+    organization: normalizeOptional(source.options.organization),
+    thinkingBudget: typeof source.options.thinkingBudget === "number" && Number.isFinite(source.options.thinkingBudget) ? source.options.thinkingBudget : void 0,
+    environment: normalizeOptional(source.options.environment)
+  };
+}
+function resolveModelSource(model, fallbackModel) {
+  if (model && typeof model === "object") {
+    const modelName2 = normalizeRequired(model.modelName, "agent.model.modelName");
+    const { modelName: _, ...options } = model;
+    return {
+      modelName: modelName2,
+      options
     };
   }
-  createLazyExtractCallback(model) {
-    let extractorPromise = null;
-    const extract = async (args) => {
-      try {
-        if (!extractorPromise) {
-          extractorPromise = Promise.resolve().then(() => (init_extractor(), extractor_exports)).then(
-            (m) => m.createExtractCallback(model)
-          );
-        }
-        const extractor = await extractorPromise;
-        return extractor(args);
-      } catch (err) {
-        extractorPromise = null;
-        throw err;
-      }
+  const modelName = normalizeOptional(model) || normalizeOptional(fallbackModel);
+  if (!modelName) {
+    throw new OpensteerAgentConfigError(
+      'A CUA model is required. Pass agent.model (for example "openai/computer-use-preview").'
+    );
+  }
+  return {
+    modelName,
+    options: {}
+  };
+}
+function parseProviderModel(modelName) {
+  const slash = modelName.indexOf("/");
+  if (slash <= 0 || slash === modelName.length - 1) {
+    throw new OpensteerAgentConfigError(
+      `Invalid CUA model "${modelName}". Use "provider/model" format (for example "openai/computer-use-preview").`
+    );
+  }
+  const providerRaw = modelName.slice(0, slash).trim().toLowerCase();
+  const providerModelName = modelName.slice(slash + 1).trim();
+  if (!providerModelName) {
+    throw new OpensteerAgentConfigError(
+      `Invalid CUA model "${modelName}". The model name segment after the provider cannot be empty.`
+    );
+  }
+  if (providerRaw !== "openai" && providerRaw !== "anthropic" && providerRaw !== "google") {
+    throw new OpensteerAgentProviderError(
+      `Unsupported CUA provider "${providerRaw}". Supported providers: openai, anthropic, google.`
+    );
+  }
+  return {
+    provider: providerRaw,
+    modelName: providerModelName
+  };
+}
+function resolveProviderApiKey(provider, explicitApiKey, env) {
+  const explicit = normalizeOptional(explicitApiKey);
+  if (explicit) return explicit;
+  if (provider === "openai") {
+    const value = normalizeOptional(env.OPENAI_API_KEY);
+    if (value) return value;
+    throw new OpensteerAgentConfigError(
+      "OpenAI CUA requires an API key via agent.model.apiKey or OPENAI_API_KEY."
+    );
+  }
+  if (provider === "anthropic") {
+    const value = normalizeOptional(env.ANTHROPIC_API_KEY);
+    if (value) return value;
+    throw new OpensteerAgentConfigError(
+      "Anthropic CUA requires an API key via agent.model.apiKey or ANTHROPIC_API_KEY."
+    );
+  }
+  const googleApiKey = normalizeOptional(env.GOOGLE_GENERATIVE_AI_API_KEY) || normalizeOptional(env.GEMINI_API_KEY) || normalizeOptional(env.GOOGLE_API_KEY);
+  if (googleApiKey) return googleApiKey;
+  throw new OpensteerAgentConfigError(
+    "Google CUA requires an API key via agent.model.apiKey, GOOGLE_GENERATIVE_AI_API_KEY, GEMINI_API_KEY, or GOOGLE_API_KEY."
+  );
+}
+function normalizeOptional(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length ? trimmed : void 0;
+}
+function normalizeRequired(value, field) {
+  const normalized = normalizeOptional(value);
+  if (!normalized) {
+    throw new OpensteerAgentConfigError(`${field} is required.`);
+  }
+  return normalized;
+}
+
+// src/agent/clients/openai.ts
+var import_openai = __toESM(require("openai"), 1);
+
+// src/agent/client.ts
+var CuaClient = class {
+  screenshotProvider = null;
+  actionHandler = null;
+  viewport = {
+    width: 1288,
+    height: 711
+  };
+  currentUrl = null;
+  setViewport(width, height) {
+    this.viewport = {
+      width,
+      height
     };
-    return extract;
   }
-  async invokeCloudActionAndResetCache(method, args) {
-    const result = await this.invokeCloudAction(method, args);
-    this.snapshotCache = null;
-    return result;
+  setCurrentUrl(url) {
+    this.currentUrl = url;
   }
-  async invokeCloudAction(method, args) {
-    const actionClient = this.cloud?.actionClient;
-    const sessionId = this.cloud?.sessionId;
-    if (!actionClient || !sessionId) {
-      throw cloudNotLaunchedError();
+  setScreenshotProvider(provider) {
+    this.screenshotProvider = provider;
+  }
+  setActionHandler(handler) {
+    this.actionHandler = handler;
+  }
+  getScreenshotProvider() {
+    if (!this.screenshotProvider) {
+      throw new Error("CUA screenshot provider is not initialized.");
     }
-    const payload = args && typeof args === "object" ? args : {};
-    try {
-      return await actionClient.request(method, payload);
-    } catch (err) {
-      if (err instanceof OpensteerCloudError && err.code === "CLOUD_ACTION_FAILED" && CLOUD_INTERACTION_METHODS.has(method)) {
-        const detailsRecord = err.details && typeof err.details === "object" ? err.details : null;
-        const cloudFailure = normalizeActionFailure(
-          detailsRecord?.actionFailure
-        );
-        const failure = cloudFailure || classifyActionFailure({
-          action: method,
-          error: err,
-          fallbackMessage: defaultActionFailureMessage(method)
-        });
-        const description = readCloudActionDescription(payload);
-        throw this.buildActionError(
-          method,
-          description,
-          failure,
-          null,
-          err
-        );
-      }
-      throw err;
+    return this.screenshotProvider;
+  }
+  getActionHandler() {
+    if (!this.actionHandler) {
+      throw new Error("CUA action handler is not initialized.");
     }
+    return this.actionHandler;
   }
-  buildActionError(action, description, failure, selectorUsed, cause) {
-    return new OpensteerActionError({
-      action,
-      failure,
-      selectorUsed: selectorUsed || null,
-      message: formatActionFailureMessage(
-        action,
-        description,
-        failure.message
-      ),
-      cause
-    });
+};
+function normalizeExecuteOptions(instructionOrOptions) {
+  if (typeof instructionOrOptions === "string") {
+    return {
+      instruction: normalizeInstruction(instructionOrOptions)
+    };
   }
-  get page() {
-    if (!this.pageRef) {
-      throw new Error(
-        "Browser page is not initialized. Call launch() or Opensteer.from(page)."
-      );
-    }
-    return this.pageRef;
+  if (!instructionOrOptions || typeof instructionOrOptions !== "object" || Array.isArray(instructionOrOptions)) {
+    throw new OpensteerAgentExecutionError(
+      "agent.execute(...) expects either a string instruction or an options object."
+    );
   }
-  get context() {
-    if (!this.contextRef) {
-      throw new Error(
-        "Browser context is not initialized. Call launch() or Opensteer.from(page)."
+  const normalized = {
+    instruction: normalizeInstruction(instructionOrOptions.instruction)
+  };
+  if (instructionOrOptions.maxSteps !== void 0) {
+    normalized.maxSteps = normalizeMaxSteps(instructionOrOptions.maxSteps);
+  }
+  if (instructionOrOptions.highlightCursor !== void 0) {
+    if (typeof instructionOrOptions.highlightCursor !== "boolean") {
+      throw new OpensteerAgentExecutionError(
+        'agent.execute(...) "highlightCursor" must be a boolean when provided.'
       );
     }
-    return this.contextRef;
+    normalized.highlightCursor = instructionOrOptions.highlightCursor;
   }
-  getCloudSessionId() {
-    return this.cloud?.sessionId ?? null;
+  return normalized;
+}
+function normalizeInstruction(instruction) {
+  if (typeof instruction !== "string") {
+    throw new OpensteerAgentExecutionError(
+      'agent.execute(...) requires a non-empty "instruction" string.'
+    );
   }
-  getCloudSessionUrl() {
-    return this.cloud?.cloudSessionUrl ?? null;
+  const normalized = instruction.trim();
+  if (!normalized) {
+    throw new OpensteerAgentExecutionError(
+      'agent.execute(...) requires a non-empty "instruction" string.'
+    );
   }
-  announceCloudSession(args) {
-    if (!this.shouldAnnounceCloudSession()) {
-      return;
-    }
-    const fields = [
-      `sessionId=${args.sessionId}`,
-      `workspaceId=${args.workspaceId}`
+  return normalized;
+}
+function normalizeMaxSteps(maxSteps) {
+  if (typeof maxSteps !== "number" || !Number.isInteger(maxSteps) || maxSteps <= 0) {
+    throw new OpensteerAgentExecutionError(
+      'agent.execute(...) "maxSteps" must be a positive integer when provided.'
+    );
+  }
+  return maxSteps;
+}
+
+// src/agent/clients/openai.ts
+var OpenAICuaClient = class extends CuaClient {
+  client;
+  modelConfig;
+  constructor(modelConfig) {
+    super();
+    this.modelConfig = modelConfig;
+    this.client = new import_openai.default({
+      apiKey: modelConfig.apiKey,
+      baseURL: modelConfig.baseUrl,
+      organization: modelConfig.organization
+    });
+  }
+  async execute(input) {
+    const actions = [];
+    let finalMessage = "";
+    let completed = false;
+    let step = 0;
+    let previousResponseId;
+    let nextInputItems = [
+      {
+        role: "system",
+        content: input.systemPrompt
+      },
+      {
+        role: "user",
+        content: input.instruction
+      }
     ];
-    if (args.cloudSessionUrl) {
-      fields.push(`url=${args.cloudSessionUrl}`);
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalReasoningTokens = 0;
+    let totalInferenceTimeMs = 0;
+    while (!completed && step < input.maxSteps) {
+      const startedAt = Date.now();
+      const response = await this.getAction(nextInputItems, previousResponseId);
+      totalInferenceTimeMs += Date.now() - startedAt;
+      totalInputTokens += toNumber(response.usage?.input_tokens);
+      totalOutputTokens += toNumber(response.usage?.output_tokens);
+      totalReasoningTokens += toNumber(response.usage?.output_tokens_details?.reasoning_tokens) || toNumber(toRecord(response.usage).reasoning_tokens);
+      previousResponseId = normalizeString(response.id) || previousResponseId;
+      const stepResult = await this.processResponse(response.output);
+      actions.push(...stepResult.actions);
+      nextInputItems = stepResult.nextInputItems;
+      completed = stepResult.completed;
+      if (stepResult.message) {
+        finalMessage = stepResult.message;
+      }
+      step += 1;
     }
-    process.stderr.write(`[opensteer] cloud session ready ${fields.join(" ")}
-`);
+    return {
+      success: completed,
+      completed,
+      message: finalMessage,
+      actions,
+      usage: {
+        inputTokens: totalInputTokens,
+        outputTokens: totalOutputTokens,
+        reasoningTokens: totalReasoningTokens > 0 ? totalReasoningTokens : void 0,
+        inferenceTimeMs: totalInferenceTimeMs
+      }
+    };
   }
-  shouldAnnounceCloudSession() {
-    const cloudConfig = this.config.cloud && typeof this.config.cloud === "object" ? this.config.cloud : null;
-    const announce = cloudConfig?.announce ?? "always";
-    if (announce === "off") {
-      return false;
-    }
+  async getAction(inputItems, previousResponseId) {
+    const request = {
+      model: this.modelConfig.providerModelName,
+      tools: [
+        {
+          type: "computer_use_preview",
+          display_width: this.viewport.width,
+          display_height: this.viewport.height,
+          environment: "browser"
+        }
+      ],
+      input: inputItems,
+      truncation: "auto",
+      ...previousResponseId ? { previous_response_id: previousResponseId } : {}
+    };
+    try {
+      return await this.client.responses.create(request);
+    } catch (error) {
+      throw mapOpenAiApiError(error);
+    }
+  }
+  async processResponse(output) {
+    const actions = [];
+    const nextInputItems = [];
+    const messageParts = [];
+    let hasComputerAction = false;
+    for (const item of output) {
+      if (item.type === "computer_call") {
+        hasComputerAction = true;
+        const action = toAgentAction(item.action);
+        actions.push(action);
+        let actionError;
+        try {
+          await this.getActionHandler()(action);
+        } catch (error) {
+          actionError = error instanceof Error ? error.message : String(error);
+        }
+        const outputItem = {
+          type: "computer_call_output",
+          call_id: item.call_id
+        };
+        const safetyChecks = item.pending_safety_checks.length ? item.pending_safety_checks : void 0;
+        const screenshotDataUrl = await this.captureScreenshotDataUrl();
+        const outputPayload = {
+          type: "input_image",
+          image_url: screenshotDataUrl
+        };
+        if (this.currentUrl) {
+          outputPayload.current_url = this.currentUrl;
+        }
+        if (actionError) {
+          outputPayload.error = actionError;
+        }
+        outputItem.output = outputPayload;
+        if (safetyChecks) {
+          outputItem.acknowledged_safety_checks = safetyChecks;
+        }
+        nextInputItems.push(outputItem);
+      }
+      if (item.type === "message") {
+        for (const content of item.content) {
+          if (content.type === "output_text") {
+            messageParts.push(content.text);
+          }
+        }
+      }
+    }
+    return {
+      actions,
+      nextInputItems,
+      completed: !hasComputerAction,
+      message: messageParts.join("\n").trim()
+    };
+  }
+  async captureScreenshotDataUrl() {
+    const base64 = await this.getScreenshotProvider()();
+    return `data:image/png;base64,${base64}`;
+  }
+};
+function toAgentAction(action) {
+  const actionRecord = toRecord(action);
+  return {
+    type: normalizeString(actionRecord.type) || "unknown",
+    ...actionRecord
+  };
+}
+function mapOpenAiApiError(error) {
+  const errorRecord = toRecord(error);
+  const nestedError = toRecord(errorRecord.error);
+  const status = toNumber(errorRecord.status);
+  const message = normalizeString(nestedError.message) || (error instanceof Error ? error.message : String(error));
+  return new OpensteerAgentApiError("openai", message, status, error);
+}
+function toRecord(value) {
+  return value && typeof value === "object" ? value : {};
+}
+function toNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function normalizeString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+
+// src/agent/clients/anthropic.ts
+var import_sdk = __toESM(require("@anthropic-ai/sdk"), 1);
+var AnthropicCuaClient = class extends CuaClient {
+  modelConfig;
+  client;
+  constructor(modelConfig) {
+    super();
+    this.modelConfig = modelConfig;
+    this.client = new import_sdk.default({
+      apiKey: modelConfig.apiKey,
+      baseURL: modelConfig.baseUrl
+    });
+  }
+  async execute(input) {
+    const actions = [];
+    let finalMessage = "";
+    let completed = false;
+    let step = 0;
+    const messages = [
+      {
+        role: "user",
+        content: input.instruction
+      }
+    ];
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalReasoningTokens = 0;
+    let totalInferenceTimeMs = 0;
+    while (!completed && step < input.maxSteps) {
+      const startedAt = Date.now();
+      const response = await this.getAction(messages, input.systemPrompt);
+      totalInferenceTimeMs += Date.now() - startedAt;
+      totalInputTokens += toNumber2(response?.usage?.input_tokens);
+      totalOutputTokens += toNumber2(response?.usage?.output_tokens);
+      totalReasoningTokens += toNumber2(toRecord2(response.usage).reasoning_tokens);
+      const content = response.content.map((item) => toRecord2(item));
+      const toolUseItems = content.filter(
+        (item) => item.type === "tool_use" && item.name === "computer"
+      );
+      const message = extractTextMessage(content);
+      if (message) {
+        finalMessage = message;
+      }
+      messages.push({
+        role: "assistant",
+        content
+      });
+      if (!toolUseItems.length) {
+        completed = true;
+      } else {
+        const stepResult = await this.processToolUseItems(toolUseItems);
+        actions.push(...stepResult.actions);
+        messages.push({
+          role: "user",
+          content: stepResult.toolResults
+        });
+      }
+      step += 1;
+    }
+    return {
+      success: completed,
+      completed,
+      message: finalMessage,
+      actions,
+      usage: {
+        inputTokens: totalInputTokens,
+        outputTokens: totalOutputTokens,
+        reasoningTokens: totalReasoningTokens > 0 ? totalReasoningTokens : void 0,
+        inferenceTimeMs: totalInferenceTimeMs
+      }
+    };
+  }
+  async processToolUseItems(items) {
+    const actions = [];
+    const toolResults = [];
+    for (const item of items) {
+      const toolUseId = normalizeString2(item.id);
+      const input = item.input && typeof item.input === "object" ? item.input : {};
+      const action = convertAnthropicAction(input);
+      actions.push(action);
+      let errorMessage2;
+      try {
+        await this.getActionHandler()(action);
+      } catch (error) {
+        errorMessage2 = error instanceof Error ? error.message : String(error);
+      }
+      let imageBlock = null;
+      try {
+        const screenshot = await this.getScreenshotProvider()();
+        imageBlock = {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: "image/png",
+            data: screenshot
+          }
+        };
+      } catch (error) {
+        errorMessage2 = errorMessage2 || (error instanceof Error ? error.message : String(error));
+      }
+      const resultContent = [];
+      if (imageBlock) {
+        resultContent.push(imageBlock);
+      }
+      if (this.currentUrl) {
+        resultContent.push({
+          type: "text",
+          text: `Current URL: ${this.currentUrl}`
+        });
+      }
+      if (errorMessage2) {
+        resultContent.push({
+          type: "text",
+          text: `Error: ${errorMessage2}`
+        });
+      }
+      toolResults.push({
+        type: "tool_result",
+        tool_use_id: toolUseId || "unknown_tool_use_id",
+        content: resultContent.length > 0 ? resultContent : [
+          {
+            type: "text",
+            text: "Action completed."
+          }
+        ]
+      });
+    }
+    return {
+      actions,
+      toolResults
+    };
+  }
+  async getAction(messages, systemPrompt) {
+    const toolVersion = requiresNewestAnthropicToolVersion(
+      this.modelConfig.providerModelName
+    ) ? "computer_20251124" : "computer_20250124";
+    const betaFlag = toolVersion === "computer_20251124" ? "computer-use-2025-11-24" : "computer-use-2025-01-24";
+    const request = {
+      model: this.modelConfig.providerModelName,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages,
+      tools: [
+        {
+          type: toolVersion,
+          name: "computer",
+          display_width_px: this.viewport.width,
+          display_height_px: this.viewport.height,
+          display_number: 1
+        }
+      ],
+      betas: [betaFlag]
+    };
+    if (typeof this.modelConfig.thinkingBudget === "number") {
+      request.thinking = {
+        type: "enabled",
+        budget_tokens: this.modelConfig.thinkingBudget
+      };
+    }
+    try {
+      return await this.client.beta.messages.create(
+        request
+      );
+    } catch (error) {
+      throw mapAnthropicApiError(error);
+    }
+  }
+};
+function convertAnthropicAction(input) {
+  const type = normalizeString2(input.action) || "unknown";
+  if (type === "left_click") {
+    const coordinates = resolveCoordinates(input, type);
+    return {
+      type: "click",
+      x: coordinates.x,
+      y: coordinates.y,
+      button: "left"
+    };
+  }
+  if (type === "double_click" || type === "doubleClick") {
+    const coordinates = resolveCoordinates(input, type);
+    return {
+      type: "double_click",
+      x: coordinates.x,
+      y: coordinates.y
+    };
+  }
+  if (type === "drag" || type === "left_click_drag") {
+    const start = resolveCoordinateArray(
+      input.start_coordinate,
+      type,
+      "start_coordinate"
+    );
+    const end = resolveCoordinates(input, type);
+    return {
+      type: "drag",
+      path: [start, end]
+    };
+  }
+  if (type === "scroll") {
+    const coordinates = resolveCoordinates(input, type);
+    const direction = normalizeScrollDirection(input.scroll_direction, type);
+    const amount = resolvePositiveNumber(
+      input.scroll_amount,
+      type,
+      "scroll_amount"
+    );
+    const magnitude = Math.max(1, amount) * 100;
+    let scrollX = 0;
+    let scrollY = 0;
+    if (direction === "up") scrollY = -magnitude;
+    if (direction === "down") scrollY = magnitude;
+    if (direction === "left") scrollX = -magnitude;
+    if (direction === "right") scrollX = magnitude;
+    return {
+      type: "scroll",
+      x: coordinates.x,
+      y: coordinates.y,
+      scrollX,
+      scrollY
+    };
+  }
+  if (type === "keypress" || type === "key") {
+    const keyText = normalizeRequiredString(
+      input.text,
+      `Anthropic action "${type}" requires a non-empty text value.`
+    );
+    return {
+      type: "keypress",
+      keys: [keyText]
+    };
+  }
+  if (type === "move") {
+    const coordinates = resolveCoordinates(input, type);
+    return {
+      type: "move",
+      x: coordinates.x,
+      y: coordinates.y
+    };
+  }
+  if (type === "click") {
+    const coordinates = resolveCoordinates(input, type);
+    return {
+      type: "click",
+      x: coordinates.x,
+      y: coordinates.y,
+      button: normalizeMouseButton(input.button)
+    };
+  }
+  if (type === "type") {
+    const coordinates = resolveCoordinates(input, type);
+    return {
+      type: "type",
+      text: normalizeRequiredString(
+        input.text,
+        `Anthropic action "${type}" requires a non-empty text value.`
+      ),
+      x: coordinates.x,
+      y: coordinates.y
+    };
+  }
+  return {
+    type,
+    ...input
+  };
+}
+function extractTextMessage(content) {
+  const texts = content.filter((item) => item.type === "text" && typeof item.text === "string").map((item) => String(item.text));
+  return texts.join("\n").trim();
+}
+function requiresNewestAnthropicToolVersion(modelName) {
+  return modelName === "claude-opus-4-6" || modelName === "claude-sonnet-4-6" || modelName === "claude-opus-4-5-20251101";
+}
+function normalizeString2(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function normalizeRequiredString(value, errorMessage2) {
+  const normalized = normalizeString2(value);
+  if (!normalized) {
+    throw new OpensteerAgentActionError(errorMessage2);
+  }
+  return normalized;
+}
+function toNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function arrayNumber(value) {
+  if (!Array.isArray(value)) return [NaN, NaN];
+  return [
+    typeof value[0] === "number" ? value[0] : NaN,
+    typeof value[1] === "number" ? value[1] : NaN
+  ];
+}
+function resolveCoordinates(input, actionType) {
+  const [xFromCoordinate, yFromCoordinate] = arrayNumber(input.coordinate);
+  const xFromFallback = toFiniteNumber(input.x);
+  const yFromFallback = toFiniteNumber(input.y);
+  const x = Number.isFinite(xFromCoordinate) ? xFromCoordinate : xFromFallback;
+  const y = Number.isFinite(yFromCoordinate) ? yFromCoordinate : yFromFallback;
+  if (x == null || y == null) {
+    throw new OpensteerAgentActionError(
+      `Anthropic action "${actionType}" requires numeric x/y coordinates.`
+    );
+  }
+  return { x, y };
+}
+function resolveCoordinateArray(value, actionType, field) {
+  const [x, y] = arrayNumber(value);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    throw new OpensteerAgentActionError(
+      `Anthropic action "${actionType}" requires numeric "${field}" coordinates.`
+    );
+  }
+  return { x, y };
+}
+function resolvePositiveNumber(value, actionType, field) {
+  const number = toFiniteNumber(value);
+  if (number == null || number <= 0) {
+    throw new OpensteerAgentActionError(
+      `Anthropic action "${actionType}" requires a positive numeric "${field}" value.`
+    );
+  }
+  return number;
+}
+function normalizeScrollDirection(value, actionType) {
+  const direction = normalizeString2(value);
+  if (direction === "up" || direction === "down" || direction === "left" || direction === "right") {
+    return direction;
+  }
+  throw new OpensteerAgentActionError(
+    `Anthropic action "${actionType}" requires "scroll_direction" to be one of: up, down, left, right.`
+  );
+}
+function normalizeMouseButton(value) {
+  const button = normalizeRequiredString(
+    value,
+    'Anthropic action "click" requires a non-empty "button" value.'
+  ).toLowerCase();
+  if (button === "left" || button === "right" || button === "middle") {
+    return button;
+  }
+  throw new OpensteerAgentActionError(
+    `Anthropic action "click" has unsupported button "${button}".`
+  );
+}
+function toFiniteNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  return null;
+}
+function mapAnthropicApiError(error) {
+  const errorRecord = toRecord2(error);
+  const nestedError = toRecord2(errorRecord.error);
+  const status = typeof errorRecord.status === "number" ? errorRecord.status : void 0;
+  const message = normalizeString2(nestedError.message) || (error instanceof Error ? error.message : String(error));
+  return new OpensteerAgentApiError("anthropic", message, status, error);
+}
+function toRecord2(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+// src/agent/clients/google.ts
+var import_genai = require("@google/genai");
+
+// src/agent/coords.ts
+var DEFAULT_CUA_VIEWPORT = {
+  width: 1288,
+  height: 711
+};
+function normalizeGoogleCoordinates(x, y, viewport) {
+  const clampedX = Math.min(999, Math.max(0, x));
+  const clampedY = Math.min(999, Math.max(0, y));
+  return {
+    x: Math.floor(clampedX / 1e3 * viewport.width),
+    y: Math.floor(clampedY / 1e3 * viewport.height)
+  };
+}
+function maybeNormalizeCoordinates(provider, x, y, viewport) {
+  if (provider === "google") {
+    return normalizeGoogleCoordinates(x, y, viewport);
+  }
+  return { x, y };
+}
+
+// src/agent/key-mapping.ts
+var KEY_MAP = {
+  ENTER: "Enter",
+  RETURN: "Enter",
+  ESCAPE: "Escape",
+  ESC: "Escape",
+  BACKSPACE: "Backspace",
+  TAB: "Tab",
+  SPACE: " ",
+  DELETE: "Delete",
+  DEL: "Delete",
+  ARROWUP: "ArrowUp",
+  ARROWDOWN: "ArrowDown",
+  ARROWLEFT: "ArrowLeft",
+  ARROWRIGHT: "ArrowRight",
+  ARROW_UP: "ArrowUp",
+  ARROW_DOWN: "ArrowDown",
+  ARROW_LEFT: "ArrowLeft",
+  ARROW_RIGHT: "ArrowRight",
+  UP: "ArrowUp",
+  DOWN: "ArrowDown",
+  LEFT: "ArrowLeft",
+  RIGHT: "ArrowRight",
+  SHIFT: "Shift",
+  CONTROL: "Control",
+  CTRL: "Control",
+  ALT: "Alt",
+  OPTION: "Alt",
+  META: "Meta",
+  COMMAND: "Meta",
+  CMD: "Meta",
+  SUPER: "Meta",
+  WINDOWS: "Meta",
+  WIN: "Meta",
+  HOME: "Home",
+  END: "End",
+  PAGEUP: "PageUp",
+  PAGEDOWN: "PageDown",
+  PAGE_UP: "PageUp",
+  PAGE_DOWN: "PageDown",
+  PGUP: "PageUp",
+  PGDN: "PageDown",
+  CONTROLORMETA: process.platform === "darwin" ? "Meta" : "Control"
+};
+function mapKeyToPlaywright(key) {
+  const normalized = key.trim();
+  if (!normalized) return normalized;
+  const mapped = KEY_MAP[normalized.toUpperCase()];
+  return mapped || normalized;
+}
+
+// src/agent/clients/google.ts
+var GoogleCuaClient = class extends CuaClient {
+  modelConfig;
+  client;
+  history = [];
+  constructor(modelConfig) {
+    super();
+    this.modelConfig = modelConfig;
+    this.client = new import_genai.GoogleGenAI({
+      apiKey: modelConfig.apiKey,
+      ...modelConfig.baseUrl ? { httpOptions: { baseUrl: modelConfig.baseUrl } } : {}
+    });
+  }
+  async execute(input) {
+    this.history = [
+      {
+        role: "user",
+        parts: [
+          {
+            text: `System prompt: ${input.systemPrompt}`
+          }
+        ]
+      },
+      {
+        role: "user",
+        parts: [
+          {
+            text: input.instruction
+          }
+        ]
+      }
+    ];
+    const actions = [];
+    let finalMessage = "";
+    let completed = false;
+    let step = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalInferenceTimeMs = 0;
+    while (!completed && step < input.maxSteps) {
+      const startedAt = Date.now();
+      const response = await this.generateContent();
+      totalInferenceTimeMs += Date.now() - startedAt;
+      const usageMetadata = response.usageMetadata || {};
+      totalInputTokens += toFiniteNumberOrZero(usageMetadata.promptTokenCount);
+      totalOutputTokens += toFiniteNumberOrZero(
+        usageMetadata.candidatesTokenCount
+      );
+      const candidate = Array.isArray(response.candidates) ? response.candidates[0] : null;
+      const content = candidate && typeof candidate === "object" && candidate.content && typeof candidate.content === "object" ? candidate.content : null;
+      const parts = content && Array.isArray(content.parts) ? content.parts : [];
+      const finishReason = extractFinishReason(candidate);
+      if (content) {
+        this.history.push({
+          role: "model",
+          parts
+        });
+      }
+      const messageParts = [];
+      const functionCalls = [];
+      for (const part of parts) {
+        if (typeof part.text === "string") {
+          messageParts.push(part.text);
+        }
+        if (part.functionCall && typeof part.functionCall === "object") {
+          functionCalls.push(part.functionCall);
+        }
+      }
+      if (messageParts.length) {
+        finalMessage = messageParts.join("\n").trim();
+      }
+      if (!functionCalls.length) {
+        completed = isSuccessfulGoogleFinishReason(finishReason);
+        if (!completed && !finalMessage) {
+          finalMessage = `Google CUA stopped with finish reason: ${finishReason || "unknown"}.`;
+        }
+      } else {
+        const functionResponses = [];
+        for (const functionCall of functionCalls) {
+          const mappedActions = mapGoogleFunctionCallToActions(
+            functionCall,
+            this.viewport
+          );
+          actions.push(...mappedActions);
+          let executionError;
+          for (const mappedAction of mappedActions) {
+            try {
+              await this.getActionHandler()(mappedAction);
+            } catch (error) {
+              executionError = error instanceof Error ? error.message : String(error);
+            }
+          }
+          const screenshotBase64 = await this.getScreenshotProvider()();
+          const responsePayload = {
+            url: this.currentUrl || ""
+          };
+          const args = functionCall.args && typeof functionCall.args === "object" ? functionCall.args : null;
+          if (args && args.safety_decision !== void 0) {
+            responsePayload.safety_acknowledgement = "true";
+          }
+          if (executionError) {
+            responsePayload.error = executionError;
+          }
+          functionResponses.push({
+            functionResponse: {
+              name: typeof functionCall.name === "string" && functionCall.name || "computer_use",
+              response: responsePayload,
+              parts: [
+                {
+                  inlineData: {
+                    mimeType: "image/png",
+                    data: screenshotBase64
+                  }
+                }
+              ]
+            }
+          });
+        }
+        if (functionResponses.length) {
+          this.history.push({
+            role: "user",
+            parts: functionResponses
+          });
+        }
+        if (finishReason && finishReason !== "STOP") {
+          throw new OpensteerAgentActionError(
+            `Google CUA returned function calls with terminal finish reason "${finishReason}".`
+          );
+        }
+        completed = false;
+      }
+      step += 1;
+    }
+    return {
+      success: completed,
+      completed,
+      message: finalMessage,
+      actions,
+      usage: {
+        inputTokens: totalInputTokens,
+        outputTokens: totalOutputTokens,
+        inferenceTimeMs: totalInferenceTimeMs
+      }
+    };
+  }
+  async generateContent() {
+    const params = {
+      model: this.modelConfig.providerModelName,
+      contents: this.history,
+      config: {
+        temperature: 1,
+        topP: 0.95,
+        topK: 40,
+        maxOutputTokens: 8192,
+        tools: [
+          {
+            computerUse: {
+              environment: resolveGoogleEnvironment(
+                this.modelConfig.environment
+              )
+            }
+          }
+        ]
+      }
+    };
+    try {
+      return await this.client.models.generateContent(params);
+    } catch (error) {
+      throw mapGoogleApiError(error);
+    }
+  }
+};
+function mapGoogleFunctionCallToActions(functionCall, viewport) {
+  const name = normalizeString3(functionCall.name);
+  const args = functionCall.args && typeof functionCall.args === "object" ? functionCall.args : {};
+  if (!name) {
+    throw new OpensteerAgentActionError(
+      'Google CUA function call is missing a "name" value.'
+    );
+  }
+  switch (name) {
+    case "click_at": {
+      const coordinates = normalizeCoordinates(args, viewport, name);
+      return [
+        {
+          type: "click",
+          x: coordinates.x,
+          y: coordinates.y,
+          button: normalizeString3(args.button) || "left"
+        }
+      ];
+    }
+    case "type_text_at": {
+      const coordinates = normalizeCoordinates(args, viewport, name);
+      const clearBeforeTyping = typeof args.clear_before_typing === "boolean" ? args.clear_before_typing : true;
+      const pressEnter = typeof args.press_enter === "boolean" ? args.press_enter : false;
+      const text = normalizeRequiredString2(
+        args.text,
+        'Google action "type_text_at" requires a non-empty "text" value.'
+      );
+      const actions = [
+        {
+          type: "click",
+          x: coordinates.x,
+          y: coordinates.y,
+          button: "left"
+        }
+      ];
+      if (clearBeforeTyping) {
+        actions.push({
+          type: "keypress",
+          keys: ["ControlOrMeta+A"]
+        });
+        actions.push({
+          type: "keypress",
+          keys: ["Backspace"]
+        });
+      }
+      actions.push({
+        type: "type",
+        text,
+        x: coordinates.x,
+        y: coordinates.y
+      });
+      if (pressEnter) {
+        actions.push({
+          type: "keypress",
+          keys: ["Enter"]
+        });
+      }
+      return actions;
+    }
+    case "key_combination": {
+      const keysRaw = normalizeRequiredString2(
+        args.keys,
+        'Google action "key_combination" requires a non-empty "keys" value.'
+      );
+      const keys = keysRaw.split("+").map((part) => part.trim()).filter(Boolean).map((part) => mapKeyToPlaywright(part));
+      if (!keys.length) {
+        throw new OpensteerAgentActionError(
+          'Google action "key_combination" did not produce any key tokens.'
+        );
+      }
+      return [
+        {
+          type: "keypress",
+          keys
+        }
+      ];
+    }
+    case "scroll_document": {
+      const direction = normalizeVerticalDirection(
+        args.direction,
+        "scroll_document"
+      );
+      return [
+        {
+          type: "keypress",
+          keys: [direction === "up" ? "PageUp" : "PageDown"]
+        }
+      ];
+    }
+    case "scroll_at": {
+      const coordinates = normalizeCoordinates(args, viewport, name);
+      const direction = normalizeScrollDirection2(args.direction, "scroll_at");
+      const magnitude = parsePositiveNumber(
+        args.magnitude,
+        "scroll_at",
+        "magnitude"
+      );
+      let scrollX = 0;
+      let scrollY = 0;
+      if (direction === "up") scrollY = -magnitude;
+      if (direction === "down") scrollY = magnitude;
+      if (direction === "left") scrollX = -magnitude;
+      if (direction === "right") scrollX = magnitude;
+      return [
+        {
+          type: "scroll",
+          x: coordinates.x,
+          y: coordinates.y,
+          scrollX,
+          scrollY
+        }
+      ];
+    }
+    case "hover_at": {
+      const coordinates = normalizeCoordinates(args, viewport, name);
+      return [
+        {
+          type: "move",
+          x: coordinates.x,
+          y: coordinates.y
+        }
+      ];
+    }
+    case "drag_and_drop": {
+      const startX = parseRequiredNumber(args.x, "drag_and_drop", "x");
+      const startY = parseRequiredNumber(args.y, "drag_and_drop", "y");
+      const endX = parseRequiredNumber(
+        args.destination_x,
+        "drag_and_drop",
+        "destination_x"
+      );
+      const endY = parseRequiredNumber(
+        args.destination_y,
+        "drag_and_drop",
+        "destination_y"
+      );
+      const start = maybeNormalizeCoordinates(
+        "google",
+        startX,
+        startY,
+        viewport
+      );
+      const end = maybeNormalizeCoordinates(
+        "google",
+        endX,
+        endY,
+        viewport
+      );
+      return [
+        {
+          type: "drag",
+          path: [start, end]
+        }
+      ];
+    }
+    case "navigate":
+      return [
+        {
+          type: "goto",
+          url: normalizeRequiredString2(
+            args.url,
+            'Google action "navigate" requires a non-empty "url" value.'
+          )
+        }
+      ];
+    case "go_back":
+      return [{ type: "back" }];
+    case "go_forward":
+      return [{ type: "forward" }];
+    case "wait_5_seconds":
+      return [{ type: "wait", timeMs: 5e3 }];
+    case "search":
+      return [
+        {
+          type: "goto",
+          url: buildGoogleSearchUrl(args)
+        }
+      ];
+    case "open_web_browser":
+      return [{ type: "open_web_browser" }];
+    default:
+      throw new OpensteerAgentActionError(
+        `Unsupported Google CUA function call "${name}".`
+      );
+  }
+}
+function normalizeCoordinates(args, viewport, actionName) {
+  const x = parseRequiredNumber(args.x, actionName, "x");
+  const y = parseRequiredNumber(args.y, actionName, "y");
+  return maybeNormalizeCoordinates(
+    "google",
+    x,
+    y,
+    viewport
+  );
+}
+function parseRequiredNumber(value, actionName, field) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  throw new OpensteerAgentActionError(
+    `Google action "${actionName}" requires numeric "${field}" coordinates.`
+  );
+}
+function parsePositiveNumber(value, actionName, field) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return value;
+  }
+  throw new OpensteerAgentActionError(
+    `Google action "${actionName}" requires a positive numeric "${field}" value.`
+  );
+}
+function toFiniteNumberOrZero(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function normalizeString3(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function normalizeRequiredString2(value, errorMessage2) {
+  const normalized = normalizeString3(value);
+  if (!normalized) {
+    throw new OpensteerAgentActionError(errorMessage2);
+  }
+  return normalized;
+}
+function normalizeScrollDirection2(value, actionName) {
+  const direction = normalizeString3(value);
+  if (direction === "up" || direction === "down" || direction === "left" || direction === "right") {
+    return direction;
+  }
+  throw new OpensteerAgentActionError(
+    `Google action "${actionName}" requires "direction" to be one of: up, down, left, right.`
+  );
+}
+function normalizeVerticalDirection(value, actionName) {
+  const direction = normalizeString3(value);
+  if (direction === "up" || direction === "down") {
+    return direction;
+  }
+  throw new OpensteerAgentActionError(
+    `Google action "${actionName}" requires "direction" to be "up" or "down".`
+  );
+}
+function buildGoogleSearchUrl(args) {
+  const query = normalizeRequiredString2(
+    args.query ?? args.text,
+    'Google action "search" requires a non-empty "query" value.'
+  );
+  return `https://www.google.com/search?q=${encodeURIComponent(query)}`;
+}
+function extractFinishReason(candidate) {
+  if (!candidate || typeof candidate !== "object") {
+    return void 0;
+  }
+  return normalizeString3(candidate.finishReason);
+}
+function isSuccessfulGoogleFinishReason(finishReason) {
+  return !finishReason || finishReason === "STOP";
+}
+function resolveGoogleEnvironment(value) {
+  const environment = normalizeString3(value);
+  if (environment === import_genai.Environment.ENVIRONMENT_UNSPECIFIED) {
+    return import_genai.Environment.ENVIRONMENT_UNSPECIFIED;
+  }
+  return import_genai.Environment.ENVIRONMENT_BROWSER;
+}
+function mapGoogleApiError(error) {
+  const errorRecord = toRecord3(error);
+  const status = typeof errorRecord.status === "number" ? errorRecord.status : void 0;
+  const message = normalizeString3(errorRecord.message) || (error instanceof Error ? error.message : String(error));
+  return new OpensteerAgentApiError("google", message, status, error);
+}
+function toRecord3(value) {
+  return value && typeof value === "object" ? value : {};
+}
+
+// src/agent/provider.ts
+var DEFAULT_SYSTEM_PROMPT = "You are a browser automation agent. Complete the user instruction safely and efficiently. Do not ask follow-up questions. Finish as soon as the task is complete.";
+function resolveAgentConfig(args) {
+  const { agentConfig } = args;
+  if (!agentConfig || typeof agentConfig !== "object") {
+    throw new OpensteerAgentConfigError(
+      'agent() requires a configuration object with mode: "cua".'
+    );
+  }
+  if (agentConfig.mode !== "cua") {
+    throw new OpensteerAgentConfigError(
+      `Unsupported agent mode "${String(agentConfig.mode)}". OpenSteer currently supports only mode: "cua".`
+    );
+  }
+  const model = resolveCuaModelConfig({
+    agentConfig,
+    fallbackModel: args.fallbackModel,
+    env: args.env
+  });
+  return {
+    mode: "cua",
+    systemPrompt: normalizeNonEmptyString(agentConfig.systemPrompt) || DEFAULT_SYSTEM_PROMPT,
+    waitBetweenActionsMs: normalizeWaitBetween(agentConfig.waitBetweenActionsMs),
+    model
+  };
+}
+function createCuaClient(config) {
+  switch (config.model.provider) {
+    case "openai":
+      return new OpenAICuaClient(config.model);
+    case "anthropic":
+      return new AnthropicCuaClient(config.model);
+    case "google":
+      return new GoogleCuaClient(config.model);
+    default:
+      throw new OpensteerAgentProviderError(
+        `Unsupported CUA provider "${String(config.model.provider)}".`
+      );
+  }
+}
+function normalizeNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function normalizeWaitBetween(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return 500;
+  }
+  return Math.floor(value);
+}
+
+// src/agent/action-executor.ts
+async function executeAgentAction(page, action) {
+  const type = normalizeActionType(action.type);
+  switch (type) {
+    case "click": {
+      const { x, y } = toPoint(action);
+      await page.mouse.click(x, y, {
+        button: normalizeMouseButton2(action.button, "left"),
+        clickCount: normalizeClickCount(action.clickCount, 1)
+      });
+      return;
+    }
+    case "doubleclick": {
+      const { x, y } = toPoint(action);
+      await page.mouse.click(x, y, {
+        button: normalizeMouseButton2(action.button, "left"),
+        clickCount: 2
+      });
+      return;
+    }
+    case "tripleclick": {
+      const { x, y } = toPoint(action);
+      await page.mouse.click(x, y, {
+        button: normalizeMouseButton2(action.button, "left"),
+        clickCount: 3
+      });
+      return;
+    }
+    case "rightclick": {
+      const { x, y } = toPoint(action);
+      await page.mouse.click(x, y, {
+        button: "right",
+        clickCount: normalizeClickCount(action.clickCount, 1)
+      });
+      return;
+    }
+    case "type": {
+      await maybeFocusPoint(page, action);
+      const text = typeof action.text === "string" ? action.text : "";
+      if (action.clearBeforeTyping === true) {
+        await pressKeyCombo(page, "ControlOrMeta+A");
+        await page.keyboard.press("Backspace");
+      }
+      await page.keyboard.type(text);
+      if (action.pressEnter === true) {
+        await page.keyboard.press("Enter");
+      }
+      return;
+    }
+    case "keypress": {
+      const combos = normalizeKeyCombos(action.keys);
+      for (const combo of combos) {
+        await pressKeyCombo(page, combo);
+      }
+      return;
+    }
+    case "scroll": {
+      const x = numberOr(action.scrollX, action.scroll_x, 0);
+      const y = numberOr(action.scrollY, action.scroll_y, 0);
+      const point = maybePoint(action);
+      if (point) {
+        await page.mouse.move(point.x, point.y);
+      }
+      await page.mouse.wheel(x, y);
+      return;
+    }
+    case "drag": {
+      const path5 = normalizePath(action.path);
+      if (!path5.length) {
+        throw new OpensteerAgentActionError(
+          "Drag action requires a non-empty path."
+        );
+      }
+      await page.mouse.move(path5[0].x, path5[0].y);
+      await page.mouse.down();
+      for (const point of path5.slice(1)) {
+        await page.mouse.move(point.x, point.y);
+      }
+      await page.mouse.up();
+      return;
+    }
+    case "move":
+    case "hover": {
+      const { x, y } = toPoint(action);
+      await page.mouse.move(x, y);
+      return;
+    }
+    case "wait": {
+      const ms = numberOr(action.timeMs, action.time_ms, 1e3);
+      await sleep3(ms);
+      return;
+    }
+    case "goto": {
+      const url = normalizeRequiredString3(action.url, "Action URL is required for goto.");
+      await page.goto(url, { waitUntil: "load" });
+      return;
+    }
+    case "back": {
+      await page.goBack({ waitUntil: "load" }).catch(() => void 0);
+      return;
+    }
+    case "forward": {
+      await page.goForward({ waitUntil: "load" }).catch(() => void 0);
+      return;
+    }
+    case "screenshot":
+    case "open_web_browser": {
+      return;
+    }
+    default:
+      throw new OpensteerAgentActionError(
+        `Unsupported CUA action type "${String(action.type)}".`
+      );
+  }
+}
+function isMutatingAgentAction(action) {
+  const type = normalizeActionType(action.type);
+  return type !== "wait" && type !== "screenshot" && type !== "open_web_browser";
+}
+function normalizeActionType(value) {
+  const raw = typeof value === "string" ? value : "";
+  const normalized = raw.trim().toLowerCase();
+  if (!normalized) return "";
+  if (normalized === "double_click" || normalized === "doubleclick") {
+    return "doubleclick";
+  }
+  if (normalized === "triple_click" || normalized === "tripleclick") {
+    return "tripleclick";
+  }
+  if (normalized === "left_click") {
+    return "click";
+  }
+  if (normalized === "right_click") {
+    return "rightclick";
+  }
+  if (normalized === "openwebbrowser" || normalized === "open_web_browser") {
+    return "open_web_browser";
+  }
+  return normalized;
+}
+function toPoint(action) {
+  const point = maybePoint(action);
+  if (point) {
+    return point;
+  }
+  throw new OpensteerAgentActionError(
+    `Action "${String(action.type)}" requires numeric x and y coordinates.`
+  );
+}
+function maybePoint(action) {
+  const coordinate = Array.isArray(action.coordinate) ? action.coordinate : Array.isArray(action.coordinates) ? action.coordinates : null;
+  const x = numberOr(action.x, coordinate?.[0]);
+  const y = numberOr(action.y, coordinate?.[1]);
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    return null;
+  }
+  return {
+    x,
+    y
+  };
+}
+async function maybeFocusPoint(page, action) {
+  const point = maybePoint(action);
+  if (!point) {
+    return;
+  }
+  await page.mouse.click(point.x, point.y, {
+    button: normalizeMouseButton2(action.button, "left"),
+    clickCount: 1
+  });
+}
+function normalizePath(path5) {
+  if (!Array.isArray(path5)) return [];
+  const points = [];
+  for (const entry of path5) {
+    if (!entry || typeof entry !== "object") continue;
+    const candidate = entry;
+    const x = Number(candidate.x);
+    const y = Number(candidate.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) continue;
+    points.push({ x, y });
+  }
+  return points;
+}
+function normalizeMouseButton2(value, fallback) {
+  if (value === "left" || value === "right" || value === "middle") {
+    return value;
+  }
+  if (typeof value === "string") {
+    const normalized = value.toLowerCase();
+    if (normalized === "left" || normalized === "right" || normalized === "middle") {
+      return normalized;
+    }
+  }
+  return fallback;
+}
+function normalizeClickCount(value, fallback) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.floor(value);
+  }
+  return fallback;
+}
+function normalizeKeyCombos(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? [trimmed] : [];
+  }
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const keys = value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean);
+  if (!keys.length) {
+    return [];
+  }
+  const hasExplicitComboSyntax = keys.some((entry) => entry.includes("+"));
+  if (!hasExplicitComboSyntax && keys.length > 1) {
+    return [keys.join("+")];
+  }
+  return keys;
+}
+function numberOr(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return NaN;
+}
+function normalizeRequiredString3(value, errorMessage2) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new OpensteerAgentActionError(errorMessage2);
+  }
+  return value.trim();
+}
+async function pressKeyCombo(page, combo) {
+  const trimmed = combo.trim();
+  if (!trimmed) return;
+  if (!trimmed.includes("+")) {
+    await page.keyboard.press(mapKeyToPlaywright(trimmed));
+    return;
+  }
+  const parts = trimmed.split("+").map((part) => part.trim()).filter(Boolean).map((part) => mapKeyToPlaywright(part));
+  if (!parts.length) return;
+  const modifiers = parts.slice(0, -1);
+  const last = parts[parts.length - 1];
+  for (const modifier of modifiers) {
+    await page.keyboard.down(modifier);
+  }
+  try {
+    await page.keyboard.press(last);
+  } finally {
+    for (const modifier of modifiers.slice().reverse()) {
+      await page.keyboard.up(modifier);
+    }
+  }
+}
+function sleep3(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+// src/agent/handler.ts
+var OpensteerCuaAgentHandler = class {
+  page;
+  config;
+  client;
+  debug;
+  onMutatingAction;
+  cursorOverlayInjected = false;
+  constructor(options) {
+    this.page = options.page;
+    this.config = options.config;
+    this.client = options.client;
+    this.debug = options.debug;
+    this.onMutatingAction = options.onMutatingAction;
+  }
+  async execute(options) {
+    const instruction = options.instruction;
+    const maxSteps = options.maxSteps ?? 20;
+    await this.initializeClient();
+    const highlightCursor = options.highlightCursor === true;
+    this.client.setActionHandler(async (action) => {
+      if (highlightCursor) {
+        await this.maybeRenderCursor(action);
+      }
+      await executeAgentAction(this.page, action);
+      this.client.setCurrentUrl(this.page.url());
+      if (isMutatingAgentAction(action)) {
+        this.onMutatingAction?.(action);
+      }
+      await sleep4(this.config.waitBetweenActionsMs);
+    });
+    try {
+      const result = await this.client.execute({
+        instruction,
+        maxSteps,
+        systemPrompt: this.config.systemPrompt
+      });
+      return {
+        ...result,
+        provider: this.config.model.provider,
+        model: this.config.model.fullModelName
+      };
+    } catch (error) {
+      throw new OpensteerAgentExecutionError(
+        `CUA agent execution failed: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    }
+  }
+  async initializeClient() {
+    const viewport = await this.resolveViewport();
+    this.client.setViewport(viewport.width, viewport.height);
+    this.client.setCurrentUrl(this.page.url());
+    this.client.setScreenshotProvider(async () => {
+      const buffer = await this.page.screenshot({
+        fullPage: false,
+        type: "png"
+      });
+      return buffer.toString("base64");
+    });
+  }
+  async resolveViewport() {
+    const directViewport = this.page.viewportSize();
+    if (directViewport?.width && directViewport?.height) {
+      return directViewport;
+    }
+    try {
+      const evaluated = await this.page.evaluate(() => ({
+        width: window.innerWidth,
+        height: window.innerHeight
+      }));
+      if (evaluated && typeof evaluated === "object" && typeof evaluated.width === "number" && typeof evaluated.height === "number" && evaluated.width > 0 && evaluated.height > 0) {
+        return {
+          width: Math.floor(evaluated.width),
+          height: Math.floor(evaluated.height)
+        };
+      }
+    } catch {
+    }
+    return DEFAULT_CUA_VIEWPORT;
+  }
+  async maybeRenderCursor(action) {
+    const x = typeof action.x === "number" ? action.x : null;
+    const y = typeof action.y === "number" ? action.y : null;
+    if (x == null || y == null) {
+      return;
+    }
+    try {
+      if (!this.cursorOverlayInjected) {
+        await this.page.evaluate(() => {
+          if (document.getElementById("__opensteer_cua_cursor")) return;
+          const cursor = document.createElement("div");
+          cursor.id = "__opensteer_cua_cursor";
+          cursor.style.position = "fixed";
+          cursor.style.width = "14px";
+          cursor.style.height = "14px";
+          cursor.style.borderRadius = "999px";
+          cursor.style.background = "rgba(255, 51, 51, 0.85)";
+          cursor.style.border = "2px solid rgba(255, 255, 255, 0.95)";
+          cursor.style.boxShadow = "0 0 0 3px rgba(255, 51, 51, 0.25)";
+          cursor.style.pointerEvents = "none";
+          cursor.style.zIndex = "2147483647";
+          cursor.style.transform = "translate(-9999px, -9999px)";
+          cursor.style.transition = "transform 80ms linear";
+          document.documentElement.appendChild(cursor);
+        });
+        this.cursorOverlayInjected = true;
+      }
+      await this.page.evaluate(
+        ({ px, py }) => {
+          const cursor = document.getElementById("__opensteer_cua_cursor");
+          if (!cursor) return;
+          cursor.style.transform = `translate(${Math.round(px - 7)}px, ${Math.round(py - 7)}px)`;
+        },
+        { px: x, py: y }
+      );
+    } catch (error) {
+      if (this.debug) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[opensteer] cursor overlay failed: ${message}`);
+      }
+    }
+  }
+};
+function sleep4(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+// src/opensteer.ts
+var CLOUD_INTERACTION_METHODS = /* @__PURE__ */ new Set([
+  "click",
+  "dblclick",
+  "rightclick",
+  "hover",
+  "input",
+  "select",
+  "scroll",
+  "uploadFile"
+]);
+var Opensteer = class _Opensteer {
+  config;
+  aiResolve;
+  aiExtract;
+  namespace;
+  storage;
+  pool;
+  cloud;
+  browser = null;
+  pageRef = null;
+  contextRef = null;
+  ownsBrowser = false;
+  snapshotCache = null;
+  agentExecutionInFlight = false;
+  constructor(config = {}) {
+    const resolved = resolveConfig(config);
+    const cloudSelection = resolveCloudSelection({
+      cloud: resolved.cloud
+    });
+    const model = resolved.model;
+    this.config = resolved;
+    this.aiResolve = this.createLazyResolveCallback(model);
+    this.aiExtract = this.createLazyExtractCallback(model);
+    const rootDir = resolved.storage?.rootDir || process.cwd();
+    this.namespace = resolveNamespace(resolved, rootDir);
+    this.storage = new LocalSelectorStorage(rootDir, this.namespace);
+    this.pool = new BrowserPool(resolved.browser || {});
+    if (cloudSelection.cloud) {
+      const cloudConfig = resolved.cloud && typeof resolved.cloud === "object" ? resolved.cloud : void 0;
+      const apiKey = cloudConfig?.apiKey?.trim();
+      if (!apiKey) {
+        throw new Error(
+          "Cloud mode requires a non-empty API key via cloud.apiKey or OPENSTEER_API_KEY."
+        );
+      }
+      this.cloud = createCloudRuntimeState(
+        apiKey,
+        cloudConfig?.baseUrl,
+        cloudConfig?.authScheme
+      );
+    } else {
+      this.cloud = null;
+    }
+  }
+  createLazyResolveCallback(model) {
+    let resolverPromise = null;
+    return async (...args) => {
+      try {
+        if (!resolverPromise) {
+          resolverPromise = Promise.resolve().then(() => (init_resolver(), resolver_exports)).then(
+            (m) => m.createResolveCallback(model)
+          );
+        }
+        const resolver = await resolverPromise;
+        return resolver(...args);
+      } catch (err) {
+        resolverPromise = null;
+        throw err;
+      }
+    };
+  }
+  createLazyExtractCallback(model) {
+    let extractorPromise = null;
+    const extract = async (args) => {
+      try {
+        if (!extractorPromise) {
+          extractorPromise = Promise.resolve().then(() => (init_extractor(), extractor_exports)).then(
+            (m) => m.createExtractCallback(model)
+          );
+        }
+        const extractor = await extractorPromise;
+        return extractor(args);
+      } catch (err) {
+        extractorPromise = null;
+        throw err;
+      }
+    };
+    return extract;
+  }
+  async invokeCloudActionAndResetCache(method, args) {
+    const result = await this.invokeCloudAction(method, args);
+    this.snapshotCache = null;
+    return result;
+  }
+  async invokeCloudAction(method, args) {
+    const actionClient = this.cloud?.actionClient;
+    const sessionId = this.cloud?.sessionId;
+    if (!actionClient || !sessionId) {
+      throw cloudNotLaunchedError();
+    }
+    const payload = args && typeof args === "object" ? args : {};
+    try {
+      return await actionClient.request(method, payload);
+    } catch (err) {
+      if (err instanceof OpensteerCloudError && err.code === "CLOUD_ACTION_FAILED" && CLOUD_INTERACTION_METHODS.has(method)) {
+        const detailsRecord = err.details && typeof err.details === "object" ? err.details : null;
+        const cloudFailure = normalizeActionFailure(
+          detailsRecord?.actionFailure
+        );
+        const failure = cloudFailure || classifyActionFailure({
+          action: method,
+          error: err,
+          fallbackMessage: defaultActionFailureMessage(method)
+        });
+        const description = readCloudActionDescription(payload);
+        throw this.buildActionError(
+          method,
+          description,
+          failure,
+          null,
+          err
+        );
+      }
+      throw err;
+    }
+  }
+  buildActionError(action, description, failure, selectorUsed, cause) {
+    return new OpensteerActionError({
+      action,
+      failure,
+      selectorUsed: selectorUsed || null,
+      message: formatActionFailureMessage(
+        action,
+        description,
+        failure.message
+      ),
+      cause
+    });
+  }
+  async syncCloudPageRef(args) {
+    if (!this.cloud || !this.browser) return;
+    let tabs;
+    try {
+      tabs = await this.invokeCloudAction("tabs", {});
+    } catch {
+      return;
+    }
+    if (!tabs.length) {
+      return;
+    }
+    const contexts = this.browser.contexts();
+    if (!contexts.length) return;
+    const syncContext = this.contextRef && contexts.includes(this.contextRef) ? this.contextRef : contexts[0];
+    const syncContextPages = syncContext.pages();
+    const activeTab = tabs.find((tab) => tab.active) ?? null;
+    if (activeTab && activeTab.index >= 0 && activeTab.index < syncContextPages.length) {
+      this.contextRef = syncContext;
+      this.pageRef = syncContextPages[activeTab.index];
+      return;
+    }
+    const expectedUrl = args?.expectedUrl?.trim() || null;
+    const expectedUrlInSyncContext = expectedUrl ? syncContextPages.find((page) => page.url() === expectedUrl) : void 0;
+    if (expectedUrlInSyncContext) {
+      this.contextRef = syncContext;
+      this.pageRef = expectedUrlInSyncContext;
+      return;
+    }
+    const firstNonInternalInSyncContext = syncContextPages.find(
+      (page) => !isInternalOrBlankPageUrl(page.url())
+    );
+    if (firstNonInternalInSyncContext) {
+      this.contextRef = syncContext;
+      this.pageRef = firstNonInternalInSyncContext;
+      return;
+    }
+    const firstAboutBlankInSyncContext = syncContextPages.find(
+      (page) => page.url() === "about:blank"
+    );
+    if (firstAboutBlankInSyncContext) {
+      this.contextRef = syncContext;
+      this.pageRef = firstAboutBlankInSyncContext;
+      return;
+    }
+    const pages = [];
+    for (const context of contexts) {
+      for (const page of context.pages()) {
+        pages.push({
+          context,
+          page,
+          url: page.url()
+        });
+      }
+    }
+    if (!pages.length) return;
+    const expectedUrlMatch = expectedUrl ? pages.find(({ url }) => url === expectedUrl) : void 0;
+    if (expectedUrlMatch) {
+      this.contextRef = expectedUrlMatch.context;
+      this.pageRef = expectedUrlMatch.page;
+      return;
+    }
+    const firstNonInternal = pages.find(
+      ({ url }) => !isInternalOrBlankPageUrl(url)
+    );
+    if (firstNonInternal) {
+      this.contextRef = firstNonInternal.context;
+      this.pageRef = firstNonInternal.page;
+      return;
+    }
+    const firstAboutBlank = pages.find(({ url }) => url === "about:blank");
+    if (firstAboutBlank) {
+      this.contextRef = firstAboutBlank.context;
+      this.pageRef = firstAboutBlank.page;
+      return;
+    }
+    this.contextRef = pages[0].context;
+    this.pageRef = pages[0].page;
+  }
+  get page() {
+    if (!this.pageRef) {
+      throw new Error(
+        "Browser page is not initialized. Call launch() or Opensteer.from(page)."
+      );
+    }
+    return this.pageRef;
+  }
+  get context() {
+    if (!this.contextRef) {
+      throw new Error(
+        "Browser context is not initialized. Call launch() or Opensteer.from(page)."
+      );
+    }
+    return this.contextRef;
+  }
+  getCloudSessionId() {
+    return this.cloud?.sessionId ?? null;
+  }
+  getCloudSessionUrl() {
+    return this.cloud?.cloudSessionUrl ?? null;
+  }
+  announceCloudSession(args) {
+    if (!this.shouldAnnounceCloudSession()) {
+      return;
+    }
+    const fields = [
+      `sessionId=${args.sessionId}`,
+      `workspaceId=${args.workspaceId}`
+    ];
+    if (args.cloudSessionUrl) {
+      fields.push(`url=${args.cloudSessionUrl}`);
+    }
+    process.stderr.write(`[opensteer] cloud session ready ${fields.join(" ")}
+`);
+  }
+  shouldAnnounceCloudSession() {
+    const cloudConfig = this.config.cloud && typeof this.config.cloud === "object" ? this.config.cloud : null;
+    const announce = cloudConfig?.announce ?? "always";
+    if (announce === "off") {
+      return false;
+    }
     if (announce === "tty") {
       return Boolean(process.stderr.isTTY);
     }
@@ -8343,6 +10207,7 @@ var Opensteer = class _Opensteer {
         this.cloud.actionClient = actionClient;
         this.cloud.sessionId = sessionId;
         this.cloud.cloudSessionUrl = session3.cloudSessionUrl;
+        await this.syncCloudPageRef().catch(() => void 0);
         this.announceCloudSession({
           sessionId: session3.sessionId,
           workspaceId: session3.cloudSession.workspaceId,
@@ -8438,6 +10303,9 @@ var Opensteer = class _Opensteer {
   async goto(url, options) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("goto", { url, options });
+      await this.syncCloudPageRef({ expectedUrl: url }).catch(
+        () => void 0
+      );
       return;
     }
     const { waitUntil = "domcontentloaded", ...rest } = options ?? {};
@@ -8942,9 +10810,16 @@ var Opensteer = class _Opensteer {
   }
   async newTab(url) {
     if (this.cloud) {
-      return await this.invokeCloudActionAndResetCache("newTab", {
-        url
-      });
+      const result = await this.invokeCloudActionAndResetCache(
+        "newTab",
+        {
+          url
+        }
+      );
+      await this.syncCloudPageRef({ expectedUrl: result.url }).catch(
+        () => void 0
+      );
+      return result;
     }
     const { page, info } = await createTab(this.context, url);
     this.pageRef = page;
@@ -8954,6 +10829,7 @@ var Opensteer = class _Opensteer {
   async switchTab(index) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("switchTab", { index });
+      await this.syncCloudPageRef().catch(() => void 0);
       return;
     }
     const page = await switchTab(this.context, index);
@@ -8963,6 +10839,7 @@ var Opensteer = class _Opensteer {
   async closeTab(index) {
     if (this.cloud) {
       await this.invokeCloudActionAndResetCache("closeTab", { index });
+      await this.syncCloudPageRef().catch(() => void 0);
       return;
     }
     const newPage = await closeTab(this.context, this.page, index);
@@ -9373,6 +11250,37 @@ var Opensteer = class _Opensteer {
     this.storage.clearNamespace();
     this.snapshotCache = null;
   }
+  agent(config) {
+    const resolvedAgentConfig = resolveAgentConfig({
+      agentConfig: config,
+      fallbackModel: this.config.model
+    });
+    return {
+      execute: async (instructionOrOptions) => {
+        if (this.agentExecutionInFlight) {
+          throw new OpensteerAgentBusyError();
+        }
+        this.agentExecutionInFlight = true;
+        try {
+          const options = normalizeExecuteOptions(instructionOrOptions);
+          const handler = new OpensteerCuaAgentHandler({
+            page: this.page,
+            config: resolvedAgentConfig,
+            client: createCuaClient(resolvedAgentConfig),
+            debug: Boolean(this.config.debug),
+            onMutatingAction: () => {
+              this.snapshotCache = null;
+            }
+          });
+          const result = await handler.execute(options);
+          this.snapshotCache = null;
+          return result;
+        } finally {
+          this.agentExecutionInFlight = false;
+        }
+      }
+    };
+  }
   async runWithPostActionWait(action, waitOverride, execute) {
     const waitSession = createPostActionWaitSession(
       this.page,
@@ -10395,6 +12303,11 @@ function getScrollDelta2(options) {
       return { x: 0, y: absoluteAmount };
   }
 }
+function isInternalOrBlankPageUrl(url) {
+  if (!url) return true;
+  if (url === "about:blank") return true;
+  return url.startsWith("chrome://") || url.startsWith("devtools://") || url.startsWith("edge://");
+}
 function buildLocalRunId(namespace) {
   const normalized = namespace.trim() || "default";
   return `${normalized}-${Date.now().toString(36)}-${(0, import_crypto2.randomUUID)().slice(0, 8)}`;