@btraut/browser-bridge 0.11.1 → 0.12.0

package/dist/index.js

@@ -26,55 +26,8 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // packages/cli/src/index.ts
 var import_commander = require("commander");
 
-// packages/shared/src/errors.ts
-var import_zod = require("zod");
-var ErrorCodeSchema = import_zod.z.enum([
-  "UNKNOWN",
-  "INVALID_ARGUMENT",
-  "NOT_FOUND",
-  "ALREADY_EXISTS",
-  "FAILED_PRECONDITION",
-  "UNAUTHORIZED",
-  "FORBIDDEN",
-  "PERMISSION_REQUIRED",
-  "PERMISSION_DENIED",
-  "PERMISSION_PROMPT_TIMEOUT",
-  "CONFLICT",
-  "TIMEOUT",
-  "CANCELLED",
-  "UNAVAILABLE",
-  "RATE_LIMITED",
-  "NOT_IMPLEMENTED",
-  "INTERNAL",
-  "SESSION_NOT_FOUND",
-  "SESSION_CLOSED",
-  "SESSION_BROKEN",
-  "DRIVE_UNAVAILABLE",
-  "INSPECT_UNAVAILABLE",
-  "EXTENSION_DISCONNECTED",
-  "DEBUGGER_IN_USE",
-  "ATTACH_DENIED",
-  "TAB_NOT_FOUND",
-  "NOT_SUPPORTED",
-  "LOCATOR_NOT_FOUND",
-  "NAVIGATION_FAILED",
-  "EVALUATION_FAILED",
-  "ARTIFACT_IO_ERROR"
-]);
-var ErrorInfoSchema = import_zod.z.object({
-  code: ErrorCodeSchema,
-  message: import_zod.z.string(),
-  retryable: import_zod.z.boolean(),
-  details: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
-});
-var ErrorEnvelopeSchema = import_zod.z.object({
-  ok: import_zod.z.literal(false),
-  error: ErrorInfoSchema
-});
-var successEnvelopeSchema = (result) => import_zod.z.object({
-  ok: import_zod.z.literal(true),
-  result
-});
+// packages/shared/src/core-readiness.ts
+var import_promises = require("node:timers/promises");
 
 // packages/shared/src/logging.ts
 var import_node_fs2 = require("node:fs");
@@ -605,6 +558,248 @@ var createJsonlLogger = (options) => {
   return buildLogger(state, options.bindings ?? {});
 };
 
+// packages/shared/src/core-readiness.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_HEALTH_RETRY_MS = 250;
+var DEFAULT_HEALTH_ATTEMPTS = 20;
+var DEFAULT_HEALTH_TIMEOUT_MS = 2e3;
+var DEFAULT_HEALTH_BUDGET_MS = 15e3;
+var resolveTimeoutMs = (timeoutMs) => {
+  const candidate = timeoutMs ?? (process.env.BROWSER_BRIDGE_CORE_TIMEOUT_MS ? Number.parseInt(process.env.BROWSER_BRIDGE_CORE_TIMEOUT_MS, 10) : process.env.BROWSER_VISION_CORE_TIMEOUT_MS ? Number.parseInt(process.env.BROWSER_VISION_CORE_TIMEOUT_MS, 10) : void 0);
+  if (candidate === void 0 || candidate === null) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  const parsed = typeof candidate === "number" ? candidate : Number(candidate);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid timeoutMs: ${String(candidate)}`);
+  }
+  return Math.floor(parsed);
+};
+var resolvePositiveInteger = (value, fallback) => {
+  if (value === void 0) {
+    return fallback;
+  }
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`Invalid positive integer value: ${String(value)}`);
+  }
+  return Math.floor(value);
+};
+var hasExplicitRuntimeInput = (options) => options.host !== void 0 || options.port !== void 0 || process.env.BROWSER_BRIDGE_CORE_HOST !== void 0 || process.env.BROWSER_VISION_CORE_HOST !== void 0 || process.env.BROWSER_BRIDGE_CORE_PORT !== void 0 || process.env.BROWSER_VISION_CORE_PORT !== void 0;
+var createCoreReadinessController = (options = {}) => {
+  const logger = options.logger ?? createJsonlLogger({
+    stream: "cli",
+    cwd: options.cwd
+  }).child({ scope: "core-readiness" });
+  const logPrefix = options.logPrefix ?? "core";
+  const timeoutMs = resolveTimeoutMs(options.timeoutMs);
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const ensureDaemon = options.ensureDaemon ?? true;
+  const healthRetryMs = resolvePositiveInteger(
+    options.healthRetryMs,
+    DEFAULT_HEALTH_RETRY_MS
+  );
+  const healthAttempts = resolvePositiveInteger(
+    options.healthAttempts,
+    DEFAULT_HEALTH_ATTEMPTS
+  );
+  const healthTimeoutMs = resolvePositiveInteger(
+    options.healthTimeoutMs,
+    Math.min(timeoutMs, DEFAULT_HEALTH_TIMEOUT_MS)
+  );
+  const healthBudgetMs = resolvePositiveInteger(
+    options.healthBudgetMs,
+    DEFAULT_HEALTH_BUDGET_MS
+  );
+  let runtime = resolveCoreRuntime({
+    host: options.host,
+    port: options.port,
+    cwd: options.cwd,
+    strictEnvPort: options.strictEnvPort ?? true
+  });
+  let baseUrl = `http://${runtime.host}:${runtime.port}`;
+  const allowRuntimeRefresh = !hasExplicitRuntimeInput(options);
+  const refreshRuntime = () => {
+    if (!allowRuntimeRefresh) {
+      return;
+    }
+    runtime = resolveCoreRuntime({
+      cwd: options.cwd,
+      strictEnvPort: options.strictEnvPort ?? true
+    });
+    baseUrl = `http://${runtime.host}:${runtime.port}`;
+  };
+  const checkHealth = async () => {
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), healthTimeoutMs);
+      try {
+        let response;
+        try {
+          response = await fetchImpl(`${baseUrl}/health`, {
+            method: "GET",
+            signal: controller.signal
+          });
+        } catch (error) {
+          if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
+            logger.warn(`${logPrefix}.health.timeout`, {
+              base_url: baseUrl,
+              timeout_ms: healthTimeoutMs
+            });
+            return false;
+          }
+          logger.warn(`${logPrefix}.health.fetch_failed`, {
+            base_url: baseUrl,
+            error
+          });
+          throw error;
+        }
+        if (!response.ok) {
+          logger.warn(`${logPrefix}.health.non_ok`, {
+            base_url: baseUrl,
+            status: response.status
+          });
+          return false;
+        }
+        const data = await response.json().catch(() => null);
+        const ok = Boolean(data?.ok);
+        if (!ok) {
+          logger.warn(`${logPrefix}.health.not_ready`, {
+            base_url: baseUrl
+          });
+        }
+        return ok;
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch (error) {
+      logger.warn(`${logPrefix}.health.error`, {
+        base_url: baseUrl,
+        error
+      });
+      return false;
+    }
+  };
+  const ensureCoreRunning = async () => {
+    refreshRuntime();
+    if (await checkHealth()) {
+      logger.debug(`${logPrefix}.ensure_ready.already_running`, {
+        base_url: baseUrl
+      });
+      return;
+    }
+    if (!options.spawnDaemon) {
+      logger.error(`${logPrefix}.ensure_ready.missing_spawn`, {
+        host: runtime.host,
+        port: runtime.port
+      });
+      throw new Error(
+        `Core daemon is not running on ${runtime.host}:${runtime.port} and spawnDaemon is not configured.`
+      );
+    }
+    options.spawnDaemon(runtime);
+    const deadlineAt = Date.now() + healthBudgetMs;
+    for (let attempt = 0; attempt < healthAttempts; attempt += 1) {
+      const remainingBudgetMs = deadlineAt - Date.now();
+      if (remainingBudgetMs <= 0) {
+        break;
+      }
+      await (0, import_promises.setTimeout)(Math.min(healthRetryMs, remainingBudgetMs));
+      refreshRuntime();
+      if (await checkHealth()) {
+        logger.info(`${logPrefix}.ensure_ready.ready`, {
+          base_url: baseUrl,
+          attempts: attempt + 1
+        });
+        return;
+      }
+    }
+    logger.error(`${logPrefix}.ensure_ready.failed`, {
+      host: runtime.host,
+      port: runtime.port,
+      attempts: healthAttempts,
+      health_budget_ms: healthBudgetMs,
+      health_timeout_ms: healthTimeoutMs
+    });
+    throw new Error(
+      `Core daemon failed to start on ${runtime.host}:${runtime.port}.`
+    );
+  };
+  let ensurePromise = null;
+  const ensureReady = async () => {
+    if (!ensureDaemon) {
+      return;
+    }
+    if (!ensurePromise) {
+      ensurePromise = ensureCoreRunning().catch((error) => {
+        ensurePromise = null;
+        throw error;
+      });
+    }
+    await ensurePromise;
+  };
+  return {
+    get baseUrl() {
+      return baseUrl;
+    },
+    get runtime() {
+      return runtime;
+    },
+    refreshRuntime,
+    ensureReady,
+    checkHealth
+  };
+};
+
+// packages/shared/src/errors.ts
+var import_zod = require("zod");
+var ErrorCodeSchema = import_zod.z.enum([
+  "UNKNOWN",
+  "INVALID_ARGUMENT",
+  "NOT_FOUND",
+  "ALREADY_EXISTS",
+  "FAILED_PRECONDITION",
+  "UNAUTHORIZED",
+  "FORBIDDEN",
+  "PERMISSION_REQUIRED",
+  "PERMISSION_DENIED",
+  "PERMISSION_PROMPT_TIMEOUT",
+  "CONFLICT",
+  "TIMEOUT",
+  "CANCELLED",
+  "UNAVAILABLE",
+  "RATE_LIMITED",
+  "NOT_IMPLEMENTED",
+  "INTERNAL",
+  "SESSION_NOT_FOUND",
+  "SESSION_CLOSED",
+  "SESSION_BROKEN",
+  "DRIVE_UNAVAILABLE",
+  "INSPECT_UNAVAILABLE",
+  "EXTENSION_DISCONNECTED",
+  "DEBUGGER_IN_USE",
+  "ATTACH_DENIED",
+  "TAB_NOT_FOUND",
+  "NOT_SUPPORTED",
+  "LOCATOR_NOT_FOUND",
+  "NAVIGATION_FAILED",
+  "EVALUATION_FAILED",
+  "ARTIFACT_IO_ERROR"
+]);
+var ErrorInfoSchema = import_zod.z.object({
+  code: ErrorCodeSchema,
+  message: import_zod.z.string(),
+  retryable: import_zod.z.boolean(),
+  details: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()).optional()
+});
+var ErrorEnvelopeSchema = import_zod.z.object({
+  ok: import_zod.z.literal(false),
+  error: ErrorInfoSchema
+});
+var successEnvelopeSchema = (result) => import_zod.z.object({
+  ok: import_zod.z.literal(true),
+  result
+});
+
 // packages/shared/src/schemas.ts
 var import_zod2 = require("zod");
 var LocatorRoleSchema = import_zod2.z.object({
@@ -669,6 +864,39 @@ var DiagnosticCheckSchema = import_zod2.z.object({
   message: import_zod2.z.string().optional(),
   details: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.unknown()).optional()
 });
+var DiagnosticsRuntimeEndpointSchema = import_zod2.z.object({
+  host: import_zod2.z.string().optional(),
+  port: import_zod2.z.number().finite().optional(),
+  base_url: import_zod2.z.string().optional(),
+  host_source: import_zod2.z.string().optional(),
+  port_source: import_zod2.z.string().optional(),
+  metadata_path: import_zod2.z.string().optional(),
+  isolated_mode: import_zod2.z.boolean().optional()
+});
+var DiagnosticsRuntimeProcessSchema = import_zod2.z.object({
+  component: import_zod2.z.enum(["cli", "mcp", "core"]).optional(),
+  version: import_zod2.z.string().optional(),
+  pid: import_zod2.z.number().int().positive().optional(),
+  node_version: import_zod2.z.string().optional(),
+  binary_path: import_zod2.z.string().optional(),
+  argv_entry: import_zod2.z.string().optional()
+});
+var DiagnosticsRuntimeCallerSchema = import_zod2.z.object({
+  endpoint: DiagnosticsRuntimeEndpointSchema.optional(),
+  process: DiagnosticsRuntimeProcessSchema.optional()
+});
+var DiagnosticsRuntimeContextSchema = import_zod2.z.object({
+  caller: DiagnosticsRuntimeCallerSchema.optional(),
+  core: import_zod2.z.object({
+    endpoint: DiagnosticsRuntimeEndpointSchema.optional(),
+    process: DiagnosticsRuntimeProcessSchema.optional()
+  }).optional(),
+  extension: import_zod2.z.object({
+    version: import_zod2.z.string().optional(),
+    endpoint: DiagnosticsRuntimeEndpointSchema.optional(),
+    port_source: import_zod2.z.enum(["default", "storage"]).optional()
+  }).optional()
+});
 var DiagnosticReportSchema = import_zod2.z.object({
   ok: import_zod2.z.boolean(),
   session_id: import_zod2.z.string().optional(),
@@ -717,7 +945,8 @@ var DiagnosticReportSchema = import_zod2.z.object({
     loop_detected: import_zod2.z.boolean().optional()
   }).optional(),
   warnings: import_zod2.z.array(import_zod2.z.string()).optional(),
-  notes: import_zod2.z.array(import_zod2.z.string()).optional()
+  notes: import_zod2.z.array(import_zod2.z.string()).optional(),
+  runtime: DiagnosticsRuntimeContextSchema.optional()
 });
 var SessionIdSchema = import_zod2.z.object({
   session_id: import_zod2.z.string().min(1)
@@ -1109,7 +1338,8 @@ var HealthCheckOutputSchema = import_zod2.z.object({
   }).passthrough()
 }).passthrough();
 var DiagnosticsDoctorInputSchema = import_zod2.z.object({
-  session_id: import_zod2.z.string().min(1).optional()
+  session_id: import_zod2.z.string().min(1).optional(),
+  caller: DiagnosticsRuntimeCallerSchema.optional()
 });
 var DiagnosticsDoctorOutputSchema = DiagnosticReportSchema;
 
@@ -1119,7 +1349,6 @@ var import_zod3 = require("zod");
 // packages/cli/src/core-client.ts
 var import_node_child_process = require("node:child_process");
 var import_node_path3 = require("node:path");
-var import_promises = require("node:timers/promises");
 var CoreClientError = class extends Error {
   constructor(info) {
     super(info.message);
@@ -1127,13 +1356,11 @@ var CoreClientError = class extends Error {
     this.info = info;
   }
 };
-var DEFAULT_TIMEOUT_MS = 3e4;
-var HEALTH_RETRY_MS = 250;
-var HEALTH_ATTEMPTS = 20;
-var resolveTimeoutMs = (timeoutMs) => {
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var resolveTimeoutMs2 = (timeoutMs) => {
   const candidate = timeoutMs ?? (process.env.BROWSER_BRIDGE_CORE_TIMEOUT_MS ? Number.parseInt(process.env.BROWSER_BRIDGE_CORE_TIMEOUT_MS, 10) : process.env.BROWSER_VISION_CORE_TIMEOUT_MS ? Number.parseInt(process.env.BROWSER_VISION_CORE_TIMEOUT_MS, 10) : void 0);
   if (candidate === void 0 || candidate === null) {
-    return DEFAULT_TIMEOUT_MS;
+    return DEFAULT_TIMEOUT_MS2;
   }
   const parsed = typeof candidate === "number" ? candidate : Number(candidate);
   if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -1148,42 +1375,70 @@ var createCoreClient = (options = {}) => {
     stream: "cli",
     cwd: options.cwd
   }).child({ scope: "core-client" });
-  let runtime = resolveCoreRuntime({
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const spawnImpl = options.spawnImpl ?? import_node_child_process.spawn;
+  const timeoutMs = resolveTimeoutMs2(options.timeoutMs);
+  const readiness = createCoreReadinessController({
     host: options.host,
     port: options.port,
     cwd: options.cwd,
-    strictEnvPort: true
-  });
-  let baseUrl = `http://${runtime.host}:${runtime.port}`;
-  const timeoutMs = resolveTimeoutMs(options.timeoutMs);
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const spawnImpl = options.spawnImpl ?? import_node_child_process.spawn;
-  const ensureDaemon = options.ensureDaemon ?? true;
-  const allowRuntimeRefresh = options.host === void 0 && options.port === void 0 && process.env.BROWSER_BRIDGE_CORE_HOST === void 0 && process.env.BROWSER_VISION_CORE_HOST === void 0 && process.env.BROWSER_BRIDGE_CORE_PORT === void 0 && process.env.BROWSER_VISION_CORE_PORT === void 0;
-  const refreshRuntime = () => {
-    if (!allowRuntimeRefresh) {
-      return;
+    timeoutMs,
+    ensureDaemon: options.ensureDaemon ?? true,
+    strictEnvPort: true,
+    fetchImpl,
+    logger,
+    logPrefix: "cli.core",
+    spawnDaemon: (runtime) => {
+      const coreEntry = (0, import_node_path3.resolve)(__dirname, "api.js");
+      const startOptions = [];
+      if (runtime.hostSource === "option" || runtime.hostSource === "env") {
+        startOptions.push(`host: ${JSON.stringify(runtime.host)}`);
+      }
+      if (runtime.portSource === "option" || runtime.portSource === "env") {
+        startOptions.push(`port: ${runtime.port}`);
+      }
+      const script = `const { startCoreServer } = require(${JSON.stringify(
+        coreEntry
+      )});
+startCoreServer({ ${startOptions.join(
+        ", "
+      )} })
+  .catch((err) => { console.error(err); process.exit(1); });`;
+      logger.info("cli.core.spawn.start", {
+        host: runtime.host,
+        port: runtime.port,
+        host_source: runtime.hostSource,
+        port_source: runtime.portSource
+      });
+      const child = spawnImpl(process.execPath, ["-e", script], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env }
+      });
+      child.on("error", (error) => {
+        logger.error("cli.core.spawn.error", {
+          host: runtime.host,
+          port: runtime.port,
+          error
+        });
+      });
+      child.unref();
     }
-    runtime = resolveCoreRuntime({
-      cwd: options.cwd,
-      strictEnvPort: true
-    });
-    baseUrl = `http://${runtime.host}:${runtime.port}`;
-  };
+  });
   const requestJson = async (method, path9, body) => {
     const requestPath = normalizePath(path9);
     const startedAt = process.hrtime.bigint();
     logger.debug("cli.core.request.start", {
       method,
       path: requestPath,
-      base_url: baseUrl
+      base_url: readiness.baseUrl
     });
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
       let response;
       try {
-        response = await fetchImpl(`${baseUrl}${requestPath}`, {
+        response = await fetchImpl(`${readiness.baseUrl}${requestPath}`, {
           method,
           headers: {
             "content-type": "application/json"
@@ -1196,203 +1451,77 @@ var createCoreClient = (options = {}) => {
           logger.warn("cli.core.request.timeout", {
             method,
             path: requestPath,
-            base_url: baseUrl,
+            base_url: readiness.baseUrl,
             timeout_ms: timeoutMs,
-            duration_ms: durationMs(startedAt)
-          });
-          throw new CoreClientError({
-            code: "TIMEOUT",
-            message: `Core request timed out after ${timeoutMs}ms.`,
-            retryable: true,
-            details: {
-              timeout_ms: timeoutMs,
-              base_url: baseUrl,
-              path: requestPath
-            }
-          });
-        }
-        logger.error("cli.core.request.failed", {
-          method,
-          path: requestPath,
-          base_url: baseUrl,
-          duration_ms: durationMs(startedAt),
-          error
-        });
-        throw error;
-      }
-      const raw = await response.text();
-      if (!raw) {
-        logger.warn("cli.core.request.empty_response", {
-          method,
-          path: requestPath,
-          base_url: baseUrl,
-          status: response.status,
-          duration_ms: durationMs(startedAt)
-        });
-        throw new Error(`Empty response from Core (${response.status}).`);
-      }
-      try {
-        const parsed = JSON.parse(raw);
-        logger.debug("cli.core.request.end", {
-          method,
-          path: requestPath,
-          base_url: baseUrl,
-          status: response.status,
-          duration_ms: durationMs(startedAt)
-        });
-        return parsed;
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown JSON parse error";
-        logger.error("cli.core.request.invalid_json", {
-          method,
-          path: requestPath,
-          base_url: baseUrl,
-          status: response.status,
-          duration_ms: durationMs(startedAt),
-          error
-        });
-        throw new Error(`Failed to parse Core response: ${message}`);
-      }
-    } finally {
-      clearTimeout(timeout);
-    }
-  };
-  const checkHealth = async () => {
-    try {
-      const controller = new AbortController();
-      const timeout = setTimeout(() => controller.abort(), timeoutMs);
-      try {
-        let response;
-        try {
-          response = await fetchImpl(`${baseUrl}/health`, {
-            method: "GET",
-            signal: controller.signal
-          });
-        } catch (error) {
-          if (controller.signal.aborted || error instanceof Error && error.name === "AbortError") {
-            logger.warn("cli.core.health.timeout", {
-              base_url: baseUrl,
-              timeout_ms: timeoutMs
-            });
-            return false;
-          }
-          logger.warn("cli.core.health.fetch_failed", {
-            base_url: baseUrl,
-            error
-          });
-          throw error;
-        }
-        if (!response.ok) {
-          logger.warn("cli.core.health.non_ok", {
-            base_url: baseUrl,
-            status: response.status
-          });
-          return false;
-        }
-        const data = await response.json().catch(() => null);
-        const ok = Boolean(data?.ok);
-        if (!ok) {
-          logger.warn("cli.core.health.not_ready", {
-            base_url: baseUrl
-          });
-        }
-        return ok;
-      } finally {
-        clearTimeout(timeout);
-      }
-    } catch (error) {
-      logger.warn("cli.core.health.error", {
-        base_url: baseUrl,
-        error
-      });
-      return false;
-    }
-  };
-  const spawnDaemon = () => {
-    const coreEntry = (0, import_node_path3.resolve)(__dirname, "api.js");
-    const startOptions = [];
-    if (runtime.hostSource === "option" || runtime.hostSource === "env") {
-      startOptions.push(`host: ${JSON.stringify(runtime.host)}`);
-    }
-    if (runtime.portSource === "option" || runtime.portSource === "env") {
-      startOptions.push(`port: ${runtime.port}`);
-    }
-    const script = `const { startCoreServer } = require(${JSON.stringify(
-      coreEntry
-    )});
-startCoreServer({ ${startOptions.join(
-      ", "
-    )} })
-  .catch((err) => { console.error(err); process.exit(1); });`;
-    logger.info("cli.core.spawn.start", {
-      host: runtime.host,
-      port: runtime.port,
-      host_source: runtime.hostSource,
-      port_source: runtime.portSource
-    });
-    const child = spawnImpl(process.execPath, ["-e", script], {
-      detached: true,
-      stdio: "ignore",
-      env: { ...process.env }
-    });
-    child.on("error", (error) => {
-      logger.error("cli.core.spawn.error", {
-        host: runtime.host,
-        port: runtime.port,
-        error
-      });
-    });
-    child.unref();
-  };
-  const ensureCoreRunning = async () => {
-    refreshRuntime();
-    if (await checkHealth()) {
-      logger.debug("cli.core.ensure_ready.already_running", {
-        base_url: baseUrl
-      });
-      return;
-    }
-    spawnDaemon();
-    for (let attempt = 0; attempt < HEALTH_ATTEMPTS; attempt += 1) {
-      await (0, import_promises.setTimeout)(HEALTH_RETRY_MS);
-      refreshRuntime();
-      if (await checkHealth()) {
-        logger.info("cli.core.ensure_ready.ready", {
-          base_url: baseUrl,
-          attempts: attempt + 1
+            duration_ms: durationMs(startedAt)
+          });
+          throw new CoreClientError({
+            code: "TIMEOUT",
+            message: `Core request timed out after ${timeoutMs}ms.`,
+            retryable: true,
+            details: {
+              timeout_ms: timeoutMs,
+              base_url: readiness.baseUrl,
+              path: requestPath
+            }
+          });
+        }
+        logger.error("cli.core.request.failed", {
+          method,
+          path: requestPath,
+          base_url: readiness.baseUrl,
+          duration_ms: durationMs(startedAt),
+          error
         });
-        return;
+        throw error;
       }
+      const raw = await response.text();
+      if (!raw) {
+        logger.warn("cli.core.request.empty_response", {
+          method,
+          path: requestPath,
+          base_url: readiness.baseUrl,
+          status: response.status,
+          duration_ms: durationMs(startedAt)
+        });
+        throw new Error(`Empty response from Core (${response.status}).`);
+      }
+      try {
+        const parsed = JSON.parse(raw);
+        logger.debug("cli.core.request.end", {
+          method,
+          path: requestPath,
+          base_url: readiness.baseUrl,
+          status: response.status,
+          duration_ms: durationMs(startedAt)
+        });
+        return parsed;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown JSON parse error";
+        logger.error("cli.core.request.invalid_json", {
+          method,
+          path: requestPath,
+          base_url: readiness.baseUrl,
+          status: response.status,
+          duration_ms: durationMs(startedAt),
+          error
+        });
+        throw new Error(`Failed to parse Core response: ${message}`);
+      }
+    } finally {
+      clearTimeout(timeout);
     }
-    logger.error("cli.core.ensure_ready.failed", {
-      host: runtime.host,
-      port: runtime.port,
-      attempts: HEALTH_ATTEMPTS
-    });
-    throw new Error(
-      `Core daemon failed to start on ${runtime.host}:${runtime.port}.`
-    );
-  };
-  let ensurePromise = null;
-  const ensureReady = async () => {
-    if (!ensureDaemon) {
-      return;
-    }
-    if (!ensurePromise) {
-      ensurePromise = ensureCoreRunning();
-    }
-    await ensurePromise;
   };
   const post = async (path9, body) => {
-    await ensureReady();
-    refreshRuntime();
+    await readiness.ensureReady();
+    readiness.refreshRuntime();
     return requestJson("POST", path9, body);
   };
   return {
     get baseUrl() {
-      return baseUrl;
+      return readiness.baseUrl;
     },
-    ensureReady,
+    ensureReady: readiness.ensureReady,
     post
   };
 };
@@ -1627,9 +1756,26 @@ var registerDialogCommands = (program2) => {
 var registerDiagnosticsCommands = (program2) => {
   const diagnostics = program2.command("diagnostics").description("Diagnostics commands");
   diagnostics.command("doctor").description("Run diagnostics").option("--session-id <id>", "Session identifier").action(async (options, command) => {
-    await runCommand(command, (client) => {
+    await runCommand(command, (client, globalOptions) => {
+      const runtime = resolveCoreRuntime({
+        host: globalOptions.host,
+        port: globalOptions.port,
+        strictEnvPort: true
+      });
       const payload = parseInput(DiagnosticsDoctorInputSchema, {
-        session_id: options.sessionId
+        session_id: options.sessionId,
+        caller: {
+          endpoint: {
+            host: runtime.host,
+            port: runtime.port,
+            base_url: `http://${runtime.host}:${runtime.port}`,
+            host_source: runtime.hostSource,
+            port_source: runtime.portSource
+          },
+          process: {
+            component: "cli"
+          }
+        }
       });
       return client.post("/diagnostics/doctor", payload);
     });
@@ -2243,36 +2389,92 @@ var registerInspectCommands = (program2) => {
 };
 
 // packages/mcp-adapter/src/core-client.ts
-var DEFAULT_TIMEOUT_MS2 = 3e4;
+var import_node_child_process3 = require("node:child_process");
+var import_node_path4 = require("node:path");
+var DEFAULT_TIMEOUT_MS3 = 3e4;
 var normalizePath2 = (path9) => path9.startsWith("/") ? path9 : `/${path9}`;
 var durationMs3 = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
+var toReadinessErrorEnvelope = (error, baseUrl) => ({
+  ok: false,
+  error: {
+    code: "UNAVAILABLE",
+    message: error instanceof Error ? `Core not ready at ${baseUrl}: ${error.message}` : `Core not ready at ${baseUrl}.`,
+    retryable: true,
+    details: {
+      base_url: baseUrl
+    }
+  }
+});
 var createCoreClient2 = (options = {}) => {
   const logger = options.logger ?? createJsonlLogger({
     stream: "mcp-adapter",
     cwd: options.cwd
   }).child({ scope: "core-client" });
-  const runtime = resolveCoreRuntime({
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const spawnImpl = options.spawnImpl ?? import_node_child_process3.spawn;
+  const ensureDaemon = options.ensureDaemon ?? false;
+  const componentVersion = options.componentVersion ?? process.env.BROWSER_BRIDGE_VERSION ?? process.env.npm_package_version;
+  const readiness = createCoreReadinessController({
     host: options.host,
     port: options.port,
     cwd: options.cwd,
-    strictEnvPort: true
+    timeoutMs,
+    ensureDaemon,
+    strictEnvPort: true,
+    fetchImpl,
+    logger,
+    logPrefix: "mcp.core",
+    healthRetryMs: options.healthRetryMs,
+    healthAttempts: options.healthAttempts,
+    spawnDaemon: ensureDaemon ? (runtime) => {
+      const coreEntry = (0, import_node_path4.resolve)(__dirname, "api.js");
+      const startOptions = [];
+      if (runtime.hostSource === "option" || runtime.hostSource === "env") {
+        startOptions.push(`host: ${JSON.stringify(runtime.host)}`);
+      }
+      if (runtime.portSource === "option" || runtime.portSource === "env") {
+        startOptions.push(`port: ${runtime.port}`);
+      }
+      const script = `const { startCoreServer } = require(${JSON.stringify(
+        coreEntry
+      )});
+startCoreServer({ ${startOptions.join(
+        ", "
+      )} })
+  .catch((err) => { console.error(err); process.exit(1); });`;
+      logger.info("mcp.core.spawn.start", {
+        host: runtime.host,
+        port: runtime.port,
+        host_source: runtime.hostSource,
+        port_source: runtime.portSource
+      });
+      const child = spawnImpl(process.execPath, ["-e", script], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env }
+      });
+      child.on("error", (error) => {
+        logger.error("mcp.core.spawn.error", {
+          host: runtime.host,
+          port: runtime.port,
+          error
+        });
+      });
+      child.unref();
+    } : void 0
   });
-  const host = runtime.host;
-  const port = runtime.port;
-  const baseUrl = `http://${host}:${port}`;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
-  const fetchImpl = options.fetchImpl ?? fetch;
   const requestJson = async (path9, body) => {
     const requestPath = normalizePath2(path9);
     const startedAt = process.hrtime.bigint();
     logger.debug("mcp.core.request.start", {
       path: requestPath,
-      base_url: baseUrl
+      base_url: readiness.baseUrl
     });
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
     try {
-      const response = await fetchImpl(`${baseUrl}${requestPath}`, {
+      const response = await fetchImpl(`${readiness.baseUrl}${requestPath}`, {
         method: "POST",
         headers: {
           "content-type": "application/json"
@@ -2284,7 +2486,7 @@ var createCoreClient2 = (options = {}) => {
       if (!raw) {
         logger.warn("mcp.core.request.empty_response", {
           path: requestPath,
-          base_url: baseUrl,
+          base_url: readiness.baseUrl,
           status: response.status,
           duration_ms: durationMs3(startedAt)
         });
@@ -2294,7 +2496,7 @@ var createCoreClient2 = (options = {}) => {
         const parsed = JSON.parse(raw);
         logger.debug("mcp.core.request.end", {
           path: requestPath,
-          base_url: baseUrl,
+          base_url: readiness.baseUrl,
           status: response.status,
           duration_ms: durationMs3(startedAt)
         });
@@ -2303,7 +2505,7 @@ var createCoreClient2 = (options = {}) => {
         const message = error instanceof Error ? error.message : "Unknown JSON parse error";
         logger.error("mcp.core.request.invalid_json", {
           path: requestPath,
-          base_url: baseUrl,
+          base_url: readiness.baseUrl,
           status: response.status,
           duration_ms: durationMs3(startedAt),
           error
@@ -2313,7 +2515,7 @@ var createCoreClient2 = (options = {}) => {
     } catch (error) {
       logger.error("mcp.core.request.failed", {
         path: requestPath,
-        base_url: baseUrl,
+        base_url: readiness.baseUrl,
         duration_ms: durationMs3(startedAt),
         error
       });
@@ -2323,9 +2525,47 @@ var createCoreClient2 = (options = {}) => {
     }
   };
   const post = async (path9, body) => {
-    return requestJson(path9, body);
+    try {
+      await readiness.ensureReady();
+    } catch (error) {
+      logger.warn("mcp.core.ensure_ready.unavailable", {
+        base_url: readiness.baseUrl,
+        error
+      });
+      throw toReadinessErrorEnvelope(error, readiness.baseUrl);
+    }
+    readiness.refreshRuntime();
+    const payload = path9 === "/diagnostics/doctor" && (!body || typeof body === "object" && !Array.isArray(body)) ? {
+      ...body && typeof body === "object" ? body : {},
+      caller: {
+        endpoint: {
+          host: readiness.runtime.host,
+          port: readiness.runtime.port,
+          base_url: readiness.baseUrl,
+          host_source: readiness.runtime.hostSource,
+          port_source: readiness.runtime.portSource,
+          metadata_path: readiness.runtime.metadataPath,
+          isolated_mode: readiness.runtime.isolatedMode
+        },
+        process: {
+          component: "mcp",
+          version: componentVersion,
+          pid: process.pid,
+          node_version: process.version,
+          binary_path: process.execPath,
+          argv_entry: process.argv[1]
+        }
+      }
+    } : body;
+    return requestJson(path9, payload);
+  };
+  return {
+    get baseUrl() {
+      return readiness.baseUrl;
+    },
+    ensureReady: readiness.ensureReady,
+    post
   };
-  return { baseUrl, post };
 };
 
 // packages/mcp-adapter/src/tools.ts
@@ -2722,10 +2962,11 @@ var TOOL_DEFINITIONS = [
     }
   }
 ];
-var createToolHandler = (client, corePath) => {
+var createToolHandler = (clientProvider, corePath) => {
   return (async (args, _extra) => {
     void _extra;
     try {
+      const client = typeof clientProvider === "function" ? await clientProvider() : clientProvider;
       const envelopeResult = await client.post(corePath, args);
       return toToolResult(envelopeResult);
     } catch (error) {
@@ -2737,7 +2978,7 @@ var createToolHandler = (client, corePath) => {
     }
   });
 };
-var registerBrowserBridgeTools = (server, client) => {
+var registerBrowserBridgeTools = (server, clientProvider) => {
   for (const tool of TOOL_DEFINITIONS) {
     server.registerTool(
       tool.name,
@@ -2747,73 +2988,310 @@ var registerBrowserBridgeTools = (server, client) => {
         inputSchema: tool.config.inputSchema,
         outputSchema: tool.config.outputSchema
       },
-      createToolHandler(client, tool.config.corePath)
+      createToolHandler(clientProvider, tool.config.corePath)
     );
   }
 };
 
 // packages/mcp-adapter/src/server.ts
-var import_node_http = require("node:http");
 var import_node_crypto = require("node:crypto");
+var import_node_http = require("node:http");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 var import_types = require("@modelcontextprotocol/sdk/types.js");
+
+// packages/mcp-adapter/src/deferred-logger.ts
+var LOG_LEVEL_PRIORITY2 = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+var isEnabled = (state, level) => LOG_LEVEL_PRIORITY2[level] >= LOG_LEVEL_PRIORITY2[state.level];
+var enqueue = (state, entry) => {
+  if (state.buffered.length >= state.maxBufferEntries) {
+    state.buffered.shift();
+    state.droppedEntries += 1;
+  }
+  state.buffered.push(entry);
+};
+var flushBuffered = (state) => {
+  const destination = state.destination;
+  if (!destination) {
+    return;
+  }
+  if (state.droppedEntries > 0) {
+    destination.warn("mcp.log.buffer.dropped", {
+      dropped_entries: state.droppedEntries
+    });
+    state.droppedEntries = 0;
+  }
+  for (const entry of state.buffered) {
+    destination.log(entry.level, entry.event, {
+      ...entry.bindings,
+      ...entry.fields
+    });
+  }
+  state.buffered.length = 0;
+};
+var buildLogger2 = (state, bindings) => {
+  const log = (level, event, fields = {}) => {
+    if (!isEnabled(state, level)) {
+      return;
+    }
+    if (state.destination) {
+      state.destination.log(level, event, {
+        ...bindings,
+        ...fields
+      });
+      return;
+    }
+    enqueue(state, {
+      level,
+      event,
+      fields: { ...fields },
+      bindings: { ...bindings }
+    });
+  };
+  return {
+    stream: state.stream,
+    get level() {
+      return state.destination?.level ?? state.level;
+    },
+    get logDir() {
+      return state.destination?.logDir ?? "";
+    },
+    get filePath() {
+      return state.destination?.filePath ?? "";
+    },
+    child: (childBindings) => buildLogger2(state, {
+      ...bindings,
+      ...childBindings
+    }),
+    log,
+    debug: (event, fields) => log("debug", event, fields),
+    info: (event, fields) => log("info", event, fields),
+    warn: (event, fields) => log("warn", event, fields),
+    error: (event, fields) => log("error", event, fields)
+  };
+};
+var createDeferredJsonlLogger = (options) => {
+  const state = {
+    stream: options.stream,
+    level: options.level ?? "debug",
+    destination: null,
+    buffered: [],
+    droppedEntries: 0,
+    maxBufferEntries: Math.max(1, options.maxBufferEntries ?? 2e3)
+  };
+  return {
+    logger: buildLogger2(state, options.bindings ?? {}),
+    activate: () => {
+      if (!state.destination) {
+        state.destination = createJsonlLogger(options);
+      }
+      flushBuffered(state);
+      return state.destination;
+    },
+    isActivated: () => state.destination !== null
+  };
+};
+
+// packages/mcp-adapter/src/server.ts
 var DEFAULT_SERVER_NAME = "browser-bridge";
 var DEFAULT_SERVER_VERSION = "0.0.0";
 var DEFAULT_HTTP_HOST = "127.0.0.1";
 var DEFAULT_HTTP_PATH = "/mcp";
+var ENV_MCP_EAGER = "BROWSER_BRIDGE_MCP_EAGER";
+var ENV_LEGACY_MCP_EAGER = "BROWSER_VISION_MCP_EAGER";
 var durationMs4 = (startedAt) => Number((Number(process.hrtime.bigint() - startedAt) / 1e6).toFixed(3));
-var resolveAdapterLogger = (options) => options.logger ?? createJsonlLogger({
-  stream: "mcp-adapter",
-  cwd: options.cwd
+var parseBoolean2 = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on") {
+    return true;
+  }
+  if (normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off") {
+    return false;
+  }
+  return void 0;
+};
+var resolveEagerMode = (explicit) => {
+  if (typeof explicit === "boolean") {
+    return explicit;
+  }
+  const envValue = parseBoolean2(process.env[ENV_MCP_EAGER]) ?? parseBoolean2(process.env[ENV_LEGACY_MCP_EAGER]);
+  return envValue ?? false;
+};
+var toCoreClientOptions = (options, logger) => ({
+  host: options.host,
+  port: options.port,
+  cwd: options.cwd,
+  timeoutMs: options.timeoutMs,
+  ensureDaemon: options.ensureDaemon ?? true,
+  componentVersion: options.version ?? DEFAULT_SERVER_VERSION,
+  healthRetryMs: options.healthRetryMs,
+  healthAttempts: options.healthAttempts,
+  fetchImpl: options.fetchImpl,
+  spawnImpl: options.spawnImpl,
+  logger
 });
-var createMcpServer = (options = {}) => {
-  const logger = resolveAdapterLogger(options);
+var buildInitializationError = (error) => {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown initialization failure.";
+  return {
+    ok: false,
+    error: {
+      code: "UNAVAILABLE",
+      message: `MCP runtime initialization failed: ${message}`,
+      retryable: true,
+      details: {
+        phase: "mcp_runtime_init"
+      }
+    }
+  };
+};
+var resolveDeferredLoggerController = (options) => {
+  if (options.logger) {
+    return {
+      logger: options.logger,
+      activate: () => void 0
+    };
+  }
+  const deferred = createDeferredJsonlLogger({
+    stream: "mcp-adapter",
+    cwd: options.cwd
+  });
+  return {
+    logger: deferred.logger,
+    activate: () => {
+      deferred.activate();
+    }
+  };
+};
+var createRuntimeController = (options) => {
+  const deferredLogger = resolveDeferredLoggerController(options);
+  const logger = deferredLogger.logger;
+  const coreLogger = logger.child({ scope: "core-client" });
+  let initializedClient = null;
+  let initializationPromise = null;
+  const createClient = async () => {
+    if (options.coreClient) {
+      return options.coreClient;
+    }
+    if (options.coreClientFactory) {
+      return await options.coreClientFactory(coreLogger);
+    }
+    return createCoreClient2(toCoreClientOptions(options, coreLogger));
+  };
+  const proxyClient = {
+    get baseUrl() {
+      return initializedClient?.baseUrl ?? "";
+    },
+    ensureReady: async () => {
+      await ensureInitialized();
+    },
+    post: async (path9, body) => {
+      const client = await ensureInitialized();
+      return client.post(path9, body);
+    }
+  };
+  const ensureInitialized = async () => {
+    if (initializedClient) {
+      return initializedClient;
+    }
+    if (!initializationPromise) {
+      initializationPromise = (async () => {
+        logger.info("mcp.runtime.init.begin");
+        try {
+          const candidate = await createClient();
+          const maybeEnsureReady = candidate.ensureReady;
+          if (typeof maybeEnsureReady === "function") {
+            await maybeEnsureReady.call(candidate);
+          }
+          deferredLogger.activate();
+          initializedClient = candidate;
+          logger.info("mcp.runtime.init.ready", {
+            core_base_url: candidate.baseUrl
+          });
+          return candidate;
+        } catch (error) {
+          logger.error("mcp.runtime.init.failed", {
+            error
+          });
+          throw buildInitializationError(error);
+        }
+      })();
+      initializationPromise = initializationPromise.catch((error) => {
+        initializationPromise = null;
+        throw error;
+      });
+    }
+    return initializationPromise;
+  };
+  return {
+    logger,
+    client: options.coreClient ?? proxyClient,
+    ensureInitialized,
+    isInitialized: () => initializedClient !== null
+  };
+};
+var createMcpServerBootstrap = (options = {}) => {
+  const runtime = createRuntimeController(options);
   const server = new import_mcp.McpServer({
     name: options.name ?? DEFAULT_SERVER_NAME,
     version: options.version ?? DEFAULT_SERVER_VERSION
   });
-  const client = options.coreClient ?? createCoreClient2({
-    ...options,
-    logger: logger.child({ scope: "core-client" })
-  });
-  registerBrowserBridgeTools(server, client);
-  logger.info("mcp.server.created", {
+  registerBrowserBridgeTools(server, runtime.ensureInitialized);
+  runtime.logger.info("mcp.server.created", {
     name: options.name ?? DEFAULT_SERVER_NAME,
     version: options.version ?? DEFAULT_SERVER_VERSION,
-    core_base_url: client.baseUrl
+    lazy_init: true
   });
-  return { server, client };
+  return {
+    server,
+    client: runtime.client,
+    logger: runtime.logger,
+    ensureInitialized: runtime.ensureInitialized,
+    isInitialized: runtime.isInitialized
+  };
 };
 var startMcpServer = async (options = {}) => {
-  const logger = resolveAdapterLogger(options);
-  logger.info("mcp.stdio.start.begin", {
+  const eager = resolveEagerMode(options.eager);
+  const handle = createMcpServerBootstrap(options);
+  handle.logger.info("mcp.stdio.start.begin", {
     name: options.name ?? DEFAULT_SERVER_NAME,
-    version: options.version ?? DEFAULT_SERVER_VERSION
-  });
-  const handle = createMcpServer({
-    ...options,
-    logger
+    version: options.version ?? DEFAULT_SERVER_VERSION,
+    eager
   });
   const transport = new import_stdio.StdioServerTransport();
   try {
+    if (eager) {
+      await handle.ensureInitialized();
+    }
     await handle.server.connect(transport);
-    logger.info("mcp.stdio.start.ready", {
-      core_base_url: handle.client.baseUrl
+    handle.logger.info("mcp.stdio.start.ready", {
+      core_base_url: handle.isInitialized() ? handle.client.baseUrl : null,
+      eager
     });
   } catch (error) {
-    logger.error("mcp.stdio.start.failed", {
+    handle.logger.error("mcp.stdio.start.failed", {
       error
     });
     throw error;
   }
-  return { ...handle, transport };
+  return {
+    server: handle.server,
+    client: handle.client,
+    transport
+  };
 };
 var readJsonBody = async (req, maxBytes = 5 * 1024 * 1024) => {
   const chunks = [];
   let total = 0;
-  await new Promise((resolve3, reject) => {
+  await new Promise((resolve4, reject) => {
     req.on("data", (chunk) => {
       total += chunk.length;
       if (total > maxBytes) {
@@ -2823,7 +3301,7 @@ var readJsonBody = async (req, maxBytes = 5 * 1024 * 1024) => {
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolve3());
+    req.on("end", () => resolve4());
     req.on("error", (err) => reject(err));
   });
   const raw = Buffer.concat(chunks).toString("utf8");
@@ -2842,19 +3320,21 @@ var getHeaderValue = (value) => {
   return void 0;
 };
 var startMcpHttpServer = async (options = {}) => {
-  const logger = resolveAdapterLogger(options).child({ scope: "http-server" });
+  const eager = resolveEagerMode(options.eager);
+  const runtime = createRuntimeController(options);
+  const logger = runtime.logger.child({ scope: "http-server" });
   const host = options.host ?? DEFAULT_HTTP_HOST;
   const port = typeof options.port === "number" ? options.port : 0;
   const path9 = options.path ?? DEFAULT_HTTP_PATH;
   logger.info("mcp.http.start.begin", {
     host,
     port,
-    path: path9
-  });
-  const client = options.coreClient ?? createCoreClient2({
-    ...options,
-    logger: logger.child({ scope: "core-client" })
+    path: path9,
+    eager
   });
+  if (eager) {
+    await runtime.ensureInitialized();
+  }
   const sessions = /* @__PURE__ */ new Map();
   const closeAllSessions = async () => {
     const entries = Array.from(sessions.values());
@@ -2965,7 +3445,7 @@ var startMcpHttpServer = async (options = {}) => {
         name: options.name ?? DEFAULT_SERVER_NAME,
         version: options.version ?? DEFAULT_SERVER_VERSION
       });
-      registerBrowserBridgeTools(sessionServer, client);
+      registerBrowserBridgeTools(sessionServer, runtime.ensureInitialized);
       await sessionServer.connect(transport);
       sessionEntry = { transport, server: sessionServer };
       await transport.handleRequest(req, res, parsedBody);
@@ -2989,10 +3469,10 @@ var startMcpHttpServer = async (options = {}) => {
       );
     }
   });
-  const resolvedPort = await new Promise((resolve3, reject) => {
+  const resolvedPort = await new Promise((resolve4, reject) => {
     httpServer.listen(port, host, () => {
       const address = httpServer.address();
-      resolve3(typeof address === "object" && address ? address.port : port);
+      resolve4(typeof address === "object" && address ? address.port : port);
     });
     httpServer.on("error", reject);
   });
@@ -3000,10 +3480,11 @@ var startMcpHttpServer = async (options = {}) => {
     host,
     port: resolvedPort,
     path: path9,
-    core_base_url: client.baseUrl
+    core_base_url: runtime.isInitialized() ? runtime.client.baseUrl : null,
+    eager
   });
   return {
-    client,
+    client: runtime.client,
     host,
     port: resolvedPort,
     path: path9,
@@ -3012,12 +3493,12 @@ var startMcpHttpServer = async (options = {}) => {
         host,
         port: resolvedPort
       });
-      await new Promise((resolve3, reject) => {
+      await new Promise((resolve4, reject) => {
         httpServer.close((err) => {
           if (err) {
             reject(err);
           } else {
-            resolve3();
+            resolve4();
           }
         });
       });
@@ -3054,19 +3535,19 @@ var checkboxPrompt = async (options) => {
 };
 
 // packages/cli/src/installer/mcp-install.ts
-var import_node_child_process3 = require("node:child_process");
+var import_node_child_process4 = require("node:child_process");
 
 // packages/cli/src/installer/cursor-mcp.ts
 var import_promises2 = __toESM(require("node:fs/promises"));
 var import_node_os = __toESM(require("node:os"));
-var import_node_path4 = __toESM(require("node:path"));
+var import_node_path5 = __toESM(require("node:path"));
 var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var resolveCursorUserSettingsPath = (options) => {
   const platform = options?.platform ?? process.platform;
   const homeDir = options?.homeDir ?? import_node_os.default.homedir();
   const env = options?.env ?? process.env;
   if (platform === "darwin") {
-    return import_node_path4.default.join(
+    return import_node_path5.default.join(
       homeDir,
       "Library",
       "Application Support",
@@ -3082,13 +3563,13 @@ var resolveCursorUserSettingsPath = (options) => {
         "APPDATA is not set; cannot resolve Cursor settings path."
       );
     }
-    return import_node_path4.default.join(appData, "Cursor", "User", "settings.json");
+    return import_node_path5.default.join(appData, "Cursor", "User", "settings.json");
   }
-  return import_node_path4.default.join(homeDir, ".config", "Cursor", "User", "settings.json");
+  return import_node_path5.default.join(homeDir, ".config", "Cursor", "User", "settings.json");
 };
 var installCursorMcp = async (settingsPath) => {
   const filePath = settingsPath ?? resolveCursorUserSettingsPath();
-  const dir = import_node_path4.default.dirname(filePath);
+  const dir = import_node_path5.default.dirname(filePath);
   await import_promises2.default.mkdir(dir, { recursive: true });
   let settings = {};
   try {
@@ -3124,15 +3605,15 @@ var installCursorMcp = async (settingsPath) => {
 
 // packages/cli/src/installer/mcp-install.ts
 var runQuiet = async (cmd, args) => {
-  await new Promise((resolve3, reject) => {
-    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+  await new Promise((resolve4, reject) => {
+    const child = (0, import_node_child_process4.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stderr = "";
     child.stderr?.on("data", (chunk) => {
       stderr += String(chunk);
     });
     child.on("error", reject);
     child.on("exit", (code) => {
-      if (code === 0) resolve3();
+      if (code === 0) resolve4();
       else {
         const suffix = stderr.trim() ? `: ${stderr.trim()}` : "";
         reject(new Error(`${cmd} exited with ${code ?? "unknown"}${suffix}`));
@@ -3211,16 +3692,17 @@ var installMcp = async (harness) => {
 var registerMcpCommand = (program2) => {
   const startServer = async (options, command) => {
     const globals = getGlobalOptions(command);
-    const coreClient = createCoreClient({
-      host: globals.host,
-      port: globals.port,
-      ensureDaemon: globals.daemon !== false
-    });
     try {
       await startMcpServer({
         name: options.name,
         version: options.version,
-        coreClient
+        eager: options.eager,
+        coreClientFactory: (logger) => createCoreClient({
+          host: globals.host,
+          port: globals.port,
+          ensureDaemon: globals.daemon !== false,
+          logger
+        })
       });
     } catch (error) {
       console.error(error);
@@ -3257,15 +3739,10 @@ var registerMcpCommand = (program2) => {
       return { ok: true, result: { installed: results } };
     });
   });
-  mcp.option("--name <name>", "MCP server name").option("--version <version>", "MCP server version").action(startServer);
-  mcp.command("serve").description("Run the MCP server over stdio").option("--name <name>", "MCP server name").option("--version <version>", "MCP server version").action(startServer);
-  mcp.command("serve-http").description("Run the MCP server over Streamable HTTP").option("--name <name>", "MCP server name").option("--version <version>", "MCP server version").option("--host <host>", "HTTP host (default 127.0.0.1)").option("--port <port>", "HTTP port (default random available port)").option("--path <path>", "HTTP path (default /mcp)").action(async (options, command) => {
+  mcp.option("--name <name>", "MCP server name").option("--version <version>", "MCP server version").option("--eager", "Initialize runtime on startup (debug only)").action(startServer);
+  mcp.command("serve").description("Run the MCP server over stdio").option("--name <name>", "MCP server name").option("--version <version>", "MCP server version").option("--eager", "Initialize runtime on startup (debug only)").action(startServer);
+  mcp.command("serve-http").description("Run the MCP server over Streamable HTTP").option("--name <name>", "MCP server name").option("--version <version>", "MCP server version").option("--host <host>", "HTTP host (default 127.0.0.1)").option("--port <port>", "HTTP port (default random available port)").option("--path <path>", "HTTP path (default /mcp)").option("--eager", "Initialize runtime on startup (debug only)").action(async (options, command) => {
     const globals = getGlobalOptions(command);
-    const coreClient = createCoreClient({
-      host: globals.host,
-      port: globals.port,
-      ensureDaemon: globals.daemon !== false
-    });
     const parsedPort = typeof options.port === "string" && options.port.length > 0 ? Number(options.port) : void 0;
     try {
       const handle = await startMcpHttpServer({
@@ -3274,7 +3751,13 @@ var registerMcpCommand = (program2) => {
         host: options.host,
         port: typeof parsedPort === "number" && Number.isFinite(parsedPort) ? parsedPort : void 0,
         path: options.path,
-        coreClient
+        eager: options.eager,
+        coreClientFactory: (logger) => createCoreClient({
+          host: globals.host,
+          port: globals.port,
+          ensureDaemon: globals.daemon !== false,
+          logger
+        })
       });
       console.error(
         `MCP HTTP server listening on http://${handle.host}:${handle.port}${handle.path}`
@@ -3300,10 +3783,10 @@ var import_turndown = __toESM(require("turndown"));
 // packages/core/src/artifacts.ts
 var import_promises3 = require("node:fs/promises");
 var import_node_os2 = __toESM(require("node:os"));
-var import_node_path5 = __toESM(require("node:path"));
+var import_node_path6 = __toESM(require("node:path"));
 var ARTIFACTS_DIR_NAME = "browser-agent";
 var resolveTempRoot = () => process.env.TMPDIR || process.env.TEMP || process.env.TMP || import_node_os2.default.tmpdir();
-var getArtifactRootDir = (sessionId) => import_node_path5.default.join(resolveTempRoot(), ARTIFACTS_DIR_NAME, sessionId);
+var getArtifactRootDir = (sessionId) => import_node_path6.default.join(resolveTempRoot(), ARTIFACTS_DIR_NAME, sessionId);
 var ensureArtifactRootDir = async (sessionId) => {
   const rootDir = getArtifactRootDir(sessionId);
   await (0, import_promises3.mkdir)(rootDir, { recursive: true });
@@ -3490,60 +3973,60 @@ var registerSessionCommands = (program2) => {
 // packages/cli/src/commands/skill.ts
 var import_promises7 = __toESM(require("node:fs/promises"));
 var import_node_os4 = __toESM(require("node:os"));
-var import_node_path10 = __toESM(require("node:path"));
+var import_node_path11 = __toESM(require("node:path"));
 
 // packages/cli/src/installer/harness-targets.ts
 var import_node_os3 = __toESM(require("node:os"));
-var import_node_path6 = __toESM(require("node:path"));
+var import_node_path7 = __toESM(require("node:path"));
 var getDefaultHarnessTargets = (homeDir) => {
   const home = homeDir ?? import_node_os3.default.homedir();
   return [
     {
       id: "codex",
       label: "Codex",
-      skillsDir: import_node_path6.default.join(home, ".agents", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".agents", "skills"),
       supportsMcpInstall: true
     },
     {
       id: "claude",
       label: "Claude",
-      skillsDir: import_node_path6.default.join(home, ".claude", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".claude", "skills"),
       supportsMcpInstall: true
     },
     {
       id: "cursor",
       label: "Cursor",
-      skillsDir: import_node_path6.default.join(home, ".cursor", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".cursor", "skills"),
       supportsMcpInstall: true
     },
     {
       id: "factory",
       label: "Factory",
-      skillsDir: import_node_path6.default.join(home, ".factory", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".factory", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "opencode",
       label: "OpenCode",
-      skillsDir: import_node_path6.default.join(home, ".opencode", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".opencode", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "gemini",
       label: "Gemini",
-      skillsDir: import_node_path6.default.join(home, ".gemini", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".gemini", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "github",
       label: "GitHub",
-      skillsDir: import_node_path6.default.join(home, ".github", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".github", "skills"),
       supportsMcpInstall: false
     },
     {
       id: "ampcode",
       label: "Ampcode",
-      skillsDir: import_node_path6.default.join(home, ".ampcode", "skills"),
+      skillsDir: import_node_path7.default.join(home, ".ampcode", "skills"),
       supportsMcpInstall: false
     }
   ];
@@ -3551,7 +4034,7 @@ var getDefaultHarnessTargets = (homeDir) => {
 
 // packages/cli/src/installer/package-info.ts
 var import_promises4 = __toESM(require("node:fs/promises"));
-var import_node_path7 = __toESM(require("node:path"));
+var import_node_path8 = __toESM(require("node:path"));
 var PACKAGE_NAME = "@btraut/browser-bridge";
 var tryReadJson = async (filePath) => {
   try {
@@ -3564,12 +4047,12 @@ var tryReadJson = async (filePath) => {
 var resolveCliPackageRootDir = async () => {
   let dir = __dirname;
   for (let i = 0; i < 12; i++) {
-    const candidate = import_node_path7.default.join(dir, "package.json");
+    const candidate = import_node_path8.default.join(dir, "package.json");
     const parsed = await tryReadJson(candidate);
     if (parsed && parsed.name === PACKAGE_NAME) {
       return dir;
     }
-    const parent = import_node_path7.default.dirname(dir);
+    const parent = import_node_path8.default.dirname(dir);
     if (parent === dir) {
       break;
     }
@@ -3581,7 +4064,7 @@ var resolveCliPackageRootDir = async () => {
 };
 var readCliPackageVersion = async () => {
   const rootDir = await resolveCliPackageRootDir();
-  const pkgPath = import_node_path7.default.join(rootDir, "package.json");
+  const pkgPath = import_node_path8.default.join(rootDir, "package.json");
   const parsed = await tryReadJson(pkgPath);
   if (!parsed || typeof parsed.version !== "string" || !parsed.version) {
     throw new Error(`Unable to read version from ${pkgPath}`);
@@ -3590,14 +4073,14 @@ var readCliPackageVersion = async () => {
 };
 var resolveSkillSourceDir = async () => {
   const rootDir = await resolveCliPackageRootDir();
-  const packaged = import_node_path7.default.join(rootDir, "skills", "browser-bridge");
+  const packaged = import_node_path8.default.join(rootDir, "skills", "browser-bridge");
   try {
     await import_promises4.default.stat(packaged);
     return packaged;
   } catch {
   }
-  const repoRoot = import_node_path7.default.resolve(rootDir, "..", "..");
-  const docsSkill = import_node_path7.default.join(repoRoot, "docs", "skills", "browser-bridge");
+  const repoRoot = import_node_path8.default.resolve(rootDir, "..", "..");
+  const docsSkill = import_node_path8.default.join(repoRoot, "docs", "skills", "browser-bridge");
   try {
     await import_promises4.default.stat(docsSkill);
     return docsSkill;
@@ -3610,16 +4093,16 @@ var resolveSkillSourceDir = async () => {
 
 // packages/cli/src/installer/skill-install.ts
 var import_promises6 = __toESM(require("node:fs/promises"));
-var import_node_path9 = __toESM(require("node:path"));
+var import_node_path10 = __toESM(require("node:path"));
 
 // packages/cli/src/installer/skill-manifest.ts
 var import_promises5 = __toESM(require("node:fs/promises"));
-var import_node_path8 = __toESM(require("node:path"));
+var import_node_path9 = __toESM(require("node:path"));
 var SKILL_MANIFEST_FILENAME = "skill.json";
 var readSkillManifest = async (skillDir) => {
   try {
     const raw = await import_promises5.default.readFile(
-      import_node_path8.default.join(skillDir, SKILL_MANIFEST_FILENAME),
+      import_node_path9.default.join(skillDir, SKILL_MANIFEST_FILENAME),
       "utf8"
     );
     const parsed = JSON.parse(raw);
@@ -3634,7 +4117,7 @@ var readSkillManifest = async (skillDir) => {
 var writeSkillManifest = async (skillDir, version) => {
   const payload = { name: "browser-bridge", version };
   await import_promises5.default.writeFile(
-    import_node_path8.default.join(skillDir, SKILL_MANIFEST_FILENAME),
+    import_node_path9.default.join(skillDir, SKILL_MANIFEST_FILENAME),
     JSON.stringify(payload, null, 2) + "\n",
     "utf8"
   );
@@ -3642,7 +4125,7 @@ var writeSkillManifest = async (skillDir, version) => {
 
 // packages/cli/src/installer/skill-install.ts
 var installBrowserBridgeSkill = async (options) => {
-  const destDir = import_node_path9.default.join(options.destSkillsDir, "browser-bridge");
+  const destDir = import_node_path10.default.join(options.destSkillsDir, "browser-bridge");
   await import_promises6.default.mkdir(options.destSkillsDir, { recursive: true });
   await import_promises6.default.rm(destDir, { recursive: true, force: true });
   await import_promises6.default.cp(options.srcSkillDir, destDir, { recursive: true });
@@ -3654,9 +4137,9 @@ var installBrowserBridgeSkill = async (options) => {
 var getHarnessMarkerDir = (homeDir, harness) => {
   switch (harness) {
     case "codex":
-      return import_node_path10.default.join(homeDir, ".agents");
+      return import_node_path11.default.join(homeDir, ".agents");
     default:
-      return import_node_path10.default.join(homeDir, `.${harness}`);
+      return import_node_path11.default.join(homeDir, `.${harness}`);
   }
 };
 var registerSkillCommands = (program2) => {
@@ -3734,7 +4217,7 @@ var registerSkillCommands = (program2) => {
       const targets = getDefaultHarnessTargets();
       const rows = [];
       for (const t of targets) {
-        const skillDir = import_node_path10.default.join(t.skillsDir, "browser-bridge");
+        const skillDir = import_node_path11.default.join(t.skillsDir, "browser-bridge");
         let installed = false;
         try {
           await import_promises7.default.stat(skillDir);
@@ -3762,7 +4245,7 @@ var registerSkillCommands = (program2) => {
 // packages/cli/src/commands/install.ts
 var import_promises8 = __toESM(require("node:fs/promises"));
 var import_node_os5 = __toESM(require("node:os"));
-var import_node_path11 = __toESM(require("node:path"));
+var import_node_path12 = __toESM(require("node:path"));
 var formatInstallSummary = (options) => {
   const wantsSkill = options.setup.includes("skill");
   const wantsMcp = options.setup.includes("mcp");
@@ -3797,9 +4280,9 @@ var getHarnessMarkerDir2 = (harness) => {
   const homeDir = import_node_os5.default.homedir();
   switch (harness) {
     case "codex":
-      return import_node_path11.default.join(homeDir, ".agents");
+      return import_node_path12.default.join(homeDir, ".agents");
     default:
-      return import_node_path11.default.join(homeDir, `.${harness}`);
+      return import_node_path12.default.join(homeDir, `.${harness}`);
   }
 };
 var registerInstallCommand = (program2) => {