agentkernel 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -29,6 +29,21 @@ interface CreateSandboxOptions {
     vcpus?: number;
     memory_mb?: number;
     profile?: SecurityProfile;
+    /** Git repository URL to clone into the sandbox. */
+    source_url?: string;
+    /** Git ref to checkout after cloning. */
+    source_ref?: string;
+    /** Volume mounts (slug:/path or slug:/path:ro). Create volumes via CLI first. */
+    volumes?: string[];
+}
+/** Options for executing a command in a sandbox. */
+interface ExecOptions {
+    /** Environment variables (KEY=VALUE). */
+    env?: string[];
+    /** Working directory inside the container. */
+    workdir?: string;
+    /** Run as root. */
+    sudo?: boolean;
 }
 /** Output from a command execution. */
 interface RunOutput {
@@ -73,16 +88,125 @@ interface BatchResult {
 interface BatchRunResponse {
     results: BatchResult[];
 }
+/** Result of a batch file write. */
+interface BatchFileWriteResponse {
+    written: number;
+}
+/** Status of a detached command. */
+type DetachedStatus = "running" | "completed" | "failed";
+/** A detached (background) command running in a sandbox. */
+interface DetachedCommand {
+    id: string;
+    sandbox: string;
+    command: string[];
+    pid: number;
+    status: DetachedStatus;
+    exit_code: number | null;
+    started_at: string;
+}
+/** Response from detached command logs. */
+interface DetachedLogsResponse {
+    stdout?: string;
+    stderr?: string;
+}
 /** API response wrapper. */
 interface ApiResponse<T> {
     success: boolean;
     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[];
+}
 
-type ExecFn = (name: string, command: string[]) => Promise<RunOutput>;
+/**
+ * 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>;
+    /** 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>;
 type GetFn = (name: string) => Promise<SandboxInfo>;
+type WriteFilesFn = (name: string, files: Record<string, string>) => Promise<BatchFileWriteResponse>;
 /**
  * A sandbox session that auto-removes the sandbox on dispose.
  *
@@ -102,12 +226,15 @@ declare class SandboxSession implements AsyncDisposable {
     private readonly _execInSandbox;
     private readonly _removeSandbox;
     private readonly _getSandbox;
+    private readonly _writeFiles;
     /** @internal */
-    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn);
+    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn, writeFiles: WriteFilesFn);
     /** Run a command in this sandbox. */
-    run(command: string[]): Promise<RunOutput>;
+    run(command: string[], opts?: ExecOptions): Promise<RunOutput>;
     /** Get sandbox info. */
     info(): Promise<SandboxInfo>;
+    /** Write multiple files in one request. */
+    writeFiles(files: Record<string, string>): Promise<BatchFileWriteResponse>;
     /** Remove the sandbox. Idempotent. */
     remove(): Promise<void>;
     /** Auto-cleanup for `await using`. */
@@ -153,7 +280,7 @@ declare class AgentKernel {
     /** Remove a sandbox. */
     removeSandbox(name: string): Promise<void>;
     /** Run a command in an existing sandbox. */
-    execInSandbox(name: string, command: string[]): Promise<RunOutput>;
+    execInSandbox(name: string, command: string[], opts?: ExecOptions): Promise<RunOutput>;
     /** Read a file from a sandbox. */
     readFile(name: string, path: string): Promise<FileReadResponse>;
     /** Write a file to a sandbox. */
@@ -162,8 +289,20 @@ declare class AgentKernel {
     deleteFile(name: string, path: string): Promise<string>;
     /** Get audit log entries for a sandbox. */
     getSandboxLogs(name: string): Promise<Record<string, unknown>[]>;
+    /** Write multiple files to a sandbox in one request. */
+    writeFiles(name: string, files: Record<string, string>): Promise<BatchFileWriteResponse>;
     /** Run multiple commands in parallel. */
     batchRun(commands: BatchCommand[]): Promise<BatchRunResponse>;
+    /** Start a detached (background) command in a sandbox. */
+    execDetached(name: string, command: string[], opts?: ExecOptions): Promise<DetachedCommand>;
+    /** Get the status of a detached command. */
+    detachedStatus(name: string, cmdId: string): Promise<DetachedCommand>;
+    /** Get logs from a detached command. */
+    detachedLogs(name: string, cmdId: string, stream?: "stdout" | "stderr"): Promise<DetachedLogsResponse>;
+    /** Kill a detached command. */
+    detachedKill(name: string, cmdId: string): Promise<string>;
+    /** List detached commands in a sandbox. */
+    detachedList(name: string): Promise<DetachedCommand[]>;
     /**
      * Create a sandbox session with automatic cleanup.
      *
@@ -178,6 +317,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;
@@ -216,4 +384,4 @@ declare class StreamError extends AgentKernelError {
     constructor(message?: string);
 }
 
-export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, AuthError, type CreateSandboxOptions, 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, AuthError, BROWSER_SETUP_CMD, type BatchFileWriteResponse, 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

@@ -29,6 +29,21 @@ interface CreateSandboxOptions {
     vcpus?: number;
     memory_mb?: number;
     profile?: SecurityProfile;
+    /** Git repository URL to clone into the sandbox. */
+    source_url?: string;
+    /** Git ref to checkout after cloning. */
+    source_ref?: string;
+    /** Volume mounts (slug:/path or slug:/path:ro). Create volumes via CLI first. */
+    volumes?: string[];
+}
+/** Options for executing a command in a sandbox. */
+interface ExecOptions {
+    /** Environment variables (KEY=VALUE). */
+    env?: string[];
+    /** Working directory inside the container. */
+    workdir?: string;
+    /** Run as root. */
+    sudo?: boolean;
 }
 /** Output from a command execution. */
 interface RunOutput {
@@ -73,16 +88,125 @@ interface BatchResult {
 interface BatchRunResponse {
     results: BatchResult[];
 }
+/** Result of a batch file write. */
+interface BatchFileWriteResponse {
+    written: number;
+}
+/** Status of a detached command. */
+type DetachedStatus = "running" | "completed" | "failed";
+/** A detached (background) command running in a sandbox. */
+interface DetachedCommand {
+    id: string;
+    sandbox: string;
+    command: string[];
+    pid: number;
+    status: DetachedStatus;
+    exit_code: number | null;
+    started_at: string;
+}
+/** Response from detached command logs. */
+interface DetachedLogsResponse {
+    stdout?: string;
+    stderr?: string;
+}
 /** API response wrapper. */
 interface ApiResponse<T> {
     success: boolean;
     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[];
+}
 
-type ExecFn = (name: string, command: string[]) => Promise<RunOutput>;
+/**
+ * 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>;
+    /** 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>;
 type GetFn = (name: string) => Promise<SandboxInfo>;
+type WriteFilesFn = (name: string, files: Record<string, string>) => Promise<BatchFileWriteResponse>;
 /**
  * A sandbox session that auto-removes the sandbox on dispose.
  *
@@ -102,12 +226,15 @@ declare class SandboxSession implements AsyncDisposable {
     private readonly _execInSandbox;
     private readonly _removeSandbox;
     private readonly _getSandbox;
+    private readonly _writeFiles;
     /** @internal */
-    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn);
+    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn, writeFiles: WriteFilesFn);
     /** Run a command in this sandbox. */
-    run(command: string[]): Promise<RunOutput>;
+    run(command: string[], opts?: ExecOptions): Promise<RunOutput>;
     /** Get sandbox info. */
     info(): Promise<SandboxInfo>;
+    /** Write multiple files in one request. */
+    writeFiles(files: Record<string, string>): Promise<BatchFileWriteResponse>;
     /** Remove the sandbox. Idempotent. */
     remove(): Promise<void>;
     /** Auto-cleanup for `await using`. */
@@ -153,7 +280,7 @@ declare class AgentKernel {
     /** Remove a sandbox. */
     removeSandbox(name: string): Promise<void>;
     /** Run a command in an existing sandbox. */
-    execInSandbox(name: string, command: string[]): Promise<RunOutput>;
+    execInSandbox(name: string, command: string[], opts?: ExecOptions): Promise<RunOutput>;
     /** Read a file from a sandbox. */
     readFile(name: string, path: string): Promise<FileReadResponse>;
     /** Write a file to a sandbox. */
@@ -162,8 +289,20 @@ declare class AgentKernel {
     deleteFile(name: string, path: string): Promise<string>;
     /** Get audit log entries for a sandbox. */
     getSandboxLogs(name: string): Promise<Record<string, unknown>[]>;
+    /** Write multiple files to a sandbox in one request. */
+    writeFiles(name: string, files: Record<string, string>): Promise<BatchFileWriteResponse>;
     /** Run multiple commands in parallel. */
     batchRun(commands: BatchCommand[]): Promise<BatchRunResponse>;
+    /** Start a detached (background) command in a sandbox. */
+    execDetached(name: string, command: string[], opts?: ExecOptions): Promise<DetachedCommand>;
+    /** Get the status of a detached command. */
+    detachedStatus(name: string, cmdId: string): Promise<DetachedCommand>;
+    /** Get logs from a detached command. */
+    detachedLogs(name: string, cmdId: string, stream?: "stdout" | "stderr"): Promise<DetachedLogsResponse>;
+    /** Kill a detached command. */
+    detachedKill(name: string, cmdId: string): Promise<string>;
+    /** List detached commands in a sandbox. */
+    detachedList(name: string): Promise<DetachedCommand[]>;
     /**
      * Create a sandbox session with automatic cleanup.
      *
@@ -178,6 +317,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;
@@ -216,4 +384,4 @@ declare class StreamError extends AgentKernelError {
     constructor(message?: string);
 }
 
-export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, AuthError, type CreateSandboxOptions, 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, AuthError, BROWSER_SETUP_CMD, type BatchFileWriteResponse, 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 };