opendevbrowser 0.0.12 → 0.0.16

package/dist/opendevbrowser.js

@@ -1,11 +1,351 @@
 import {
+  DaemonClient,
+  ScriptRunner,
+  buildAnnotateResult,
+  buildBlockerArtifacts,
+  classifyBlockerSignal,
+  createBrowserFallbackPort,
+  createConfiguredProviderRuntime,
   createOpenDevBrowserCore,
-  extractExtension
-} from "./chunk-WTFSMBVH.js";
+  createRequestId,
+  executeMacroResolution,
+  extractExtension,
+  fetchDaemonStatusFromMetadata,
+  runProductVideoWorkflow,
+  runResearchWorkflow,
+  runShoppingWorkflow,
+  shapeExecutionPayload,
+  startDaemon
+} from "./chunk-ST7CO5FA.js";
+import "./chunk-7W3SPXIB.js";
+
+// src/cli/remote-manager.ts
+function isLegacyRelayEndpoint(wsEndpoint) {
+  try {
+    const url = new URL(wsEndpoint);
+    const path = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+    return path === "/cdp";
+  } catch {
+    return false;
+  }
+}
+var RemoteManager = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  launch(options) {
+    return this.client.call("session.launch", options);
+  }
+  connect(options) {
+    return this.client.call("session.connect", options);
+  }
+  connectRelay(wsEndpoint) {
+    return this.client.call(
+      "session.connect",
+      isLegacyRelayEndpoint(wsEndpoint) ? { wsEndpoint, extensionLegacy: true } : { wsEndpoint }
+    );
+  }
+  disconnect(sessionId, closeBrowser = false) {
+    return this.client.call("session.disconnect", { sessionId, closeBrowser });
+  }
+  status(sessionId) {
+    return this.client.call("session.status", { sessionId });
+  }
+  cookieImport(sessionId, cookies, strict = true, requestId) {
+    return this.client.call("session.cookieImport", {
+      sessionId,
+      cookies,
+      strict,
+      requestId
+    });
+  }
+  cookieList(sessionId, urls, requestId) {
+    return this.client.call("session.cookieList", {
+      sessionId,
+      ...urls && urls.length > 0 ? { urls } : {},
+      requestId
+    });
+  }
+  goto(sessionId, url, waitUntil = "load", timeoutMs = 3e4, _sessionOverride, targetId) {
+    return this.client.call("nav.goto", {
+      sessionId,
+      url,
+      waitUntil,
+      timeoutMs,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  waitForLoad(sessionId, until, timeoutMs = 3e4, targetId) {
+    return this.client.call("nav.wait", {
+      sessionId,
+      until,
+      timeoutMs,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  waitForRef(sessionId, ref, state = "attached", timeoutMs = 3e4, targetId) {
+    return this.client.call("nav.wait", {
+      sessionId,
+      ref,
+      state,
+      timeoutMs,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  snapshot(sessionId, mode, maxChars, cursor, targetId) {
+    return this.client.call("nav.snapshot", {
+      sessionId,
+      mode,
+      maxChars,
+      cursor,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  click(sessionId, ref, targetId) {
+    return this.client.call("interact.click", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  hover(sessionId, ref, targetId) {
+    return this.client.call("interact.hover", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  press(sessionId, key, ref, targetId) {
+    return this.client.call("interact.press", {
+      sessionId,
+      key,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  check(sessionId, ref, targetId) {
+    return this.client.call("interact.check", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  uncheck(sessionId, ref, targetId) {
+    return this.client.call("interact.uncheck", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  type(sessionId, ref, text, clear = false, submit = false, targetId) {
+    return this.client.call("interact.type", {
+      sessionId,
+      ref,
+      text,
+      clear,
+      submit,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  select(sessionId, ref, values, targetId) {
+    return this.client.call("interact.select", {
+      sessionId,
+      ref,
+      values,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  scroll(sessionId, dy, ref, targetId) {
+    return this.client.call("interact.scroll", {
+      sessionId,
+      dy,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  scrollIntoView(sessionId, ref, targetId) {
+    return this.client.call("interact.scrollIntoView", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domGetHtml(sessionId, ref, maxChars = 8e3, targetId) {
+    return this.client.call("dom.getHtml", {
+      sessionId,
+      ref,
+      maxChars,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domGetText(sessionId, ref, maxChars = 8e3, targetId) {
+    return this.client.call("dom.getText", {
+      sessionId,
+      ref,
+      maxChars,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domGetAttr(sessionId, ref, name, targetId) {
+    return this.client.call("dom.getAttr", {
+      sessionId,
+      ref,
+      name,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domGetValue(sessionId, ref, targetId) {
+    return this.client.call("dom.getValue", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domIsVisible(sessionId, ref, targetId) {
+    return this.client.call("dom.isVisible", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domIsEnabled(sessionId, ref, targetId) {
+    return this.client.call("dom.isEnabled", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  domIsChecked(sessionId, ref, targetId) {
+    return this.client.call("dom.isChecked", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  clonePage(sessionId, targetId) {
+    return this.client.call("export.clonePage", {
+      sessionId,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  cloneComponent(sessionId, ref, targetId) {
+    return this.client.call("export.cloneComponent", {
+      sessionId,
+      ref,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  perfMetrics(sessionId, targetId) {
+    return this.client.call("devtools.perf", {
+      sessionId,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  screenshot(sessionId, path, targetId) {
+    return this.client.call("page.screenshot", {
+      sessionId,
+      path,
+      ...typeof targetId === "string" ? { targetId } : {}
+    });
+  }
+  consolePoll(sessionId, sinceSeq, max = 50) {
+    return this.client.call("devtools.consolePoll", { sessionId, sinceSeq, max });
+  }
+  networkPoll(sessionId, sinceSeq, max = 50) {
+    return this.client.call("devtools.networkPoll", { sessionId, sinceSeq, max });
+  }
+  listTargets(sessionId, includeUrls = false) {
+    return this.client.call("targets.list", { sessionId, includeUrls });
+  }
+  useTarget(sessionId, targetId) {
+    return this.client.call("targets.use", { sessionId, targetId });
+  }
+  newTarget(sessionId, url) {
+    return this.client.call("targets.new", { sessionId, url });
+  }
+  closeTarget(sessionId, targetId) {
+    return this.client.call("targets.close", { sessionId, targetId });
+  }
+  page(sessionId, name, url) {
+    return this.client.call("page.open", { sessionId, name, url });
+  }
+  listPages(sessionId) {
+    return this.client.call("page.list", { sessionId });
+  }
+  closePage(sessionId, name) {
+    return this.client.call("page.close", { sessionId, name });
+  }
+  async withPage(_sessionId, _targetId, _fn) {
+    throw new Error("Direct annotate is unavailable via daemon-managed sessions.");
+  }
+};
+
+// src/cli/remote-relay.ts
+var emptyStatus = {
+  running: false,
+  extensionConnected: false,
+  extensionHandshakeComplete: false,
+  cdpConnected: false,
+  annotationConnected: false,
+  opsConnected: false,
+  pairingRequired: false,
+  instanceId: "",
+  epoch: 0,
+  health: {
+    ok: false,
+    reason: "relay_down",
+    extensionConnected: false,
+    extensionHandshakeComplete: false,
+    cdpConnected: false,
+    annotationConnected: false,
+    opsConnected: false,
+    pairingRequired: false
+  }
+};
+var RemoteRelay = class {
+  client;
+  lastStatus = emptyStatus;
+  lastCdpUrl = null;
+  lastAnnotationUrl = null;
+  lastOpsUrl = null;
+  constructor(client) {
+    this.client = client;
+  }
+  async refresh() {
+    try {
+      const status = await this.client.call("relay.status");
+      this.lastStatus = status;
+      const cdpUrl = await this.client.call("relay.cdpUrl");
+      this.lastCdpUrl = typeof cdpUrl === "string" ? cdpUrl : null;
+      const annotationUrl = await this.client.call("relay.annotationUrl");
+      this.lastAnnotationUrl = typeof annotationUrl === "string" ? annotationUrl : null;
+      const opsUrl = await this.client.call("relay.opsUrl");
+      this.lastOpsUrl = typeof opsUrl === "string" ? opsUrl : null;
+    } catch {
+      this.lastStatus = emptyStatus;
+      this.lastCdpUrl = null;
+      this.lastAnnotationUrl = null;
+      this.lastOpsUrl = null;
+    }
+  }
+  status() {
+    return this.lastStatus;
+  }
+  getCdpUrl() {
+    return this.lastCdpUrl;
+  }
+  getAnnotationUrl() {
+    return this.lastAnnotationUrl;
+  }
+  getOpsUrl() {
+    return this.lastOpsUrl;
+  }
+};
 
 // src/skills/skill-nudge.ts
 var SKILL_NUDGE_MARKER = "[opendevbrowser:skill-nudge]";
-var SKILL_NUDGE_MESSAGE = `${SKILL_NUDGE_MARKER} If this task likely matches a skill, call the OpenCode skill tool early (skill("<skill-name>", topic?)) and load only the most relevant skill before using browser tools. If unsure which skill applies, check the available skills first.`;
+var SKILL_NUDGE_MESSAGE = `${SKILL_NUDGE_MARKER} If this task likely matches a skill, start with skill("opendevbrowser-best-practices", "quick start"). Use another skill only when it is more relevant.`;
 function createSkillNudgeState() {
   return { pending: false, requestedAtMs: null };
 }
@@ -68,7 +408,7 @@ function consumeContinuityNudge(state, nowMs, maxAgeMs) {
 }
 function buildContinuityNudgeMessage(filePath) {
   const target = filePath?.trim() || DEFAULT_FILE_PATH;
-  return `${CONTINUITY_NUDGE_MARKER} For long-running tasks, create or update ${target} at the repo root with Goal, Constraints/Assumptions, Key decisions, State (Done/Now/Next), Open questions, and Working set. Keep it brief.`;
+  return `${CONTINUITY_NUDGE_MARKER} For long-running tasks, load skill("opendevbrowser-continuity-ledger") and create or update ${target} at the repo root with Goal, Constraints/Assumptions, Key decisions, State (Done/Now/Next), Open questions, and Working set. Keep it brief.`;
 }
 
 // src/tools/launch.ts
@@ -98,7 +438,7 @@ function serializeError(error) {
 var z = tool.schema;
 function createLaunchTool(deps) {
   return tool({
-    description: "Launch a managed Chrome session and return a sessionId.",
+    description: "Launch a browser session (extension relay first) and return a sessionId.",
     args: {
       profile: z.string().optional().describe("Profile name for persistent browsing"),
       headless: z.boolean().optional().describe("Run Chrome in headless mode"),
@@ -108,102 +448,356 @@ function createLaunchTool(deps) {
       persistProfile: z.boolean().optional().describe("Persist profile data between sessions"),
       noExtension: z.boolean().optional().describe("Skip extension relay and launch a new browser"),
       extensionOnly: z.boolean().optional().describe("Require extension relay or fail"),
+      extensionLegacy: z.boolean().optional().describe("Use legacy extension relay (/cdp) instead of ops"),
       waitForExtension: z.boolean().optional().describe("Wait for extension to connect before launching"),
       waitTimeoutMs: z.number().int().optional().describe("Timeout for waiting on extension (ms)")
     },
     async execute(args) {
-      try {
-        let relayStatus = deps.relay?.status();
-        const relayUrl = deps.relay?.getCdpUrl();
-        const waitTimeoutMs = args.waitTimeoutMs ?? 3e4;
-        if (args.waitForExtension && deps.relay) {
-          const connected = await waitForExtension(deps.relay, waitTimeoutMs);
-          if (connected) {
-            relayStatus = deps.relay.status();
+      let attemptedRebind = false;
+      while (true) {
+        try {
+          await deps.relay?.refresh?.();
+          const config = deps.config.get();
+          const extensionLegacy = args.extensionLegacy === true;
+          let relayStatus = deps.relay?.status();
+          let relayUrl = extensionLegacy ? deps.relay?.getCdpUrl() ?? null : deps.relay?.getOpsUrl?.() ?? null;
+          const relayPort = relayStatus?.port;
+          if (!relayUrl && isValidPort(relayPort)) {
+            relayUrl = `ws://127.0.0.1:${relayPort}/${extensionLegacy ? "cdp" : "ops"}`;
           }
-        }
-        const useRelay = Boolean(!args.noExtension && relayStatus?.extensionConnected && relayUrl);
-        let usedRelay = false;
-        let relayWarning = null;
-        let result = null;
-        if (args.extensionOnly && !useRelay) {
-          return failure("Extension not connected; use --no-extension to launch a new browser.", "extension_not_connected");
-        }
-        if (useRelay && relayUrl) {
-          try {
-            result = await deps.manager.connectRelay(relayUrl);
-            usedRelay = true;
-          } catch {
-            if (args.extensionOnly) {
-              return failure("Extension relay connection failed.", "extension_connect_failed");
+          const waitTimeoutMs = clampWaitTimeout(args.waitTimeoutMs ?? 3e4);
+          const headlessExplicit = args.headless === true;
+          const managedExplicit = Boolean(args.noExtension || headlessExplicit);
+          const managedHeadless = headlessExplicit ? true : false;
+          if (headlessExplicit && !args.noExtension) {
+            return failure(
+              "Extension mode does not support headless launches. Use noExtension=true with headless=true for managed mode.",
+              "unsupported_mode"
+            );
+          }
+          if (args.waitForExtension && !managedExplicit) {
+            const observedPort2 = resolveObservedPort(relayStatus, config.relayPort);
+            const connected = await waitForExtensionHandshake(deps.relay, observedPort2, waitTimeoutMs);
+            if (connected) {
+              relayStatus = deps.relay?.status() ?? relayStatus;
+              relayUrl = extensionLegacy ? deps.relay?.getCdpUrl() ?? relayUrl : deps.relay?.getOpsUrl?.() ?? relayUrl;
             }
-            relayWarning = "Relay connection failed; falling back to managed Chrome.";
           }
-        }
-        if (!result) {
-          if (relayUrl && !args.noExtension) {
-            relayWarning ??= "Extension not connected; launching managed Chrome instead.";
+          const observedPort = resolveObservedPort(relayStatus, config.relayPort);
+          const shouldFetchObserved = !managedExplicit && (!relayUrl || !(relayStatus?.extensionHandshakeComplete || relayStatus?.extensionConnected));
+          const observedStatus = shouldFetchObserved ? await fetchRelayObservedStatus(observedPort) : null;
+          if (!relayUrl) {
+            const fallbackPort = isValidPort(observedStatus?.port) ? observedStatus?.port : observedPort;
+            relayUrl = fallbackPort ? `ws://127.0.0.1:${fallbackPort}/${extensionLegacy ? "cdp" : "ops"}` : null;
+          }
+          const extensionReady = Boolean(
+            relayUrl && (relayStatus?.extensionHandshakeComplete || relayStatus?.extensionConnected || observedStatus?.extensionHandshakeComplete || observedStatus?.extensionConnected)
+          );
+          let usedRelay = false;
+          let result = null;
+          if (args.extensionOnly && !extensionReady) {
+            const diagnostics = buildRelayNotReadyDiagnostics("Extension not connected.", {
+              relayUrl,
+              relayStatus,
+              observedStatus,
+              observedPort
+            });
+            if (await maybeRetryHubMismatch(diagnostics.hint, attemptedRebind, deps)) {
+              attemptedRebind = true;
+              continue;
+            }
+            return failure(buildExtensionMissingMessage(diagnostics.message), "extension_not_connected");
+          }
+          if (!managedExplicit) {
+            if (!extensionReady || !relayUrl) {
+              const diagnostics = buildRelayNotReadyDiagnostics("Extension not connected.", {
+                relayUrl,
+                relayStatus,
+                observedStatus,
+                observedPort
+              });
+              if (await maybeRetryHubMismatch(diagnostics.hint, attemptedRebind, deps)) {
+                attemptedRebind = true;
+                continue;
+              }
+              return failure(buildExtensionMissingMessage(diagnostics.message), "extension_not_connected");
+            }
+            try {
+              result = await deps.manager.connectRelay(relayUrl);
+              usedRelay = true;
+            } catch (error) {
+              const errorMessage = serializeError(error).message;
+              const unauthorized = errorMessage.toLowerCase().includes("unauthorized") || errorMessage.includes("401");
+              const relayLabel = extensionLegacy ? "/cdp" : "/ops";
+              const errorObservedStatus = observedStatus ?? await fetchRelayObservedStatus(observedPort);
+              const diagnostics = buildRelayNotReadyDiagnostics(
+                unauthorized ? `Extension relay connection failed: relay ${relayLabel} unauthorized (token mismatch).` : `Extension relay connection failed: ${errorMessage}`,
+                {
+                  relayUrl,
+                  relayStatus,
+                  observedStatus: errorObservedStatus,
+                  observedPort
+                }
+              );
+              if (await maybeRetryHubMismatch(diagnostics.hint, attemptedRebind, deps)) {
+                attemptedRebind = true;
+                continue;
+              }
+              return failure(buildExtensionMissingMessage(diagnostics.message), "extension_connect_failed");
+            }
+          }
+          if (!result) {
+            try {
+              result = await deps.manager.launch({
+                profile: args.profile,
+                headless: managedHeadless,
+                startUrl: args.startUrl,
+                chromePath: args.chromePath,
+                flags: args.flags,
+                persistProfile: args.persistProfile,
+                noExtension: args.noExtension
+              });
+            } catch (error) {
+              return failure(buildManagedFailureMessage(error), "launch_failed");
+            }
+          }
+          if (usedRelay && args.startUrl && result.activeTargetId) {
+            await deps.manager.goto(result.sessionId, args.startUrl, "load", 3e4);
           }
-          result = await deps.manager.launch({
-            profile: args.profile,
-            headless: args.headless,
-            startUrl: args.startUrl,
-            chromePath: args.chromePath,
-            flags: args.flags,
-            persistProfile: args.persistProfile
+          const warnings = result.warnings ?? [];
+          return ok({
+            sessionId: result.sessionId,
+            mode: result.mode,
+            browserWsEndpoint: result.wsEndpoint,
+            activeTargetId: result.activeTargetId,
+            warnings: warnings.length ? warnings : void 0
           });
+        } catch (error) {
+          return failure(serializeError(error).message, "launch_failed");
         }
-        if (usedRelay && args.startUrl && result.activeTargetId) {
-          await deps.manager.goto(result.sessionId, args.startUrl, "load", 3e4);
-        }
-        const warnings = [
-          ...result.warnings ?? [],
-          ...relayWarning ? [relayWarning] : []
-        ];
-        return ok({
-          sessionId: result.sessionId,
-          mode: result.mode,
-          browserWsEndpoint: result.wsEndpoint,
-          activeTargetId: result.activeTargetId,
-          warnings: warnings.length ? warnings : void 0
-        });
-      } catch (error) {
-        return failure(serializeError(error).message, "launch_failed");
       }
     }
   });
 }
-async function waitForExtension(relay, timeoutMs) {
+var buildExtensionMissingMessage = (reason) => {
+  return [
+    reason,
+    "Connect the extension: open the Chrome extension popup and click Connect, then retry.",
+    "Tip: If the popup says Connected, it may be connected to a different relay instance/port than this tool expects.",
+    "Legend: ext=extension websocket, handshake=extension handshake, ops=active /ops client, cdp=active /cdp client, pairing=token required.",
+    "",
+    "Other options (explicit):",
+    "- Managed (headed): npx opendevbrowser launch --no-extension",
+    "- Managed (headless): npx opendevbrowser launch --no-extension --headless",
+    "- Legacy extension relay: npx opendevbrowser launch --extension-legacy",
+    "- CDPConnect (default port): npx opendevbrowser connect --cdp-port 9222",
+    "- CDPConnect (explicit WS): npx opendevbrowser connect --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>",
+    "Note: CDPConnect requires Chrome started with --remote-debugging-port=9222."
+  ].join("\n");
+};
+var buildManagedFailureMessage = (error) => {
+  const detail = serializeError(error).message;
+  return [
+    `Managed session failed: ${detail}`,
+    "",
+    "Final option (explicit):",
+    "- CDPConnect (default port): npx opendevbrowser connect --cdp-port 9222",
+    "- CDPConnect (explicit WS): npx opendevbrowser connect --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>"
+  ].join("\n");
+};
+var MIN_WAIT_TIMEOUT_MS = 3e3;
+var WAIT_MIN_DELAY_MS = 250;
+var WAIT_MAX_DELAY_MS = 2e3;
+function clampWaitTimeout(timeoutMs) {
+  if (!Number.isFinite(timeoutMs)) {
+    return MIN_WAIT_TIMEOUT_MS;
+  }
+  return Math.max(timeoutMs, MIN_WAIT_TIMEOUT_MS);
+}
+async function waitForExtensionHandshake(relay, observedPort, timeoutMs) {
   const start = Date.now();
+  let delay = WAIT_MIN_DELAY_MS;
   while (Date.now() - start < timeoutMs) {
-    if (relay.status().extensionConnected) {
+    if (relay?.status().extensionHandshakeComplete) {
+      return true;
+    }
+    const observedStatus = await fetchRelayObservedStatus(observedPort);
+    if (observedStatus?.extensionHandshakeComplete) {
       return true;
     }
-    await new Promise((resolve) => setTimeout(resolve, 500));
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    delay = Math.min(delay * 2, WAIT_MAX_DELAY_MS);
   }
   return false;
 }
+function resolveObservedPort(relayStatus, configPort) {
+  const relayPort = relayStatus?.port;
+  if (isValidPort(relayPort)) return relayPort;
+  if (isValidPort(configPort)) return configPort;
+  return null;
+}
+function isValidPort(port) {
+  return typeof port === "number" && Number.isInteger(port) && port > 0 && port <= 65535;
+}
+function shortInstanceId(value) {
+  if (!value) return "?";
+  return value.slice(0, 8);
+}
+function formatRelayUrl(relayUrl) {
+  return relayUrl ?? "null";
+}
+function formatLocalStatus(status) {
+  return [
+    "local(instance=",
+    shortInstanceId(status?.instanceId),
+    " port=",
+    typeof status?.port === "number" ? String(status.port) : "?",
+    " ext=",
+    String(Boolean(status?.extensionConnected)),
+    " handshake=",
+    String(Boolean(status?.extensionHandshakeComplete)),
+    " ops=",
+    String(Boolean(status?.opsConnected)),
+    " cdp=",
+    String(Boolean(status?.cdpConnected)),
+    " pairing=",
+    String(Boolean(status?.pairingRequired)),
+    ")"
+  ].join("");
+}
+function formatObservedStatus(status, port) {
+  const label = port ?? "?";
+  if (!status) {
+    return `observed@${label}=none`;
+  }
+  return [
+    "observed@",
+    label,
+    "=instance=",
+    shortInstanceId(status.instanceId),
+    " ext=",
+    String(Boolean(status.extensionConnected)),
+    " handshake=",
+    String(Boolean(status.extensionHandshakeComplete)),
+    " ops=",
+    String(Boolean(status.opsConnected)),
+    " cdp=",
+    String(Boolean(status.cdpConnected)),
+    " pairing=",
+    String(Boolean(status.pairingRequired))
+  ].join("");
+}
+function buildRelayNotReadyDiagnostics(baseReason, detail) {
+  const localExt = Boolean(detail.relayStatus?.extensionConnected);
+  const observedExt = Boolean(detail.observedStatus?.extensionConnected);
+  let hint = "none";
+  if (detail.relayUrl === null) {
+    hint = "relayUrl_null";
+  } else if (detail.observedStatus && !localExt && observedExt) {
+    hint = "possible_mismatch";
+  } else if (detail.relayStatus?.instanceId && detail.observedStatus?.instanceId && detail.relayStatus.instanceId !== detail.observedStatus.instanceId) {
+    hint = "possible_mismatch";
+  }
+  const diagnostics = [
+    "Diagnostics: relayUrl=",
+    formatRelayUrl(detail.relayUrl),
+    " ",
+    formatLocalStatus(detail.relayStatus),
+    " ",
+    formatObservedStatus(detail.observedStatus, detail.observedPort),
+    " hint=",
+    hint
+  ].join("");
+  return { message: [baseReason, diagnostics].join("\n"), hint };
+}
+async function maybeRetryHubMismatch(hint, attempted, deps) {
+  if (attempted) return false;
+  if (hint !== "possible_mismatch") return false;
+  if (!deps.ensureHub) return false;
+  await deps.ensureHub();
+  await deps.relay?.refresh?.();
+  return true;
+}
+async function fetchRelayObservedStatus(port) {
+  if (!isValidPort(port)) return null;
+  if (typeof fetch !== "function") return null;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 500);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/status`, { signal: controller.signal });
+    if (!response.ok) return null;
+    const payload = await response.json();
+    if (!payload || typeof payload.instanceId !== "string") return null;
+    return {
+      instanceId: payload.instanceId,
+      running: Boolean(payload.running),
+      port: typeof payload.port === "number" ? payload.port : void 0,
+      extensionConnected: Boolean(payload.extensionConnected),
+      extensionHandshakeComplete: Boolean(payload.extensionHandshakeComplete),
+      cdpConnected: Boolean(payload.cdpConnected),
+      opsConnected: Boolean(payload.opsConnected),
+      pairingRequired: Boolean(payload.pairingRequired)
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
 
 // src/tools/connect.ts
 import { tool as tool2 } from "@opencode-ai/plugin";
 var z2 = tool2.schema;
+function normalizeRelayEndpoint(wsEndpoint, path, allowBase) {
+  if (!wsEndpoint) return null;
+  try {
+    const url = new URL(wsEndpoint);
+    if (url.protocol !== "ws:" && url.protocol !== "wss:") return null;
+    if (url.hostname !== "127.0.0.1" && url.hostname !== "localhost") return null;
+    if (!url.port || !/^\d+$/.test(url.port)) return null;
+    const normalizedPath = url.pathname.endsWith("/") ? url.pathname.slice(0, -1) : url.pathname;
+    if (!allowBase && normalizedPath === "") return null;
+    if (normalizedPath && normalizedPath !== `/${path}`) return null;
+    return `${url.protocol}//${url.hostname}:${url.port}/${path}`;
+  } catch {
+    return null;
+  }
+}
 function createConnectTool(deps) {
   return tool2({
-    description: "Connect to an existing Chrome CDP endpoint.",
+    description: "Connect to an existing Chrome CDP endpoint or extension relay.",
     args: {
       wsEndpoint: z2.string().optional().describe("Full WebSocket endpoint to connect to"),
       host: z2.string().optional().describe("Host for /json/version lookup"),
-      port: z2.number().int().optional().describe("Port for /json/version lookup")
+      port: z2.number().int().optional().describe("Port for /json/version lookup"),
+      extensionLegacy: z2.boolean().optional().describe("Use legacy extension relay (/cdp) instead of ops")
     },
     async execute(args) {
       try {
-        const relayUrl = deps.relay?.getCdpUrl();
-        const useRelay = Boolean(relayUrl && args.wsEndpoint === relayUrl);
-        const result = useRelay && relayUrl ? await deps.manager.connectRelay(relayUrl) : await deps.manager.connect({
-          wsEndpoint: args.wsEndpoint,
-          host: args.host,
-          port: args.port
-        });
+        await deps.relay?.refresh?.();
+        const wsEndpoint = args.wsEndpoint;
+        const extensionLegacy = args.extensionLegacy === true;
+        const hasExplicitCdp = Boolean(wsEndpoint || args.host || args.port);
+        const relayUrl = extensionLegacy ? deps.relay?.getCdpUrl() ?? null : deps.relay?.getOpsUrl?.() ?? null;
+        const normalizedOpsEndpoint = normalizeRelayEndpoint(wsEndpoint, "ops", true);
+        const normalizedLegacyEndpoint = normalizeRelayEndpoint(wsEndpoint, "cdp", extensionLegacy);
+        if (normalizedLegacyEndpoint && !extensionLegacy) {
+          return failure("Legacy extension relay (/cdp) requires extensionLegacy=true.", "extension_legacy_required");
+        }
+        const relayEndpoint = relayUrl && wsEndpoint === relayUrl ? relayUrl : extensionLegacy ? normalizedLegacyEndpoint ?? normalizedOpsEndpoint : normalizedOpsEndpoint;
+        let result;
+        if (relayEndpoint || !hasExplicitCdp && relayUrl) {
+          result = await deps.manager.connectRelay(relayEndpoint ?? relayUrl ?? "");
+        } else {
+          if (!hasExplicitCdp) {
+            return failure("Extension relay not available. Connect the extension or pass wsEndpoint/host/port.", "extension_not_connected");
+          }
+          result = await deps.manager.connect({
+            wsEndpoint,
+            host: args.host,
+            port: args.port
+          });
+        }
         return ok({
           sessionId: result.sessionId,
           mode: result.mode,
@@ -244,6 +838,13 @@ import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { tool as tool4 } from "@opencode-ai/plugin";
+
+// src/utils/hub-enabled.ts
+var isHubEnabled = (config) => {
+  return config.relayToken !== false && config.relayPort > 0;
+};
+
+// src/tools/status.ts
 var z4 = tool4.schema;
 function getPackageVersion() {
   try {
@@ -285,17 +886,45 @@ async function fetchLatestVersion(packageName) {
 }
 function createStatusTool(deps) {
   return tool4({
-    description: "Get status of a browser session.",
+    description: "Get daemon or session status.",
     args: {
-      sessionId: z4.string().describe("Session id")
+      sessionId: z4.string().optional().describe("Session id (required when hub is disabled)")
     },
     async execute(args) {
       try {
-        const status = await deps.manager.status(args.sessionId);
-        const extensionPath = deps.getExtensionPath?.() ?? null;
         const config = deps.config.get();
+        const hubEnabled = isHubEnabled(config);
+        const extensionPath = deps.getExtensionPath?.() ?? null;
         const version = getPackageVersion();
         let updateHint;
+        let sessionStatus = null;
+        if (hubEnabled) {
+          const daemonStatus = await fetchDaemonStatusFromMetadata();
+          if (!daemonStatus) {
+            return failure("Daemon not running. Start with `npx opendevbrowser serve`.", "status_failed");
+          }
+          if (args.sessionId) {
+            sessionStatus = await deps.manager.status(args.sessionId);
+          }
+          if (config.checkForUpdates && version) {
+            const latest = await fetchLatestVersion("opendevbrowser");
+            if (latest && latest !== version) {
+              updateHint = `Update available: ${version} -> ${latest}`;
+            }
+          }
+          return ok({
+            ...sessionStatus ?? {},
+            daemon: daemonStatus,
+            hubEnabled: true,
+            extensionPath: extensionPath ?? void 0,
+            version,
+            updateHint
+          });
+        }
+        if (!args.sessionId) {
+          return failure("Missing sessionId for status.", "status_failed");
+        }
+        sessionStatus = await deps.manager.status(args.sessionId);
         if (config.checkForUpdates && version) {
           const latest = await fetchLatestVersion("opendevbrowser");
           if (latest && latest !== version) {
@@ -303,10 +932,10 @@ function createStatusTool(deps) {
           }
         }
         return ok({
-          mode: status.mode,
-          activeTargetId: status.activeTargetId,
-          url: status.url,
-          title: status.title,
+          mode: sessionStatus.mode,
+          activeTargetId: sessionStatus.activeTargetId,
+          url: sessionStatus.url,
+          title: sessionStatus.title,
           extensionPath: extensionPath ?? void 0,
           version,
           updateHint
@@ -599,266 +1228,921 @@ function createClickTool(deps) {
   });
 }
 
-// src/tools/type.ts
+// src/tools/hover.ts
 import { tool as tool16 } from "@opencode-ai/plugin";
 var z16 = tool16.schema;
-function createTypeTool(deps) {
+function createHoverTool(deps) {
   return tool16({
-    description: "Type text into a referenced input.",
+    description: "Hover over an element by ref.",
     args: {
-      sessionId: z16.string().describe("Session id"),
-      ref: z16.string().describe("Element ref"),
-      text: z16.string().describe("Text to type"),
-      clear: z16.boolean().optional().describe("Clear before typing"),
-      submit: z16.boolean().optional().describe("Press Enter after typing")
+      sessionId: z16.string().describe("Active browser session id"),
+      ref: z16.string().describe("Element ref from snapshot")
     },
     async execute(args) {
       try {
-        const result = await deps.manager.type(
-          args.sessionId,
-          args.ref,
-          args.text,
-          Boolean(args.clear),
-          Boolean(args.submit)
-        );
+        const result = await deps.manager.hover(args.sessionId, args.ref);
         return ok(result);
       } catch (error) {
-        return failure(serializeError(error).message, "type_failed");
+        return failure(serializeError(error).message, "hover_failed");
       }
     }
   });
 }
 
-// src/tools/select.ts
+// src/tools/press.ts
 import { tool as tool17 } from "@opencode-ai/plugin";
 var z17 = tool17.schema;
-function createSelectTool(deps) {
+function createPressTool(deps) {
   return tool17({
-    description: "Select options in a referenced select element.",
+    description: "Press a keyboard key, optionally focusing a ref first.",
     args: {
-      sessionId: z17.string().describe("Session id"),
-      ref: z17.string().describe("Element ref"),
-      values: z17.array(z17.string()).describe("Values to select")
+      sessionId: z17.string().describe("Active browser session id"),
+      key: z17.string().describe("Keyboard key to press, e.g. Enter or ArrowDown"),
+      ref: z17.string().optional().describe("Optional element ref to focus first")
     },
     async execute(args) {
       try {
-        await deps.manager.select(args.sessionId, args.ref, args.values);
-        return ok({});
+        const result = await deps.manager.press(args.sessionId, args.key, args.ref);
+        return ok(result);
       } catch (error) {
-        return failure(serializeError(error).message, "select_failed");
+        return failure(serializeError(error).message, "press_failed");
       }
     }
   });
 }
 
-// src/tools/scroll.ts
+// src/tools/check.ts
 import { tool as tool18 } from "@opencode-ai/plugin";
 var z18 = tool18.schema;
-function createScrollTool(deps) {
+function createCheckTool(deps) {
   return tool18({
-    description: "Scroll the page or a referenced element.",
+    description: "Check a checkbox or toggle by ref.",
     args: {
-      sessionId: z18.string().describe("Session id"),
-      dy: z18.number().describe("Scroll delta in pixels"),
-      ref: z18.string().optional().describe("Optional element ref to scroll")
+      sessionId: z18.string().describe("Active browser session id"),
+      ref: z18.string().describe("Element ref from snapshot")
     },
     async execute(args) {
       try {
-        await deps.manager.scroll(args.sessionId, args.dy, args.ref);
-        return ok({});
+        const result = await deps.manager.check(args.sessionId, args.ref);
+        return ok(result);
       } catch (error) {
-        return failure(serializeError(error).message, "scroll_failed");
+        return failure(serializeError(error).message, "check_failed");
       }
     }
   });
 }
 
-// src/tools/dom_get_html.ts
+// src/tools/uncheck.ts
 import { tool as tool19 } from "@opencode-ai/plugin";
 var z19 = tool19.schema;
-function createDomGetHtmlTool(deps) {
+function createUncheckTool(deps) {
   return tool19({
-    description: "Get outerHTML for a referenced element.",
+    description: "Uncheck a checkbox or toggle by ref.",
     args: {
-      sessionId: z19.string().describe("Session id"),
-      ref: z19.string().describe("Element ref"),
-      maxChars: z19.number().int().optional().describe("Max characters")
+      sessionId: z19.string().describe("Active browser session id"),
+      ref: z19.string().describe("Element ref from snapshot")
     },
     async execute(args) {
       try {
-        const result = await deps.manager.domGetHtml(
-          args.sessionId,
-          args.ref,
-          args.maxChars ?? 8e3
-        );
-        return ok({
-          ref: args.ref,
-          outerHTML: result.outerHTML,
-          truncated: result.truncated
-        });
+        const result = await deps.manager.uncheck(args.sessionId, args.ref);
+        return ok(result);
       } catch (error) {
-        return failure(serializeError(error).message, "dom_get_html_failed");
+        return failure(serializeError(error).message, "uncheck_failed");
       }
     }
   });
 }
 
-// src/tools/dom_get_text.ts
+// src/tools/type.ts
 import { tool as tool20 } from "@opencode-ai/plugin";
 var z20 = tool20.schema;
-function createDomGetTextTool(deps) {
+function createTypeTool(deps) {
   return tool20({
-    description: "Get inner text for a referenced element.",
+    description: "Type text into a referenced input.",
     args: {
       sessionId: z20.string().describe("Session id"),
       ref: z20.string().describe("Element ref"),
-      maxChars: z20.number().int().optional().describe("Max characters")
+      text: z20.string().describe("Text to type"),
+      clear: z20.boolean().optional().describe("Clear before typing"),
+      submit: z20.boolean().optional().describe("Press Enter after typing")
     },
     async execute(args) {
       try {
-        const result = await deps.manager.domGetText(
+        const result = await deps.manager.type(
           args.sessionId,
           args.ref,
-          args.maxChars ?? 8e3
+          args.text,
+          Boolean(args.clear),
+          Boolean(args.submit)
         );
-        return ok({
-          ref: args.ref,
-          text: result.text,
-          truncated: result.truncated
-        });
+        return ok(result);
       } catch (error) {
-        return failure(serializeError(error).message, "dom_get_text_failed");
+        return failure(serializeError(error).message, "type_failed");
       }
     }
   });
 }
 
-// src/tools/run.ts
+// src/tools/select.ts
 import { tool as tool21 } from "@opencode-ai/plugin";
 var z21 = tool21.schema;
-var stepSchema = z21.object({
-  action: z21.string().describe("Action name"),
-  args: z21.record(z21.string(), z21.unknown()).optional().describe("Action arguments")
-});
-function createRunTool(deps) {
+function createSelectTool(deps) {
   return tool21({
-    description: "Run multiple actions in a single tool call.",
+    description: "Select options in a referenced select element.",
     args: {
       sessionId: z21.string().describe("Session id"),
-      steps: z21.array(stepSchema).describe("Steps to execute"),
-      stopOnError: z21.boolean().optional().describe("Stop when a step fails"),
-      maxSnapshotChars: z21.number().int().optional().describe("Default maxChars for snapshot steps")
+      ref: z21.string().describe("Element ref"),
+      values: z21.array(z21.string()).describe("Values to select")
     },
     async execute(args) {
       try {
-        const steps = normalizeSteps(args.steps, args.maxSnapshotChars);
-        const result = await deps.runner.run(
-          args.sessionId,
-          steps,
-          args.stopOnError ?? true
-        );
-        return ok(result);
+        await deps.manager.select(args.sessionId, args.ref, args.values);
+        return ok({});
       } catch (error) {
-        return failure(serializeError(error).message, "run_failed");
+        return failure(serializeError(error).message, "select_failed");
       }
     }
   });
 }
-function normalizeSteps(steps, maxSnapshotChars) {
-  if (!maxSnapshotChars) return steps;
-  return steps.map((step) => {
-    if (step.action !== "snapshot") return step;
-    if (step.args && typeof step.args.maxChars === "number") return step;
-    return {
-      ...step,
-      args: {
-        ...step.args,
-        maxChars: maxSnapshotChars
-      }
-    };
-  });
-}
 
-// src/tools/prompting_guide.ts
+// src/tools/scroll.ts
 import { tool as tool22 } from "@opencode-ai/plugin";
 var z22 = tool22.schema;
-function createPromptingGuideTool(deps) {
+function createScrollTool(deps) {
   return tool22({
-    description: "Return best-practice prompting guidance for OpenDevBrowser.",
+    description: "Scroll the page or a referenced element.",
     args: {
-      topic: z22.string().optional().describe("Optional topic for guidance")
+      sessionId: z22.string().describe("Session id"),
+      dy: z22.number().describe("Scroll delta in pixels"),
+      ref: z22.string().optional().describe("Optional element ref to scroll")
     },
     async execute(args) {
       try {
-        const guide = await deps.skills.loadBestPractices(args.topic);
-        return ok({ guide });
+        await deps.manager.scroll(args.sessionId, args.dy, args.ref);
+        return ok({});
       } catch (error) {
-        return failure(serializeError(error).message, "prompting_guide_failed");
+        return failure(serializeError(error).message, "scroll_failed");
       }
     }
   });
 }
 
-// src/tools/console_poll.ts
+// src/tools/scroll_into_view.ts
 import { tool as tool23 } from "@opencode-ai/plugin";
 var z23 = tool23.schema;
-function createConsolePollTool(deps) {
+function createScrollIntoViewTool(deps) {
   return tool23({
-    description: "Poll console events for the active target.",
+    description: "Scroll an element into view by ref.",
     args: {
-      sessionId: z23.string().describe("Session id"),
-      sinceSeq: z23.number().int().optional().describe("Sequence to resume from"),
-      max: z23.number().int().optional().describe("Max events to return")
+      sessionId: z23.string().describe("Active browser session id"),
+      ref: z23.string().describe("Element ref from snapshot")
     },
     async execute(args) {
       try {
-        const result = deps.manager.consolePoll(
-          args.sessionId,
-          args.sinceSeq,
-          args.max ?? 50
-        );
+        const result = await deps.manager.scrollIntoView(args.sessionId, args.ref);
         return ok(result);
       } catch (error) {
-        return failure(serializeError(error).message, "console_poll_failed");
+        return failure(serializeError(error).message, "scroll_into_view_failed");
       }
     }
   });
 }
 
-// src/tools/network_poll.ts
+// src/tools/dom_get_html.ts
 import { tool as tool24 } from "@opencode-ai/plugin";
 var z24 = tool24.schema;
-function createNetworkPollTool(deps) {
+function createDomGetHtmlTool(deps) {
   return tool24({
-    description: "Poll network events for the active target.",
+    description: "Get outerHTML for a referenced element.",
     args: {
       sessionId: z24.string().describe("Session id"),
-      sinceSeq: z24.number().int().optional().describe("Sequence to resume from"),
-      max: z24.number().int().optional().describe("Max events to return")
+      ref: z24.string().describe("Element ref"),
+      maxChars: z24.number().int().optional().describe("Max characters")
     },
     async execute(args) {
       try {
-        const result = deps.manager.networkPoll(
+        const result = await deps.manager.domGetHtml(
           args.sessionId,
-          args.sinceSeq,
-          args.max ?? 50
+          args.ref,
+          args.maxChars ?? 8e3
         );
-        return ok(result);
-      } catch (error) {
-        return failure(serializeError(error).message, "network_poll_failed");
-      }
+        return ok({
+          ref: args.ref,
+          outerHTML: result.outerHTML,
+          truncated: result.truncated
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "dom_get_html_failed");
+      }
     }
   });
 }
 
-// src/tools/clone_page.ts
+// src/tools/dom_get_text.ts
 import { tool as tool25 } from "@opencode-ai/plugin";
 var z25 = tool25.schema;
-function createClonePageTool(deps) {
+function createDomGetTextTool(deps) {
   return tool25({
+    description: "Get inner text for a referenced element.",
+    args: {
+      sessionId: z25.string().describe("Session id"),
+      ref: z25.string().describe("Element ref"),
+      maxChars: z25.number().int().optional().describe("Max characters")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.domGetText(
+          args.sessionId,
+          args.ref,
+          args.maxChars ?? 8e3
+        );
+        return ok({
+          ref: args.ref,
+          text: result.text,
+          truncated: result.truncated
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "dom_get_text_failed");
+      }
+    }
+  });
+}
+
+// src/tools/get_attr.ts
+import { tool as tool26 } from "@opencode-ai/plugin";
+var z26 = tool26.schema;
+function createGetAttrTool(deps) {
+  return tool26({
+    description: "Get a DOM attribute value by ref.",
+    args: {
+      sessionId: z26.string().describe("Active browser session id"),
+      ref: z26.string().describe("Element ref from snapshot"),
+      name: z26.string().describe("Attribute name, e.g. href or aria-label")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.domGetAttr(args.sessionId, args.ref, args.name);
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "get_attr_failed");
+      }
+    }
+  });
+}
+
+// src/tools/get_value.ts
+import { tool as tool27 } from "@opencode-ai/plugin";
+var z27 = tool27.schema;
+function createGetValueTool(deps) {
+  return tool27({
+    description: "Get the input value for an element by ref.",
+    args: {
+      sessionId: z27.string().describe("Active browser session id"),
+      ref: z27.string().describe("Element ref from snapshot")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.domGetValue(args.sessionId, args.ref);
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "get_value_failed");
+      }
+    }
+  });
+}
+
+// src/tools/is_visible.ts
+import { tool as tool28 } from "@opencode-ai/plugin";
+var z28 = tool28.schema;
+function createIsVisibleTool(deps) {
+  return tool28({
+    description: "Check if an element is visible by ref.",
+    args: {
+      sessionId: z28.string().describe("Active browser session id"),
+      ref: z28.string().describe("Element ref from snapshot")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.domIsVisible(args.sessionId, args.ref);
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "is_visible_failed");
+      }
+    }
+  });
+}
+
+// src/tools/is_enabled.ts
+import { tool as tool29 } from "@opencode-ai/plugin";
+var z29 = tool29.schema;
+function createIsEnabledTool(deps) {
+  return tool29({
+    description: "Check if an element is enabled by ref.",
+    args: {
+      sessionId: z29.string().describe("Active browser session id"),
+      ref: z29.string().describe("Element ref from snapshot")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.domIsEnabled(args.sessionId, args.ref);
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "is_enabled_failed");
+      }
+    }
+  });
+}
+
+// src/tools/is_checked.ts
+import { tool as tool30 } from "@opencode-ai/plugin";
+var z30 = tool30.schema;
+function createIsCheckedTool(deps) {
+  return tool30({
+    description: "Check if an element is checked by ref.",
+    args: {
+      sessionId: z30.string().describe("Active browser session id"),
+      ref: z30.string().describe("Element ref from snapshot")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.domIsChecked(args.sessionId, args.ref);
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "is_checked_failed");
+      }
+    }
+  });
+}
+
+// src/tools/run.ts
+import { tool as tool31 } from "@opencode-ai/plugin";
+var z31 = tool31.schema;
+var stepSchema = z31.object({
+  action: z31.string().describe("Action name"),
+  args: z31.record(z31.string(), z31.unknown()).optional().describe("Action arguments")
+});
+function createRunTool(deps) {
+  return tool31({
+    description: "Run multiple actions in a single tool call.",
+    args: {
+      sessionId: z31.string().describe("Session id"),
+      steps: z31.array(stepSchema).describe("Steps to execute"),
+      stopOnError: z31.boolean().optional().describe("Stop when a step fails"),
+      maxSnapshotChars: z31.number().int().optional().describe("Default maxChars for snapshot steps")
+    },
+    async execute(args) {
+      try {
+        const steps = normalizeSteps(args.steps, args.maxSnapshotChars);
+        const result = await deps.runner.run(
+          args.sessionId,
+          steps,
+          args.stopOnError ?? true
+        );
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "run_failed");
+      }
+    }
+  });
+}
+function normalizeSteps(steps, maxSnapshotChars) {
+  if (!maxSnapshotChars) return steps;
+  return steps.map((step) => {
+    if (step.action !== "snapshot") return step;
+    if (step.args && typeof step.args.maxChars === "number") return step;
+    return {
+      ...step,
+      args: {
+        ...step.args,
+        maxChars: maxSnapshotChars
+      }
+    };
+  });
+}
+
+// src/tools/prompting_guide.ts
+import { tool as tool32 } from "@opencode-ai/plugin";
+var z32 = tool32.schema;
+function createPromptingGuideTool(deps) {
+  return tool32({
+    description: "Return best-practice prompting guidance for OpenDevBrowser.",
+    args: {
+      topic: z32.string().optional().describe("Optional topic for guidance")
+    },
+    async execute(args) {
+      try {
+        const guide = await deps.skills.loadBestPractices(args.topic);
+        return ok({ guide });
+      } catch (error) {
+        return failure(serializeError(error).message, "prompting_guide_failed");
+      }
+    }
+  });
+}
+
+// src/tools/console_poll.ts
+import { tool as tool33 } from "@opencode-ai/plugin";
+var z33 = tool33.schema;
+function createConsolePollTool(deps) {
+  return tool33({
+    description: "Poll console events for the active target.",
+    args: {
+      sessionId: z33.string().describe("Session id"),
+      sinceSeq: z33.number().int().optional().describe("Sequence to resume from"),
+      max: z33.number().int().optional().describe("Max events to return")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.consolePoll(
+          args.sessionId,
+          args.sinceSeq,
+          args.max ?? 50
+        );
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "console_poll_failed");
+      }
+    }
+  });
+}
+
+// src/tools/network_poll.ts
+import { tool as tool34 } from "@opencode-ai/plugin";
+var z34 = tool34.schema;
+function createNetworkPollTool(deps) {
+  return tool34({
+    description: "Poll network events for the active target.",
+    args: {
+      sessionId: z34.string().describe("Session id"),
+      sinceSeq: z34.number().int().optional().describe("Sequence to resume from"),
+      max: z34.number().int().optional().describe("Max events to return")
+    },
+    async execute(args) {
+      try {
+        const result = await deps.manager.networkPoll(
+          args.sessionId,
+          args.sinceSeq,
+          args.max ?? 50
+        );
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "network_poll_failed");
+      }
+    }
+  });
+}
+
+// src/tools/debug_trace_snapshot.ts
+import { tool as tool35 } from "@opencode-ai/plugin";
+var z35 = tool35.schema;
+function createDebugTraceSnapshotTool(deps) {
+  return tool35({
+    description: "Capture a combined debug trace snapshot (page + console + network + exceptions).",
+    args: {
+      sessionId: z35.string().describe("Session id"),
+      sinceConsoleSeq: z35.number().int().optional().describe("Resume cursor for console events"),
+      sinceNetworkSeq: z35.number().int().optional().describe("Resume cursor for network events"),
+      sinceExceptionSeq: z35.number().int().optional().describe("Resume cursor for exception events"),
+      max: z35.number().int().optional().describe("Max events per channel"),
+      requestId: z35.string().optional().describe("Optional trace request id")
+    },
+    async execute(args) {
+      try {
+        const manager = deps.manager;
+        const options = {
+          sinceConsoleSeq: args.sinceConsoleSeq,
+          sinceNetworkSeq: args.sinceNetworkSeq,
+          sinceExceptionSeq: args.sinceExceptionSeq,
+          max: args.max,
+          requestId: args.requestId
+        };
+        if (typeof manager.debugTraceSnapshot === "function") {
+          const result = await manager.debugTraceSnapshot(args.sessionId, options);
+          return ok(result);
+        }
+        const max = args.max ?? 500;
+        const requestId = args.requestId ?? createRequestId();
+        const [page, consoleChannel, networkChannel] = await Promise.all([
+          deps.manager.status(args.sessionId),
+          deps.manager.consolePoll(args.sessionId, args.sinceConsoleSeq, max),
+          deps.manager.networkPoll(args.sessionId, args.sinceNetworkSeq, max)
+        ]);
+        const exceptionChannel = typeof manager.exceptionPoll === "function" ? await manager.exceptionPoll(args.sessionId, args.sinceExceptionSeq, max) : {
+          events: [],
+          nextSeq: args.sinceExceptionSeq ?? 0,
+          truncated: false
+        };
+        const annotateTraceContext = (events) => events.map((event) => ({
+          ...event,
+          requestId,
+          sessionId: args.sessionId
+        }));
+        const blocker = classifyBlockerSignal({
+          source: "network",
+          url: typeof page.url === "string" ? page.url : void 0,
+          finalUrl: typeof page.url === "string" ? page.url : void 0,
+          title: typeof page.title === "string" ? page.title : void 0,
+          status: findLatestStatus(networkChannel.events),
+          traceRequestId: requestId,
+          networkHosts: extractHosts(networkChannel.events),
+          threshold: deps.config.get().blockerDetectionThreshold,
+          promptGuardEnabled: deps.config.get().security.promptInjectionGuard?.enabled ?? true
+        });
+        const blockerArtifacts = blocker ? buildBlockerArtifacts({
+          networkEvents: networkChannel.events,
+          consoleEvents: consoleChannel.events,
+          exceptionEvents: exceptionChannel.events,
+          promptGuardEnabled: deps.config.get().security.promptInjectionGuard?.enabled ?? true,
+          caps: deps.config.get().blockerArtifactCaps
+        }) : void 0;
+        return ok({
+          requestId,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          page,
+          channels: {
+            console: {
+              nextSeq: consoleChannel.nextSeq,
+              truncated: consoleChannel.truncated,
+              events: annotateTraceContext(consoleChannel.events)
+            },
+            network: {
+              nextSeq: networkChannel.nextSeq,
+              truncated: networkChannel.truncated,
+              events: annotateTraceContext(networkChannel.events)
+            },
+            exception: {
+              nextSeq: exceptionChannel.nextSeq,
+              truncated: exceptionChannel.truncated,
+              events: annotateTraceContext(exceptionChannel.events)
+            }
+          },
+          meta: {
+            blockerState: blocker ? "active" : "clear",
+            ...blocker ? { blocker } : {},
+            ...blockerArtifacts ? { blockerArtifacts } : {}
+          }
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "debug_trace_snapshot_failed");
+      }
+    }
+  });
+}
+function findLatestStatus(events) {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const status = events[index]?.status;
+    if (typeof status === "number") {
+      return status;
+    }
+  }
+  return void 0;
+}
+function extractHosts(events) {
+  const hosts = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const event of events) {
+    if (typeof event.url !== "string") continue;
+    try {
+      const host = new URL(event.url).hostname.toLowerCase();
+      if (!host || seen.has(host)) continue;
+      seen.add(host);
+      hosts.push(host);
+    } catch {
+    }
+  }
+  return hosts;
+}
+
+// src/tools/cookie_import.ts
+import { tool as tool36 } from "@opencode-ai/plugin";
+var z36 = tool36.schema;
+function validateCookieRecord(cookie) {
+  const name = cookie.name?.trim();
+  if (!name) {
+    return { valid: false, reason: "Cookie name is required.", cookie };
+  }
+  if (!/^[^\s;=]+$/.test(name)) {
+    return { valid: false, reason: `Invalid cookie name: ${cookie.name}.`, cookie };
+  }
+  if (typeof cookie.value !== "string") {
+    return { valid: false, reason: `Invalid cookie value for ${name}.`, cookie };
+  }
+  const value = cookie.value;
+  if (/\r|\n|;/.test(value)) {
+    return { valid: false, reason: `Invalid cookie value for ${name}.`, cookie };
+  }
+  const hasUrl = typeof cookie.url === "string" && cookie.url.trim().length > 0;
+  const hasDomain = typeof cookie.domain === "string" && cookie.domain.trim().length > 0;
+  if (!hasUrl && !hasDomain) {
+    return { valid: false, reason: `Cookie ${name} requires url or domain.`, cookie };
+  }
+  let normalizedUrl;
+  if (hasUrl) {
+    try {
+      const parsedUrl = new URL(cookie.url);
+      if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+        return { valid: false, reason: `Cookie ${name} url must be http(s).`, cookie };
+      }
+      normalizedUrl = parsedUrl.toString();
+    } catch {
+      return { valid: false, reason: `Cookie ${name} has invalid url.`, cookie };
+    }
+  }
+  let normalizedDomain;
+  if (hasDomain) {
+    normalizedDomain = String(cookie.domain).trim().toLowerCase();
+    if (!/^\.?[a-z0-9.-]+$/.test(normalizedDomain)) {
+      return { valid: false, reason: `Cookie ${name} has invalid domain.`, cookie };
+    }
+    if (normalizedDomain.includes("..")) {
+      return { valid: false, reason: `Cookie ${name} has invalid domain.`, cookie };
+    }
+  }
+  const normalizedPath = typeof cookie.path === "string" ? cookie.path.trim() : void 0;
+  if (typeof normalizedPath === "string" && !normalizedPath.startsWith("/")) {
+    return { valid: false, reason: `Cookie ${name} path must start with '/'.`, cookie };
+  }
+  if (typeof cookie.expires !== "undefined") {
+    if (!Number.isFinite(cookie.expires)) {
+      return { valid: false, reason: `Cookie ${name} has invalid expires.`, cookie };
+    }
+    if (cookie.expires < -1) {
+      return { valid: false, reason: `Cookie ${name} has invalid expires.`, cookie };
+    }
+  }
+  if (cookie.sameSite === "None" && cookie.secure !== true) {
+    return { valid: false, reason: `Cookie ${name} with SameSite=None must set secure=true.`, cookie };
+  }
+  const normalizedCookie = {
+    name,
+    value,
+    ...typeof cookie.expires === "number" ? { expires: cookie.expires } : {},
+    ...typeof cookie.httpOnly === "boolean" ? { httpOnly: cookie.httpOnly } : {},
+    ...typeof cookie.secure === "boolean" ? { secure: cookie.secure } : {},
+    ...cookie.sameSite ? { sameSite: cookie.sameSite } : {}
+  };
+  if (normalizedDomain) {
+    normalizedCookie.domain = normalizedDomain;
+    normalizedCookie.path = normalizedPath ?? "/";
+  } else if (normalizedUrl) {
+    normalizedCookie.url = normalizedUrl;
+  }
+  return {
+    valid: true,
+    reason: "",
+    cookie: normalizedCookie
+  };
+}
+function createCookieImportTool(deps) {
+  return tool36({
+    description: "Import validated cookies into the current session context.",
+    args: {
+      sessionId: z36.string().describe("Session id"),
+      cookies: z36.array(z36.object({
+        name: z36.string().min(1),
+        value: z36.string(),
+        url: z36.string().optional(),
+        domain: z36.string().optional(),
+        path: z36.string().optional(),
+        expires: z36.number().optional(),
+        httpOnly: z36.boolean().optional(),
+        secure: z36.boolean().optional(),
+        sameSite: z36.enum(["Strict", "Lax", "None"]).optional()
+      })).min(1).describe("Cookies to import"),
+      strict: z36.boolean().optional().describe("Reject on first invalid cookie (default true)"),
+      requestId: z36.string().optional().describe("Optional trace request id")
+    },
+    async execute(args) {
+      try {
+        const strict = args.strict ?? true;
+        const requestId = args.requestId ?? createRequestId();
+        const manager = deps.manager;
+        const normalized = [];
+        const rejected = [];
+        args.cookies.forEach((cookie, index) => {
+          const validation = validateCookieRecord(cookie);
+          if (!validation.valid) {
+            rejected.push({ index, reason: validation.reason });
+            return;
+          }
+          normalized.push(validation.cookie);
+        });
+        if (typeof manager.cookieImport === "function") {
+          return ok(await manager.cookieImport(args.sessionId, normalized, strict, requestId));
+        }
+        if (strict && rejected.length > 0) {
+          return failure(`Cookie import rejected ${rejected.length} entries.`, "cookie_import_failed");
+        }
+        if (normalized.length > 0) {
+          await deps.manager.withPage(args.sessionId, null, async (page) => {
+            await page.context().addCookies(normalized);
+            return void 0;
+          });
+        }
+        return ok({
+          requestId,
+          imported: normalized.length,
+          rejected
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "cookie_import_failed");
+      }
+    }
+  });
+}
+
+// src/tools/cookie_list.ts
+import { tool as tool37 } from "@opencode-ai/plugin";
+var z37 = tool37.schema;
+function normalizeCookieUrls(urls) {
+  if (!urls || urls.length === 0) {
+    return void 0;
+  }
+  const normalized = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of urls) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+      throw new Error("Cookie list urls must be non-empty strings.");
+    }
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(trimmed);
+    } catch {
+      throw new Error(`Cookie list url is invalid: ${trimmed}`);
+    }
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+      throw new Error(`Cookie list url must be http(s): ${trimmed}`);
+    }
+    const normalizedUrl = parsedUrl.toString();
+    if (seen.has(normalizedUrl)) {
+      continue;
+    }
+    seen.add(normalizedUrl);
+    normalized.push(normalizedUrl);
+  }
+  return normalized;
+}
+function createCookieListTool(deps) {
+  return tool37({
+    description: "List cookies in the current session context with optional URL filtering.",
+    args: {
+      sessionId: z37.string().describe("Session id"),
+      urls: z37.array(z37.string().min(1)).optional().describe("Optional URL filters for cookie scoping"),
+      requestId: z37.string().optional().describe("Optional trace request id")
+    },
+    async execute(args) {
+      try {
+        const manager = deps.manager;
+        const normalizedUrls = normalizeCookieUrls(args.urls);
+        const requestId = args.requestId ?? createRequestId();
+        if (typeof manager.cookieList === "function") {
+          return ok(await manager.cookieList(args.sessionId, normalizedUrls, requestId));
+        }
+        const cookies = await deps.manager.withPage(
+          args.sessionId,
+          null,
+          async (page) => {
+            const listed = normalizedUrls ? await page.context().cookies(normalizedUrls) : await page.context().cookies();
+            return listed.map((cookie) => ({
+              name: cookie.name,
+              value: cookie.value,
+              domain: cookie.domain,
+              path: cookie.path,
+              expires: cookie.expires,
+              httpOnly: cookie.httpOnly,
+              secure: cookie.secure,
+              ...cookie.sameSite ? { sameSite: cookie.sameSite } : {}
+            }));
+          }
+        );
+        return ok({
+          requestId,
+          cookies,
+          count: cookies.length
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "cookie_list_failed");
+      }
+    }
+  });
+}
+
+// src/tools/macro_resolve.ts
+import { tool as tool38 } from "@opencode-ai/plugin";
+var z38 = tool38.schema;
+async function loadMacroRuntime() {
+  try {
+    const module = await import("./macros-NUBRM44Y.js");
+    return module;
+  } catch {
+    return null;
+  }
+}
+function parseFallbackMacro(expression, defaultProvider) {
+  const raw = expression.trim();
+  if (!raw.startsWith("@")) {
+    throw new Error("Macro expressions must start with '@'");
+  }
+  const body = raw.slice(1).trim();
+  if (!body) {
+    throw new Error("Macro name is required");
+  }
+  const openParen = body.indexOf("(");
+  const closeParen = body.endsWith(")") ? body.length - 1 : -1;
+  const macroName = openParen >= 0 ? body.slice(0, openParen).trim() : body;
+  const argsBody = openParen >= 0 && closeParen > openParen ? body.slice(openParen + 1, closeParen).trim() : "";
+  const positional = argsBody ? argsBody.split(",").map((part) => part.trim().replace(/^['\"]|['\"]$/g, "")).filter(Boolean) : [];
+  const query = positional[0] ?? macroName;
+  const provider = defaultProvider ?? "web/default";
+  return {
+    action: {
+      source: "web",
+      operation: "search",
+      input: {
+        query,
+        limit: 10,
+        providerId: provider
+      }
+    },
+    provenance: {
+      macro: macroName,
+      provider,
+      resolvedQuery: query,
+      pack: "fallback",
+      args: {
+        positional,
+        named: {}
+      }
+    }
+  };
+}
+function createMacroResolveTool(deps) {
+  return tool38({
+    description: "Resolve a macro expression to a provider action with provenance metadata.",
+    args: {
+      expression: z38.string().min(2).describe('Macro expression, e.g. @web.search("query")'),
+      defaultProvider: z38.string().optional().describe("Default provider fallback"),
+      includeCatalog: z38.boolean().optional().describe("Include available runtime macro names"),
+      execute: z38.boolean().optional().describe("Execute the resolved provider action and include execution payload")
+    },
+    async execute(args) {
+      try {
+        const runtime = await loadMacroRuntime();
+        const registry = runtime?.createDefaultMacroRegistry?.();
+        let resolvedRuntime = "fallback";
+        let resolution;
+        let catalog;
+        if (registry) {
+          resolvedRuntime = "macros";
+          resolution = await registry.resolve(args.expression, {
+            defaultProvider: args.defaultProvider
+          });
+          catalog = args.includeCatalog ? registry.list().map((entry) => ({
+            name: entry.name,
+            pack: entry.pack,
+            description: entry.description
+          })) : void 0;
+        } else {
+          resolution = parseFallbackMacro(args.expression, args.defaultProvider);
+        }
+        if (!args.execute) {
+          return ok({
+            runtime: resolvedRuntime,
+            resolution,
+            ...catalog ? { catalog } : {}
+          });
+        }
+        const runtimeConfig = deps.config?.get?.();
+        const providerRuntime = deps.providerRuntime ?? createConfiguredProviderRuntime({
+          config: runtimeConfig,
+          manager: deps.manager,
+          browserFallbackPort: deps.browserFallbackPort
+        });
+        const execution = shapeExecutionPayload(
+          await executeMacroResolution(resolution, providerRuntime)
+        );
+        return ok({
+          runtime: resolvedRuntime,
+          resolution,
+          ...catalog ? { catalog } : {},
+          execution
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "macro_resolve_failed");
+      }
+    }
+  });
+}
+
+// src/tools/clone_page.ts
+import { tool as tool39 } from "@opencode-ai/plugin";
+var z39 = tool39.schema;
+function createClonePageTool(deps) {
+  return tool39({
     description: "Export the active page as a React component and CSS bundle.",
     args: {
-      sessionId: z25.string().describe("Active browser session id")
+      sessionId: z39.string().describe("Active browser session id")
     },
     async execute(args) {
       try {
@@ -872,14 +2156,14 @@ function createClonePageTool(deps) {
 }
 
 // src/tools/clone_component.ts
-import { tool as tool26 } from "@opencode-ai/plugin";
-var z26 = tool26.schema;
+import { tool as tool40 } from "@opencode-ai/plugin";
+var z40 = tool40.schema;
 function createCloneComponentTool(deps) {
-  return tool26({
+  return tool40({
     description: "Export a selected element subtree as a React component and CSS bundle.",
     args: {
-      sessionId: z26.string().describe("Active browser session id"),
-      ref: z26.string().describe("Element ref from snapshot")
+      sessionId: z40.string().describe("Active browser session id"),
+      ref: z40.string().describe("Element ref from snapshot")
     },
     async execute(args) {
       try {
@@ -893,13 +2177,13 @@ function createCloneComponentTool(deps) {
 }
 
 // src/tools/perf.ts
-import { tool as tool27 } from "@opencode-ai/plugin";
-var z27 = tool27.schema;
+import { tool as tool41 } from "@opencode-ai/plugin";
+var z41 = tool41.schema;
 function createPerfTool(deps) {
-  return tool27({
+  return tool41({
     description: "Fetch lightweight performance metrics from the active page.",
     args: {
-      sessionId: z27.string().describe("Active browser session id")
+      sessionId: z41.string().describe("Active browser session id")
     },
     async execute(args) {
       try {
@@ -913,14 +2197,14 @@ function createPerfTool(deps) {
 }
 
 // src/tools/screenshot.ts
-import { tool as tool28 } from "@opencode-ai/plugin";
-var z28 = tool28.schema;
+import { tool as tool42 } from "@opencode-ai/plugin";
+var z42 = tool42.schema;
 function createScreenshotTool(deps) {
-  return tool28({
+  return tool42({
     description: "Capture a screenshot of the active page.",
     args: {
-      sessionId: z28.string().describe("Active browser session id"),
-      path: z28.string().optional().describe("Optional output file path")
+      sessionId: z42.string().describe("Active browser session id"),
+      path: z42.string().optional().describe("Optional output file path")
     },
     async execute(args) {
       try {
@@ -933,10 +2217,243 @@ function createScreenshotTool(deps) {
   });
 }
 
+// src/tools/annotate.ts
+import { tool as tool43 } from "@opencode-ai/plugin";
+var z43 = tool43.schema;
+var screenshotModeSchema = z43.enum(["visible", "full", "none"]);
+var transportSchema = z43.enum(["auto", "direct", "relay"]);
+function createAnnotateTool(deps) {
+  return tool43({
+    description: "Request interactive annotations via direct (CDP) or relay transport.",
+    args: {
+      sessionId: z43.string().describe("Session id"),
+      transport: transportSchema.optional().describe("auto | direct | relay (default: auto)"),
+      targetId: z43.string().optional().describe("Optional target id for direct mode"),
+      tabId: z43.number().int().optional().describe("Optional Chrome tab id for relay mode"),
+      url: z43.string().optional().describe("Optional URL to open before annotating"),
+      screenshotMode: screenshotModeSchema.optional().describe("visible | full | none (default: visible)"),
+      debug: z43.boolean().optional().describe("Include debug metadata"),
+      context: z43.string().optional().describe("Optional context for the annotator"),
+      timeoutMs: z43.number().int().optional().describe("Timeout in milliseconds")
+    },
+    async execute(args) {
+      try {
+        const transport = args.transport ?? "auto";
+        if (transport === "relay") {
+          const status = await deps.manager.status(args.sessionId);
+          if (status.mode !== "extension") {
+            return failure("Annotations require extension mode (relay).", "annotate_requires_extension");
+          }
+        }
+        const response = await deps.annotationManager.requestAnnotation({
+          sessionId: args.sessionId,
+          transport,
+          targetId: args.targetId,
+          tabId: args.tabId,
+          url: args.url,
+          screenshotMode: args.screenshotMode ?? "visible",
+          debug: args.debug ?? false,
+          context: args.context,
+          timeoutMs: args.timeoutMs
+        });
+        if (response.status !== "ok" || !response.payload) {
+          const message2 = response.error?.message ?? "Annotation failed.";
+          const code = response.error?.code ?? "annotate_failed";
+          return failure(message2, code);
+        }
+        const { message, details, screenshots } = await buildAnnotateResult(response.payload);
+        return ok({
+          message,
+          details,
+          screenshots
+        });
+      } catch (error) {
+        return failure(serializeError(error).message, "annotate_failed");
+      }
+    }
+  });
+}
+
+// src/tools/research_run.ts
+import { tool as tool44 } from "@opencode-ai/plugin";
+
+// src/tools/workflow-runtime.ts
+var resolveProviderRuntime = (deps) => {
+  if (deps.providerRuntime) {
+    return deps.providerRuntime;
+  }
+  return createConfiguredProviderRuntime({
+    config: deps.config?.get?.(),
+    manager: deps.manager,
+    browserFallbackPort: deps.browserFallbackPort
+  });
+};
+
+// src/tools/research_run.ts
+var z44 = tool44.schema;
+var sourceSelectionSchema = z44.enum(["auto", "web", "community", "social", "shopping", "all"]);
+var sourceSchema = z44.enum(["web", "community", "social", "shopping"]);
+var modeSchema = z44.enum(["compact", "json", "md", "context", "path"]);
+var cookiePolicySchema = z44.enum(["off", "auto", "required"]);
+function createResearchRunTool(deps) {
+  return tool44({
+    description: "Run cross-source research with strict timebox and artifact outputs.",
+    args: {
+      topic: z44.string().min(1).describe("Research topic"),
+      days: z44.number().int().positive().optional().describe("Timebox in days"),
+      from: z44.string().optional().describe("ISO start date"),
+      to: z44.string().optional().describe("ISO end date"),
+      sourceSelection: sourceSelectionSchema.optional().describe("auto|web|community|social|shopping|all"),
+      sources: z44.array(sourceSchema).optional().describe("Explicit source list"),
+      mode: modeSchema.optional().describe("compact|json|md|context|path"),
+      includeEngagement: z44.boolean().optional().describe("Include engagement enrichment"),
+      limitPerSource: z44.number().int().positive().optional().describe("Result limit per source"),
+      outputDir: z44.string().optional().describe("Optional artifact output directory"),
+      ttlHours: z44.number().int().positive().optional().describe("Artifact retention TTL in hours"),
+      useCookies: z44.boolean().optional().describe("Enable/disable provider cookie injection for this run"),
+      cookiePolicyOverride: cookiePolicySchema.optional().describe("Override cookie policy: off|auto|required")
+    },
+    async execute(args) {
+      try {
+        const runtime = resolveProviderRuntime(deps);
+        const result = await runResearchWorkflow(runtime, {
+          topic: args.topic,
+          days: args.days,
+          from: args.from,
+          to: args.to,
+          sourceSelection: args.sourceSelection,
+          sources: args.sources,
+          mode: args.mode ?? "compact",
+          includeEngagement: args.includeEngagement,
+          limitPerSource: args.limitPerSource,
+          outputDir: args.outputDir,
+          ttlHours: args.ttlHours,
+          useCookies: args.useCookies,
+          cookiePolicyOverride: args.cookiePolicyOverride
+        });
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "research_run_failed");
+      }
+    }
+  });
+}
+
+// src/tools/shopping_run.ts
+import { tool as tool45 } from "@opencode-ai/plugin";
+var z45 = tool45.schema;
+var sortSchema = z45.enum(["best_deal", "lowest_price", "highest_rating", "fastest_shipping"]);
+var modeSchema2 = z45.enum(["compact", "json", "md", "context", "path"]);
+var cookiePolicySchema2 = z45.enum(["off", "auto", "required"]);
+function createShoppingRunTool(deps) {
+  return tool45({
+    description: "Run shopping/deal intelligence across shopping providers.",
+    args: {
+      query: z45.string().min(1).describe("Shopping query"),
+      providers: z45.array(z45.string()).optional().describe("Optional provider allow-list"),
+      budget: z45.number().positive().optional().describe("Optional budget amount"),
+      region: z45.string().optional().describe("Region hint"),
+      sort: sortSchema.optional().describe("best_deal|lowest_price|highest_rating|fastest_shipping"),
+      mode: modeSchema2.optional().describe("compact|json|md|context|path"),
+      outputDir: z45.string().optional().describe("Optional artifact output directory"),
+      ttlHours: z45.number().int().positive().optional().describe("Artifact retention TTL in hours"),
+      useCookies: z45.boolean().optional().describe("Enable/disable provider cookie injection for this run"),
+      cookiePolicyOverride: cookiePolicySchema2.optional().describe("Override cookie policy: off|auto|required")
+    },
+    async execute(args) {
+      try {
+        const runtime = resolveProviderRuntime(deps);
+        const result = await runShoppingWorkflow(runtime, {
+          query: args.query,
+          providers: args.providers,
+          budget: args.budget,
+          region: args.region,
+          sort: args.sort,
+          mode: args.mode ?? "compact",
+          outputDir: args.outputDir,
+          ttlHours: args.ttlHours,
+          useCookies: args.useCookies,
+          cookiePolicyOverride: args.cookiePolicyOverride
+        });
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "shopping_run_failed");
+      }
+    }
+  });
+}
+
+// src/tools/product_video_run.ts
+import { tool as tool46 } from "@opencode-ai/plugin";
+var z46 = tool46.schema;
+var cookiePolicySchema3 = z46.enum(["off", "auto", "required"]);
+async function captureScreenshotBuffer(deps, url) {
+  let sessionId = null;
+  try {
+    const launched = await deps.manager.launch({
+      headless: true,
+      startUrl: url
+    });
+    sessionId = launched.sessionId;
+    const screenshot = await deps.manager.screenshot(sessionId);
+    if (typeof screenshot.base64 === "string" && screenshot.base64.length > 0) {
+      return Buffer.from(screenshot.base64, "base64");
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (sessionId) {
+      await deps.manager.disconnect(sessionId, true).catch(() => {
+      });
+    }
+  }
+}
+function createProductVideoRunTool(deps) {
+  return tool46({
+    description: "Collect a product presentation asset pack for video/UGC workflows.",
+    args: {
+      product_url: z46.string().optional().describe("Product URL"),
+      product_name: z46.string().optional().describe("Product name"),
+      provider_hint: z46.string().optional().describe("Optional provider hint"),
+      include_screenshots: z46.boolean().optional().describe("Include screenshots (default true)"),
+      include_all_images: z46.boolean().optional().describe("Include all discovered images (default true)"),
+      include_copy: z46.boolean().optional().describe("Include product copy extraction (default true)"),
+      output_dir: z46.string().optional().describe("Optional output directory"),
+      ttl_hours: z46.number().int().positive().optional().describe("Artifact retention TTL in hours"),
+      useCookies: z46.boolean().optional().describe("Enable/disable provider cookie injection for this run"),
+      cookiePolicyOverride: cookiePolicySchema3.optional().describe("Override cookie policy: off|auto|required")
+    },
+    async execute(args) {
+      try {
+        const runtime = resolveProviderRuntime(deps);
+        const includeScreenshots = args.include_screenshots ?? true;
+        const result = await runProductVideoWorkflow(runtime, {
+          product_url: args.product_url,
+          product_name: args.product_name,
+          provider_hint: args.provider_hint,
+          include_screenshots: includeScreenshots,
+          include_all_images: args.include_all_images,
+          include_copy: args.include_copy,
+          output_dir: args.output_dir,
+          ttl_hours: args.ttl_hours,
+          useCookies: args.useCookies,
+          cookiePolicyOverride: args.cookiePolicyOverride
+        }, {
+          captureScreenshot: includeScreenshots ? async (url) => captureScreenshotBuffer(deps, url) : void 0
+        });
+        return ok(result);
+      } catch (error) {
+        return failure(serializeError(error).message, "product_video_run_failed");
+      }
+    }
+  });
+}
+
 // src/tools/skill_list.ts
-import { tool as tool29 } from "@opencode-ai/plugin";
+import { tool as tool47 } from "@opencode-ai/plugin";
 function createSkillListTool(deps) {
-  return tool29({
+  return tool47({
     description: "List available skills from OpenCode skill directories (compatibility wrapper)",
     args: {},
     async execute() {
@@ -952,14 +2469,14 @@ function createSkillListTool(deps) {
 }
 
 // src/tools/skill_load.ts
-import { tool as tool30 } from "@opencode-ai/plugin";
-var z29 = tool30.schema;
+import { tool as tool48 } from "@opencode-ai/plugin";
+var z47 = tool48.schema;
 function createSkillLoadTool(deps) {
-  return tool30({
+  return tool48({
     description: "Load a specific skill by name from OpenCode skill directories (compatibility wrapper)",
     args: {
-      name: z29.string().describe("Name of the skill to load (e.g., 'login-automation', 'form-testing')"),
-      topic: z29.string().optional().describe("Optional topic to filter the skill content")
+      name: z47.string().describe("Name of the skill to load (e.g., 'opendevbrowser-login-automation', 'opendevbrowser-form-testing')"),
+      topic: z47.string().optional().describe("Optional topic to filter the skill content")
     },
     async execute(args) {
       try {
@@ -975,44 +2492,83 @@ function createSkillLoadTool(deps) {
 
 // src/tools/index.ts
 function createTools(deps) {
+  const wrap = (definition) => {
+    if (!deps.ensureHub) return definition;
+    return {
+      ...definition,
+      execute: async (args, context) => {
+        try {
+          await deps.ensureHub?.();
+        } catch {
+        }
+        return definition.execute(args, context);
+      }
+    };
+  };
   return {
-    opendevbrowser_launch: createLaunchTool(deps),
-    opendevbrowser_connect: createConnectTool(deps),
-    opendevbrowser_disconnect: createDisconnectTool(deps),
-    opendevbrowser_status: createStatusTool(deps),
-    opendevbrowser_targets_list: createTargetsListTool(deps),
-    opendevbrowser_target_use: createTargetUseTool(deps),
-    opendevbrowser_target_new: createTargetNewTool(deps),
-    opendevbrowser_target_close: createTargetCloseTool(deps),
-    opendevbrowser_page: createPageTool(deps),
-    opendevbrowser_list: createListTool(deps),
-    opendevbrowser_close: createCloseTool(deps),
-    opendevbrowser_goto: createGotoTool(deps),
-    opendevbrowser_wait: createWaitTool(deps),
-    opendevbrowser_snapshot: createSnapshotTool(deps),
-    opendevbrowser_click: createClickTool(deps),
-    opendevbrowser_type: createTypeTool(deps),
-    opendevbrowser_select: createSelectTool(deps),
-    opendevbrowser_scroll: createScrollTool(deps),
-    opendevbrowser_dom_get_html: createDomGetHtmlTool(deps),
-    opendevbrowser_dom_get_text: createDomGetTextTool(deps),
-    opendevbrowser_run: createRunTool(deps),
-    opendevbrowser_prompting_guide: createPromptingGuideTool(deps),
-    opendevbrowser_console_poll: createConsolePollTool(deps),
-    opendevbrowser_network_poll: createNetworkPollTool(deps),
-    opendevbrowser_clone_page: createClonePageTool(deps),
-    opendevbrowser_clone_component: createCloneComponentTool(deps),
-    opendevbrowser_perf: createPerfTool(deps),
-    opendevbrowser_screenshot: createScreenshotTool(deps),
-    opendevbrowser_skill_list: createSkillListTool(deps),
-    opendevbrowser_skill_load: createSkillLoadTool(deps)
+    opendevbrowser_launch: wrap(createLaunchTool(deps)),
+    opendevbrowser_connect: wrap(createConnectTool(deps)),
+    opendevbrowser_disconnect: wrap(createDisconnectTool(deps)),
+    opendevbrowser_status: wrap(createStatusTool(deps)),
+    opendevbrowser_targets_list: wrap(createTargetsListTool(deps)),
+    opendevbrowser_target_use: wrap(createTargetUseTool(deps)),
+    opendevbrowser_target_new: wrap(createTargetNewTool(deps)),
+    opendevbrowser_target_close: wrap(createTargetCloseTool(deps)),
+    opendevbrowser_page: wrap(createPageTool(deps)),
+    opendevbrowser_list: wrap(createListTool(deps)),
+    opendevbrowser_close: wrap(createCloseTool(deps)),
+    opendevbrowser_goto: wrap(createGotoTool(deps)),
+    opendevbrowser_wait: wrap(createWaitTool(deps)),
+    opendevbrowser_snapshot: wrap(createSnapshotTool(deps)),
+    opendevbrowser_click: wrap(createClickTool(deps)),
+    opendevbrowser_hover: wrap(createHoverTool(deps)),
+    opendevbrowser_press: wrap(createPressTool(deps)),
+    opendevbrowser_check: wrap(createCheckTool(deps)),
+    opendevbrowser_uncheck: wrap(createUncheckTool(deps)),
+    opendevbrowser_type: wrap(createTypeTool(deps)),
+    opendevbrowser_select: wrap(createSelectTool(deps)),
+    opendevbrowser_scroll: wrap(createScrollTool(deps)),
+    opendevbrowser_scroll_into_view: wrap(createScrollIntoViewTool(deps)),
+    opendevbrowser_dom_get_html: wrap(createDomGetHtmlTool(deps)),
+    opendevbrowser_dom_get_text: wrap(createDomGetTextTool(deps)),
+    opendevbrowser_get_attr: wrap(createGetAttrTool(deps)),
+    opendevbrowser_get_value: wrap(createGetValueTool(deps)),
+    opendevbrowser_is_visible: wrap(createIsVisibleTool(deps)),
+    opendevbrowser_is_enabled: wrap(createIsEnabledTool(deps)),
+    opendevbrowser_is_checked: wrap(createIsCheckedTool(deps)),
+    opendevbrowser_run: wrap(createRunTool(deps)),
+    opendevbrowser_prompting_guide: wrap(createPromptingGuideTool(deps)),
+    opendevbrowser_console_poll: wrap(createConsolePollTool(deps)),
+    opendevbrowser_network_poll: wrap(createNetworkPollTool(deps)),
+    opendevbrowser_debug_trace_snapshot: wrap(createDebugTraceSnapshotTool(deps)),
+    opendevbrowser_cookie_import: wrap(createCookieImportTool(deps)),
+    opendevbrowser_cookie_list: wrap(createCookieListTool(deps)),
+    opendevbrowser_macro_resolve: wrap(createMacroResolveTool(deps)),
+    opendevbrowser_research_run: wrap(createResearchRunTool(deps)),
+    opendevbrowser_shopping_run: wrap(createShoppingRunTool(deps)),
+    opendevbrowser_product_video_run: wrap(createProductVideoRunTool(deps)),
+    opendevbrowser_clone_page: wrap(createClonePageTool(deps)),
+    opendevbrowser_clone_component: wrap(createCloneComponentTool(deps)),
+    opendevbrowser_perf: wrap(createPerfTool(deps)),
+    opendevbrowser_screenshot: wrap(createScreenshotTool(deps)),
+    opendevbrowser_annotate: wrap(createAnnotateTool(deps)),
+    opendevbrowser_skill_list: wrap(createSkillListTool(deps)),
+    opendevbrowser_skill_load: wrap(createSkillLoadTool(deps))
   };
 }
 
 // src/index.ts
 var OpenDevBrowserPlugin = async ({ directory, worktree }) => {
   const core = createOpenDevBrowserCore({ directory, worktree });
-  const { config, configStore, manager, runner, skills, relay, ensureRelay, cleanup, getExtensionPath } = core;
+  const { config, configStore, skills, ensureRelay, cleanup, getExtensionPath } = core;
+  let relay = core.relay;
+  let manager = core.manager;
+  let runner = core.runner;
+  let annotationManager = core.annotationManager;
+  let providerRuntime = core.providerRuntime;
+  let browserFallbackPort = core.browserFallbackPort;
+  let hubStop = null;
+  let daemonClient = null;
   const skillNudgeState = createSkillNudgeState();
   const continuityNudgeState = createContinuityNudgeState();
   console.info(
@@ -1023,12 +2579,99 @@ var OpenDevBrowserPlugin = async ({ directory, worktree }) => {
   } catch (error) {
     console.warn("Extension extraction failed:", error instanceof Error ? error.message : error);
   }
-  process.on("SIGINT", cleanup);
-  process.on("SIGTERM", cleanup);
-  process.on("beforeExit", cleanup);
-  await ensureRelay(config.relayPort);
+  const toolDeps = {
+    manager,
+    annotationManager,
+    runner,
+    config: configStore,
+    skills,
+    providerRuntime,
+    browserFallbackPort,
+    relay,
+    getExtensionPath
+  };
+  const bindRemote = () => {
+    if (!daemonClient) {
+      daemonClient = new DaemonClient({ autoRenew: true });
+    }
+    manager = new RemoteManager(daemonClient);
+    relay = new RemoteRelay(daemonClient);
+    annotationManager.setRelay(relay);
+    annotationManager.setBrowserManager(manager);
+    runner = new ScriptRunner(manager);
+    browserFallbackPort = createBrowserFallbackPort(manager);
+    providerRuntime = createConfiguredProviderRuntime({
+      config: configStore.get(),
+      manager,
+      browserFallbackPort
+    });
+    toolDeps.manager = manager;
+    toolDeps.relay = relay;
+    toolDeps.runner = runner;
+    toolDeps.providerRuntime = providerRuntime;
+    toolDeps.browserFallbackPort = browserFallbackPort;
+  };
+  const ensureHub = async () => {
+    const currentConfig = configStore.get();
+    if (!isHubEnabled(currentConfig)) {
+      return;
+    }
+    if (!daemonClient) {
+      daemonClient = new DaemonClient({ autoRenew: true });
+    }
+    const deadline = Date.now() + 2e3;
+    let attempt = 0;
+    let lastError = null;
+    while (attempt < 2 && Date.now() < deadline) {
+      attempt += 1;
+      const status = await fetchDaemonStatusFromMetadata(currentConfig);
+      if (status?.ok) {
+        bindRemote();
+        await relay?.refresh?.();
+        return;
+      }
+      try {
+        const { stop } = await startDaemon({ config: currentConfig, directory, worktree });
+        hubStop = stop;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+      }
+      if (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+    }
+    if (lastError) {
+      throw lastError;
+    }
+    throw new Error("Hub daemon unavailable.");
+  };
+  toolDeps.ensureHub = ensureHub;
+  const hubEnabled = isHubEnabled(config);
+  if (hubEnabled) {
+    bindRemote();
+    try {
+      await ensureHub();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[opendevbrowser] Hub daemon unavailable: ${message}`);
+    }
+  } else {
+    await ensureRelay(config.relayPort);
+  }
+  const cleanupAll = () => {
+    if (hubStop) {
+      hubStop().catch(() => {
+      });
+    }
+    daemonClient?.releaseBinding().catch(() => {
+    });
+    cleanup();
+  };
+  process.on("SIGINT", cleanupAll);
+  process.on("SIGTERM", cleanupAll);
+  process.on("beforeExit", cleanupAll);
   return {
-    tool: createTools({ manager, runner, config: configStore, skills, relay, getExtensionPath }),
+    tool: createTools(toolDeps),
     "chat.message": async (_input, output) => {
       const config2 = configStore.get();
       if (output.message.role !== "user") return;