@deepagents/context 0.10.2 → 0.11.0

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/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.
  */

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":"AAAA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAK9D,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,CA0FjB"}

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"}