@deepagents/context 0.39.0 → 2.1.0

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

@@ -1,12 +1,13 @@
 import type { CreateBashToolOptions } from 'bash-tool';
-import { type BinaryInstall, type DockerMount, type DockerResources, type DockerSandbox } from './docker-sandbox.ts';
+import { type DockerResources, type DockerSandboxVolume } from './docker-sandbox.ts';
+import type { Installer } from './installers/installer.ts';
 import type { AgentSandbox, SkillUploadInput } from './types.ts';
 /**
  * Base options shared by RuntimeContainerToolOptions and DockerfileContainerToolOptions.
  */
 interface BaseContainerToolOptions extends Omit<CreateBashToolOptions, 'sandbox' | 'uploadDirectory'> {
-    /** Directories to mount from host into the container */
-    mounts?: DockerMount[];
+    /** Bind paths or Docker-managed volumes to attach to the container. */
+    volumes?: DockerSandboxVolume[];
     /** Resource limits for the container */
     resources?: DockerResources;
     /** Environment variables to set in the container */
@@ -16,6 +17,14 @@ interface BaseContainerToolOptions extends Omit<CreateBashToolOptions, 'sandbox'
      * contents are copied to `sandbox` and parsed into `sandbox.skills`.
      */
     skills?: SkillUploadInput[];
+    /**
+     * Stable container name suffix. When set, the container is named
+     * `sandbox-<name>`; subsequent calls with the same `name` attach to the
+     * running (or stopped) container instead of creating a new one — skipping
+     * installers, volume setup, and env. Otherwise a randomized
+     * `sandbox-<8hex>` name is used per call.
+     */
+    name?: string;
 }
 /**
  * Options for container tool using RuntimeStrategy.
@@ -24,10 +33,31 @@ interface BaseContainerToolOptions extends Omit<CreateBashToolOptions, 'sandbox'
 export interface RuntimeContainerToolOptions extends BaseContainerToolOptions {
     /** Docker image to use (default: 'alpine:latest') */
     image?: string;
-    /** Packages to install in the container via package manager (apk/apt) */
-    packages?: string[];
-    /** Binaries to install from URLs (for tools not in package managers) */
-    binaries?: BinaryInstall[];
+    /**
+     * Ordered list of installers run after the container starts.
+     *
+     * Built-in factory helpers:
+     * - `pkg([...])` — OS packages (apk/apt-get auto-detected)
+     * - `urlBinary({ name, url, binaryPath? })` — pre-built binary from a URL
+     * - `npm(name, { ensureRuntime?, version? })` — global npm install
+     * - `pip(name, { ensureRuntime?, version? })` — pip install
+     * - `githubRelease({ owner, repo, version, name, asset })` — GitHub release asset
+     *
+     * For anything else, subclass `Installer` and pass an instance directly.
+     *
+     * @example
+     * ```ts
+     * import { pkg, urlBinary, npm } from '@deepagents/context';
+     *
+     * createContainerTool({
+     *   installers: [
+     *     pkg(['curl', 'jq']),
+     *     npm('prettier', { ensureRuntime: true }),
+     *   ],
+     * });
+     * ```
+     */
+    installers?: Installer[];
 }
 /**
  * Options for container tool using DockerfileStrategy.
@@ -63,14 +93,6 @@ export interface ComposeContainerToolOptions extends Omit<CreateBashToolOptions,
  * - ComposeContainerToolOptions: Multi-container environments via Docker Compose
  */
 export type ContainerToolOptions = RuntimeContainerToolOptions | DockerfileContainerToolOptions | ComposeContainerToolOptions;
-/**
- * Result of creating a container tool. Extends AgentSandbox (so
- * `sandbox.skills` is populated from the `skills` option) but with
- * DockerSandbox (which has dispose()) as the underlying sandbox.
- */
-export type ContainerToolResult = Omit<AgentSandbox, 'sandbox'> & {
-    sandbox: DockerSandbox;
-};
 /**
  * Creates a bash tool that runs in a Docker container.
  *
@@ -89,9 +111,12 @@ export type ContainerToolResult = Omit<AgentSandbox, 'sandbox'> & {
  *
  * @example RuntimeStrategy (default)
  * ```typescript
+ * import { createContainerTool, pkg } from '@deepagents/context';
+ *
  * const sandbox = await createContainerTool({
- *   packages: ['curl', 'jq'],
- *   mounts: [{
+ *   installers: [pkg(['curl', 'jq'])],
+ *   volumes: [{
+ *     type: 'bind',
  *     hostPath: process.cwd(),
  *     containerPath: '/workspace',
  *     readOnly: false,
@@ -112,7 +137,7 @@ export type ContainerToolResult = Omit<AgentSandbox, 'sandbox'> & {
  * @example RuntimeStrategy with skills
  * ```typescript
  * const sandbox = await createContainerTool({
- *   packages: ['curl', 'jq'],
+ *   installers: [pkg(['curl', 'jq'])],
  *   skills: [
  *     { host: './skills', sandbox: '/workspace/skills' },
  *   ],
@@ -129,7 +154,8 @@ export type ContainerToolResult = Omit<AgentSandbox, 'sandbox'> & {
  *     RUN pip install pandas numpy
  *   `,
  *   context: '.',
- *   mounts: [{
+ *   volumes: [{
+ *     type: 'bind',
  *     hostPath: process.cwd(),
  *     containerPath: '/workspace',
  *   }],
@@ -149,7 +175,7 @@ export type ContainerToolResult = Omit<AgentSandbox, 'sandbox'> & {
  * @example With hooks for logging
  * ```typescript
  * const sandbox = await createContainerTool({
- *   packages: ['python3'],
+ *   installers: [pkg(['python3'])],
  *   onBeforeBashCall: ({ command }) => {
  *     console.log('Running:', command);
  *   },
@@ -159,6 +185,6 @@ export type ContainerToolResult = Omit<AgentSandbox, 'sandbox'> & {
  * });
  * ```
  */
-export declare function createContainerTool(options?: ContainerToolOptions): Promise<ContainerToolResult>;
+export declare function createContainerTool(options?: ContainerToolOptions): Promise<AgentSandbox>;
 export {};
 //# sourceMappingURL=container-tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"container-tool.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/container-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGvD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,aAAa,EAKnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjE;;GAEG;AACH,UAAU,wBAAyB,SAAQ,IAAI,CAC7C,qBAAqB,EACrB,SAAS,GAAG,iBAAiB,CAC9B;IACC,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,wCAAwC;IACxC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB;IAC3E,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA+B,SAAQ,wBAAwB;IAC9E,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,qBAAqB,EACrB,SAAS,GAAG,iBAAiB,CAC9B;IACC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B,2BAA2B,GAC3B,8BAA8B,GAC9B,2BAA2B,CAAC;AAEhC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,GAAG;IAChE,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAqD9B"}
+{"version":3,"file":"container-tool.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/container-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGvD,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,mBAAmB,EAIzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjE;;GAEG;AACH,UAAU,wBAAyB,SAAQ,IAAI,CAC7C,qBAAqB,EACrB,SAAS,GAAG,iBAAiB,CAC9B;IACC,uEAAuE;IACvE,OAAO,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAChC,wCAAwC;IACxC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB;IAC3E,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,8BAA+B,SAAQ,wBAAwB;IAC9E,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,qBAAqB,EACrB,SAAS,GAAG,iBAAiB,CAC9B;IACC,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B,2BAA2B,GAC3B,8BAA8B,GAC9B,2BAA2B,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,YAAY,CAAC,CAuDvB"}

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

@@ -0,0 +1,74 @@
+export declare class DockerSandboxError extends Error {
+    readonly containerId?: string;
+    constructor(message: string, containerId?: string);
+}
+export declare class DockerNotAvailableError extends DockerSandboxError {
+    constructor();
+}
+export declare class ContainerCreationError extends DockerSandboxError {
+    readonly image: string;
+    cause?: Error;
+    constructor(message: string, image: string, cause?: Error);
+}
+export declare class PackageInstallError extends DockerSandboxError {
+    readonly packages: string[];
+    readonly image: string;
+    readonly packageManager: 'apk' | 'apt-get';
+    readonly stderr: string;
+    constructor(packages: string[], image: string, packageManager: 'apk' | 'apt-get', stderr: string, containerId?: string);
+}
+export type InstallSource = 'url' | 'npm' | 'pypi' | 'github-release';
+export interface InstallErrorOptions {
+    /** Logical name of the thing being installed (e.g. `'prettier'`, `'presenterm'`). */
+    target: string;
+    /** Where it was being fetched from. */
+    source: InstallSource;
+    /** Underlying failure message (typically stderr). */
+    reason: string;
+    /** Resolved URL when applicable (URL binary / GitHub release). */
+    url?: string;
+    containerId?: string;
+}
+export declare class InstallError extends DockerSandboxError {
+    readonly target: string;
+    readonly source: InstallSource;
+    readonly reason: string;
+    readonly url?: string;
+    constructor(opts: InstallErrorOptions);
+}
+export declare class MissingRuntimeError extends DockerSandboxError {
+    readonly runtime: string;
+    readonly required: string[];
+    constructor(runtime: string, required: string[], details?: string, containerId?: string);
+}
+export declare class VolumePathError extends DockerSandboxError {
+    readonly source: string;
+    readonly 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;
+    constructor(stderr: string);
+}
+export declare class ComposeStartError extends DockerSandboxError {
+    readonly composeFile: string;
+    readonly stderr: string;
+    constructor(composeFile: string, stderr: string);
+}
+//# sourceMappingURL=docker-sandbox-errors.d.ts.map

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

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