@deepagents/context 1.0.0 → 2.2.0

package/dist/lib/guardrail.d.ts

@@ -34,13 +34,9 @@
  * });
  * ```
  */
-import type { InferUIMessageChunk, UIDataTypes, UIMessage } from 'ai';
 import type { SkillPathMapping } from './skills/types.ts';
-/**
- * Type alias for stream parts from the AI SDK's UI message stream.
- * This is the full chunk type that includes text-delta, error, reasoning-delta, etc.
- */
-export type StreamPart = InferUIMessageChunk<UIMessage<unknown, UIDataTypes, Record<string, never>>>;
+import type { StreamPart } from './stream/types.ts';
+export type { StreamPart } from './stream/types.ts';
 /**
  * Result of a guardrail check.
  * - `pass`: The part is allowed through (optionally modified)

package/dist/lib/guardrail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../../src/lib/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,mBAAmB,CAC1C,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CACvD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uEAAuE;IACvE,eAAe,EAAE,gBAAgB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,KAAK,eAAe,CAAC;CAC1E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,EAAE,gBAAgB,GACxB,eAAe,CAejB"}
+{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../../src/lib/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uEAAuE;IACvE,eAAe,EAAE,gBAAgB,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,gBAAgB,KAAK,eAAe,CAAC;CAC1E;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAEtD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAEtD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,EAAE,gBAAgB,GACxB,eAAe,CAejB"}

package/dist/lib/sandbox/abort.d.ts

@@ -0,0 +1,24 @@
+import type { DisposableSandbox } from './types.ts';
+/**
+ * Set the ambient abort signal for the duration of `fn`. Inside `fn`,
+ * any sandbox call going through `withAbortSignal` will receive this
+ * signal via its `executeCommand` options.
+ *
+ * Use at the boundary where an external abort signal becomes available
+ * (e.g. a tool's `execute` callback). The signal then propagates down
+ * the decorator chain without explicit parameter threading.
+ */
+export declare function runWithAbortSignal<T>(signal: AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+/**
+ * Decorator: when `executeCommand` is called without an explicit signal,
+ * fills in the ambient signal set by `runWithAbortSignal`. Explicit
+ * caller-provided signals take precedence. Has no effect outside a
+ * `runWithAbortSignal` scope.
+ *
+ * Bridges the signature mismatch between upstream `bash-tool` (which
+ * calls `sandbox.executeCommand(command)` with no options) and backends
+ * that can honor cancellation. The decorator goes between upstream and
+ * the inner sandbox.
+ */
+export declare function withAbortSignal(sandbox: DisposableSandbox): DisposableSandbox;
+//# sourceMappingURL=abort.d.ts.map

package/dist/lib/sandbox/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/abort.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG,iBAAiB,CAqB7E"}

package/dist/lib/sandbox/agent-os-sandbox.d.ts

@@ -1,4 +1,4 @@
-import { type Sandbox } from 'bash-tool';
+import type { DisposableSandbox } from './types.ts';
 export declare class AgentOsSandboxError extends Error {
     constructor(message: string);
 }
@@ -27,16 +27,17 @@ export interface AgentOsSandboxOptions {
      */
     moduleAccessCwd?: string;
 }
-export interface AgentOsSandbox extends Sandbox {
-    dispose(): Promise<void>;
-}
 /**
  * Creates a WASM-based sandbox backed by Agent OS.
  *
  * Agent OS runs commands in an in-process WASM virtual machine — no Docker required.
  * Near-zero cold start (~6ms) with real WASM-compiled binaries (coreutils, grep, etc.).
  *
- * @experimental Agent OS is v0.1.0 preview. API may change.
+ * Internally, `executeCommand` lowers to `spawn('sh', ['-c', cmd])` so a single
+ * code path supports `AbortSignal` (the kernel's `exec(command)` does not return
+ * a pid and so cannot be cancelled).
+ *
+ * @experimental Agent OS is v0.1.1 preview. API may change.
  *
  * Requires optional peer dependencies:
  * - `@rivet-dev/agent-os-core`
@@ -63,7 +64,7 @@ export interface AgentOsSandbox extends Sandbox {
  * await sandbox.dispose();
  * ```
  */
-export declare function createAgentOsSandbox(options?: AgentOsSandboxOptions): Promise<AgentOsSandbox>;
+export declare function createAgentOsSandbox(options?: AgentOsSandboxOptions): Promise<DisposableSandbox>;
 /**
  * Run a function with an Agent OS sandbox that auto-disposes on completion.
  *
@@ -80,5 +81,5 @@ export declare function createAgentOsSandbox(options?: AgentOsSandboxOptions): P
  * );
  * ```
  */
-export declare function useAgentOsSandbox<T>(options: AgentOsSandboxOptions, fn: (sandbox: AgentOsSandbox) => Promise<T>): Promise<T>;
+export declare function useAgentOsSandbox<T>(options: AgentOsSandboxOptions, fn: (sandbox: DisposableSandbox) => Promise<T>): Promise<T>;
 //# sourceMappingURL=agent-os-sandbox.d.ts.map

package/dist/lib/sandbox/agent-os-sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-os-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/agent-os-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAwB7D,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,wBAAyB,SAAQ,mBAAmB;gBACnD,KAAK,CAAC,EAAE,KAAK;CAO1B;AAED,qBAAa,oBAAqB,SAAQ,mBAAmB;gBAC/C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAK3C;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,sCAAsC;IACtC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,cAAc,CAAC,CAyEzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,qBAAqB,EAC9B,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"agent-os-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/agent-os-sandbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AA8BpB,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,wBAAyB,SAAQ,mBAAmB;gBACnD,KAAK,CAAC,EAAE,KAAK;CAO1B;AAED,qBAAa,oBAAqB,SAAQ,mBAAmB;gBAC/C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAK3C;AAED,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,sCAAsC;IACtC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACtE,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAwFD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAiH5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,qBAAqB,EAC9B,EAAE,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/lib/sandbox/bash-tool.d.ts

@@ -1,27 +1,40 @@
 import { type CreateBashToolOptions } from 'bash-tool';
-import type { AgentSandbox, SkillUploadInput } from './types.ts';
-export interface CreateBashToolWithSkillsOptions extends CreateBashToolOptions {
+import type { AgentSandbox, DisposableSandbox, SkillUploadInput } from './types.ts';
+export interface CreateBashToolWithSkillsOptions extends Omit<CreateBashToolOptions, 'sandbox'> {
+    /**
+     * Backend satisfying `DisposableSandbox`. Callers pick the backend
+     * explicitly via `createVirtualSandbox`, `createDockerSandbox`, or
+     * `createAgentOsSandbox`. `@vercel/sandbox` is intentionally not
+     * accepted; if it's needed, wrap it to `DisposableSandbox` first.
+     */
+    sandbox: DisposableSandbox;
     /**
      * Skill directories to upload into the sandbox at startup. Each entry's
      * contents are copied to `sandbox` (files + subdirectories) and each
      * subdirectory containing a SKILL.md is parsed into `sandbox.skills`.
      */
     skills?: SkillUploadInput[];
+    /**
+     * Working directory + file-event observation root. Defaults to
+     * `/workspace` (matching upstream `bash-tool`). `drainFileEvents()`
+     * reports activity rooted here.
+     */
+    destination?: string;
 }
 /**
- * Wrapper around the external `bash-tool` factory. Adds:
- *   - Always-on `reasoning` input on the bash tool schema.
- *   - Sandbox-boundary catch for `BashException` (subclasses define their own
- *     `format()` → CommandResult). Applies to `toolkit.sandbox.executeCommand`
- *     and therefore to the tool-execute path as well (upstream calls that
- *     exact method).
- *   - Generic meta channel (`useBashMeta()`): handlers can call
- *     `setHidden(patch)` to attach host-only metadata and `setReminder(text)`
- *     to surface a model-visible nudge. `meta` is stripped from model output
- *     via `toModelOutput`; `reminder` stays visible.
- *   - Single-shot `skills` upload: the sandbox becomes the single source of
- *     truth for skills — pass `skills: [{ host, sandbox }]` to upload files
- *     and populate `sandbox.skills` in one shot.
+ * Composes an `AgentSandbox` from a backend by layering decorators:
+ *
+ *     backend → observeSandboxFileEvents → withBashExceptionCatch
+ *
+ * The composed sandbox is handed to upstream `bash-tool`; upstream's
+ * internal `bash` / `readFile` / `writeFile` tools therefore close over
+ * the decorated methods. The outer `bash` tool adds:
+ *
+ *   - `reasoning` input on the schema.
+ *   - Generic meta channel (`useBashMeta()`): `setHidden(patch)` attaches
+ *     host-only metadata; `setReminder(text)` surfaces a model-visible
+ *     nudge. `meta` is stripped from model output via `toModelOutput`.
+ *   - Single-shot `skills` upload populating `sandbox.skills`.
  */
-export declare function createBashTool(options?: CreateBashToolWithSkillsOptions): Promise<AgentSandbox>;
+export declare function createBashTool(options: CreateBashToolWithSkillsOptions): Promise<AgentSandbox>;
 //# sourceMappingURL=bash-tool.d.ts.map

package/dist/lib/sandbox/bash-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash-tool.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/bash-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,WAAW,CAAC;AAKnB,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,+BAAgC,SAAQ,qBAAqB;IAC5E;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,YAAY,CAAC,CAkGvB"}
+{"version":3,"file":"bash-tool.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/bash-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,qBAAqB,EAE3B,MAAM,WAAW,CAAC;AAOnB,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AA8BpB,MAAM,WAAW,+BAAgC,SAAQ,IAAI,CAC3D,qBAAqB,EACrB,SAAS,CACV;IACC;;;;;OAKG;IACH,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,YAAY,CAAC,CA6FvB"}

package/dist/lib/sandbox/daytona-sandbox.d.ts

@@ -0,0 +1,63 @@
+import type { DisposableSandbox } from './types.ts';
+export declare const DAYTONA_DEFAULT_DESTINATION = "/home/daytona";
+export interface DaytonaResources {
+    cpu?: number;
+    gpu?: number;
+    memory?: number;
+    disk?: number;
+}
+export interface DaytonaVolumeMount {
+    volumeId: string;
+    mountPath: string;
+    [key: string]: unknown;
+}
+export interface DaytonaSandboxOptions {
+    apiKey?: string;
+    jwtToken?: string;
+    organizationId?: string;
+    apiUrl?: string;
+    target?: string;
+    otelEnabled?: boolean;
+    experimental?: Record<string, unknown>;
+    /**
+     * Existing Daytona sandbox id or name to attach to. Attached sandboxes are
+     * preserved on dispose unless `deleteOnDispose` is explicitly true.
+     */
+    sandboxId?: string;
+    name?: string;
+    user?: string;
+    snapshot?: string;
+    image?: string;
+    language?: string;
+    envVars?: Record<string, string>;
+    labels?: Record<string, string>;
+    public?: boolean;
+    resources?: DaytonaResources;
+    volumes?: DaytonaVolumeMount[];
+    networkAllowList?: string;
+    networkBlockAll?: boolean;
+    autoStopInterval?: number;
+    autoArchiveInterval?: number;
+    autoDeleteInterval?: number;
+    ephemeral?: boolean;
+    createTimeout?: number;
+    startTimeout?: number;
+    deleteTimeout?: number;
+    commandTimeout?: number;
+    onSnapshotCreateLogs?: (chunk: string) => void;
+    deleteOnDispose?: boolean;
+}
+export declare class DaytonaSandboxError extends Error {
+    constructor(message: string, cause?: Error);
+}
+export declare class DaytonaNotAvailableError extends DaytonaSandboxError {
+    constructor(cause?: Error);
+}
+export declare class DaytonaCreationError extends DaytonaSandboxError {
+    constructor(message: string, cause?: Error);
+}
+export declare class DaytonaCommandError extends DaytonaSandboxError {
+    constructor(message: string, cause?: Error);
+}
+export declare function createDaytonaSandbox(options?: DaytonaSandboxOptions): Promise<DisposableSandbox>;
+//# sourceMappingURL=daytona-sandbox.d.ts.map

package/dist/lib/sandbox/daytona-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daytona-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/daytona-sandbox.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,iBAAiB,EAKlB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AAmC3D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AA4FD,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAK3C;AAED,qBAAa,wBAAyB,SAAQ,mBAAmB;gBACnD,KAAK,CAAC,EAAE,KAAK;CAO1B;AAED,qBAAa,oBAAqB,SAAQ,mBAAmB;gBAC/C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED,qBAAa,mBAAoB,SAAQ,mBAAmB;gBAC9C,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAI3C;AAED,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAsC5B"}

package/dist/lib/sandbox/docker-sandbox-errors.d.ts

@@ -17,12 +17,17 @@ export declare class PackageInstallError extends DockerSandboxError {
     readonly stderr: string;
     constructor(packages: string[], image: string, packageManager: 'apk' | 'apt-get', stderr: string, containerId?: string);
 }
-export type InstallSource = 'url' | 'npm' | 'pypi' | 'github-release';
+/**
+ * Discriminator for `InstallError`. Most values are fetch sources (`'npm'`,
+ * `'pypi'`, `'url'`, `'github-release'`); `'bin'` covers the local-filesystem
+ * `BinInstaller` which has no remote source.
+ */
+export type InstallKind = 'url' | 'npm' | 'pypi' | 'github-release' | 'bin';
 export interface InstallErrorOptions {
     /** Logical name of the thing being installed (e.g. `'prettier'`, `'presenterm'`). */
     target: string;
-    /** Where it was being fetched from. */
-    source: InstallSource;
+    /** Installer kind (registry, URL, local binary, …). */
+    source: InstallKind;
     /** Underlying failure message (typically stderr). */
     reason: string;
     /** Resolved URL when applicable (URL binary / GitHub release). */
@@ -31,7 +36,7 @@ export interface InstallErrorOptions {
 }
 export declare class InstallError extends DockerSandboxError {
     readonly target: string;
-    readonly source: InstallSource;
+    readonly source: InstallKind;
     readonly reason: string;
     readonly url?: string;
     constructor(opts: InstallErrorOptions);
@@ -41,10 +46,26 @@ export declare class MissingRuntimeError extends DockerSandboxError {
     readonly required: string[];
     constructor(runtime: string, required: string[], details?: string, containerId?: string);
 }
-export declare class MountPathError extends DockerSandboxError {
-    readonly hostPath: string;
+export declare class VolumePathError extends DockerSandboxError {
+    readonly source: string;
     readonly containerPath: string;
-    constructor(hostPath: string, containerPath: string);
+    readonly reason: string;
+    constructor(source: string, containerPath: string, reason: string);
+}
+export declare class VolumeInspectError extends DockerSandboxError {
+    readonly volume: string;
+    readonly reason: string;
+    constructor(volume: string, reason: string);
+}
+export declare class VolumeCreateError extends DockerSandboxError {
+    readonly volume: string;
+    readonly reason: string;
+    constructor(volume: string, reason: string);
+}
+export declare class VolumeRemoveError extends DockerSandboxError {
+    readonly volume: string;
+    readonly reason: string;
+    constructor(volume: string, reason: string);
 }
 export declare class DockerfileBuildError extends DockerSandboxError {
     readonly stderr: string;

package/dist/lib/sandbox/docker-sandbox-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docker-sandbox-errors.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/docker-sandbox-errors.ts"],"names":[],"mappings":"AAAA,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAKlD;AAED,qBAAa,uBAAwB,SAAQ,kBAAkB;;CAK9D;AAED,qBAAa,sBAAuB,SAAQ,kBAAkB;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAM1D;AAED,qBAAa,mBAAoB,SAAQ,kBAAkB;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,KAAK,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGtB,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,KAAK,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,MAAM;CAavB;AAED,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAAC;AAEtE,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,MAAM,EAAE,aAAa,CAAC;IACtB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAa,SAAQ,kBAAkB;IAClD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,mBAAmB;CAYtC;AAED,qBAAa,mBAAoB,SAAQ,kBAAkB;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;gBAG1B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM;CAQvB;AAED,qBAAa,cAAe,SAAQ,kBAAkB;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;CAQpD;AAED,qBAAa,oBAAqB,SAAQ,kBAAkB;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED,qBAAa,iBAAkB,SAAQ,kBAAkB;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMhD"}
+{"version":3,"file":"docker-sandbox-errors.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/docker-sandbox-errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/sandbox/docker-sandbox.d.ts

@@ -1,19 +1,58 @@
-import { type CommandResult, type Sandbox } from 'bash-tool';
+import { type CommandResult } from 'bash-tool';
 import { type Installer } from './installers/installer.ts';
+import type { DisposableSandbox, ExecuteCommandOptions, SandboxProcess, SpawnOptions } from './types.ts';
 export type { CommandResult as ExecResult, Sandbox } from 'bash-tool';
-export { ComposeStartError, ContainerCreationError, DockerNotAvailableError, DockerSandboxError, DockerfileBuildError, type InstallErrorOptions, type InstallSource, InstallError, MissingRuntimeError, MountPathError, PackageInstallError, } from './docker-sandbox-errors.ts';
-export interface DockerMount {
+export { ComposeStartError, ContainerCreationError, DockerNotAvailableError, DockerSandboxError, DockerfileBuildError, type InstallErrorOptions, type InstallKind, InstallError, MissingRuntimeError, PackageInstallError, VolumeCreateError, VolumeInspectError, VolumePathError, VolumeRemoveError, } from './docker-sandbox-errors.ts';
+export interface DockerBindVolume {
+    type: 'bind';
     hostPath: string;
     containerPath: string;
     /** Default: `true`. */
     readOnly?: boolean;
 }
+export interface DockerNamedVolume {
+    type: 'volume';
+    name: string;
+    containerPath: string;
+    /** Default: `true`. */
+    readOnly?: boolean;
+    /** Default: `'external'`. */
+    lifecycle?: 'external' | 'managed';
+    /** Docker volume driver used when `lifecycle` is `'managed'`. */
+    driver?: string;
+    /** Docker volume driver options used when `lifecycle` is `'managed'`. */
+    driverOptions?: Record<string, string>;
+    subPath?: string;
+    noCopy?: boolean;
+    /** Default: `true` for managed volumes created by this sandbox. */
+    removeOnDispose?: boolean;
+}
+export type DockerSandboxVolume = DockerBindVolume | DockerNamedVolume;
 export interface DockerResources {
     /** e.g. `'1g'`, `'512m'`. */
     memory?: string;
     /** Number of CPUs. */
     cpus?: number;
 }
+/**
+ * Stable identity suffix for the container. When provided, the container
+ * is named `sandbox-<name>` instead of getting a randomized
+ * `sandbox-<8hex>`. If a container with that name already exists on the
+ * host, the sandbox attaches to it: installers, volume preparation, and
+ * env are skipped (the pre-existing container is assumed already
+ * configured). If it exists but is stopped, it is started first.
+ * Otherwise the container is created fresh and installers run as usual.
+ *
+ * Must match `/^[A-Za-z0-9_.-]+$/`. The full Docker container name
+ * (`sandbox-<name>`) is always legal because the prefix begins with an
+ * alphanumeric character.
+ *
+ * Warning: `dispose()` stops (and `--rm` removes) the container regardless
+ * of whether it was created or attached to. If two callers in the same
+ * process share a name, the first `dispose()` destroys the container the
+ * other one is still using.
+ */
+type StableContainerName = string;
 export interface RuntimeSandboxOptions {
     /** Docker image to use (default: `'alpine:latest'`). */
     image?: string;
@@ -23,18 +62,20 @@ export interface RuntimeSandboxOptions {
      * `githubRelease({...})`, or any custom `Installer` subclass.
      */
     installers?: Installer[];
-    mounts?: DockerMount[];
+    volumes?: DockerSandboxVolume[];
     resources?: DockerResources;
     env?: Record<string, string>;
+    name?: StableContainerName;
 }
 export interface DockerfileSandboxOptions {
     /** Inline Dockerfile content (contains `\n`) or a path. */
     dockerfile: string;
     /** Build context directory (default: `'.'`). */
     context?: string;
-    mounts?: DockerMount[];
+    volumes?: DockerSandboxVolume[];
     resources?: DockerResources;
     env?: Record<string, string>;
+    name?: StableContainerName;
 }
 export interface ComposeSandboxOptions {
     compose: string;
@@ -42,9 +83,6 @@ export interface ComposeSandboxOptions {
     resources?: DockerResources;
 }
 export type DockerSandboxOptions = RuntimeSandboxOptions | DockerfileSandboxOptions | ComposeSandboxOptions;
-export interface DockerSandbox extends Sandbox {
-    dispose(): Promise<void>;
-}
 export declare function isDockerfileOptions(opts: DockerSandboxOptions): opts is DockerfileSandboxOptions;
 export declare function isComposeOptions(opts: DockerSandboxOptions): opts is ComposeSandboxOptions;
 interface StrategyContext {
@@ -52,9 +90,10 @@ interface StrategyContext {
     image: string;
 }
 export interface DockerSandboxStrategyArgs {
-    mounts?: DockerMount[];
+    volumes?: DockerSandboxVolume[];
     resources?: DockerResources;
     env?: Record<string, string>;
+    name?: StableContainerName;
 }
 /**
  * Template Method base for sandbox creation strategies. Subclasses choose
@@ -63,17 +102,41 @@ export interface DockerSandboxStrategyArgs {
  */
 export declare abstract class DockerSandboxStrategy {
     protected context: StrategyContext;
-    protected mounts: DockerMount[];
+    protected volumes: DockerSandboxVolume[];
     protected resources: DockerResources;
     protected env: Record<string, string>;
+    protected name?: StableContainerName;
+    private createdVolumes;
     constructor(args?: DockerSandboxStrategyArgs);
-    create(): Promise<DockerSandbox>;
-    protected validateMounts(): void;
+    create(): Promise<DisposableSandbox>;
+    private namedContainerId;
+    protected defaultContainerId(): string;
+    protected acquireContainer(image: string): Promise<{
+        containerId: string;
+        attached: boolean;
+    }>;
+    private startStoppedContainer;
+    protected inspectContainer(containerId: string): Promise<'running' | 'stopped' | 'absent'>;
+    private isMissingContainerError;
+    private isNameConflictError;
+    protected prepareVolumes(): Promise<void>;
+    protected validateVolumes(): void;
+    private validateMountValue;
     protected buildDockerArgs(image: string, containerId: string): string[];
-    protected startContainer(image: string): Promise<string>;
+    protected buildVolumeMountArg(volume: DockerSandboxVolume): string;
+    private inspectVolume;
+    private volumeExists;
+    private createVolume;
+    private cleanupCreatedVolumes;
+    private cleanupCreatedVolumesAfterFailure;
+    private getDockerErrorMessage;
+    private isDockerUnavailableError;
+    private isMissingVolumeInspectError;
+    protected startContainer(image: string, containerId: string): Promise<void>;
     protected stopContainer(containerId: string): Promise<void>;
-    protected exec(command: string): Promise<CommandResult>;
-    protected createSandboxMethods(): DockerSandbox;
+    protected exec(command: string, options?: ExecuteCommandOptions): Promise<CommandResult>;
+    protected spawnProcess(command: string, options?: SpawnOptions): SandboxProcess;
+    protected createSandboxMethods(): DisposableSandbox;
     protected abstract getImage(): Promise<string>;
     protected abstract configure(): Promise<void>;
 }
@@ -139,9 +202,11 @@ export declare class ComposeStrategy extends DockerSandboxStrategy {
     constructor(args: ComposeStrategyArgs);
     private computeProjectName;
     protected getImage(): Promise<string>;
-    protected startContainer(_image: string): Promise<string>;
+    protected startContainer(_image: string, _containerId: string): Promise<void>;
+    protected defaultContainerId(): string;
     protected configure(): Promise<void>;
-    protected exec(command: string): Promise<CommandResult>;
+    protected exec(command: string, options?: ExecuteCommandOptions): Promise<CommandResult>;
+    protected spawnProcess(command: string, options?: SpawnOptions): SandboxProcess;
     protected stopContainer(_containerId: string): Promise<void>;
 }
 /**
@@ -179,10 +244,10 @@ export declare class ComposeStrategy extends DockerSandboxStrategy {
  * });
  * ```
  */
-export declare function createDockerSandbox(options?: DockerSandboxOptions): Promise<DockerSandbox>;
+export declare function createDockerSandbox(options?: DockerSandboxOptions): Promise<DisposableSandbox>;
 /**
  * Run a function with a Docker sandbox; the container is disposed on
  * completion (success or thrown).
  */
-export declare function useSandbox<T>(options: DockerSandboxOptions, fn: (sandbox: DockerSandbox) => Promise<T>): Promise<T>;
+export declare function useSandbox<T>(options: DockerSandboxOptions, fn: (sandbox: DisposableSandbox) => Promise<T>): Promise<T>;
 //# sourceMappingURL=docker-sandbox.d.ts.map

package/dist/lib/sandbox/docker-sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docker-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/docker-sandbox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"docker-sandbox.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/docker-sandbox.ts"],"names":[],"mappings":"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"}

package/dist/lib/sandbox/file-events.d.ts

@@ -1,47 +1,42 @@
-import type { BufferEncoding, CpOptions, FileContent, FsStat, IFileSystem, MkdirOptions, RmOptions } from 'just-bash';
-interface ReadFileOptions {
-    encoding?: BufferEncoding | null;
-}
-interface WriteFileOptions {
-    encoding?: BufferEncoding;
-}
-interface DirentEntry {
-    name: string;
-    isFile: boolean;
-    isDirectory: boolean;
-    isSymbolicLink: boolean;
-}
+import type { DisposableSandbox } from './types.ts';
 export type FileEventOp = 'read' | 'write' | 'delete' | 'modify';
 export interface FileEvent {
     path: string;
     op: FileEventOp;
     timestamp: number;
 }
-export declare class ObservedFs implements IFileSystem {
-    #private;
-    readdirWithFileTypes?: (path: string) => Promise<DirentEntry[]>;
-    constructor(base: IFileSystem);
+export interface ObserveOptions {
+    destination: string;
+}
+export interface SandboxObserver {
+    sandbox: DisposableSandbox;
     drain(): FileEvent[];
-    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
-    readFileBuffer(path: string): Promise<Uint8Array>;
-    writeFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
-    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
-    rm(path: string, options?: RmOptions): Promise<void>;
-    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-    mv(src: string, dest: string): Promise<void>;
-    symlink(target: string, linkPath: string): Promise<void>;
-    link(existingPath: string, newPath: string): Promise<void>;
-    mkdir(path: string, options?: MkdirOptions): Promise<void>;
-    exists(path: string): Promise<boolean>;
-    stat(path: string): Promise<FsStat>;
-    lstat(path: string): Promise<FsStat>;
-    readdir(path: string): Promise<string[]>;
-    readlink(path: string): Promise<string>;
-    realpath(path: string): Promise<string>;
-    chmod(path: string, mode: number): Promise<void>;
-    utimes(path: string, atime: Date, mtime: Date): Promise<void>;
-    resolvePath(base: string, path: string): string;
-    getAllPaths(): string[];
 }
-export {};
+export declare class SnapshotFailedError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+/**
+ * Wraps a `Sandbox` with file-event observation rooted at `destination`.
+ *
+ * - `executeCommand` and `writeFiles` are bracketed by `find -print0` +
+ *   `sha256sum` snapshots; hash diff produces write/modify/delete events.
+ * - `readFile` records a `read` event on success.
+ * - `spawn` (when the backend exposes it) is bracketed similarly: the
+ *   before-snapshot resolves before the inner spawn starts (via a
+ *   lazy `ReadableStream`), and the returned `exit` Promise resolves only
+ *   after the after-snapshot is recorded. The after-snapshot runs when the
+ *   OS reports child exit; data still buffered in stdio after that point
+ *   is *not* observed — write events for files flushed only on stream
+ *   close may be missed.
+ * - If `destination` does not exist in the sandbox at snapshot time, the
+ *   snapshot is treated as empty (graceful — supports observation rooted at
+ *   paths that the sandbox will create later). Snapshot command failures
+ *   (e.g. permission denied, missing `find`) throw `SnapshotFailedError`
+ *   from `executeCommand`/`writeFiles`, but are silently dropped on `spawn`
+ *   because the caller's signal already comes via `exit`.
+ * - Single-flight by convention. Concurrent `executeCommand` calls are not
+ *   serialized internally and will produce interleaved diffs.
+ */
+export declare function observeSandboxFileEvents(sandbox: DisposableSandbox, options: ObserveOptions): SandboxObserver;
 //# sourceMappingURL=file-events.d.ts.map

package/dist/lib/sandbox/file-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-events.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/file-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-events.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/file-events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAY,MAAM,YAAY,CAAC;AAE9D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,IAAI,SAAS,EAAE,CAAC;CACtB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AA6ED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,cAAc,GACtB,eAAe,CA0FjB"}

package/dist/lib/sandbox/index.d.ts

@@ -1,10 +1,11 @@
+export * from './abort.ts';
 export * from './agent-os-sandbox.ts';
 export * from './bash-exception.ts';
 export * from './bash-meta.ts';
 export * from './bash-tool.ts';
 export * from './file-events.ts';
 export * from './binary-bridges.ts';
-export * from './container-tool.ts';
+export * from './daytona-sandbox.ts';
 export * from './docker-sandbox.ts';
 export * from './installers/index.ts';
 export * from './subcommand.ts';