agentkernel 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -115,6 +115,138 @@ interface ApiResponse<T> {
     data?: T;
     error?: string;
 }
+/** Response from extending a sandbox's TTL. */
+interface ExtendTtlResponse {
+    expires_at?: string;
+}
+/** Options for extending TTL. */
+interface ExtendTtlOptions {
+    /** Duration string like "1h", "30m", "2d". */
+    by: string;
+}
+/** Metadata for a sandbox snapshot. */
+interface SnapshotMeta {
+    name: string;
+    sandbox: string;
+    image_tag: string;
+    backend: string;
+    base_image?: string;
+    vcpus?: number;
+    memory_mb?: number;
+    created_at: string;
+}
+/** Options for taking a snapshot. */
+interface TakeSnapshotOptions {
+    /** Name of the sandbox to snapshot. */
+    sandbox: string;
+    /** Optional snapshot name (auto-generated if not provided). */
+    name?: string;
+}
+/** A link extracted from a web page. */
+interface PageLink {
+    text: string;
+    href: string;
+}
+/** Result of navigating to a web page. */
+interface PageResult {
+    /** Page title. */
+    title: string;
+    /** Final URL after redirects. */
+    url: string;
+    /** Page body text (truncated to ~8KB). */
+    text: string;
+    /** First 50 links on the page. */
+    links: PageLink[];
+}
+/** ARIA accessibility tree snapshot of a web page (v2). */
+interface AriaSnapshot {
+    /** ARIA tree as YAML. */
+    snapshot: string;
+    /** Current page URL. */
+    url: string;
+    /** Page title. */
+    title: string;
+    /** Available ref IDs (e.g. ["e1", "e2", ...]). */
+    refs: string[];
+}
+/** A browser interaction event for debugging and context recovery. */
+interface BrowserEvent {
+    /** Monotonic sequence number. */
+    seq: number;
+    /** Event type (e.g. "page.navigated", "page.clicked"). */
+    type: string;
+    /** Page name. */
+    page: string;
+    /** ISO 8601 timestamp. */
+    ts: string;
+}
+
+/**
+ * Browser session for orchestrating headless browsers in sandboxes.
+ *
+ * Each method generates a self-contained Python/Playwright script,
+ * runs it inside the sandbox, and parses the JSON result.
+ */
+
+type RunInSandboxFn = (name: string, command: string[]) => Promise<RunOutput>;
+type RemoveSandboxFn = (name: string) => Promise<void>;
+/** Command to install Playwright + Chromium inside the sandbox. */
+declare const BROWSER_SETUP_CMD: string[];
+/**
+ * A sandboxed headless browser controlled from outside.
+ *
+ * The browser (Chromium via Playwright) runs inside an agentkernel sandbox.
+ * You call high-level methods; the SDK generates and runs scripts internally.
+ *
+ * @example
+ * ```ts
+ * await using browser = await client.browser("my-browser");
+ * const page = await browser.goto("https://example.com");
+ * console.log(page.title, page.links);
+ * ```
+ */
+declare class BrowserSession implements AsyncDisposable {
+    readonly name: string;
+    private _removed;
+    private _lastUrl;
+    private readonly _run;
+    private readonly _remove;
+    /** @internal */
+    constructor(name: string, runFn: RunInSandboxFn, removeFn: RemoveSandboxFn);
+    /** Navigate to a URL and return page data (title, text, links). */
+    goto(url: string): Promise<PageResult>;
+    /** Take a PNG screenshot. Returns a base64-encoded string. */
+    screenshot(url?: string): Promise<string>;
+    /** Run a JavaScript expression on a page and return the result. */
+    evaluate(expression: string, url?: string): Promise<unknown>;
+    /** Navigate to a URL and return an ARIA snapshot. */
+    open(url: string, page?: string): Promise<AriaSnapshot>;
+    /** Get the current ARIA snapshot without navigating. */
+    snapshot(page?: string): Promise<AriaSnapshot>;
+    /** Click an element by ref ID or CSS selector. Returns new snapshot. */
+    click(opts: {
+        ref?: string;
+        selector?: string;
+        page?: string;
+    }): Promise<AriaSnapshot>;
+    /** Fill an input by ref ID or CSS selector. Returns new snapshot. */
+    fill(value: string, opts: {
+        ref?: string;
+        selector?: string;
+        page?: string;
+    }): Promise<AriaSnapshot>;
+    /** Close a named page. */
+    closePage(page?: string): Promise<void>;
+    /** List active page names. */
+    listPages(): Promise<string[]>;
+    private _serverStarted;
+    private _ensureServer;
+    private _browserRequest;
+    /** Remove the sandbox. Idempotent. */
+    remove(): Promise<void>;
+    /** Auto-cleanup for `await using`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
 
 type ExecFn = (name: string, command: string[], opts?: ExecOptions) => Promise<RunOutput>;
 type RemoveFn = (name: string) => Promise<void>;
@@ -230,6 +362,35 @@ declare class AgentKernel {
      * ```
      */
     sandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxSession>;
+    /**
+     * Create a sandboxed browser session with automatic cleanup.
+     *
+     * Creates a sandbox with Chromium pre-installed via Playwright.
+     * Use `goto()`, `screenshot()`, and `evaluate()` to interact with web pages.
+     *
+     * @example
+     * ```ts
+     * await using browser = await client.browser("my-browser");
+     * const page = await browser.goto("https://example.com");
+     * console.log(page.title, page.links);
+     * // sandbox auto-removed when scope exits
+     * ```
+     */
+    browser(name: string, opts?: {
+        memory_mb?: number;
+    }): Promise<BrowserSession>;
+    /** Extend a sandbox's TTL. Returns the new expiry time. */
+    extendTtl(name: string, opts: ExtendTtlOptions): Promise<ExtendTtlResponse>;
+    /** List all snapshots. */
+    listSnapshots(): Promise<SnapshotMeta[]>;
+    /** Take a snapshot of a sandbox. */
+    takeSnapshot(opts: TakeSnapshotOptions): Promise<SnapshotMeta>;
+    /** Get info about a snapshot. */
+    getSnapshot(name: string): Promise<SnapshotMeta>;
+    /** Delete a snapshot. */
+    deleteSnapshot(name: string): Promise<void>;
+    /** Restore a sandbox from a snapshot. */
+    restoreSnapshot(name: string): Promise<SandboxInfo>;
     private headers;
     private fetch;
     private request;
@@ -268,4 +429,4 @@ declare class StreamError extends AgentKernelError {
     constructor(message?: string);
 }
 
-export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, AuthError, type BatchFileWriteResponse, type CreateSandboxOptions, type DetachedCommand, type DetachedLogsResponse, type DetachedStatus, type ExecOptions, NetworkError, NotFoundError, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type SecurityProfile, ServerError, StreamError, type StreamEvent, type StreamEventType, ValidationError };
+export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, type AriaSnapshot, AuthError, BROWSER_SETUP_CMD, type BatchFileWriteResponse, type BrowserEvent, BrowserSession, type CreateSandboxOptions, type DetachedCommand, type DetachedLogsResponse, type DetachedStatus, type ExecOptions, type ExtendTtlOptions, type ExtendTtlResponse, NetworkError, NotFoundError, type PageLink, type PageResult, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type SecurityProfile, ServerError, type SnapshotMeta, StreamError, type StreamEvent, type StreamEventType, type TakeSnapshotOptions, ValidationError };

package/dist/index.d.ts

@@ -115,6 +115,138 @@ interface ApiResponse<T> {
     data?: T;
     error?: string;
 }
+/** Response from extending a sandbox's TTL. */
+interface ExtendTtlResponse {
+    expires_at?: string;
+}
+/** Options for extending TTL. */
+interface ExtendTtlOptions {
+    /** Duration string like "1h", "30m", "2d". */
+    by: string;
+}
+/** Metadata for a sandbox snapshot. */
+interface SnapshotMeta {
+    name: string;
+    sandbox: string;
+    image_tag: string;
+    backend: string;
+    base_image?: string;
+    vcpus?: number;
+    memory_mb?: number;
+    created_at: string;
+}
+/** Options for taking a snapshot. */
+interface TakeSnapshotOptions {
+    /** Name of the sandbox to snapshot. */
+    sandbox: string;
+    /** Optional snapshot name (auto-generated if not provided). */
+    name?: string;
+}
+/** A link extracted from a web page. */
+interface PageLink {
+    text: string;
+    href: string;
+}
+/** Result of navigating to a web page. */
+interface PageResult {
+    /** Page title. */
+    title: string;
+    /** Final URL after redirects. */
+    url: string;
+    /** Page body text (truncated to ~8KB). */
+    text: string;
+    /** First 50 links on the page. */
+    links: PageLink[];
+}
+/** ARIA accessibility tree snapshot of a web page (v2). */
+interface AriaSnapshot {
+    /** ARIA tree as YAML. */
+    snapshot: string;
+    /** Current page URL. */
+    url: string;
+    /** Page title. */
+    title: string;
+    /** Available ref IDs (e.g. ["e1", "e2", ...]). */
+    refs: string[];
+}
+/** A browser interaction event for debugging and context recovery. */
+interface BrowserEvent {
+    /** Monotonic sequence number. */
+    seq: number;
+    /** Event type (e.g. "page.navigated", "page.clicked"). */
+    type: string;
+    /** Page name. */
+    page: string;
+    /** ISO 8601 timestamp. */
+    ts: string;
+}
+
+/**
+ * Browser session for orchestrating headless browsers in sandboxes.
+ *
+ * Each method generates a self-contained Python/Playwright script,
+ * runs it inside the sandbox, and parses the JSON result.
+ */
+
+type RunInSandboxFn = (name: string, command: string[]) => Promise<RunOutput>;
+type RemoveSandboxFn = (name: string) => Promise<void>;
+/** Command to install Playwright + Chromium inside the sandbox. */
+declare const BROWSER_SETUP_CMD: string[];
+/**
+ * A sandboxed headless browser controlled from outside.
+ *
+ * The browser (Chromium via Playwright) runs inside an agentkernel sandbox.
+ * You call high-level methods; the SDK generates and runs scripts internally.
+ *
+ * @example
+ * ```ts
+ * await using browser = await client.browser("my-browser");
+ * const page = await browser.goto("https://example.com");
+ * console.log(page.title, page.links);
+ * ```
+ */
+declare class BrowserSession implements AsyncDisposable {
+    readonly name: string;
+    private _removed;
+    private _lastUrl;
+    private readonly _run;
+    private readonly _remove;
+    /** @internal */
+    constructor(name: string, runFn: RunInSandboxFn, removeFn: RemoveSandboxFn);
+    /** Navigate to a URL and return page data (title, text, links). */
+    goto(url: string): Promise<PageResult>;
+    /** Take a PNG screenshot. Returns a base64-encoded string. */
+    screenshot(url?: string): Promise<string>;
+    /** Run a JavaScript expression on a page and return the result. */
+    evaluate(expression: string, url?: string): Promise<unknown>;
+    /** Navigate to a URL and return an ARIA snapshot. */
+    open(url: string, page?: string): Promise<AriaSnapshot>;
+    /** Get the current ARIA snapshot without navigating. */
+    snapshot(page?: string): Promise<AriaSnapshot>;
+    /** Click an element by ref ID or CSS selector. Returns new snapshot. */
+    click(opts: {
+        ref?: string;
+        selector?: string;
+        page?: string;
+    }): Promise<AriaSnapshot>;
+    /** Fill an input by ref ID or CSS selector. Returns new snapshot. */
+    fill(value: string, opts: {
+        ref?: string;
+        selector?: string;
+        page?: string;
+    }): Promise<AriaSnapshot>;
+    /** Close a named page. */
+    closePage(page?: string): Promise<void>;
+    /** List active page names. */
+    listPages(): Promise<string[]>;
+    private _serverStarted;
+    private _ensureServer;
+    private _browserRequest;
+    /** Remove the sandbox. Idempotent. */
+    remove(): Promise<void>;
+    /** Auto-cleanup for `await using`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
 
 type ExecFn = (name: string, command: string[], opts?: ExecOptions) => Promise<RunOutput>;
 type RemoveFn = (name: string) => Promise<void>;
@@ -230,6 +362,35 @@ declare class AgentKernel {
      * ```
      */
     sandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxSession>;
+    /**
+     * Create a sandboxed browser session with automatic cleanup.
+     *
+     * Creates a sandbox with Chromium pre-installed via Playwright.
+     * Use `goto()`, `screenshot()`, and `evaluate()` to interact with web pages.
+     *
+     * @example
+     * ```ts
+     * await using browser = await client.browser("my-browser");
+     * const page = await browser.goto("https://example.com");
+     * console.log(page.title, page.links);
+     * // sandbox auto-removed when scope exits
+     * ```
+     */
+    browser(name: string, opts?: {
+        memory_mb?: number;
+    }): Promise<BrowserSession>;
+    /** Extend a sandbox's TTL. Returns the new expiry time. */
+    extendTtl(name: string, opts: ExtendTtlOptions): Promise<ExtendTtlResponse>;
+    /** List all snapshots. */
+    listSnapshots(): Promise<SnapshotMeta[]>;
+    /** Take a snapshot of a sandbox. */
+    takeSnapshot(opts: TakeSnapshotOptions): Promise<SnapshotMeta>;
+    /** Get info about a snapshot. */
+    getSnapshot(name: string): Promise<SnapshotMeta>;
+    /** Delete a snapshot. */
+    deleteSnapshot(name: string): Promise<void>;
+    /** Restore a sandbox from a snapshot. */
+    restoreSnapshot(name: string): Promise<SandboxInfo>;
     private headers;
     private fetch;
     private request;
@@ -268,4 +429,4 @@ declare class StreamError extends AgentKernelError {
     constructor(message?: string);
 }
 
-export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, AuthError, type BatchFileWriteResponse, type CreateSandboxOptions, type DetachedCommand, type DetachedLogsResponse, type DetachedStatus, type ExecOptions, NetworkError, NotFoundError, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type SecurityProfile, ServerError, StreamError, type StreamEvent, type StreamEventType, ValidationError };
+export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, type AriaSnapshot, AuthError, BROWSER_SETUP_CMD, type BatchFileWriteResponse, type BrowserEvent, BrowserSession, type CreateSandboxOptions, type DetachedCommand, type DetachedLogsResponse, type DetachedStatus, type ExecOptions, type ExtendTtlOptions, type ExtendTtlResponse, NetworkError, NotFoundError, type PageLink, type PageResult, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type SecurityProfile, ServerError, type SnapshotMeta, StreamError, type StreamEvent, type StreamEventType, type TakeSnapshotOptions, ValidationError };

package/dist/index.js

@@ -79,6 +79,248 @@ function errorFromStatus(status, body) {
   }
 }
 
+// src/browser.ts
+var GOTO_SCRIPT = `
+import asyncio, json, sys
+from playwright.async_api import async_playwright
+async def main():
+    url = sys.argv[1]
+    async with async_playwright() as p:
+        b = await p.chromium.launch()
+        page = await b.new_page()
+        await page.goto(url, timeout=30000)
+        title = await page.title()
+        url_final = page.url
+        text = await page.evaluate("() => document.body.innerText.slice(0, 8000)")
+        links = await page.evaluate('''() =>
+            Array.from(document.querySelectorAll('a[href]'))
+                .slice(0, 50)
+                .map(a => ({text: a.textContent.trim(), href: a.href}))
+                .filter(l => l.href.startsWith("http"))
+        ''')
+        print(json.dumps({"title": title, "url": url_final, "text": text, "links": links}))
+        await b.close()
+asyncio.run(main())
+`;
+var SCREENSHOT_SCRIPT = `
+import asyncio, base64, sys
+from playwright.async_api import async_playwright
+async def main():
+    url = sys.argv[1]
+    async with async_playwright() as p:
+        b = await p.chromium.launch()
+        page = await b.new_page()
+        await page.goto(url, timeout=30000)
+        data = await page.screenshot()
+        print(base64.b64encode(data).decode())
+        await b.close()
+asyncio.run(main())
+`;
+var EVALUATE_SCRIPT = `
+import asyncio, json, sys
+from playwright.async_api import async_playwright
+async def main():
+    url = sys.argv[1]
+    expr = sys.argv[2]
+    async with async_playwright() as p:
+        b = await p.chromium.launch()
+        page = await b.new_page()
+        await page.goto(url, timeout=30000)
+        result = await page.evaluate(expr)
+        print(json.dumps(result))
+        await b.close()
+asyncio.run(main())
+`;
+var BROWSER_SETUP_CMD = [
+  "sh",
+  "-c",
+  "pip install -q playwright && playwright install --with-deps chromium"
+];
+var BROWSER_HEALTH_SCRIPT = `
+import json, urllib.request, sys
+port = sys.argv[1] if len(sys.argv) > 1 else "9222"
+try:
+    req = urllib.request.urlopen(f"http://127.0.0.1:{port}/health", timeout=5)
+    print(req.read().decode())
+except Exception as e:
+    print(json.dumps({"status": "down", "error": str(e)}))
+    sys.exit(1)
+`;
+var BROWSER_REQUEST_SCRIPT = `
+import json, urllib.request, sys
+port = sys.argv[1] if len(sys.argv) > 1 else "9222"
+method = sys.argv[2] if len(sys.argv) > 2 else "GET"
+path = sys.argv[3] if len(sys.argv) > 3 else "/health"
+body_str = sys.argv[4] if len(sys.argv) > 4 else None
+url = f"http://127.0.0.1:{port}{path}"
+data = body_str.encode() if body_str else None
+req = urllib.request.Request(url, data=data, method=method)
+if data:
+    req.add_header("Content-Type", "application/json")
+try:
+    resp = urllib.request.urlopen(req, timeout=60)
+    print(resp.read().decode())
+except urllib.error.HTTPError as e:
+    print(e.read().decode())
+    sys.exit(1)
+except Exception as e:
+    print(json.dumps({"error": str(e)}))
+    sys.exit(1)
+`;
+var BrowserSession = class {
+  name;
+  _removed = false;
+  _lastUrl = null;
+  _run;
+  _remove;
+  /** @internal */
+  constructor(name, runFn, removeFn) {
+    this.name = name;
+    this._run = runFn;
+    this._remove = removeFn;
+  }
+  /** Navigate to a URL and return page data (title, text, links). */
+  async goto(url) {
+    const result = await this._run(this.name, [
+      "python3",
+      "-c",
+      GOTO_SCRIPT,
+      url
+    ]);
+    this._lastUrl = url;
+    return JSON.parse(result.output);
+  }
+  /** Take a PNG screenshot. Returns a base64-encoded string. */
+  async screenshot(url) {
+    const target = url ?? this._lastUrl;
+    if (!target) {
+      throw new Error("No URL specified and no previous goto() call");
+    }
+    const result = await this._run(this.name, [
+      "python3",
+      "-c",
+      SCREENSHOT_SCRIPT,
+      target
+    ]);
+    return result.output.trim();
+  }
+  /** Run a JavaScript expression on a page and return the result. */
+  async evaluate(expression, url) {
+    const target = url ?? this._lastUrl;
+    if (!target) {
+      throw new Error("No URL specified and no previous goto() call");
+    }
+    const result = await this._run(this.name, [
+      "python3",
+      "-c",
+      EVALUATE_SCRIPT,
+      target,
+      expression
+    ]);
+    return JSON.parse(result.output);
+  }
+  // --- v2 methods (ARIA snapshots, persistent pages, ref-based interaction) ---
+  /** Navigate to a URL and return an ARIA snapshot. */
+  async open(url, page = "default") {
+    await this._ensureServer();
+    const result = await this._browserRequest(
+      "POST",
+      `/pages/${page}/goto`,
+      JSON.stringify({ url })
+    );
+    return JSON.parse(result.output);
+  }
+  /** Get the current ARIA snapshot without navigating. */
+  async snapshot(page = "default") {
+    await this._ensureServer();
+    const result = await this._browserRequest(
+      "GET",
+      `/pages/${page}/snapshot`
+    );
+    return JSON.parse(result.output);
+  }
+  /** Click an element by ref ID or CSS selector. Returns new snapshot. */
+  async click(opts) {
+    const page = opts.page ?? "default";
+    await this._ensureServer();
+    const body = {};
+    if (opts.ref) body.ref = opts.ref;
+    if (opts.selector) body.selector = opts.selector;
+    const result = await this._browserRequest(
+      "POST",
+      `/pages/${page}/click`,
+      JSON.stringify(body)
+    );
+    const data = JSON.parse(result.output);
+    if (data.error) throw new Error(data.error);
+    return data;
+  }
+  /** Fill an input by ref ID or CSS selector. Returns new snapshot. */
+  async fill(value, opts) {
+    const page = opts.page ?? "default";
+    await this._ensureServer();
+    const body = { value };
+    if (opts.ref) body.ref = opts.ref;
+    if (opts.selector) body.selector = opts.selector;
+    const result = await this._browserRequest(
+      "POST",
+      `/pages/${page}/fill`,
+      JSON.stringify(body)
+    );
+    const data = JSON.parse(result.output);
+    if (data.error) throw new Error(data.error);
+    return data;
+  }
+  /** Close a named page. */
+  async closePage(page = "default") {
+    await this._ensureServer();
+    await this._browserRequest("DELETE", `/pages/${page}`);
+  }
+  /** List active page names. */
+  async listPages() {
+    await this._ensureServer();
+    const result = await this._browserRequest("GET", "/pages");
+    const data = JSON.parse(result.output);
+    return data.pages ?? [];
+  }
+  _serverStarted = false;
+  async _ensureServer() {
+    if (this._serverStarted) return;
+    try {
+      const result = await this._run(this.name, [
+        "python3",
+        "-c",
+        BROWSER_HEALTH_SCRIPT,
+        "9222"
+      ]);
+      if (result.output.includes('"status":"ok"') || result.output.includes('"status": "ok"')) {
+        this._serverStarted = true;
+        return;
+      }
+    } catch {
+    }
+    throw new Error(
+      "Browser server not running. Use browser_create to set up the sandbox, or use the MCP browser_open tool which auto-starts the server."
+    );
+  }
+  async _browserRequest(method, path, body) {
+    const cmd = ["python3", "-c", BROWSER_REQUEST_SCRIPT, "9222", method, path];
+    if (body) cmd.push(body);
+    return this._run(this.name, cmd);
+  }
+  // --- v1 methods (backward compatible) ---
+  /** Remove the sandbox. Idempotent. */
+  async remove() {
+    if (this._removed) return;
+    this._removed = true;
+    await this._remove(this.name);
+  }
+  /** Auto-cleanup for `await using`. */
+  async [Symbol.asyncDispose]() {
+    await this.remove();
+  }
+};
+
 // src/sandbox.ts
 var SandboxSession = class {
   name;
@@ -189,7 +431,7 @@ async function* parseSSE(body) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.3.0";
 var AgentKernel = class {
   baseUrl;
   apiKey;
@@ -259,7 +501,8 @@ var AgentKernel = class {
       memory_mb: opts?.memory_mb,
       profile: opts?.profile,
       source_url: opts?.source_url,
-      source_ref: opts?.source_ref
+      source_ref: opts?.source_ref,
+      volumes: opts?.volumes
     });
   }
   /** Get info about a sandbox. */
@@ -389,6 +632,71 @@ var AgentKernel = class {
       (n, f) => this.writeFiles(n, f)
     );
   }
+  /**
+   * Create a sandboxed browser session with automatic cleanup.
+   *
+   * Creates a sandbox with Chromium pre-installed via Playwright.
+   * Use `goto()`, `screenshot()`, and `evaluate()` to interact with web pages.
+   *
+   * @example
+   * ```ts
+   * await using browser = await client.browser("my-browser");
+   * const page = await browser.goto("https://example.com");
+   * console.log(page.title, page.links);
+   * // sandbox auto-removed when scope exits
+   * ```
+   */
+  async browser(name, opts) {
+    await this.createSandbox(name, {
+      image: "python:3.12-slim",
+      memory_mb: opts?.memory_mb ?? 2048,
+      profile: "moderate"
+    });
+    await this.execInSandbox(name, BROWSER_SETUP_CMD);
+    return new BrowserSession(
+      name,
+      (n, cmd) => this.execInSandbox(n, cmd),
+      (n) => this.removeSandbox(n)
+    );
+  }
+  // -- TTL & Snapshot methods --
+  /** Extend a sandbox's TTL. Returns the new expiry time. */
+  async extendTtl(name, opts) {
+    return this.request(
+      "POST",
+      `/sandboxes/${encodeURIComponent(name)}/extend`,
+      { by: opts.by }
+    );
+  }
+  /** List all snapshots. */
+  async listSnapshots() {
+    return this.request("GET", "/snapshots");
+  }
+  /** Take a snapshot of a sandbox. */
+  async takeSnapshot(opts) {
+    return this.request("POST", "/snapshots", opts);
+  }
+  /** Get info about a snapshot. */
+  async getSnapshot(name) {
+    return this.request(
+      "GET",
+      `/snapshots/${encodeURIComponent(name)}`
+    );
+  }
+  /** Delete a snapshot. */
+  async deleteSnapshot(name) {
+    await this.request(
+      "DELETE",
+      `/snapshots/${encodeURIComponent(name)}`
+    );
+  }
+  /** Restore a sandbox from a snapshot. */
+  async restoreSnapshot(name) {
+    return this.request(
+      "POST",
+      `/snapshots/${encodeURIComponent(name)}/restore`
+    );
+  }
   // -- Internal helpers --
   headers(contentType) {
     const h = {
@@ -439,6 +747,8 @@ export {
   AgentKernel,
   AgentKernelError,
   AuthError,
+  BROWSER_SETUP_CMD,
+  BrowserSession,
   NetworkError,
   NotFoundError,
   SandboxSession,