@deepagents/context 0.10.2 → 0.12.0

package/dist/lib/fragments.d.ts

@@ -0,0 +1,103 @@
+import { type UIMessage } from 'ai';
+import type { FragmentCodec } from './codec.ts';
+/**
+ * Fragment type identifier.
+ * - 'fragment': Regular context fragment (default)
+ * - 'message': Conversation message (user/assistant)
+ */
+export type FragmentType = 'fragment' | 'message';
+/**
+ * A context fragment containing a name and associated data.
+ */
+export interface ContextFragment<T extends FragmentData = FragmentData> {
+    /**
+     * Unique identifier for this fragment.
+     * Auto-generated for user/assistant messages, optional for other fragments.
+     */
+    id?: string;
+    name: string;
+    data: T;
+    /**
+     * Fragment type for categorization.
+     * Messages use 'message' type and are handled separately during resolve().
+     */
+    type?: FragmentType;
+    /**
+     * When true, this fragment will be persisted to the store on save().
+     */
+    persist?: boolean;
+    /**
+     * Codec for encoding/decoding this fragment.
+     * Used by resolve() to convert to AI SDK format.
+     */
+    codec?: FragmentCodec;
+}
+/**
+ * Fragment data can be a primitive, array, object, or nested fragment.
+ */
+export type FragmentData = string | number | null | undefined | boolean | ContextFragment | FragmentData[] | {
+    [key: string]: FragmentData;
+};
+/**
+ * Type guard to check if data is a ContextFragment.
+ */
+export declare function isFragment(data: unknown): data is ContextFragment;
+/**
+ * A plain object with string keys and FragmentData values.
+ */
+export type FragmentObject = Record<string, FragmentData>;
+/**
+ * Type guard to check if data is a plain object (not array, not fragment, not primitive).
+ */
+export declare function isFragmentObject(data: unknown): data is FragmentObject;
+/**
+ * Type guard to check if a fragment is a message fragment.
+ */
+export declare function isMessageFragment(fragment: ContextFragment): boolean;
+export declare function fragment(name: string, ...children: FragmentData[]): ContextFragment;
+/**
+ * Create a user message fragment.
+ * Message fragments are separated from regular fragments during resolve().
+ *
+ * @param content - The message content
+ * @param options - Optional settings (id)
+ *
+ * @example
+ * ```ts
+ * context.set(user('Hello'));                     // Auto-generated ID
+ * context.set(user('Hello', { id: 'msg-1' }));   // Custom ID
+ * ```
+ */
+export declare function user(content: string | UIMessage): ContextFragment;
+/**
+ * Create an assistant message fragment.
+ * Message fragments are separated from regular fragments during resolve().
+ *
+ * @param message - The message content
+ * @param options - Optional settings (id)
+ *
+ * @example
+ * ```ts
+ * context.set(assistant('Hi there!'));                    // Auto-generated ID
+ * context.set(assistant('Hi there!', { id: 'resp-1' })); // Custom ID
+ * ```
+ */
+export declare function assistant(message: UIMessage): ContextFragment;
+export declare function message(content: string | UIMessage): ContextFragment;
+/**
+ * Create an assistant message fragment from text content.
+ * Convenience wrapper that creates a UIMessage internally.
+ *
+ * @param content - The message text content
+ * @param options - Optional settings (id)
+ *
+ * @example
+ * ```ts
+ * context.set(assistantText('Hi there!'));                    // Auto-generated ID
+ * context.set(assistantText('Hi there!', { id: 'resp-1' })); // Custom ID
+ * ```
+ */
+export declare function assistantText(content: string, options?: {
+    id?: string;
+}): ContextFragment;
+//# sourceMappingURL=fragments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.d.ts","sourceRoot":"","sources":["../../src/lib/fragments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,IAAI,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY;IACpE;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,CAAC,CAAC;IACR;;;OAGG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,MAAM,GACN,IAAI,GACJ,SAAS,GACT,OAAO,GACP,eAAe,GACf,YAAY,EAAE,GACd;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAEpC;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,eAAe,CAQjE;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AAE1D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,cAAc,CAOtE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAEpE;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,GAAG,QAAQ,EAAE,YAAY,EAAE,GAC1B,eAAe,CAKjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAwBjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,GAAG,eAAe,CAgB7D;AACD,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAwBpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GACxB,eAAe,CAOjB"}

package/dist/lib/guardrail.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Guardrail system for real-time stream interception and self-correction.
+ *
+ * Guardrails inspect streaming parts and can either:
+ * - `pass(part)`: Allow the part through (optionally modified)
+ * - `fail(feedback)`: Abort the stream and retry with self-correction feedback
+ *
+ * When a guardrail fails, the accumulated text is combined with the feedback
+ * to create a "self-correction" that appears as if the agent caught itself.
+ *
+ * @example
+ * ```typescript
+ * const safetyGuardrail: Guardrail = {
+ *   id: 'safety',
+ *   name: 'Safety Filter',
+ *   handle: (part, context) => {
+ *     if (part.type === 'text-delta' && part.delta.includes('unsafe')) {
+ *       return fail('I should not provide this information. Let me help differently.');
+ *     }
+ *     if (part.type === 'error' && context.availableTools.length > 0) {
+ *       return fail(`Try using: ${context.availableTools.join(', ')}`);
+ *     }
+ *     return pass(part);
+ *   },
+ * };
+ *
+ * const agent = agent({
+ *   name: 'safe_assistant',
+ *   context,
+ *   model,
+ *   guardrails: [safetyGuardrail],
+ * });
+ * ```
+ */
+import type { InferUIMessageChunk, UIDataTypes, UIMessage } from 'ai';
+/**
+ * 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>>>;
+/**
+ * Result of a guardrail check.
+ * - `pass`: The part is allowed through (optionally modified)
+ * - `fail`: The stream should abort and retry with feedback
+ */
+export type GuardrailResult = {
+    type: 'pass';
+    part: StreamPart;
+} | {
+    type: 'fail';
+    feedback: string;
+};
+/**
+ * Context passed to guardrails during stream processing.
+ * Provides information about the agent's capabilities.
+ */
+export interface GuardrailContext {
+    /** Names of tools available to the agent */
+    availableTools: string[];
+}
+/**
+ * A guardrail that inspects streaming parts.
+ */
+export interface Guardrail {
+    /** Unique identifier for this guardrail */
+    id: string;
+    /** Human-readable name for logging/debugging */
+    name: string;
+    /**
+     * Handle a stream part.
+     *
+     * @param part - The full stream part to inspect (text-delta, error, etc.)
+     * @param context - Context with agent capabilities (available tools, etc.)
+     * @returns Either `pass(part)` to allow or `fail(feedback)` to abort and retry
+     */
+    handle: (part: StreamPart, context: GuardrailContext) => GuardrailResult;
+}
+/**
+ * Configuration for guardrail behavior.
+ */
+export interface GuardrailConfig {
+    /** Maximum number of retry attempts when guardrails fail (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Allow a part to pass through the guardrail.
+ *
+ * @param part - The part to pass (can be modified from original)
+ * @returns A pass result
+ *
+ * @example
+ * ```typescript
+ * handle: (part) => {
+ *   // Pass through unchanged
+ *   return pass(part);
+ *
+ *   // Or modify text-delta before passing
+ *   if (part.type === 'text-delta') {
+ *     return pass({ ...part, delta: part.delta.replace('bad', 'good') });
+ *   }
+ *   return pass(part);
+ * }
+ * ```
+ */
+export declare function pass(part: StreamPart): GuardrailResult;
+/**
+ * Fail the guardrail check and trigger a retry with feedback.
+ *
+ * The feedback will be appended to the accumulated assistant text,
+ * making it appear as if the agent "caught itself" and self-corrected.
+ *
+ * @param feedback - The self-correction feedback to append
+ * @returns A fail result
+ *
+ * @example
+ * ```typescript
+ * handle: (part) => {
+ *   if (part.type === 'text-delta' && part.delta.includes('hack')) {
+ *     return fail('I should not provide hacking instructions. Let me suggest ethical alternatives.');
+ *   }
+ *   if (part.type === 'error') {
+ *     return fail('An error occurred. Let me try a different approach.');
+ *   }
+ *   return pass(part);
+ * }
+ * ```
+ */
+export declare function fail(feedback: string): GuardrailResult;
+/**
+ * Run a part through a chain of guardrails sequentially.
+ *
+ * @param part - The stream part to check
+ * @param guardrails - Array of guardrails to run in order
+ * @param context - Context with agent capabilities (available tools, etc.)
+ * @returns The final result after all guardrails pass, or the first failure
+ */
+export declare function runGuardrailChain(part: StreamPart, guardrails: Guardrail[], context: GuardrailContext): GuardrailResult;
+//# sourceMappingURL=guardrail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail.d.ts","sourceRoot":"","sources":["../../src/lib/guardrail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,mBAAmB,CAC1C,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CACvD,CAAC;AAEF;;;;GAIG;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,CAAC;AAEvC;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;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;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,SAAS,EAAE,EACvB,OAAO,EAAE,gBAAgB,GACxB,eAAe,CAejB"}

package/dist/lib/guardrails/error-recovery.guardrail.d.ts

@@ -0,0 +1,3 @@
+import type { Guardrail } from '../guardrail.ts';
+export declare const errorRecoveryGuardrail: Guardrail;
+//# sourceMappingURL=error-recovery.guardrail.d.ts.map

package/dist/lib/guardrails/error-recovery.guardrail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-recovery.guardrail.d.ts","sourceRoot":"","sources":["../../../src/lib/guardrails/error-recovery.guardrail.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,eAAO,MAAM,sBAAsB,EAAE,SAsFpC,CAAC"}

package/dist/lib/render.d.ts

@@ -0,0 +1,21 @@
+import { type ContextFragment } from './fragments.ts';
+/**
+ * Render fragments to XML.
+ *
+ * Wraps fragments in a parent tag and renders using XmlRenderer.
+ *
+ * @param tag - Parent tag name (e.g., 'instructions')
+ * @param fragments - Fragments to render
+ * @returns XML string
+ *
+ * @example
+ * ```ts
+ * const xml = render(
+ *   'instructions',
+ *   persona({ name: 'Freya', role: 'Data Assistant' }),
+ *   guardrail({ rule: 'Never expose PII' }),
+ * );
+ * ```
+ */
+export declare function render(tag: string, ...fragments: ContextFragment[]): string;
+//# sourceMappingURL=render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/lib/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAY,MAAM,gBAAgB,CAAC;AAGhE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,eAAe,EAAE,GAAG,MAAM,CAQ3E"}

package/dist/lib/renderers/abstract.renderer.d.ts

@@ -1,4 +1,4 @@
-import { type ContextFragment, type FragmentData, type FragmentObject } from '../context.ts';
+import { type ContextFragment, type FragmentData, type FragmentObject } from '../fragments.ts';
 /**
  * Render context passed through the template method.
  */
@@ -32,6 +32,14 @@ export declare abstract class ContextRenderer {
      * Group fragments by name for groupFragments option.
      */
     protected groupByName(fragments: ContextFragment[]): Map<string, ContextFragment[]>;
+    /**
+     * Remove null/undefined from fragments and fragment data recursively.
+     * This protects renderers from nullish values and ensures they are ignored
+     * consistently across all output formats.
+     */
+    protected sanitizeFragments(fragments: ContextFragment[]): ContextFragment[];
+    protected sanitizeFragment(fragment: ContextFragment, seen: WeakSet<object>): ContextFragment | null;
+    protected sanitizeData(data: FragmentData, seen: WeakSet<object>): FragmentData | undefined;
     /**
      * Template method - dispatches value to appropriate handler.
      */
@@ -80,8 +88,8 @@ export declare class TomlRenderer extends ContextRenderer {
      * Override renderValue to preserve type information for TOML formatting.
      */
     protected renderValue(key: string, value: unknown, ctx: RenderContext): string;
-    protected renderPrimitive(key: string, value: string, _ctx: RenderContext): string;
-    protected renderArray(key: string, items: FragmentData[], _ctx: RenderContext): string;
+    protected renderPrimitive(key: string, value: string, ctx: RenderContext): string;
+    protected renderArray(key: string, items: FragmentData[], ctx: RenderContext): string;
     protected renderObject(key: string, obj: FragmentObject, ctx: RenderContext): string;
     protected renderFragment(fragment: ContextFragment, ctx: RenderContext): string;
 }

package/dist/lib/renderers/abstract.renderer.d.ts.map

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

package/dist/lib/sandbox/binary-bridges.d.ts

@@ -0,0 +1,31 @@
+import { type CustomCommand } from 'just-bash';
+export interface BinaryBridgeConfig {
+    /** Command name in the sandbox (what the agent types) */
+    name: string;
+    /** Actual binary path on the host system (defaults to name) */
+    binaryPath?: string;
+    /** Optional regex to restrict allowed arguments for security */
+    allowedArgs?: RegExp;
+}
+export type BinaryBridgeInput = string | BinaryBridgeConfig;
+/**
+ * Creates custom commands that bridge to real system binaries.
+ *
+ * This allows just-bash sandboxed environments to execute specific
+ * host system binaries while maintaining control over which binaries
+ * are accessible.
+ *
+ * @example
+ * // Simple - just strings (name === binaryPath)
+ * createBinaryBridges('presenterm', 'node', 'cargo')
+ *
+ * @example
+ * // Mixed - strings and config objects
+ * createBinaryBridges(
+ *   'presenterm',
+ *   { name: 'python', binaryPath: 'python3' },
+ *   { name: 'git', allowedArgs: /^(status|log|diff)/ }
+ * )
+ */
+export declare function createBinaryBridges(...binaries: BinaryBridgeInput[]): CustomCommand[];
+//# sourceMappingURL=binary-bridges.d.ts.map

package/dist/lib/sandbox/binary-bridges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-bridges.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/binary-bridges.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,WAAW,CAAC;AAI9D,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,kBAAkB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,QAAQ,EAAE,iBAAiB,EAAE,GAC/B,aAAa,EAAE,CA2GjB"}

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

@@ -0,0 +1,134 @@
+import { type CreateBashToolOptions, type BashToolkit } from 'bash-tool';
+import { type BinaryInstall, type DockerMount, type DockerResources, type DockerSandbox } from './docker-sandbox.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[];
+    /** Resource limits for the container */
+    resources?: DockerResources;
+}
+/**
+ * Options for container tool using RuntimeStrategy.
+ * Installs packages/binaries at container runtime.
+ */
+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[];
+}
+/**
+ * Options for container tool using DockerfileStrategy.
+ * Builds custom image from Dockerfile (with caching).
+ */
+export interface DockerfileContainerToolOptions extends BaseContainerToolOptions {
+    /** Dockerfile content (if contains newlines) or path to Dockerfile */
+    dockerfile: string;
+    /** Build context directory (default: '.') */
+    context?: string;
+}
+/**
+ * Options for container tool using ComposeStrategy.
+ * Manages multi-container environments via Docker Compose.
+ */
+export interface ComposeContainerToolOptions extends Omit<CreateBashToolOptions, 'sandbox' | 'uploadDirectory'> {
+    /** Path to docker-compose.yml file */
+    compose: string;
+    /** Service name to execute commands in (required) */
+    service: string;
+    /** Resource limits for the container */
+    resources?: DockerResources;
+}
+/**
+ * Union type for container tool options.
+ * - RuntimeContainerToolOptions: Runtime package/binary installation
+ * - DockerfileContainerToolOptions: Pre-built images from Dockerfile
+ * - ComposeContainerToolOptions: Multi-container environments via Docker Compose
+ */
+export type ContainerToolOptions = RuntimeContainerToolOptions | DockerfileContainerToolOptions | ComposeContainerToolOptions;
+/**
+ * Result of creating a container tool.
+ * Extends BashToolkit but with DockerSandbox (which has dispose()) instead of base Sandbox.
+ */
+export type ContainerToolResult = Omit<BashToolkit, 'sandbox'> & {
+    sandbox: DockerSandbox;
+};
+/**
+ * Creates a bash tool that runs in a Docker container.
+ *
+ * This is a high-level wrapper that combines `createDockerSandbox()` and
+ * `createBashTool()` into a single call. It provides a convenient way to
+ * get a bash tool that executes real binaries in an isolated container.
+ *
+ * Supports three strategies:
+ * - **RuntimeStrategy**: Uses existing image, installs packages/binaries at runtime
+ * - **DockerfileStrategy**: Builds custom image from Dockerfile (with caching)
+ * - **ComposeStrategy**: Multi-container environments via Docker Compose
+ *
+ * @example RuntimeStrategy (default)
+ * ```typescript
+ * const { bash, tools, sandbox } = await createContainerTool({
+ *   packages: ['curl', 'jq'],
+ *   mounts: [{
+ *     hostPath: process.cwd(),
+ *     containerPath: '/workspace',
+ *     readOnly: false,
+ *   }],
+ * });
+ *
+ * // Use with AI SDK
+ * const response = await generateText({
+ *   model: yourModel,
+ *   tools,
+ *   prompt: 'Fetch the weather data and parse it with jq',
+ * });
+ *
+ * // Clean up when done
+ * await sandbox.dispose();
+ * ```
+ *
+ * @example DockerfileStrategy
+ * ```typescript
+ * const { bash, tools, sandbox } = await createContainerTool({
+ *   dockerfile: `
+ *     FROM python:3.11-slim
+ *     RUN pip install pandas numpy
+ *   `,
+ *   context: '.',
+ *   mounts: [{
+ *     hostPath: process.cwd(),
+ *     containerPath: '/workspace',
+ *   }],
+ * });
+ * ```
+ *
+ * @example ComposeStrategy
+ * ```typescript
+ * const { bash, tools, sandbox } = await createContainerTool({
+ *   compose: './docker-compose.yml',
+ *   service: 'app',
+ * });
+ * // Commands run in the 'app' service, can reach other services by name
+ * await sandbox.dispose();  // Stops ALL services
+ * ```
+ *
+ * @example With hooks for logging
+ * ```typescript
+ * const { bash, sandbox } = await createContainerTool({
+ *   packages: ['python3'],
+ *   onBeforeBashCall: ({ command }) => {
+ *     console.log('Running:', command);
+ *   },
+ *   onAfterBashCall: ({ command, result }) => {
+ *     console.log(`Exit code: ${result.exitCode}`);
+ *   },
+ * });
+ * ```
+ */
+export declare function createContainerTool(options?: ContainerToolOptions): Promise<ContainerToolResult>;
+export {};
+//# sourceMappingURL=container-tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"container-tool.d.ts","sourceRoot":"","sources":["../../../src/lib/sandbox/container-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,UAAU,wBACR,SAAQ,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAClE,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,wCAAwC;IACxC,SAAS,CAAC,EAAE,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,2BACf,SAAQ,IAAI,CAAC,qBAAqB,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAClE,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,CAAC,EAAE,eAAe,CAAC;CAE7B;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B,2BAA2B,GAC3B,8BAA8B,GAC9B,2BAA2B,CAAC;AAEhC;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG;IAC/D,OAAO,EAAE,aAAa,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAiC9B"}