agentkernel 0.19.0 → 0.20.0

package/dist/index.d.ts

@@ -1,520 +1,5 @@
-/** Security profile for sandbox execution. */
-type SecurityProfile = "permissive" | "moderate" | "restrictive";
-/** Sandbox status. */
-type SandboxStatus = "running" | "stopped";
-/** SSE event types emitted by /run/stream. */
-type StreamEventType = "started" | "progress" | "output" | "done" | "error";
-/** Configuration options for the AgentKernel client. */
-interface AgentKernelOptions {
-    /** Base URL of the agentkernel HTTP API. Default: AGENTKERNEL_BASE_URL or http://localhost:18888 */
-    baseUrl?: string;
-    /** API key for Bearer authentication. Default: AGENTKERNEL_API_KEY env var */
-    apiKey?: string;
-    /** Request timeout in milliseconds. Default: 30000 */
-    timeout?: number;
-}
-/** Options for the run command. */
-interface RunOptions {
-    /** Docker image to use (auto-detected if not specified). */
-    image?: string;
-    /** Security profile. Default: moderate */
-    profile?: SecurityProfile;
-    /** Use container pool for faster execution. Default: true */
-    fast?: boolean;
-}
-/** Options for creating a sandbox. */
-interface CreateSandboxOptions {
-    /** Docker image to use. Default: alpine:3.20 */
-    image?: string;
-    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[];
-    /**
-     * Secret bindings for proxy-based injection (Gondolin pattern).
-     * Secrets are injected as HTTP headers by the host proxy — they never enter the VM.
-     * Formats: "KEY=value:host", "KEY:host", "KEY:host:header"
-     */
-    secrets?: string[];
-    /**
-     * Secret keys to inject as files at /run/agentkernel/secrets/KEY.
-     * Values are resolved from the secret vault.
-     */
-    secret_files?: 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 {
-    output: string;
-}
-/** Information about a sandbox. */
-interface SandboxInfo {
-    name: string;
-    uuid?: string;
-    status: SandboxStatus;
-    backend: string;
-    image?: string;
-    vcpus?: number;
-    memory_mb?: number;
-    created_at?: string;
-}
-/** SSE stream event. */
-interface StreamEvent {
-    type: StreamEventType;
-    data: Record<string, unknown>;
-}
-/** Options for writing a file. */
-interface FileWriteOptions {
-    /** Content encoding: "utf8" (default) or "base64". */
-    encoding?: "utf8" | "base64";
-}
-/** Response from reading a file. */
-interface FileReadResponse {
-    content: string;
-    encoding: "utf8" | "base64";
-    size: number;
-}
-/** A command for batch execution. */
-interface BatchCommand {
-    command: string[];
-}
-/** Result of a single batch command. */
-interface BatchResult {
-    output: string | null;
-    error: string | null;
-}
-/** Response from batch execution. */
-interface BatchRunResponse {
-    results: BatchResult[];
-}
-/** Result of a batch file write. */
-interface BatchFileWriteResponse {
-    written: number;
-}
-/** Opaque orchestration payload/response body. */
-type Orchestration = Record<string, unknown>;
-type OrchestrationDefinition = Record<string, unknown>;
-/** Opaque object payload/response body. */
-type DurableObject = Record<string, unknown>;
-/** Opaque schedule payload/response body. */
-type Schedule = Record<string, unknown>;
-/** Opaque durable store payload/response body. */
-type DurableStore = Record<string, unknown>;
-type CreateStoreRequest = Record<string, unknown>;
-type DurableStoreQueryResponse = Record<string, unknown>;
-type DurableStoreExecuteResponse = Record<string, unknown>;
-type DurableStoreCommandResponse = Record<string, unknown>;
-/** 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;
-}
-/** Opaque payload used when creating orchestrations. */
-type CreateOrchestrationRequest = Record<string, unknown>;
-/** Opaque payload used when creating objects. */
-type CreateObjectRequest = Record<string, unknown>;
-/** Opaque payload used when creating schedules. */
-type CreateScheduleRequest = Record<string, unknown>;
-/** 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[];
-}
-/** 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>;
-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.
- *
- * Supports both explicit cleanup via remove() and automatic cleanup via
- * Symbol.asyncDispose (TS 5.2+ `await using`).
- *
- * @example
- * ```ts
- * await using sb = await client.sandbox("test");
- * await sb.exec(["echo", "hello"]);
- * // sandbox auto-removed when scope exits
- * ```
- */
-declare class SandboxSession implements AsyncDisposable {
-    readonly name: string;
-    private _removed;
-    private readonly _execInSandbox;
-    private readonly _removeSandbox;
-    private readonly _getSandbox;
-    private readonly _writeFiles;
-    /** @internal */
-    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn, writeFiles: WriteFilesFn);
-    /** Run a command in this sandbox. */
-    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`. */
-    [Symbol.asyncDispose](): Promise<void>;
-}
-
-/**
- * Client for the agentkernel HTTP API.
- *
- * @example
- * ```ts
- * const client = new AgentKernel();
- * const result = await client.run(["echo", "hello"]);
- * console.log(result.output); // "hello\n"
- * ```
- */
-declare class AgentKernel {
-    private readonly baseUrl;
-    private readonly apiKey;
-    private readonly timeout;
-    constructor(opts?: AgentKernelOptions);
-    /** Health check. Returns "ok" if the server is running. */
-    health(): Promise<string>;
-    /** Run a command in a temporary sandbox. */
-    run(command: string[], opts?: RunOptions): Promise<RunOutput>;
-    /**
-     * Run a command with SSE streaming output.
-     *
-     * @example
-     * ```ts
-     * for await (const event of client.runStream(["python3", "script.py"])) {
-     *   if (event.type === "output") process.stdout.write(String(event.data.data));
-     * }
-     * ```
-     */
-    runStream(command: string[], opts?: RunOptions): AsyncGenerator<StreamEvent>;
-    /** List all sandboxes. */
-    listSandboxes(): Promise<SandboxInfo[]>;
-    /** Create a new sandbox. */
-    createSandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxInfo>;
-    /** Get info about a sandbox. */
-    getSandbox(name: string): Promise<SandboxInfo>;
-    /** Get info about a sandbox by UUID. */
-    getSandboxByUuid(uuid: string): Promise<SandboxInfo>;
-    /** Remove a sandbox. */
-    removeSandbox(name: string): Promise<void>;
-    /** Run a command in an existing sandbox. */
-    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. */
-    writeFile(name: string, path: string, content: string, opts?: FileWriteOptions): Promise<string>;
-    /** Delete a file from a sandbox. */
-    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[]>;
-    /** List all orchestrations. */
-    listOrchestrations(): Promise<Orchestration[]>;
-    /** Create a new orchestration. */
-    createOrchestration(payload: CreateOrchestrationRequest): Promise<Orchestration>;
-    /** Get info about an orchestration by identifier. */
-    getOrchestration(id: string): Promise<Orchestration>;
-    /** Raise an external event for an orchestration. */
-    signalOrchestration(id: string, payload: Record<string, unknown>): Promise<Orchestration>;
-    /** Terminate an orchestration. */
-    terminateOrchestration(id: string, payload?: Record<string, unknown>): Promise<Orchestration>;
-    /** List orchestration definitions. */
-    listOrchestrationDefinitions(): Promise<OrchestrationDefinition[]>;
-    /** Register or update an orchestration definition. */
-    upsertOrchestrationDefinition(payload: OrchestrationDefinition): Promise<OrchestrationDefinition>;
-    /** Get an orchestration definition by name. */
-    getOrchestrationDefinition(name: string): Promise<OrchestrationDefinition>;
-    /** Delete an orchestration definition by name. */
-    deleteOrchestrationDefinition(name: string): Promise<string>;
-    /** List all objects. */
-    listObjects(): Promise<DurableObject[]>;
-    /** Create a new object. */
-    createObject(payload: CreateObjectRequest): Promise<DurableObject>;
-    /** Get an object by identifier. */
-    getObject(id: string): Promise<DurableObject>;
-    /** Call a method on a durable object (auto-creates/wakes if needed). */
-    callObject(className: string, objectId: string, method: string, args?: Record<string, unknown>): Promise<unknown>;
-    /** Delete a durable object by identifier. */
-    deleteObject(id: string): Promise<string>;
-    /** Partially update a durable object (storage and/or status). */
-    patchObject(id: string, payload: {
-        storage?: unknown;
-        status?: string;
-    }): Promise<DurableObject>;
-    /** List all schedules. */
-    listSchedules(): Promise<Schedule[]>;
-    /** Create a new schedule. */
-    createSchedule(payload: CreateScheduleRequest): Promise<Schedule>;
-    /** Get a schedule by identifier. */
-    getSchedule(id: string): Promise<Schedule>;
-    /** Delete a schedule by identifier. */
-    deleteSchedule(id: string): Promise<string>;
-    /** List all durable stores. */
-    listStores(): Promise<DurableStore[]>;
-    /** Create a durable store. */
-    createStore(payload: CreateStoreRequest): Promise<DurableStore>;
-    /** Get a durable store by identifier. */
-    getStore(id: string): Promise<DurableStore>;
-    /** Delete a durable store by identifier. */
-    deleteStore(id: string): Promise<string>;
-    /** Execute a read query against a durable store. */
-    queryStore(id: string, payload: Record<string, unknown>): Promise<DurableStoreQueryResponse>;
-    /** Execute a write statement against a durable store. */
-    executeStore(id: string, payload: Record<string, unknown>): Promise<DurableStoreExecuteResponse>;
-    /** Execute a command against a durable store (Redis-style engines). */
-    commandStore(id: string, payload: Record<string, unknown>): Promise<DurableStoreCommandResponse>;
-    /**
-     * Create a sandbox session with automatic cleanup.
-     *
-     * The returned SandboxSession implements AsyncDisposable,
-     * so it works with `await using` (TS 5.2+):
-     *
-     * @example
-     * ```ts
-     * await using sb = await client.sandbox("test", { image: "python:3.12-alpine" });
-     * await sb.run(["pip", "install", "numpy"]);
-     * // sandbox auto-removed when scope exits
-     * ```
-     */
-    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;
-}
-
-/** Base error for all agentkernel SDK errors. */
-declare class AgentKernelError extends Error {
-    constructor(message: string);
-}
-/** 401 Unauthorized. */
-declare class AuthError extends AgentKernelError {
-    readonly status = 401;
-    constructor(message?: string);
-}
-/** 404 Not Found. */
-declare class NotFoundError extends AgentKernelError {
-    readonly status = 404;
-    constructor(message?: string);
-}
-/** 400 Bad Request. */
-declare class ValidationError extends AgentKernelError {
-    readonly status = 400;
-    constructor(message?: string);
-}
-/** 500 Internal Server Error. */
-declare class ServerError extends AgentKernelError {
-    readonly status = 500;
-    constructor(message?: string);
-}
-/** Network / connection error. */
-declare class NetworkError extends AgentKernelError {
-    constructor(message?: string);
-}
-/** SSE streaming error. */
-declare class StreamError extends AgentKernelError {
-    constructor(message?: string);
-}
-
-export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, type AriaSnapshot, AuthError, BROWSER_SETUP_CMD, type BatchFileWriteResponse, type BrowserEvent, BrowserSession, type CreateObjectRequest, type CreateOrchestrationRequest, type CreateSandboxOptions, type CreateScheduleRequest, type CreateStoreRequest, type DetachedCommand, type DetachedLogsResponse, type DetachedStatus, type DurableObject, type DurableStore, type DurableStoreCommandResponse, type DurableStoreExecuteResponse, type DurableStoreQueryResponse, type ExecOptions, type ExtendTtlOptions, type ExtendTtlResponse, NetworkError, NotFoundError, type Orchestration, type OrchestrationDefinition, type PageLink, type PageResult, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type Schedule, type SecurityProfile, ServerError, type SnapshotMeta, StreamError, type StreamEvent, type StreamEventType, type TakeSnapshotOptions, ValidationError };
+export { AgentKernel } from "./client.js";
+export { BrowserSession, BROWSER_SETUP_CMD } from "./browser.js";
+export { SandboxSession } from "./sandbox.js";
+export { AgentKernelError, AuthError, NotFoundError, ValidationError, ServerError, NetworkError, StreamError, } from "./errors.js";
+export type { AgentKernelOptions, AriaSnapshot, BatchFileWriteResponse, BrowserEvent, CreateSandboxOptions, CreateObjectRequest, CreateOrchestrationRequest, CreateScheduleRequest, CreateStoreRequest, DetachedCommand, DetachedLogsResponse, DetachedStatus, ExecOptions, ExtendTtlOptions, ExtendTtlResponse, DurableObject, DurableStore, DurableStoreCommandResponse, DurableStoreExecuteResponse, DurableStoreQueryResponse, PageLink, PageResult, RunOptions, RunOutput, Orchestration, OrchestrationDefinition, SandboxInfo, SnapshotMeta, StreamEvent, StreamEventType, SecurityProfile, SandboxStatus, Schedule, TakeSnapshotOptions, ApiResponse, } from "./types.js";