agentenkit 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,8 @@
 
 A durable runtime for AI agent runs, as a **library**.
 
-It does not own your prompts, models, or tools — the [AI SDK](https://sdk.vercel.ai) does.
+It does not own your prompts, models, or tools — the [AI SDK](https://sdk.vercel.ai) does —
+though it ships a few [built-in tools](#built-in-tools) any model can use.
 It owns the **lifecycle of a run**: that a run outlives the request that started it,
 survives a worker dying mid-step, can be stopped, parked for a human, resumed exactly
 where it stopped, nested, metered, and watched by several people at once.
@@ -16,14 +17,14 @@ now describe that behaviour.
 
 ## Running locally, with nothing to stand up
 
-There is no `createDevRuntime`. Assembling the platform is four adapters and one wire,
+There is no `createDevRuntime`. Assembling the platform is five adapters and one wire,
 and seeing them is the point — swapping any of them for the durable equivalent later is
 then obvious rather than magic.
 
 ```ts
 import { Database } from 'bun:sqlite';           // or node:sqlite — see openSqlite
 import { setupAgentCore } from 'agentenkit';
-import { SqliteStorage } from 'agentenkit/adapters/sqlite';
+import { SqliteRunStreams, SqliteStorage } from 'agentenkit/adapters/sqlite';
 import { InlineQueue } from 'agentenkit/adapters/inline';
 import { MemoryBus, MemoryKv } from 'agentenkit/adapters/memory';
 import { SqliteAdminStore } from 'agentenkit/admin/sqlite';
@@ -36,6 +37,7 @@ const queue = new InlineQueue();
 
 export const runtime = await setupAgentCore({
   storage: new SqliteStorage(db),      // ← later: PrismaStorage, or your own
+  streams: new SqliteRunStreams(db),   // ← later: RedisRunStreams, PrismaRunStreams
   admin: SqliteAdminStore.open(db),     // ← later: PostgresAdminStore
   bus: new MemoryBus(),                // ← later: RedisBus
   kv: new MemoryKv(),                  // ← later: RedisKv
@@ -79,7 +81,7 @@ import { createClient } from 'redis';
 import { PrismaClient } from '@prisma/client';
 import { setupAgentCore } from 'agentenkit';
 import { PrismaStorage } from 'agentenkit/adapters/prisma';
-import { RedisBus, RedisKv } from 'agentenkit/adapters/redis';
+import { RedisBus, RedisKv, RedisRunStreams } from 'agentenkit/adapters/redis';
 import { QStashQueue } from 'agentenkit/adapters/qstash';
 
 const redis = createClient({ url: process.env.REDIS_URL });
@@ -93,6 +95,7 @@ export const runtime = await setupAgentCore({
     { url: 'https://app.example.com/api/queue/agent-run' },
   ),
   kv: new RedisKv(redis),
+  streams: new RedisRunStreams(redis),             // ← one stream per run segment
   // `admin` omitted on purpose: with AGENTIC_KIT_ADMIN_DATABASE_URL set, the
   // platform opens Postgres for its own history (§2.9). Pass one to override.
   resolveModel: (name) => ({ instance: () => models[name], contextWindow: 128_000 }),
@@ -110,16 +113,27 @@ await chat.run({ prompt: 'hi', state: { orgId } });      // persist + enqueue
 await chat.stop(threadId);                               // one write: state → CANCELLED (§2.1)
 await runtime.hitl.respond({ threadId, toolCallId, approved, payload, state });  // §2.5
 await runtime.getThreadSnapshot(threadId, state);        // hydrate a client (§2.2)
-const { stream, headers } = runtime.events.sse(threadId, { since, signal }); // SSE, any framework
-for await (const e of runtime.events.follow(threadId, { signal })) { … }     // or iterate
-const missed = await runtime.events.since(threadId, lastSeq);              // raw replay
-const unsub  = await runtime.events.subscribe(threadId, handler);          // raw tail
+const { stream, headers } = runtime.events.sse(threadId, { cursor, lastMessageId, signal }); // SSE, any framework
+for await (const frame of runtime.events.follow(threadId, { cursor, signal })) { … }    // or iterate
+for await (const item of runtime.streams.read(streamId, null, signal)) { … }          // one run stream
+const missed = await runtime.events.since(threadId, lastSeq);              // the thread record, raw
+const unsub  = await runtime.events.subscribe(threadId, handler);          // raw tail of the bus
 await runtime.worker.handleJob(job);                     // queue consumer (§2.8)
-await runtime.events.publishEvent(threadId, 'MY_EVENT', payload); // your own event, same pipe
+await runtime.events.publishEvent(threadId, 'MY_EVENT', payload);                     // your own event, live only
+await runtime.events.publishEvent(threadId, 'MY_EVENT', payload, { durable: true }); // …or kept in the record
+await runtime.pruneEvents({ dryRun: true });             // after upgrading: clear old stream-only rows
 ```
 
+A follow yields frames: `{ kind: 'thread', event }` (a record entry or a
+notice), `{ kind: 'stream', streamId, item }` (a run stream item) and
+`{ kind: 'snapshot', snapshot }` (sent once when the stream the client was
+reading is gone). The cursor is one string, `<seq> <streamId> <offset>`; every
+SSE frame that moves it carries it as its `id:`, so EventSource sends it back
+as `Last-Event-ID`. See [Run streams](../../docs/run-streams.md).
+
 Tools get `publishEvent` on their second argument, bound to their thread; see
-[Custom events](../../docs/custom-events.md).
+[Custom events](../../docs/custom-events.md). It is live only unless you pass
+`{ durable: true }`.
 
 The Next.js routes in [`examples/nextjs-app`](../../examples/nextjs-app) show the HTTP
 wiring — each handler is a few lines over the runtime.
@@ -154,10 +168,16 @@ declare module 'agentenkit' {
 
 | Port | Role | Reference adapter |
 | :--- | :--- | :--- |
-| `Storage` | threads / messages / events / usage — incl. atomic `claimState` | `PrismaStorage`, `SqliteStorage` |
+| `Storage` | threads / messages / the thread record / usage — incl. atomic `claimState` | `PrismaStorage`, `SqliteStorage` |
 | `EventBus` | live fan-out + HITL death notices (at-most-once) | `RedisBus`, `UpstashBus` |
 | `Queue` | durable run dispatch (at-least-once) | `QStashQueue`, `InlineQueue` (dev) |
-| `Kv` | hot state cache, HITL handoff keys, seq/attempt counters | `RedisKv`, `UpstashKv` |
+| `Kv` | hot state cache, HITL handoff keys, segment/attempt counters | `RedisKv`, `UpstashKv` |
+| `RunStreams` | one short-lived stream per run segment | `RedisRunStreams`, `UpstashRunStreams`, `PrismaRunStreams`, `SqliteRunStreams` |
+
+Leave `streams` out and they are kept in memory, with a warning logged once.
+Only that process can read them, so when web servers and workers run apart,
+pass a real one. `PrismaRunStreams` needs the `RunStream` and `RunStreamEvent`
+models from [the example schema](../../examples/nextjs-app/prisma/schema.prisma).
 
 Implement any of them for your own stack — `core/` imports nothing else. The
 [`Memory*` adapters](./src/adapters/memory.ts) are a complete implementation used by the
@@ -198,6 +218,51 @@ tokens.
 `chain`, to try one then the other. See
 [Cost and pricing](https://eadwincode.github.io/agentic-kit/cost-and-pricing).
 
+## Built-in tools
+
+Tools with one name and one input shape in both runtimes, so any model that can
+call tools can use them. What does the work is an adapter you pass in, with its
+API key, at setup; nothing reads the environment later.
+
+```ts
+import { BraveWebSearch, E2BSandbox, PageReader, setupAgentCore } from 'agentenkit';
+
+const runtime = await setupAgentCore({
+  // ... ports ...
+  tools: {
+    search: new BraveWebSearch({ apiKey: process.env.BRAVE_API_KEY! }),   // or JinaWebSearch
+    fetcher: new PageReader(),                                           // or JinaReader
+    sandbox: new E2BSandbox({ apiKey: process.env.E2B_API_KEY! }),        // or DockerSandbox, LocalSandbox
+  },
+});
+
+const coder = runtime.createStreamTextAgent({
+  name: 'coder',
+  tools: {
+    ...runtime.builtinTools(['web_search', 'web_fetch', 'bash', 'code_execution', 'text_editor']),
+    lookupInvoice,
+  },
+});
+```
+
+| Tool | What the model can do | Needs | Asks for approval |
+| :--- | :--- | :--- | :--- |
+| `web_search` | Search; results come back with short ids | `search` | No |
+| `web_fetch` | Read a page, by URL or result id; with a `prompt`, a small model answers from the page | `fetcher` | No |
+| `bash` | Run a command in the thread's sandbox | `sandbox` | Yes |
+| `code_execution` | Run a Python or JavaScript program; lists the files it made | `sandbox` | No |
+| `text_editor` | View, create and edit files by exact replacement, with undo | `sandbox` | For changes |
+
+A thread has **one sandbox**, kept between messages: every later run finds the
+same files, and it ends when the thread is deleted or has been idle for
+`sandboxIdleTtlMs` (30 minutes). Each tool call is a usage row, so
+`pricing.tools({ brave: { perUse: 0.005 }, e2b: { perSecond: 0.000028 } })`
+puts tool spend on the bill and under a run's money cap.
+
+Your own tools can use the thread's sandbox with `withSandbox(opts, fn)`. See
+[Web tools](https://eadwincode.github.io/agentic-kit/web-tools) and
+[Sandboxes](https://eadwincode.github.io/agentic-kit/sandboxes).
+
 ## The admin store (§2.9) — not yours
 
 Run records, step timings and a thread index are the **platform's** data, in the
@@ -207,7 +272,7 @@ platform's own tables. You do not implement `AdminStore`; you read it back:
 await runtime.admin.overview();          // threads and runs by state, plus what's in flight
 await runtime.admin.listRuns({ state: ['FAILED'], since });
 await runtime.admin.stats({ since });    // p50/p95 duration and queue wait, tokens, failures
-await runtime.admin.getRun(runId);       // one run: steps, nested runs, timeline, spend
+await runtime.admin.getRun(runId);       // one run: steps, nested runs, its record entries, spend
 ```
 
 Its schema migrates itself, from numbered migration files. `setupAgentCore`
@@ -236,7 +301,8 @@ reading your database at all.
 
 ## Adapter invariants (§3.4)
 
-1. `events.append` receives `seq` from `kv.incr('agent:seq:{threadId}')` — monotonic per thread.
+1. `events.append` takes an entry without a `seq` and the store mints it — monotonic per
+   thread, never repeated.
 2. `threads.claimState` must be atomic (one conditional UPDATE) — exactly one caller wins.
 3. `queue.enqueue` is at-least-once and the engine is idempotent. An adapter that cannot
    honour `delaySeconds` may deliver immediately, but must never throw for it — a HITL
@@ -251,13 +317,14 @@ reading your database at all.
 | Spec | Where in the package |
 | :--- | :--- |
 | §2.1 Detached execution, stop, run identity | `core/run.ts`, `core/stop.ts`, `core/engine.ts`, `core/keys.ts` |
-| §2.2 Multi-user stream | `ports/bus.ts` + `runtime.events` |
+| §2.2 Multi-user stream | `ports/bus.ts`, `ports/streams.ts`, `core/follow.ts` + `runtime.events` |
 | §2.5 HITL park, respond, expiry, reclaim | `core/hitl.ts`, `core/reclaim.ts` |
 | §2.6 Context ceiling & compaction | `core/context.ts` |
 | §2.7 Subagents as nested runs | `core/subagent.ts`, `core/loop.ts` |
 | §2.8 Queue dispatch + redrive/FAIL policy | `ports/queue.ts`, `core/engine.ts` |
 | §2.9 Operational history | `ports/admin.ts`, `admin/*`, `core/admin.ts` |
 | §2.10 Run state | `core/state.ts` |
+| Built-in tools | `core/builtin/*`, `ports/tools.ts`, `ports/sandbox.ts`, `adapters/{brave,jina,page-reader,docker,e2b,local-sandbox,computesdk}.ts` |
 | §5 Reference HTTP integration | `examples/nextjs-app` |
 
 ## Development

package/dist/adapters/brave.d.ts

@@ -0,0 +1,21 @@
+import type { Search, SearchHit, SearchOptions } from '../ports/tools.js';
+export interface BraveWebSearchOptions {
+    apiKey: string;
+    /** Two-letter country the results are for, like 'us'. */
+    country?: string;
+    /** Language of the results, like 'en'. */
+    searchLang?: string;
+    baseUrl?: string;
+    /** For tests. */
+    fetch?: typeof fetch;
+}
+/** Web search on the Brave Search API: its own index of the web, $5 per
+ *  1,000 searches with $5 free each month (checked 2026-09-26). The default
+ *  search adapter. */
+export declare class BraveWebSearch implements Search {
+    private readonly options;
+    readonly name = "brave";
+    constructor(options: BraveWebSearchOptions);
+    search(query: string, opts: SearchOptions): Promise<SearchHit[]>;
+}
+//# sourceMappingURL=brave.d.ts.map

package/dist/adapters/brave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave.d.ts","sourceRoot":"","sources":["../../src/adapters/brave.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,EAAiB,MAAM,mBAAmB,CAAC;AAIzF,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAID;;sBAEsB;AACtB,qBAAa,cAAe,YAAW,MAAM;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IADpC,QAAQ,CAAC,IAAI,WAAW;gBACK,OAAO,EAAE,qBAAqB;IAIrD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAgCvE"}

package/dist/adapters/brave.js

@@ -0,0 +1,52 @@
+import { domainAllowed, withSiteFilters } from './web-search-shared.js';
+import { decodeEntities } from '../core/builtin/html.js';
+const FRESHNESS = { day: 'pd', week: 'pw', month: 'pm', year: 'py' };
+/** Web search on the Brave Search API: its own index of the web, $5 per
+ *  1,000 searches with $5 free each month (checked 2026-09-26). The default
+ *  search adapter. */
+export class BraveWebSearch {
+    options;
+    name = 'brave';
+    constructor(options) {
+        this.options = options;
+        if (!options.apiKey)
+            throw new Error('BraveWebSearch: apiKey is required');
+    }
+    async search(query, opts) {
+        const params = new URLSearchParams({
+            q: withSiteFilters(query, opts),
+            count: String(Math.min(Math.max(opts.maxResults, 1), 20)),
+            text_decorations: 'false',
+        });
+        if (opts.recency)
+            params.set('freshness', FRESHNESS[opts.recency]);
+        if (this.options.country)
+            params.set('country', this.options.country);
+        if (this.options.searchLang)
+            params.set('search_lang', this.options.searchLang);
+        const doFetch = this.options.fetch ?? fetch;
+        const res = await doFetch(`${this.options.baseUrl ?? 'https://api.search.brave.com/res/v1/web/search'}?${params}`, {
+            headers: { accept: 'application/json', 'x-subscription-token': this.options.apiKey },
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        if (!res.ok)
+            throw new Error(`brave: ${res.status} ${(await res.text()).slice(0, 200)}`);
+        const body = (await res.json());
+        const hits = [];
+        for (const r of body.web?.results ?? []) {
+            if (!r.url || !domainAllowed(r.url, opts))
+                continue;
+            hits.push({
+                // Brave sends text as HTML: tags in snippets, entities in both.
+                title: decodeEntities(r.title ?? ''),
+                url: r.url,
+                snippet: decodeEntities((r.description ?? '').replace(/<[^>]*>/g, '')),
+                ...(r.page_age ? { publishedAt: r.page_age } : {}),
+            });
+            if (hits.length >= opts.maxResults)
+                break;
+        }
+        return hits;
+    }
+}
+//# sourceMappingURL=brave.js.map

package/dist/adapters/brave.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brave.js","sourceRoot":"","sources":["../../src/adapters/brave.ts"],"names":[],"mappings":"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"}

package/dist/adapters/computesdk.d.ts

@@ -0,0 +1,71 @@
+import { type CreateSandboxOptions, type Sandbox, type SandboxProvider } from '../ports/sandbox.js';
+/** The part of a ComputeSDK sandbox this adapter uses. Any ComputeSDK
+ *  provider's sandbox has it; nothing is imported from ComputeSDK, so it is
+ *  not a dependency. */
+export interface ComputeSdkSandboxLike {
+    readonly sandboxId: string;
+    readonly provider: string;
+    runCommand(command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeout?: number;
+        background?: boolean;
+        onStdout?: (d: string) => void;
+        onStderr?: (d: string) => void;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        durationMs: number;
+    }>;
+    getInfo(): Promise<{
+        id: string;
+        provider: string;
+        status: string;
+        createdAt: Date;
+        timeout: number;
+        metadata?: Record<string, any>;
+    }>;
+    getUrl(options: {
+        port: number;
+        protocol?: string;
+    }): Promise<string>;
+    destroy(): Promise<void>;
+    readonly filesystem: {
+        readFile(path: string): Promise<string>;
+        writeFile(path: string, content: string): Promise<void>;
+    };
+}
+/** A ComputeSDK provider, as `e2b({ apiKey })` or `daytona({ ... })` from
+ *  the `@computesdk/*` packages returns it. */
+export interface ComputeSdkProviderLike {
+    readonly name?: string;
+    readonly sandbox: {
+        create(options?: Record<string, unknown>): Promise<ComputeSdkSandboxLike>;
+        getById(sandboxId: string): Promise<ComputeSdkSandboxLike | null>;
+    };
+}
+export interface ComputeSdkSandboxOptions {
+    /** A ComputeSDK provider: `e2b({ apiKey })`, `daytona(...)`, `modal(...)`… */
+    provider: ComputeSdkProviderLike;
+    /** The folder relative paths are taken from. Default `/tmp/agentenkit`. */
+    workdir?: string;
+    /** How long a sandbox lives. ComputeSDK cannot push a sandbox's time back,
+     *  so each one ends this long after it was made, used or not. Default 1
+     *  hour. */
+    timeoutMs?: number;
+}
+/** Sandboxes from any ComputeSDK provider (Daytona, Modal, Vercel,
+ *  Cloudflare, …). TS only: ComputeSDK is a TypeScript library.
+ *
+ *  Files that are not plain text go through `base64` in the sandbox, since
+ *  ComputeSDK's file calls take text only. */
+export declare class ComputeSdkSandbox implements SandboxProvider {
+    private readonly options;
+    readonly name: string;
+    constructor(options: ComputeSdkSandboxOptions);
+    private get workdir();
+    create(options: CreateSandboxOptions): Promise<Sandbox>;
+    connect(sandboxId: string): Promise<Sandbox>;
+}
+//# sourceMappingURL=computesdk.d.ts.map

package/dist/adapters/computesdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computesdk.d.ts","sourceRoot":"","sources":["../../src/adapters/computesdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,oBAAoB,EAGzB,KAAK,OAAO,EAGZ,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAe7B;;wBAEwB;AACxB,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,UAAU,CACR,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,GAC/J,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF,OAAO,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,CAAC;IACvI,MAAM,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACxC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACzD,CAAC;CACH;AAED;+CAC+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE;QAChB,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;QAC1E,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;KACnE,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,QAAQ,EAAE,sBAAsB,CAAC;IACjC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;gBAEY;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;8CAI8C;AAC9C,qBAAa,iBAAkB,YAAW,eAAe;IAG3C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEO,OAAO,EAAE,wBAAwB;IAI9D,OAAO,KAAK,OAAO,GAElB;IAEK,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IAcvD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAOnD"}

package/dist/adapters/computesdk.js

@@ -0,0 +1,163 @@
+import { DEFAULT_COMMAND_TIMEOUT_MS, SandboxFileNotFoundError, SandboxGoneError, SandboxUnsupportedError, TIMED_OUT_EXIT_CODE, } from '../ports/sandbox.js';
+import { FILE_SCRIPTS, NOT_FOUND_EXIT, backgroundCommand, capOutput, decodeBase64, encodeBase64, looksTimedOut, parseListing, resolveIn, shellQuote, toBytes, } from './sandbox-shell.js';
+/** Sandboxes from any ComputeSDK provider (Daytona, Modal, Vercel,
+ *  Cloudflare, …). TS only: ComputeSDK is a TypeScript library.
+ *
+ *  Files that are not plain text go through `base64` in the sandbox, since
+ *  ComputeSDK's file calls take text only. */
+export class ComputeSdkSandbox {
+    options;
+    name;
+    constructor(options) {
+        this.options = options;
+        this.name = `computesdk:${options.provider.name ?? 'provider'}`;
+    }
+    get workdir() {
+        return this.options.workdir ?? '/tmp/agentenkit';
+    }
+    async create(options) {
+        const sandbox = await this.options.provider.sandbox.create({
+            timeout: this.options.timeoutMs ?? 60 * 60_000,
+            metadata: { threadId: options.metadata.threadId, ...(options.metadata.runId ? { runId: options.metadata.runId } : {}) },
+            ...(options.envs ? { envs: options.envs } : {}),
+            ...(options.template ? { templateId: options.template } : {}),
+            ...(options.image ? { image: options.image } : {}),
+            ...(options.extra ?? {}),
+        });
+        const box = new ComputeSdkBox(this.name, sandbox, this.workdir);
+        await box.filesystem.mkdir('.');
+        return box;
+    }
+    async connect(sandboxId) {
+        // Only "not found" means gone; any other error is thrown as it is, so a
+        // passing network fault does not throw away a live sandbox.
+        const sandbox = await this.options.provider.sandbox.getById(sandboxId);
+        if (!sandbox)
+            throw new SandboxGoneError(sandboxId);
+        return new ComputeSdkBox(this.name, sandbox, this.workdir);
+    }
+}
+class ComputeSdkBox {
+    provider;
+    inner;
+    workdir;
+    filesystem;
+    constructor(provider, inner, workdir) {
+        this.provider = provider;
+        this.inner = inner;
+        this.workdir = workdir;
+        this.filesystem = new ComputeSdkFiles(this, inner);
+    }
+    get sandboxId() {
+        return this.inner.sandboxId;
+    }
+    path(p) {
+        return resolveIn(this.workdir, p);
+    }
+    /** Runs a FILE_SCRIPTS script on one path. */
+    script(script, path) {
+        return this.inner.runCommand(`sh -c ${shellQuote(script)} sandbox ${shellQuote(this.path(path))}`);
+    }
+    async runCommand(command, options = {}) {
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        const limit = options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+        const r = await this.inner.runCommand(options.background ? backgroundCommand(command) : command, {
+            cwd: this.path(options.cwd ?? '.'),
+            ...(options.env ? { env: options.env } : {}),
+            timeout: limit,
+            ...(options.onStdout ? { onStdout: options.onStdout } : {}),
+            ...(options.onStderr ? { onStderr: options.onStderr } : {}),
+        });
+        if (options.background)
+            return { stdout: '', stderr: '', exitCode: r.exitCode, durationMs: r.durationMs };
+        const timedOut = looksTimedOut(r.exitCode, r.durationMs, limit);
+        const stdout = capOutput(r.stdout);
+        const stderr = capOutput(r.stderr);
+        return {
+            stdout: stdout.text,
+            stderr: stderr.text,
+            exitCode: timedOut ? TIMED_OUT_EXIT_CODE : r.exitCode,
+            durationMs: r.durationMs,
+            ...(timedOut ? { timedOut: true } : {}),
+            ...(stdout.truncated || stderr.truncated ? { truncated: true } : {}),
+        };
+    }
+    getUrl(options) {
+        return this.inner.getUrl(options);
+    }
+    async getInfo() {
+        const info = await this.inner.getInfo();
+        const metadata = {};
+        for (const [k, v] of Object.entries(info.metadata ?? {}))
+            if (typeof v === 'string')
+                metadata[k] = v;
+        const createdAt = new Date(info.createdAt);
+        return {
+            id: info.id,
+            provider: this.provider,
+            status: info.status === 'running' ? 'running' : info.status === 'stopped' ? 'stopped' : 'error',
+            createdAt,
+            ...(info.timeout ? { expiresAt: new Date(createdAt.getTime() + info.timeout) } : {}),
+            workdir: this.workdir,
+            metadata,
+        };
+    }
+    async setTimeout() {
+        throw new SandboxUnsupportedError(this.provider, "changing a sandbox's time");
+    }
+    destroy() {
+        return this.inner.destroy();
+    }
+}
+class ComputeSdkFiles {
+    box;
+    inner;
+    constructor(box, inner) {
+        this.box = box;
+        this.inner = inner;
+    }
+    async run(script, path) {
+        const r = await this.box.script(script, path);
+        if (r.exitCode === NOT_FOUND_EXIT)
+            throw new SandboxFileNotFoundError(path);
+        if (r.exitCode !== 0)
+            throw new Error(`${this.box.provider}: ${r.stderr.trim() || `exit ${r.exitCode}`}`);
+        return r;
+    }
+    async readFile(path) {
+        return new TextDecoder().decode(await this.readFileBytes(path));
+    }
+    async readFileBytes(path) {
+        return decodeBase64((await this.run(FILE_SCRIPTS.readBase64, path)).stdout);
+    }
+    async writeFile(path, content) {
+        const full = this.box.path(path);
+        await this.run(FILE_SCRIPTS.mkdir, full.slice(0, full.lastIndexOf('/')) || '/');
+        if (typeof content === 'string')
+            return this.inner.filesystem.writeFile(full, content);
+        // Bytes go through base64, in pieces well under the longest argument a
+        // command line takes.
+        const b64 = encodeBase64(toBytes(content));
+        await this.box.script(': > "$1"', path);
+        for (let i = 0; i < b64.length; i += 60_000) {
+            const piece = b64.slice(i, i + 60_000);
+            const r = await this.box.script(`printf %s ${shellQuote(piece)} | base64 -d >> "$1"`, path);
+            if (r.exitCode !== 0)
+                throw new Error(`${this.box.provider}: could not write ${path}: ${r.stderr.trim()}`);
+        }
+    }
+    async readdir(path) {
+        return parseListing((await this.run(FILE_SCRIPTS.list, path)).stdout);
+    }
+    async mkdir(path) {
+        await this.run(FILE_SCRIPTS.mkdir, path);
+    }
+    async exists(path) {
+        return (await this.box.script(FILE_SCRIPTS.exists, path)).exitCode === 0;
+    }
+    async remove(path) {
+        await this.run(FILE_SCRIPTS.remove, path);
+    }
+}
+//# sourceMappingURL=computesdk.js.map

package/dist/adapters/computesdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computesdk.js","sourceRoot":"","sources":["../../src/adapters/computesdk.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,gBAAgB,EAChB,uBAAuB,EACvB,mBAAmB,GASpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,SAAS,EACT,UAAU,EACV,OAAO,GACR,MAAM,oBAAoB,CAAC;AA0C5B;;;;8CAI8C;AAC9C,MAAM,OAAO,iBAAiB;IAGC;IAFpB,IAAI,CAAS;IAEtB,YAA6B,OAAiC;QAAjC,YAAO,GAAP,OAAO,CAA0B;QAC5D,IAAI,CAAC,IAAI,GAAG,cAAc,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,UAAU,EAAE,CAAC;IAClE,CAAC;IAED,IAAY,OAAO;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,iBAAiB,CAAC;IACnD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAA6B;QACxC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC;YACzD,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,GAAG,MAAM;YAC9C,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;YACvH,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;SACzB,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAChE,MAAM,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAChC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,SAAiB;QAC7B,wEAAwE;QACxE,4DAA4D;QAC5D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACpD,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC;CACF;AAED,MAAM,aAAa;IAIN;IACQ;IACA;IALV,UAAU,CAAoB;IAEvC,YACW,QAAgB,EACR,KAA4B,EAC5B,OAAe;QAFvB,aAAQ,GAAR,QAAQ,CAAQ;QACR,UAAK,GAAL,KAAK,CAAuB;QAC5B,YAAO,GAAP,OAAO,CAAQ;QAEhC,IAAI,CAAC,UAAU,GAAG,IAAI,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC,CAAS;QACZ,OAAO,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,8CAA8C;IAC9C,MAAM,CAAC,MAAc,EAAE,IAAY;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,YAAY,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IACrG,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,OAAe,EAAE,UAA6B,EAAE;QAC/D,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC;QACzD,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,IAAI,0BAA0B,CAAC;QAC9D,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE;YAC/F,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC;YAClC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,OAAO,EAAE,KAAK;YACd,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5D,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,UAAU;YAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;QAC1G,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAChE,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACnC,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,MAAM,EAAE,MAAM,CAAC,IAAI;YACnB,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ;YACrD,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvC,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrE,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,OAAsD;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACxC,MAAM,QAAQ,GAA2B,EAAE,CAAC;QAC5C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;YAAE,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACrG,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3C,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO;YAC/F,SAAS;YACT,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpF,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,IAAI,uBAAuB,CAAC,IAAI,CAAC,QAAQ,EAAE,2BAA2B,CAAC,CAAC;IAChF,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,eAAe;IAEA;IACA;IAFnB,YACmB,GAAkB,EAClB,KAA4B;QAD5B,QAAG,GAAH,GAAG,CAAe;QAClB,UAAK,GAAL,KAAK,CAAuB;IAC5C,CAAC;IAEI,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,IAAY;QAC5C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,QAAQ,KAAK,cAAc;YAAE,MAAM,IAAI,wBAAwB,CAAC,IAAI,CAAC,CAAC;QAC5E,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,QAAQ,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC1G,OAAO,CAAC,CAAC;IACX,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;IAClE,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAY;QAC9B,OAAO,YAAY,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAY,EAAE,OAA4B;QACxD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAChF,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACvF,uEAAuE;QACvE,sBAAsB;QACtB,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;YACvC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,UAAU,CAAC,KAAK,CAAC,sBAAsB,EAAE,IAAI,CAAC,CAAC;YAC5F,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,qBAAqB,IAAI,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAY;QACxB,OAAO,YAAY,CAAC,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;CACF"}

package/dist/adapters/docker.d.ts

@@ -0,0 +1,35 @@
+import { type CreateSandboxOptions, type Sandbox, type SandboxProvider } from '../ports/sandbox.js';
+export interface DockerSandboxOptions {
+    /** The image each sandbox runs. It needs `sh`; bash, Python and
+     *  `timeout` are used when there. Default `python:3.12-slim`. */
+    image?: string;
+    /** `none` (the default) or `all`. Docker has no allow list by domain. */
+    network?: 'none' | 'all';
+    /** The folder commands start in. Default `/workspace`. */
+    workdir?: string;
+    cpu?: number;
+    memoryMiB?: number;
+    /** Ports to publish on 127.0.0.1, so `getUrl` can give them. Needs
+     *  `network: 'all'`. */
+    ports?: number[];
+    /** Environment variables every command sees. */
+    env?: Record<string, string>;
+    /** More `docker run` arguments, placed before the image. */
+    runArgs?: string[];
+    /** The docker CLI. Default `docker` on the PATH. */
+    docker?: string;
+}
+/** Sandboxes as Docker containers on the machine the docker CLI talks to:
+ *  for self-hosting. One container per thread, removed when it has been idle
+ *  past its time. Uses the docker CLI, so it needs no SDK and follows your
+ *  DOCKER_HOST and contexts. The Go runtime has the same adapter
+ *  (adapters/docker). */
+export declare class DockerSandbox implements SandboxProvider {
+    private readonly options;
+    readonly name = "docker";
+    private readonly docker;
+    constructor(options?: DockerSandboxOptions);
+    create(options: CreateSandboxOptions): Promise<Sandbox>;
+    connect(sandboxId: string): Promise<Sandbox>;
+}
+//# sourceMappingURL=docker.d.ts.map

package/dist/adapters/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/adapters/docker.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,oBAAoB,EAGzB,KAAK,OAAO,EAIZ,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAe7B,MAAM,WAAW,oBAAoB;IACnC;qEACiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACzB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;4BACwB;IACxB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;yBAIyB;AACzB,qBAAa,aAAc,YAAW,eAAe;IAIvC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,OAAO,GAAE,oBAAyB;IAIzD,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BvD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAMnD"}