libretto 0.5.5 → 0.6.0

package/src/cli/core/{ai-config.ts → config.ts}

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
+import { SessionAccessModeSchema } from "../../shared/state/index.js";
 import { LIBRETTO_CONFIG_PATH } from "./context.js";
 
 export const CURRENT_CONFIG_VERSION = 1;
@@ -41,34 +42,12 @@ export const LibrettoConfigSchema = z
     ai: AiConfigSchema.optional(),
     viewport: ViewportConfigSchema.optional(),
     windowPosition: WindowPositionConfigSchema.optional(),
+    provider: z.string().optional(),
+    sessionMode: SessionAccessModeSchema.optional(),
   })
   .passthrough();
 export type LibrettoConfig = z.infer<typeof LibrettoConfigSchema>;
 
-/** Default models for each provider shorthand accepted by `ai configure`. */
-const DEFAULT_MODELS: Record<string, string> = {
-  openai: "openai/gpt-5.4",
-  anthropic: "anthropic/claude-sonnet-4-6",
-  gemini: "google/gemini-3-flash-preview",
-  vertex: "vertex/gemini-2.5-pro",
-};
-
-const PROVIDER_ALIASES: Record<string, string> = {
-  claude: DEFAULT_MODELS.anthropic,
-  google: DEFAULT_MODELS.gemini,
-};
-
-const CONFIGURE_PROVIDERS = [
-  "openai",
-  "anthropic",
-  "gemini",
-  "vertex",
-] as const;
-
-function formatConfigureProviders(separator = " | "): string {
-  return CONFIGURE_PROVIDERS.join(separator);
-}
-
 function formatConfigIssues(error: z.ZodError): string {
   return error.issues
     .map((issue) => `  - ${issue.path.join(".") || "root"}: ${issue.message}`)
@@ -91,6 +70,7 @@ function formatExpectedConfigExample(): string {
         x: 1600,
         y: 120,
       },
+      sessionMode: "write-access",
     },
     null,
     2,
@@ -105,10 +85,10 @@ function invalidConfigError(configPath: string, detail?: string): Error {
       "Expected config example:",
       formatExpectedConfigExample(),
       "Notes:",
-      '  - "ai", "viewport", and "windowPosition" are optional.',
+      '  - "ai", "viewport", "windowPosition", and "sessionMode" are optional.',
       '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
       "Fix the file to match this shape, or delete it and rerun:",
-      `  npx libretto ai configure ${formatConfigureProviders()}`,
+      `  npx libretto ai configure openai | anthropic | gemini | vertex`,
     ]
       .filter(Boolean)
       .join("\n"),
@@ -162,7 +142,14 @@ export function writeAiConfig(
   model: string,
   configPath: string = LIBRETTO_CONFIG_PATH,
 ): AiConfig {
-  const librettoConfig = readLibrettoConfig(configPath);
+  let librettoConfig: LibrettoConfig;
+  try {
+    librettoConfig = readLibrettoConfig(configPath);
+  } catch {
+    // Existing config is malformed — start fresh so repair flows can
+    // overwrite a broken file instead of throwing.
+    librettoConfig = { version: CURRENT_CONFIG_VERSION };
+  }
   const ai = AiConfigSchema.parse({
     model,
     updatedAt: new Date().toISOString(),
@@ -192,84 +179,3 @@ export function clearAiConfig(
   );
   return true;
 }
-
-function printAiConfig(config: AiConfig, configPath: string): void {
-  console.log(`Model: ${config.model}`);
-  console.log(`Config file: ${configPath}`);
-  console.log(`Updated at: ${config.updatedAt}`);
-}
-
-/**
- * Resolve the model string from a `ai configure` argument.
- * Accepts a provider shorthand ("openai", "anthropic", "gemini", "vertex")
- * or a full provider/model-id string ("openai/gpt-4o", "anthropic/claude-sonnet-4-6").
- */
-function resolveModelFromInput(input: string): string | null {
-  const trimmed = input.trim();
-  if (!trimmed) return null;
-
-  // Full model string (contains a slash)
-  if (trimmed.includes("/")) return trimmed;
-
-  // Provider shorthand
-  const normalized = trimmed.toLowerCase();
-  return DEFAULT_MODELS[normalized] ?? PROVIDER_ALIASES[normalized] ?? null;
-}
-
-export function runAiConfigure(
-  input: {
-    preset?: string;
-    clear?: boolean;
-  },
-  options: {
-    configureCommandName?: string;
-    configPath?: string;
-  } = {},
-): void {
-  const configureCommandName =
-    options.configureCommandName ?? "npx libretto ai configure";
-  const configPath = options.configPath ?? LIBRETTO_CONFIG_PATH;
-
-  const presetArg = input.preset?.trim();
-
-  if (!presetArg && !input.clear) {
-    const config = readAiConfig(configPath);
-    if (!config) {
-      console.log(
-        `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`,
-      );
-      console.log(
-        "Provider credentials still come from your shell or .env file.",
-      );
-      return;
-    }
-    printAiConfig(config, configPath);
-    return;
-  }
-
-  if (input.clear) {
-    const removed = clearAiConfig(configPath);
-    if (removed) {
-      console.log(`Cleared AI config: ${configPath}`);
-    } else {
-      console.log("No AI config was set.");
-    }
-    return;
-  }
-
-  const model = resolveModelFromInput(presetArg!);
-  if (!model) {
-    console.log(
-      `Usage: ${configureCommandName} <${CONFIGURE_PROVIDERS.join("|")}|provider/model-id>\n` +
-        `       ${configureCommandName}\n` +
-        `       ${configureCommandName} --clear`,
-    );
-    throw new Error(
-      `Invalid provider or model. Use one of: ${formatConfigureProviders()}, or a full model string like "openai/gpt-4o".`,
-    );
-  }
-
-  const config = writeAiConfig(model, configPath);
-  console.log("AI config saved.");
-  printAiConfig(config, configPath);
-}

package/src/cli/core/context.ts

@@ -1,6 +1,4 @@
 import { Logger, createFileLogSink } from "../../shared/logger/index.js";
-import type { LLMClient } from "../../shared/llm/index.js";
-import type { LoggerApi } from "../../shared/logger/index.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveLibrettoRepoRoot } from "../../shared/paths/repo-root.js";
@@ -72,13 +70,6 @@ export function createLoggerForSession(session: string): Logger {
   );
 }
 
-export async function closeLogger(
-  logger: Logger | null | undefined,
-): Promise<void> {
-  if (!logger) return;
-  await logger.close();
-}
-
 export async function withSessionLogger<T>(
   session: string,
   run: (logger: Logger) => Promise<T>,
@@ -87,41 +78,6 @@ export async function withSessionLogger<T>(
   try {
     return await run(logger);
   } finally {
-    await closeLogger(logger);
+    await logger.close();
   }
 }
-
-let llmClientFactory:
-  | ((logger: LoggerApi, model: string) => Promise<LLMClient>)
-  | null = null;
-
-export function setLLMClientFactory(
-  factory: (logger: LoggerApi, model: string) => Promise<LLMClient>,
-): void {
-  llmClientFactory = factory;
-}
-
-export function getLLMClientFactory():
-  | ((logger: LoggerApi, model: string) => Promise<LLMClient>)
-  | null {
-  return llmClientFactory;
-}
-
-export function maybeConfigureLLMClientFactoryFromEnv(): void {
-  if (llmClientFactory) return;
-
-  const hasAnyCreds =
-    process.env.GOOGLE_CLOUD_PROJECT ||
-    process.env.GCLOUD_PROJECT ||
-    process.env.ANTHROPIC_API_KEY ||
-    process.env.OPENAI_API_KEY ||
-    process.env.GEMINI_API_KEY ||
-    process.env.GOOGLE_GENERATIVE_AI_API_KEY;
-
-  if (!hasAnyCreds) return;
-
-  setLLMClientFactory(async (_logger, model) => {
-    const { createLLMClient } = await import("../../shared/llm/index.js");
-    return createLLMClient(model);
-  });
-}

package/src/cli/core/deploy-artifact.ts

@@ -10,11 +10,17 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { createRequire, Module } from "node:module";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gzipSync } from "node:zlib";
 import { build } from "esbuild";
+import {
+  getWorkflowFromModuleExports,
+  getWorkflowsFromModuleExports,
+  LIBRETTO_WORKFLOW_BRAND,
+} from "../../shared/workflow/workflow.js";
 
 type PackageManifest = {
   name?: string;
@@ -81,6 +87,7 @@ const CURRENT_LIBRETTO_VERSION = readCurrentLibrettoVersion();
 const CURRENT_LIBRETTO_PACKAGE_DIR = fileURLToPath(
   new URL("../../..", import.meta.url),
 );
+const require = createRequire(import.meta.url);
 
 function readCurrentLibrettoVersion(): string {
   const packageJsonPath = fileURLToPath(
@@ -654,46 +661,141 @@ function formatBuildError(error: unknown): string {
     .join("\n");
 }
 
-function extractExportNamesFromEsmBundle(bundleSource: string): string[] {
-  const exportNames = new Set<string>();
+function getGeneratedWorkflowExportName(index: number): string {
+  return `workflow_${index}`;
+}
 
-  for (const entry of bundleSource.matchAll(
-    /export\s+(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g,
-  )) {
-    exportNames.add(entry[1]!);
+function getPackageNameFromImportPath(importPath: string): string {
+  if (importPath.startsWith("@")) {
+    return importPath.split("/").slice(0, 2).join("/");
   }
+  return importPath.split("/")[0] ?? importPath;
+}
 
-  for (const entry of bundleSource.matchAll(/export\s+\{([^}]+)\};/g)) {
-    const specifiers = entry[1]?.split(",") ?? [];
-    for (const specifier of specifiers) {
-      const trimmed = specifier.trim();
-      if (!trimmed) {
-        continue;
+function createExternalDiscoveryStub(): object {
+  const stub = (() => createExternalDiscoveryStub()) as unknown as ((
+    ...args: unknown[]
+  ) => object) &
+    Record<PropertyKey, unknown>;
+
+  return new Proxy(stub, {
+    apply: () => createExternalDiscoveryStub(),
+    construct: () => createExternalDiscoveryStub(),
+    get: (_target, property) => {
+      if (property === "__esModule") {
+        return true;
       }
-      const aliasMatch = trimmed.match(
-        /^([A-Za-z_$][\w$]*)\s+as\s+([A-Za-z_$][\w$]*|default)$/,
-      );
-      if (aliasMatch?.[2]) {
-        exportNames.add(aliasMatch[2]);
-        continue;
+      if (property === "default") {
+        return createExternalDiscoveryStub();
       }
-      if (/^[A-Za-z_$][\w$]*$/.test(trimmed)) {
-        exportNames.add(trimmed);
+      if (property === Symbol.toPrimitive) {
+        return () => "";
       }
-    }
+      return createExternalDiscoveryStub();
+    },
+  });
+}
+
+function createDiscoveryLibrettoModule(workflowNames: Set<string>): object {
+  const moduleShape: Record<PropertyKey, unknown> = {
+    LIBRETTO_WORKFLOW_BRAND,
+    workflow: (name: string) => {
+      workflowNames.add(name);
+      return {
+        [LIBRETTO_WORKFLOW_BRAND]: true,
+        name,
+        async run() {
+          return undefined;
+        },
+      };
+    },
+  };
+
+  return new Proxy(moduleShape, {
+    get(target, property) {
+      if (property in target) {
+        return target[property];
+      }
+      if (property === "__esModule") {
+        return true;
+      }
+      return createExternalDiscoveryStub();
+    },
+  });
+}
+
+function discoverBundledWorkflowNames(args: {
+  absEntryPoint: string;
+  absSourceDir: string;
+  bundleBuffer: Buffer;
+  externalPackages: ReadonlySet<string>;
+}): string[] {
+  const discoveryPath = join(
+    args.absSourceDir,
+    `.libretto-deploy-discovery-${process.pid}-${Date.now()}.cjs`,
+  );
+  const originalRequire = Module.prototype.require;
+  const workflowNames = new Set<string>();
+  const discoveryLibrettoModule = createDiscoveryLibrettoModule(workflowNames);
+  let loadedModuleExports: Record<string, unknown> | null = null;
+
+  try {
+    writeFileSync(discoveryPath, args.bundleBuffer);
+    Module.prototype.require = function patchedRequire(id: string) {
+      const packageName = getPackageNameFromImportPath(id);
+      if (packageName === "libretto") {
+        return discoveryLibrettoModule;
+      }
+      if (packageName !== "libretto" && args.externalPackages.has(packageName)) {
+        return createExternalDiscoveryStub();
+      }
+      return originalRequire.call(this, id);
+    };
+    loadedModuleExports = require(discoveryPath) as Record<string, unknown>;
+  } catch (error) {
+    throw new Error(
+      `Failed to evaluate deploy entry point ${args.absEntryPoint} while discovering workflows.\n${formatBuildError(error)}`,
+    );
+  } finally {
+    Module.prototype.require = originalRequire;
+    delete (require.cache as Record<string, unknown> | undefined)?.[
+      discoveryPath
+    ];
+    rmSync(discoveryPath, { force: true });
   }
 
-  if (/\bexport\s+default\b/m.test(bundleSource)) {
-    exportNames.add("default");
+  const discoveredWorkflowNames = [...workflowNames].sort((left, right) =>
+    left.localeCompare(right),
+  );
+
+  if (discoveredWorkflowNames.length === 0) {
+    throw new Error(
+      `No workflows were found in ${args.absEntryPoint}. Import the workflow files you want to deploy from the entry point, or export a workflow directly from it.`,
+    );
   }
 
-  return [...exportNames];
+  const exportedWorkflowNames = new Set(
+    getWorkflowsFromModuleExports(loadedModuleExports ?? {}).map(
+      (workflow) => workflow.name,
+    ),
+  );
+  const nonExportedWorkflowNames = discoveredWorkflowNames.filter(
+    (name) => !exportedWorkflowNames.has(name),
+  );
+
+  if (nonExportedWorkflowNames.length > 0) {
+    throw new Error(
+      `Workflows discovered in ${args.absEntryPoint} must be exported from the deploy entry point. Re-export them from the entry point or export them through a \`workflows\` object. Non-exported workflows: ${nonExportedWorkflowNames.join(", ")}`,
+    );
+  }
+
+  return discoveredWorkflowNames;
 }
 
 function createBootstrapSource(args: {
   bundleBuffer: Buffer;
   deploymentName: string;
-  exportNames: readonly string[];
+  workflowNames: readonly string[];
 }): string {
   const bundleHash = createHash("sha256")
     .update(args.bundleBuffer)
@@ -703,17 +805,12 @@ function createBootstrapSource(args: {
     "base64",
   );
   const outputPrefix = `${normalizePackageName(args.deploymentName)}-`;
-  const hasDefaultExport = args.exportNames.includes("default");
-  const exportLines = args.exportNames
-    .filter((name) => name !== "default")
+  const exportLines = args.workflowNames
     .map(
-      (name) =>
-        `export const ${name} = createWorkflowProxy(${JSON.stringify(name)});`,
+      (name, index) =>
+        `export const ${getGeneratedWorkflowExportName(index)} = createWorkflowProxy(${JSON.stringify(name)});`,
     )
     .join("\n");
-  const defaultExportLine = hasDefaultExport
-    ? 'export default createWorkflowProxy("default");'
-    : "";
 
   // The deploy entrypoint is tiny on purpose. Hosted build imports this module
   // to discover workflow exports. The implementation bundle stays embedded in
@@ -724,7 +821,7 @@ import { existsSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { gunzipSync } from "node:zlib";
-import { workflow } from "libretto";
+import { getWorkflowFromModuleExports, workflow } from "libretto";
 
 const BUNDLE_HASH = ${JSON.stringify(bundleHash)};
 const BUNDLE_GZIP_BASE64 = ${JSON.stringify(bundleBase64)};
@@ -747,13 +844,13 @@ function ensureBundleFile() {
   return BUNDLE_FILENAME;
 }
 
-function createWorkflowProxy(exportName) {
-  return workflow(exportName, async (ctx, input) => {
+function createWorkflowProxy(workflowName) {
+  return workflow(workflowName, async (ctx, input) => {
     const impl = nativeRequire(ensureBundleFile());
-    const target = impl[exportName];
+    const target = getWorkflowFromModuleExports(impl, workflowName);
     if (!target || typeof target.run !== "function") {
       throw new Error(
-        \`Expected workflow export "\${exportName}" to be available in the bundled deployment implementation.\`,
+        \`Expected exported workflow "\${workflowName}" to be available in the bundled deployment implementation.\`,
       );
     }
     return await target.run(ctx, input);
@@ -761,7 +858,6 @@ function createWorkflowProxy(exportName) {
 }
 
 ${exportLines}
-${defaultExportLine}
 `;
 }
 
@@ -802,45 +898,19 @@ async function writeBundledDeployEntrypoint(args: {
       );
     }
 
-    // A separate ESM bundle is used only to read the entry module's exported
-    // workflow names. Scanning the CommonJS bundle would also see exports from
-    // bundled dependencies, which is not the deploy surface.
-    const exportBuild = await build({
-      absWorkingDir: args.absSourceDir,
-      bundle: true,
-      entryPoints: [args.absEntryPoint],
-      external: [...args.externalPackages],
-      format: "esm",
-      outfile: "entry-exports.js",
-      platform: "node",
-      plugins: [
-        workspaceSourcePlugin(args.workspacePackages, args.externalPackages),
-      ],
-      splitting: false,
-      target: "node20",
-      write: false,
+    const workflowNames = discoverBundledWorkflowNames({
+      absEntryPoint: args.absEntryPoint,
+      absSourceDir: args.absSourceDir,
+      bundleBuffer: Buffer.from(bundledImplementation.contents),
+      externalPackages: args.externalPackages,
     });
 
-    const bundledExports = exportBuild.outputFiles?.find((file) =>
-      file.path.endsWith("entry-exports.js"),
-    );
-    if (!bundledExports) {
-      throw new Error("Bundler did not produce an export analysis file.");
-    }
-
-    const exportNames = extractExportNamesFromEsmBundle(bundledExports.text);
-    if (exportNames.length === 0) {
-      throw new Error(
-        `No named exports were found in ${args.absEntryPoint}. Hosted deploy expects the entry point to export one or more workflows.`,
-      );
-    }
-
     writeFileSync(
       join(args.outputDir, "index.js"),
       createBootstrapSource({
         bundleBuffer: Buffer.from(bundledImplementation.contents),
         deploymentName: args.deploymentName,
-        exportNames,
+        workflowNames,
       }),
     );
   } catch (error) {

package/src/cli/core/providers/browserbase.ts

@@ -0,0 +1,57 @@
+import type { ProviderApi } from "./types.js";
+
+export function createBrowserbaseProvider(): ProviderApi {
+  const apiKey = process.env.BROWSERBASE_API_KEY;
+  if (!apiKey)
+    throw new Error(
+      "BROWSERBASE_API_KEY is required for Browserbase provider.",
+    );
+  const projectId = process.env.BROWSERBASE_PROJECT_ID;
+  if (!projectId)
+    throw new Error(
+      "BROWSERBASE_PROJECT_ID is required for Browserbase provider.",
+    );
+  const endpoint =
+    process.env.BROWSERBASE_ENDPOINT ?? "https://api.browserbase.com";
+
+  return {
+    async createSession() {
+      const resp = await fetch(`${endpoint}/v1/sessions`, {
+        method: "POST",
+        headers: {
+          "X-BB-API-Key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ projectId }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Browserbase API error (${resp.status}): ${body}`);
+      }
+      const json = (await resp.json()) as {
+        id: string;
+        connectUrl: string;
+      };
+      return {
+        sessionId: json.id,
+        cdpEndpoint: json.connectUrl,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/v1/sessions/${sessionId}`, {
+        method: "POST",
+        headers: {
+          "X-BB-API-Key": apiKey,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ status: "REQUEST_RELEASE" }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Browserbase API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+    },
+  };
+}

package/src/cli/core/providers/index.ts

@@ -0,0 +1,62 @@
+import { readLibrettoConfig } from "../config.js";
+import { createBrowserbaseProvider } from "./browserbase.js";
+import { createKernelProvider } from "./kernel.js";
+import { createLibrettoCloudProvider } from "./libretto-cloud.js";
+import type { ProviderApi } from "./types.js";
+
+const VALID_PROVIDERS = new Set(["local", "kernel", "browserbase", "libretto-cloud"] as const);
+export type ProviderName =
+  typeof VALID_PROVIDERS extends Set<infer T> ? T : never;
+
+function assertValidProviderName(value: string, source: string): ProviderName {
+  if (!VALID_PROVIDERS.has(value as ProviderName)) {
+    throw new Error(
+      `Invalid provider "${value}" from ${source}. Valid providers: ${[...VALID_PROVIDERS].join(", ")}`,
+    );
+  }
+  return value as ProviderName;
+}
+
+/**
+ * Resolve which provider to use.
+ * Precedence: CLI flag > LIBRETTO_PROVIDER env var > config file > "local" default.
+ */
+export function resolveProviderName(cliFlag?: string): ProviderName {
+  if (cliFlag) {
+    return assertValidProviderName(cliFlag, "--provider flag");
+  }
+
+  const envVar = process.env.LIBRETTO_PROVIDER;
+  if (envVar) {
+    return assertValidProviderName(envVar, "LIBRETTO_PROVIDER env var");
+  }
+
+  const config = readLibrettoConfig();
+  if (config.provider) {
+    return assertValidProviderName(config.provider, "config file");
+  }
+
+  return "local";
+}
+
+/**
+ * Get a ProviderApi instance for a cloud provider.
+ * Only call this for non-"local" providers.
+ */
+export function getCloudProviderApi(name: string): ProviderApi {
+  switch (name) {
+    case "kernel":
+      return createKernelProvider();
+    case "browserbase":
+      return createBrowserbaseProvider();
+    case "libretto-cloud":
+      console.warn(
+        "Note: The libretto-cloud provider is in alpha.",
+      );
+      return createLibrettoCloudProvider();
+    default:
+      throw new Error(
+        `Unknown provider "${name}". Valid cloud providers: kernel, browserbase`,
+      );
+  }
+}

package/src/cli/core/providers/kernel.ts

@@ -0,0 +1,49 @@
+import type { ProviderApi } from "./types.js";
+
+export function createKernelProvider(): ProviderApi {
+  const apiKey = process.env.KERNEL_API_KEY;
+  if (!apiKey)
+    throw new Error("KERNEL_API_KEY is required for Kernel provider.");
+  const endpoint = process.env.KERNEL_ENDPOINT ?? "https://api.onkernel.com";
+
+  return {
+    async createSession() {
+      const resp = await fetch(`${endpoint}/browsers`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          headless: process.env.KERNEL_HEADLESS !== "false",
+          stealth: process.env.KERNEL_STEALTH === "true",
+          timeout_seconds: Number(process.env.KERNEL_TIMEOUT_SECONDS ?? 300),
+        }),
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Kernel API error (${resp.status}): ${body}`);
+      }
+      const json = (await resp.json()) as {
+        session_id: string;
+        cdp_ws_url: string;
+      };
+      return {
+        sessionId: json.session_id,
+        cdpEndpoint: json.cdp_ws_url,
+      };
+    },
+    async closeSession(sessionId) {
+      const resp = await fetch(`${endpoint}/browsers/${sessionId}`, {
+        method: "DELETE",
+        headers: { Authorization: `Bearer ${apiKey}` },
+      });
+      if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(
+          `Kernel API error closing session ${sessionId} (${resp.status}): ${body}`,
+        );
+      }
+    },
+  };
+}