agentbox-sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,7 @@
 # AgentBox
 
+[Live demo](https://agentbox-demo-175164121374.us-west1.run.app/)
+
 Run coding agents inside sandboxes. One API, any provider.
 
 Unlike wrappers that shell out to CLIs in non-interactive mode (e.g. `claude --print`), AgentBox launches each agent as a **server process** inside the sandbox and communicates over WebSocket or HTTP. This preserves the full interactive capabilities of each agent — approval flows, tool-use control, streaming events.
@@ -13,6 +15,8 @@ const sandbox = new Sandbox("local-docker", {
   env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
 });
 
+await sandbox.findOrProvision();
+
 const run = new Agent("claude-code", {
   sandbox,
   cwd: "/workspace",
@@ -71,6 +75,11 @@ const sandbox = new Sandbox("local-docker", {
   env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
 });
 
+// Explicitly attach to / create the sandbox before running anything.
+// Subsequent `sandbox.run`, `sandbox.gitClone`, agent runs, etc. all
+// require this to have happened first.
+await sandbox.findOrProvision();
+
 const agent = new Agent("claude-code", {
   sandbox,
   cwd: "/workspace",
@@ -118,10 +127,24 @@ Three agent providers are supported. Each wraps a CLI that runs inside the sandb
 
 ```ts
 new Agent("claude-code", { sandbox, cwd: "/workspace", approvalMode: "auto" });
-new Agent("opencode", { sandbox, cwd: "/workspace", approvalMode: "auto" });
+new Agent("open-code", { sandbox, cwd: "/workspace", approvalMode: "auto" });
 new Agent("codex", { sandbox, cwd: "/workspace", approvalMode: "auto" });
 ```
 
+### Reasoning effort
+
+Pass an optional `reasoning` level alongside `model` on any run. It maps to each provider's native reasoning control: Codex's `effort` on `turn/start`, Claude Code's `--effort` flag, and OpenCode's `reasoningEffort` agent variant.
+
+```ts
+await agent.run({
+  model: "sonnet",
+  reasoning: "high", // "low" | "medium" | "high" | "xhigh"
+  input: "Refactor this module and explain your reasoning.",
+});
+```
+
+`xhigh` requires a model that supports it (e.g. Claude Opus 4.7+, Codex `gpt-5.4`).
+
 ## Sandboxes
 
 Five sandbox providers are supported. Each gives you an isolated environment with the same interface:
@@ -134,7 +157,23 @@ Five sandbox providers are supported. Each gives you an isolated environment wit
 | `daytona`      | Cloud dev environment  | `DAYTONA_API_KEY`                                       |
 | `vercel`       | Ephemeral cloud VM     | `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID` |
 
-Every sandbox supports: `run()`, `runAsync()`, `gitClone()`, `openPort()`, `getPreviewLink()`, `snapshot()`, `stop()`, `delete()`.
+Every sandbox supports: `findOrProvision()`, `run()`, `runAsync()`, `gitClone()`, `uploadAndRun()`, `openPort()`, `getPreviewLink()`, `snapshot()`, `stop()`, `delete()`.
+
+### Provisioning lifecycle
+
+`new Sandbox(...)` only stores configuration — it does **not** create or attach to a real sandbox. Call `findOrProvision()` once when you're ready to start using it, and every subsequent operation (`run`, `gitClone`, `uploadAndRun`, agent runs, …) reuses that sandbox:
+
+```ts
+const sandbox = new Sandbox("modal", {
+  /* … */
+});
+
+await sandbox.findOrProvision(); // attach to existing tagged sandbox or create a fresh one
+await sandbox.gitClone({ repoUrl: "…" });
+const result = await sandbox.run("pnpm install");
+```
+
+Calling a method that needs a live sandbox before `findOrProvision()` throws a clear error. This makes the (potentially slow) attach / create step explicit and lets you control exactly when it happens.
 
 Vercel sandboxes use runtime snapshots instead of pre-built images — call `sandbox.snapshot()` to capture state and pass the returned id via `provider.snapshotId` on the next run.
 
@@ -232,7 +271,7 @@ const agent = new Agent("claude-code", {
 Register slash commands the agent can use:
 
 ```ts
-const agent = new Agent("opencode", {
+const agent = new Agent("open-code", {
   sandbox,
   cwd: "/workspace",
   approvalMode: "auto",
@@ -333,7 +372,7 @@ new Agent("codex", {
 **OpenCode** — plugin-based hooks:
 
 ```ts
-new Agent("opencode", {
+new Agent("open-code", {
   sandbox,
   cwd: "/workspace",
   provider: {

package/dist/{Sandbox-BQX-sWzs.d.ts → Sandbox-CByFJI8X.d.ts}

@@ -1,10 +1,28 @@
 import { Sandbox as Sandbox$1 } from 'e2b';
 import { Sandbox as Sandbox$2 } from '@vercel/sandbox';
-import { Daytona, Sandbox as Sandbox$3 } from '@daytonaio/sdk';
-import { ModalClient, Sandbox as Sandbox$4 } from 'modal';
+import { Daytona, Sandbox as Sandbox$3, CreateSandboxFromSnapshotParams, CreateSandboxFromImageParams } from '@daytonaio/sdk';
+import { ModalClient, Sandbox as Sandbox$4, SandboxCreateParams } from 'modal';
 import Docker from 'dockerode';
 import { SandboxProvider } from './enums.js';
 
+/**
+ * Tiny in-memory tarball builder used by `Sandbox.uploadAndRun`.
+ *
+ * Builds an uncompressed POSIX USTAR archive entirely in-memory, suitable
+ * for piping through a sandbox's stdin to be extracted by `tar -x`. We
+ * deliberately don't gzip on the host: setup tarballs are small (a few
+ * KB) and the sandbox's `tar` may not always have gzip when the image is
+ * stripped down, so plain tar keeps the contract simple.
+ */
+interface TarballEntry {
+    /** Absolute or relative path the file should be written to in the sandbox. */
+    path: string;
+    /** File contents. Strings are encoded as UTF-8. */
+    content: string | Buffer;
+    /** Optional file mode (default `0o644`). Pass `0o755` for executables. */
+    mode?: number;
+}
+
 type E2bRaw = {
     sandbox?: Sandbox$1;
 };
@@ -107,6 +125,16 @@ interface ModalProviderOptions {
     unencryptedPorts?: number[];
     command?: string[];
     verbose?: boolean;
+    /**
+     * Escape hatch: extra parameters spread into Modal's
+     * `client.sandboxes.create()` call. Lets callers use Modal-specific
+     * features that are not surfaced as typed fields here (e.g.
+     * `experimentalOptions`, `gpu`, `cloudBucketMounts`, `regions`).
+     *
+     * Typed fields on `ModalProviderOptions` and `SandboxOptionsBase` take
+     * precedence over keys provided via `createParams`.
+     */
+    createParams?: Partial<SandboxCreateParams>;
 }
 interface DaytonaProviderOptions {
     apiKey?: string;
@@ -118,6 +146,16 @@ interface DaytonaProviderOptions {
     language?: string;
     user?: string;
     public?: boolean;
+    /**
+     * Escape hatch: extra parameters spread into Daytona's `client.create()`
+     * call. Lets callers use Daytona-specific features that are not surfaced
+     * as typed fields here (e.g. `volumes`, `networkBlockAll`,
+     * `networkAllowList`, `ephemeral`, `autoArchiveInterval`).
+     *
+     * Typed fields on `DaytonaProviderOptions` and `SandboxOptionsBase` take
+     * precedence over keys provided via `createParams`.
+     */
+    createParams?: Partial<CreateSandboxFromSnapshotParams & CreateSandboxFromImageParams>;
 }
 interface VercelGitSource {
     url: string;
@@ -206,6 +244,20 @@ declare class Sandbox<P extends SandboxProviderName = SandboxProviderName> {
     get optionsSnapshot(): SandboxOptions<P>;
     get id(): string | undefined;
     get raw(): SandboxRaw<P> | undefined;
+    /**
+     * Whether `findOrProvision()` warm-attached to a pre-existing tagged
+     * sandbox (`true`) or created a fresh one (`false`). Useful to skip
+     * idempotent setup that the previous run already performed (e.g.
+     * `agent.setup()`). Always `false` before `findOrProvision()` resolves.
+     */
+    get wasFound(): boolean;
+    /**
+     * Attach to an existing tagged sandbox or create a new one. Must be
+     * called before `run`, `runAsync`, `gitClone`, `uploadAndRun`,
+     * `getPreviewLink`, etc. Repeated calls are cheap (the result is
+     * cached internally).
+     */
+    findOrProvision(): Promise<this>;
     openPort(port: number): Promise<this>;
     setSecret(name: string, value: string): this;
     setSecrets(values: Record<string, string>): this;
@@ -220,6 +272,7 @@ declare class Sandbox<P extends SandboxProviderName = SandboxProviderName> {
     get previewHeaders(): Record<string, string>;
     uploadFile(content: Buffer | string, targetPath: string): Promise<void>;
     downloadFile(sourcePath: string): Promise<Buffer>;
+    uploadAndRun(files: TarballEntry[], command: string, options?: CommandOptions): Promise<CommandResult>;
 }
 
-export { type AsyncCommandHandle as A, type CommandEvent as C, type DaytonaProviderOptions as D, type E2bProviderOptions as E, type GitCloneOptions as G, type LocalDockerProviderOptions as L, type ModalProviderOptions as M, Sandbox as S, type VercelGitSource as V, type CommandOptions as a, type CommandResult as b, type DaytonaSandboxOptions as c, type E2bSandboxOptions as d, type LocalDockerSandboxOptions as e, type ModalSandboxOptions as f, type SandboxDescriptor as g, type SandboxListOptions as h, type SandboxOptions as i, type SandboxOptionsBase as j, type SandboxOptionsMap as k, type SandboxProviderName as l, type SandboxRaw as m, type SandboxRawMap as n, type SandboxResourceSpec as o, type VercelProviderOptions as p, type VercelSandboxOptions as q };
+export { type AsyncCommandHandle as A, type CommandEvent as C, type DaytonaProviderOptions as D, type E2bProviderOptions as E, type GitCloneOptions as G, type LocalDockerProviderOptions as L, type ModalProviderOptions as M, Sandbox as S, type TarballEntry as T, type VercelGitSource as V, type CommandOptions as a, type CommandResult as b, type DaytonaSandboxOptions as c, type E2bSandboxOptions as d, type LocalDockerSandboxOptions as e, type ModalSandboxOptions as f, type SandboxDescriptor as g, type SandboxListOptions as h, type SandboxOptions as i, type SandboxOptionsBase as j, type SandboxOptionsMap as k, type SandboxProviderName as l, type SandboxRaw as m, type SandboxRawMap as n, type SandboxResourceSpec as o, type VercelProviderOptions as p, type VercelSandboxOptions as q };

package/dist/agents/index.d.ts

@@ -1,7 +1,7 @@
-import { m as AgentProviderName, f as AgentOptions, q as AgentRunConfig, p as AgentRun, o as AgentResult, Z as RawAgentEvent } from '../types-Et22oPap.js';
-export { a as AgentApprovalMode, b as AgentCommandConfig, c as AgentExecutionRequest, d as AgentLocalMcpConfig, e as AgentMcpConfig, g as AgentOptionsBase, h as AgentOptionsMap, i as AgentPermissionDecision, j as AgentPermissionKind, k as AgentPermissionResponse, l as AgentProviderAdapter, n as AgentRemoteMcpConfig, r as AgentRunSink, s as AgentSkillConfig, t as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, u as ClaudeCodeHookConfig, v as ClaudeCodeHookEvent, w as ClaudeCodeHookHandler, x as ClaudeCodeHookMatcherGroup, y as ClaudeCodeHooksConfig, z as ClaudeCodeProviderOptions, B as CodexAgentOptions, D as CodexCommandHook, E as CodexHookEvent, F as CodexHookMatcherGroup, G as CodexHooksConfig, H as CodexProviderOptions, I as DataContent, J as EmbeddedSkillConfig, K as FilePart, L as ImagePart, S as OpenCodeAgentOptions, T as OpenCodePluginConfig, U as OpenCodePluginEvent, V as OpenCodePluginHookConfig, W as OpenCodeProviderOptions, $ as RepoSkillConfig, a4 as TextPart, a8 as UserContent, a9 as UserContentPart } from '../types-Et22oPap.js';
+import { o as AgentProviderName, h as AgentOptions, v as AgentSetupConfig, t as AgentRunConfig, s as AgentRun, r as AgentResult, a3 as RawAgentEvent, b as AgentAttachRequest, z as AttachedRun } from '../types-B3N-Qo2q.js';
+export { a as AgentApprovalMode, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, u as AgentRunSink, w as AgentSetupRequest, x as AgentSkillConfig, y as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, B as ClaudeCodeHookConfig, D as ClaudeCodeHookEvent, E as ClaudeCodeHookHandler, F as ClaudeCodeHookMatcherGroup, G as ClaudeCodeHooksConfig, H as ClaudeCodeProviderOptions, I as CodexAgentOptions, J as CodexCommandHook, K as CodexHookEvent, L as CodexHookMatcherGroup, M as CodexHooksConfig, N as CodexProviderOptions, O as DataContent, P as EmbeddedSkillConfig, Q as FilePart, R as ImagePart, Y as OpenCodeAgentOptions, Z as OpenCodePluginConfig, _ as OpenCodePluginEvent, $ as OpenCodePluginHookConfig, a0 as OpenCodeProviderOptions, a5 as RepoSkillConfig, aa as TextPart, ae as UserContent, af as UserContentPart } from '../types-B3N-Qo2q.js';
+import { S as Sandbox } from '../Sandbox-CByFJI8X.js';
 export { AgentProvider } from '../enums.js';
-import '../Sandbox-BQX-sWzs.js';
 import 'e2b';
 import '@vercel/sandbox';
 import '@daytonaio/sdk';
@@ -10,12 +10,61 @@ import 'dockerode';
 
 declare class Agent<P extends AgentProviderName = AgentProviderName> {
     private readonly adapter;
-    private readonly provider;
+    readonly provider: P;
     private readonly options;
+    private setupPromise?;
     constructor(provider: P, options: AgentOptions<P>);
+    /**
+     * The sandbox the agent will run inside, if any was passed via
+     * `options.sandbox`. Returns `undefined` for host-mode runs (no sandbox).
+     */
+    get sandbox(): Sandbox | undefined;
+    /**
+     * Prepare provider-specific runtime state on the configured sandbox
+     * (skill artifacts, MCP/hook/sub-agent config, app-server / relay boot, …).
+     *
+     * `setup()` is REQUIRED before {@link Agent.stream} or {@link Agent.run}
+     * for any sandbox-backed run. `stream` and the underlying
+     * `adapter.execute` deliberately do not trigger setup themselves so
+     * callers can run sandbox-side preparation in parallel with other
+     * long-running work (e.g. `git clone`).
+     *
+     * `execute` does not consume any setup output and does not re-do
+     * setup work. It assumes the relay/server boot performed here is
+     * already up. Skipping `setup()` against a remote sandbox is a
+     * programmer error and surfaces as a connect-retry timeout inside
+     * `execute`, not a silent fallback.
+     *
+     * Idempotent across repeated invocations: subsequent calls return the
+     * promise from the first call. The differential setup cache and the
+     * relay/server probes also make this cheap on warm sandboxes — the
+     * second `setup()` against the same sandbox does ~one round-trip of
+     * work.
+     */
+    setup(config?: AgentSetupConfig): Promise<void>;
     stream(runConfig: AgentRunConfig): AgentRun;
     run(runConfig: AgentRunConfig): Promise<AgentResult>;
     rawEvents(runConfig: AgentRunConfig): AsyncIterable<RawAgentEvent>;
+    /**
+     * Stateless control plane for an in-flight run.
+     *
+     * Returns an {@link AttachedRun} whose `abort()` / `sendMessage()` methods
+     * dial the in-sandbox provider server directly (codex app-server, opencode
+     * HTTP server, claude-code relay control endpoint) — there is no shared
+     * in-memory registry or Redis broker. Any process with the right `sandbox`
+     * + `runId` (+ optional provider-native `sessionId`) can issue commands
+     * against a run started on a different process.
+     *
+     * The originating process keeps owning the event stream that
+     * `agent.stream()` returned; commands attached here cause the in-sandbox
+     * server to emit the natural follow-up events (`turn/aborted`, message
+     * events, etc.), which the originating process ingests through its
+     * existing transport.
+     *
+     * The handle is short-lived: each method call opens a fresh connection,
+     * performs the operation with a timeout, and tears the connection down.
+     */
+    static attach<P extends AgentProviderName>(request: AgentAttachRequest<P>): Promise<AttachedRun>;
 }
 
 /**
@@ -36,4 +85,4 @@ declare class Agent<P extends AgentProviderName = AgentProviderName> {
 declare const AGENT_RESERVED_PORTS: Record<AgentProviderName, readonly number[]>;
 declare function collectAllAgentReservedPorts(): number[];
 
-export { AGENT_RESERVED_PORTS, Agent, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig, collectAllAgentReservedPorts };
+export { AGENT_RESERVED_PORTS, Agent, AgentAttachRequest, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig, AgentSetupConfig, AttachedRun, collectAllAgentReservedPorts };

package/dist/agents/index.js

@@ -1,15 +1,15 @@
 import {
   Agent
-} from "../chunk-G27423WX.js";
-import "../chunk-7FLLQJ6J.js";
+} from "../chunk-4MBB6QHD.js";
+import "../chunk-ZOWBRUQR.js";
 import {
   AGENT_RESERVED_PORTS,
   collectAllAgentReservedPorts
-} from "../chunk-O7HCJXKW.js";
+} from "../chunk-INMA52FV.js";
 import "../chunk-NSJM57Z4.js";
 import {
   AgentProvider
-} from "../chunk-2NKMDGYH.js";
+} from "../chunk-GOFJNFAD.js";
 export {
   AGENT_RESERVED_PORTS,
   Agent,