@polos/sdk 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -129,6 +129,20 @@ interface BatchWorkflowInput {
     /** Timeout in seconds for the sub-workflow execution */
     runTimeoutSeconds?: number | undefined;
 }
+/**
+ * Result of a single workflow in a batch invocation.
+ * Matches Python BatchStepResult.
+ */
+interface BatchStepResult<T = unknown> {
+    /** The workflow ID that was invoked */
+    workflowId: string;
+    /** Whether the workflow completed successfully */
+    success: boolean;
+    /** The result from the workflow (if successful) */
+    result: T | null;
+    /** Error message (if failed) */
+    error: string | null;
+}
 /**
  * Configuration for agent invocation.
  * Matches Python AgentRunConfig.
@@ -217,7 +231,7 @@ interface StepHelper {
     /**
      * Invoke multiple workflows and wait for all results.
      */
-    batchInvokeAndWait<T>(key: string, items: BatchWorkflowInput[]): Promise<T[]>;
+    batchInvokeAndWait<T>(key: string, items: BatchWorkflowInput[]): Promise<BatchStepResult<T>[]>;
     /**
      * Wait for a time duration.
      */
@@ -276,7 +290,7 @@ interface StepHelper {
     /**
      * Invoke multiple agent workflows in batch and wait for all results.
      */
-    batchAgentInvokeAndWait<T>(key: string, configs: AgentRunConfig[]): Promise<T[]>;
+    batchAgentInvokeAndWait<T>(key: string, configs: AgentRunConfig[]): Promise<BatchStepResult<T>[]>;
     /**
      * Create a custom traced span around an async operation.
      */
@@ -662,6 +676,7 @@ declare function defineWorkflow<TPayload = unknown, TState = unknown, TResult =
  * LLM-specific metadata (description, JSON schema parameters).
  */
 
+type ToolApproval = 'always' | 'none';
 /**
  * LLM tool definition format (OpenAI/Anthropic compatible).
  */
@@ -693,6 +708,10 @@ interface DefineToolConfig<TInput = unknown, TOutput = unknown, TState = unknown
     onStart?: HookHandler<TInput, TState> | Hook<TInput, TState> | (HookHandler<TInput, TState> | Hook<TInput, TState>)[] | undefined;
     /** Hook(s) to run after tool completion */
     onEnd?: HookHandler<TInput, TState> | Hook<TInput, TState> | (HookHandler<TInput, TState> | Hook<TInput, TState>)[] | undefined;
+    /** Whether to auto-register in the global workflow registry (default: true) */
+    autoRegister?: boolean | undefined;
+    /** Require human approval before tool execution. @default undefined (no approval) */
+    approval?: ToolApproval | undefined;
 }
 /**
  * A Workflow with tool-specific LLM metadata.
@@ -1628,6 +1647,10 @@ declare class OrchestratorClient {
     private readonly timeout;
     private readonly maxRetries;
     constructor(config: OrchestratorClientConfig);
+    /**
+     * Get the API URL.
+     */
+    getApiUrl(): string;
     /**
      * Get the project ID.
      */
@@ -2132,8 +2155,8 @@ declare class DuplicateWorkflowError extends Error {
  */
 interface WorkflowRegistry {
     /**
-     * Register a workflow.
-     * @throws DuplicateWorkflowError if workflow ID is already registered
+     * Register a workflow. If a workflow with the same ID is already
+     * registered, it is silently replaced.
      */
     register(workflow: Workflow): void;
     /**
@@ -2983,6 +3006,8 @@ interface LLMUsage {
     input_tokens: number;
     output_tokens: number;
     total_tokens: number;
+    cache_read_input_tokens?: number | undefined;
+    cache_creation_input_tokens?: number | undefined;
 }
 /**
  * A tool call made by the LLM
@@ -3125,6 +3150,10 @@ declare function convertVercelUsageToPython(usage: {
     inputTokens: number | undefined;
     outputTokens: number | undefined;
     totalTokens?: number | undefined;
+    inputTokenDetails?: {
+        cacheReadTokens?: number | undefined;
+        cacheWriteTokens?: number | undefined;
+    };
 }): LLMUsage;
 /**
  * Convert Vercel finish reason (kebab-case) to Python format (snake_case).
@@ -3504,6 +3533,8 @@ interface DefineAgentConfig {
     guardrailMaxRetries?: number | undefined;
     /** Number of conversation history messages to retain (default: 10) */
     conversationHistory?: number | undefined;
+    /** Publish text_delta and tool_call events to the workflow topic for all invocations */
+    streamToWorkflow?: boolean | undefined;
 }
 /**
  * Payload for agent run() and stream() calls.
@@ -3770,4 +3801,536 @@ declare function generateTraceIdFromExecutionId(executionId: string): string;
  */
 declare function isOtelAvailable(): boolean;
 
-export { type Agent, type AgentConfig, type AgentContext, type AgentResult, AgentRunConfig, type AgentRunOptions, type AgentRunPayload, type AgentStep, type AgentStream, type AgentStreamEvent, type AgentStreamPayload, type AgentStreamResult, type AgentWorkflow, type BatchEventPayload, type BatchWorkflowInput, type ClientBatchWorkflowInput, type ClientInvokeOptions, type CoreMessage$1 as CoreMessage, type DefineAgentConfig, type DefineGuardrailOptions, type DefineHookOptions, type DefineToolConfig, DuplicateWorkflowError, type Event, type EventData, type EventItem, type EventPayload, type EventTriggerPayload, type EventsApi, type ExecuteGuardrailsOptions, type ExecuteHooksOptions, type ExecuteWorkflowOptions, type ExecutionContext, type ExecutionData, ExecutionHandle, type ExecutionHandleFields, type ExecutionResult, type FinishReason, type GenerateConfig, type Guardrail$1 as Guardrail, type GuardrailChainResult, type GuardrailContext$1 as GuardrailContext, GuardrailError, type GuardrailHandler, GuardrailResult$1 as GuardrailResult, type GuardrailResultType, type Hook, type HookChainResult, type HookContext, HookExecutionError, type HookHandler, HookResult, type HookResultType, type InferPayload, type InferResult, type InferState, type InvokeOptions, LLM, type LLMGenerateOptions, type LLMGeneratePayload, type LLMGenerateResult, type LLMProvider, type LLMResponse, type LLMStreamEvent, type LLMStreamPayload, type LLMToolCall, type LLMToolResult, type LLMUsage, type LlmToolDefinition, type Logger, type Guardrail as MiddlewareGuardrail, type GuardrailContext as MiddlewareGuardrailContext, GuardrailResult as MiddlewareGuardrailResult, OrchestratorApiError, OrchestratorClient, type OrchestratorClientConfig, type OtelConfig, PolosClient, type PolosClientConfig, type PublishEventFn, type PublishEventOptions, Queue, type QueueConfig$1 as QueueConfig, type QueueOptions, type ResumeOptions, type ScheduleConfig, type SchedulePayload, type SchedulesApi, StateSizeError, StateValidationError, StepExecutionError, type StepHelper, type StepInfo, type StepOptions, type StepStore, type StopCondition, type StopConditionContext, type StreamEvent, StreamResult, type StreamTopicOptions, type StreamWorkflowOptions, type SuspendOptions, type TextDeltaEvent, type TokenUsage, type Tool, type ToolCall, type ToolCallEvent, type ToolConfig, type ToolHandler, type ToolResult, type ToolResultInfo, type ToolWorkflow, WaitError, type WaitForEventOptions, type WaitForOptions, Worker, type WorkerConfig, type WorkerExecutionData, WorkerServer, type WorkerServerConfig, type Workflow, type WorkflowConfig, type WorkflowContext, type WorkflowEvent, type WorkflowHandle, type WorkflowHandler, WorkflowNotFoundError, type WorkflowRegistry, type WorkflowRunClient, type WorkflowRunOptions, type WorkflowStatus, agentStreamFunction, batchAgentInvoke, batchInvoke, composeGuardrails, composeHooks, conditionalHook, convertFinishReason, convertMiddlewareToolCallToPython, convertPythonToolCallToMiddleware, convertToolResultsToMessages, convertToolsToVercel, convertVercelToolCallToPython, convertVercelUsageToPython, createLogger, createStepHelper, createStepStore, createWorkflowRegistry, defineAgent, defineGuardrail, defineHook, defineTool, defineWorkflow, executeGuardrailChain, executeGuardrailsOrThrow, executeHookChain, executeHooksOrThrow, executeWorkflow, executedTool, extractTraceparent, generateTraceIdFromExecutionId, getTracer, globalRegistry, hasText, initializeOtel, initializeState, isAgentWorkflow, isGuardrail, isHook, isOtelAvailable, isToolWorkflow, isWaitError, llmGenerate, llmStream, maxSteps, maxTokens, normalizeGuardrail, normalizeGuardrails, normalizeHook, normalizeHooks, retry, serializeFinalState, sleep, stopCondition, validateState };
+/**
+ * Ask-user tool — lets agents ask questions and receive answers from the user.
+ *
+ * Uses ctx.step.suspend() to pause the workflow, emit a suspend event with a
+ * _form schema, and wait for the user to respond via client.resume(). Supports
+ * both structured form fields and simple free-text responses.
+ */
+
+/**
+ * Create the ask_user tool for agent-to-user communication.
+ *
+ * When an agent calls this tool, the workflow suspends and emits a suspend
+ * event with a `_form` schema. The client handles the event, collects the
+ * user's response, and resumes the workflow with the response data.
+ *
+ * @example
+ * ```typescript
+ * import { createAskUserTool } from '@polos/sdk';
+ *
+ * const askUser = createAskUserTool();
+ * // Add to agent tools array
+ * ```
+ */
+declare function createAskUserTool(): ToolWorkflow;
+
+/**
+ * Web search tool — lets agents search the web for current information.
+ *
+ * Defaults to the Tavily Search API using raw fetch() (no additional
+ * dependencies). Users can plug in any search provider via a custom
+ * function.
+ *
+ * @example
+ * ```typescript
+ * import { createWebSearchTool } from '@polos/sdk';
+ *
+ * // Tavily with env var (TAVILY_API_KEY)
+ * const webSearch = createWebSearchTool();
+ *
+ * // Custom provider
+ * const webSearch = createWebSearchTool({
+ *   search: async (query, opts) => {
+ *     const res = await mySearchApi(query, opts.maxResults);
+ *     return { query, results: res.items };
+ *   },
+ * });
+ * ```
+ */
+
+/** A single search result item. */
+interface WebSearchResultItem {
+    title: string;
+    url: string;
+    /** Snippet or summary of the page content. */
+    content: string;
+    /** Relevance score, 0–1. */
+    score?: number | undefined;
+    /** Publication date in ISO 8601 format. */
+    publishedDate?: string | undefined;
+}
+/** Full search result returned by the tool. */
+interface WebSearchResult {
+    query: string;
+    results: WebSearchResultItem[];
+    /** AI-generated summary (Tavily feature). */
+    answer?: string | undefined;
+}
+/** Options forwarded to the search function at call time. */
+interface WebSearchOptions {
+    maxResults: number;
+    topic: 'general' | 'news';
+}
+/** Signature for a custom search provider function. */
+type WebSearchFunction = (query: string, options: WebSearchOptions) => Promise<WebSearchResult>;
+/** Tavily-specific configuration knobs. */
+interface TavilySearchConfig {
+    /** Tavily API key. Falls back to the TAVILY_API_KEY environment variable. */
+    apiKey?: string;
+    /** Search depth. @default 'basic' */
+    searchDepth?: 'basic' | 'advanced';
+    /** Include an AI-generated answer in the response. @default true */
+    includeAnswer?: boolean;
+    /** Include raw page content in results. @default false */
+    includeRawContent?: boolean;
+    /** Tavily API base URL. @default 'https://api.tavily.com' */
+    baseUrl?: string;
+}
+/** Configuration for createWebSearchTool(). */
+interface WebSearchToolConfig extends TavilySearchConfig {
+    /** Custom search provider. When set, overrides the built-in Tavily implementation. */
+    search?: WebSearchFunction;
+    /** Default maximum results per query. @default 5 */
+    maxResults?: number;
+    /** Default topic filter. @default 'general' */
+    topic?: 'general' | 'news';
+    /** Tool identifier exposed to the LLM. @default 'web_search' */
+    toolId?: string;
+    /** Require human approval before execution. */
+    approval?: ToolApproval;
+}
+/**
+ * Create a web search tool for agent use.
+ *
+ * By default uses the Tavily Search API via raw fetch(). Pass a custom
+ * `search` function to use any other provider.
+ *
+ * @example
+ * ```typescript
+ * // Tavily with env var
+ * const webSearch = createWebSearchTool();
+ *
+ * // Tavily with explicit key
+ * const webSearch = createWebSearchTool({ apiKey: 'tvly-xxx' });
+ *
+ * // Custom provider
+ * const webSearch = createWebSearchTool({
+ *   search: async (query, opts) => {
+ *     const res = await myApi(query, opts.maxResults);
+ *     return { query, results: res.items };
+ *   },
+ * });
+ * ```
+ */
+declare function createWebSearchTool(config?: WebSearchToolConfig): ToolWorkflow;
+
+/**
+ * Shared types for the execution framework.
+ *
+ * Defines interfaces for execution environments, command results,
+ * file operations, and configuration.
+ */
+/**
+ * Abstract interface for an execution environment (Docker, E2B, Local).
+ * All sandbox tools operate against this interface.
+ */
+interface ExecutionEnvironment {
+    /** Environment type discriminator */
+    readonly type: 'local' | 'docker' | 'e2b';
+    /** Execute a shell command in the environment */
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /** Read a file's contents as UTF-8 text */
+    readFile(path: string): Promise<string>;
+    /** Write content to a file, creating parent directories as needed */
+    writeFile(path: string, content: string): Promise<void>;
+    /** Check whether a file exists */
+    fileExists(path: string): Promise<boolean>;
+    /** Find files matching a glob pattern */
+    glob(pattern: string, opts?: GlobOptions): Promise<string[]>;
+    /** Search file contents for a pattern */
+    grep(pattern: string, opts?: GrepOptions): Promise<GrepMatch[]>;
+    /** Initialize the environment (create container, connect to sandbox, etc.) */
+    initialize(): Promise<void>;
+    /** Tear down the environment (remove container, kill sandbox, etc.) */
+    destroy(): Promise<void>;
+    /** Get the current working directory inside the environment */
+    getCwd(): string;
+    /** Get environment metadata */
+    getInfo(): EnvironmentInfo;
+}
+/**
+ * Options for command execution.
+ */
+interface ExecOptions {
+    /** Working directory for the command */
+    cwd?: string | undefined;
+    /** Environment variables to set */
+    env?: Record<string, string> | undefined;
+    /** Timeout in seconds (default: 300) */
+    timeout?: number | undefined;
+    /** Data to pipe to stdin */
+    stdin?: string | undefined;
+}
+/**
+ * Result of a command execution.
+ */
+interface ExecResult {
+    /** Process exit code (0 = success) */
+    exitCode: number;
+    /** Standard output */
+    stdout: string;
+    /** Standard error */
+    stderr: string;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Whether output was truncated due to size limits */
+    truncated: boolean;
+}
+/**
+ * Options for glob file search.
+ */
+interface GlobOptions {
+    /** Working directory for the search */
+    cwd?: string | undefined;
+    /** Glob patterns to exclude */
+    ignore?: string[] | undefined;
+}
+/**
+ * Options for grep content search.
+ */
+interface GrepOptions {
+    /** Working directory for the search */
+    cwd?: string | undefined;
+    /** File glob patterns to include (e.g., "*.ts") */
+    include?: string[] | undefined;
+    /** Maximum number of matches to return */
+    maxResults?: number | undefined;
+    /** Number of context lines around each match */
+    contextLines?: number | undefined;
+}
+/**
+ * A single grep match result.
+ */
+interface GrepMatch {
+    /** File path (relative to search root) */
+    path: string;
+    /** Line number of the match */
+    line: number;
+    /** The matching line text */
+    text: string;
+    /** Context lines around the match */
+    context?: string | undefined;
+}
+/**
+ * Metadata about an execution environment.
+ */
+interface EnvironmentInfo {
+    /** Environment type */
+    type: 'local' | 'docker' | 'e2b';
+    /** Current working directory */
+    cwd: string;
+    /** Sandbox/container identifier (container ID for Docker, sandbox ID for E2B) */
+    sandboxId?: string | undefined;
+    /** Operating system info */
+    os?: string | undefined;
+}
+/**
+ * Configuration for a Docker execution environment.
+ */
+interface DockerEnvironmentConfig {
+    /** Docker image to use (e.g., "node:20-slim") */
+    image: string;
+    /** Host directory to mount as workspace */
+    workspaceDir: string;
+    /** Working directory inside the container (default: "/workspace") */
+    containerWorkdir?: string | undefined;
+    /** Environment variables to set in the container */
+    env?: Record<string, string> | undefined;
+    /** Memory limit (e.g., "512m", "2g") */
+    memory?: string | undefined;
+    /** CPU limit (e.g., "1", "0.5") */
+    cpus?: string | undefined;
+    /** Network mode (default: "none") */
+    network?: string | undefined;
+    /** Command to run after container creation (e.g., "npm install") */
+    setupCommand?: string | undefined;
+}
+/**
+ * Configuration for an E2B execution environment.
+ */
+interface E2BEnvironmentConfig {
+    /** E2B template name (default: "base") */
+    template?: string | undefined;
+    /** E2B API key (defaults to E2B_API_KEY env var) */
+    apiKey?: string | undefined;
+    /** Sandbox timeout in seconds (default: 3600) */
+    timeout?: number | undefined;
+    /** Working directory inside the sandbox */
+    cwd?: string | undefined;
+    /** Environment variables */
+    env?: Record<string, string> | undefined;
+    /** Setup command to run after sandbox creation */
+    setupCommand?: string | undefined;
+}
+/**
+ * Configuration for a local execution environment.
+ */
+interface LocalEnvironmentConfig {
+    /** Working directory (default: process.cwd()) */
+    cwd?: string | undefined;
+    /** Restrict file operations to this directory */
+    pathRestriction?: string | undefined;
+}
+/**
+ * Configuration for the exec tool's security and behavior.
+ */
+interface ExecToolConfig {
+    /** Security mode: allow-always (default), allowlist, or always require approval */
+    security?: 'allow-always' | 'allowlist' | 'approval-always' | undefined;
+    /** Allowed command patterns (for allowlist mode) */
+    allowlist?: string[] | undefined;
+    /** Default command timeout in seconds (default: 300) */
+    timeout?: number | undefined;
+    /** Maximum output characters before truncation (default: 100000) */
+    maxOutputChars?: number | undefined;
+}
+/**
+ * Configuration for the sandboxTools() factory.
+ */
+interface SandboxToolsConfig {
+    /** Environment type (default: "docker") */
+    env?: 'local' | 'docker' | 'e2b' | undefined;
+    /** Working directory override */
+    cwd?: string | undefined;
+    /** Subset of tools to include (default: all) */
+    tools?: ('exec' | 'read' | 'write' | 'edit' | 'glob' | 'grep')[] | undefined;
+    /** Docker environment configuration */
+    docker?: DockerEnvironmentConfig | undefined;
+    /** E2B environment configuration */
+    e2b?: E2BEnvironmentConfig | undefined;
+    /** Local environment configuration */
+    local?: LocalEnvironmentConfig | undefined;
+    /** Exec tool configuration */
+    exec?: ExecToolConfig | undefined;
+    /** Approval mode for file-mutating tools (write, edit). Defaults to 'always' for local env. */
+    fileApproval?: 'always' | 'none' | undefined;
+}
+
+/**
+ * Sandbox tools factory.
+ *
+ * Creates a set of tools (exec, read, write, edit, glob, grep) that share
+ * a lazily-initialized execution environment via closure. The environment
+ * is created on first tool use and reused for all subsequent calls.
+ *
+ * @example
+ * ```typescript
+ * import { defineAgent, sandboxTools } from '@polos/sdk';
+ *
+ * const agent = defineAgent({
+ *   id: 'solver',
+ *   tools: sandboxTools({
+ *     env: 'docker',
+ *     docker: { image: 'node:20', workspaceDir: '/path/to/project' },
+ *   }),
+ * });
+ * ```
+ */
+
+/**
+ * Return type for sandboxTools — an array of ToolWorkflow with a cleanup method.
+ */
+interface SandboxToolsResult extends Array<ToolWorkflow> {
+    /** Destroy the shared execution environment (remove container, etc.) */
+    cleanup(): Promise<void>;
+}
+/**
+ * Create sandbox tools for AI agents.
+ *
+ * Returns an array of ToolWorkflow that can be passed directly to defineAgent().
+ * All tools share a single execution environment that is lazily created on first use.
+ *
+ * The returned array has a `cleanup()` method for destroying the environment.
+ */
+declare function sandboxTools(config?: SandboxToolsConfig): SandboxToolsResult;
+
+/**
+ * Docker execution environment.
+ *
+ * Runs commands inside a Docker container and accesses files via bind mount
+ * for optimal performance. The container runs `sleep infinity` and commands
+ * are executed via `docker exec`.
+ */
+
+/**
+ * Docker-based execution environment.
+ *
+ * Creates a persistent Docker container with a bind-mounted workspace.
+ * Commands run inside the container via `docker exec`, while file
+ * operations use the host filesystem through the bind mount for speed.
+ */
+declare class DockerEnvironment implements ExecutionEnvironment {
+    readonly type: "docker";
+    private containerId;
+    private containerName;
+    private readonly config;
+    private readonly containerWorkdir;
+    private readonly maxOutputChars;
+    constructor(config: DockerEnvironmentConfig, maxOutputChars?: number);
+    initialize(): Promise<void>;
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    fileExists(filePath: string): Promise<boolean>;
+    glob(pattern: string, opts?: GlobOptions): Promise<string[]>;
+    grep(pattern: string, opts?: GrepOptions): Promise<GrepMatch[]>;
+    destroy(): Promise<void>;
+    getCwd(): string;
+    getInfo(): EnvironmentInfo;
+    /**
+     * Translate a container path to the corresponding host filesystem path.
+     * Validates the path stays within the workspace to prevent traversal.
+     */
+    toHostPath(containerPath: string): string;
+    /**
+     * Translate a host filesystem path to the corresponding container path.
+     */
+    toContainerPath(hostPath: string): string;
+    private assertInitialized;
+}
+
+/**
+ * Evaluate a command against an allowlist of glob patterns.
+ *
+ * Matches the full command string against each pattern.
+ * Patterns support `*` wildcards (e.g., `node *`, `npm *`, `*`).
+ *
+ * @param command - The shell command to check
+ * @param patterns - Array of glob patterns to match against
+ * @returns Whether the command matches any pattern in the allowlist
+ */
+declare function evaluateAllowlist(command: string, patterns: string[]): boolean;
+/**
+ * Assert that a file path stays within a restriction directory.
+ * Throws if path traversal is detected.
+ *
+ * @param filePath - The file path to check
+ * @param restriction - The base directory paths must stay within
+ * @throws Error if the resolved path escapes the restriction directory
+ */
+declare function assertSafePath(filePath: string, restriction: string): void;
+
+/**
+ * Output utilities for the execution framework.
+ *
+ * Provides functions for truncating large outputs, detecting binary content,
+ * parsing grep output, and stripping ANSI escape codes.
+ */
+
+/**
+ * Truncate output that exceeds the maximum character limit.
+ *
+ * Keeps the first 20K characters (head) and last 80K characters (tail)
+ * of a 100K max, with a truncation message in between.
+ */
+declare function truncateOutput(output: string, maxChars?: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Detect binary content by checking for null bytes in the first 8KB.
+ */
+declare function isBinary(buffer: Buffer): boolean;
+/**
+ * Parse `grep -rn` output into structured GrepMatch objects.
+ *
+ * Expected format: `filepath:linenum:matched text`
+ */
+declare function parseGrepOutput(output: string): GrepMatch[];
+/**
+ * Strip ANSI escape codes from text.
+ */
+declare function stripAnsi(text: string): string;
+
+/**
+ * Exec tool — run shell commands inside the execution environment.
+ */
+
+/**
+ * Create the exec tool for running shell commands.
+ */
+declare function createExecTool(getEnv: () => Promise<ExecutionEnvironment>, config?: ExecToolConfig): ToolWorkflow;
+
+/**
+ * Path-based approval for read-only sandbox tools.
+ *
+ * When pathRestriction is set, read-only tools (read, glob, grep) allow
+ * operations within the restricted path without approval. Operations
+ * outside the restriction suspend for user approval.
+ */
+
+/**
+ * Configuration for path-restricted approval on read-only tools.
+ */
+interface PathRestrictionConfig {
+    /** Directory to allow without approval. Paths outside require approval. */
+    pathRestriction: string;
+}
+
+/**
+ * Read tool — read file contents from the execution environment.
+ *
+ * When pathRestriction is set, reads within the restriction proceed
+ * without approval. Reads outside the restriction suspend for user approval.
+ */
+
+/**
+ * Create the read tool for reading file contents.
+ */
+declare function createReadTool(getEnv: () => Promise<ExecutionEnvironment>, pathConfig?: PathRestrictionConfig): ToolWorkflow;
+
+/**
+ * Write tool — create or overwrite files in the execution environment.
+ */
+
+/**
+ * Create the write tool for writing file contents.
+ */
+declare function createWriteTool(getEnv: () => Promise<ExecutionEnvironment>, approval?: ToolApproval): ToolWorkflow;
+
+/**
+ * Edit tool — find-and-replace text in files in the execution environment.
+ */
+
+/**
+ * Create the edit tool for find-and-replace in files.
+ */
+declare function createEditTool(getEnv: () => Promise<ExecutionEnvironment>, approval?: ToolApproval): ToolWorkflow;
+
+/**
+ * Glob tool — find files by pattern in the execution environment.
+ *
+ * When pathRestriction is set, searches within the restriction proceed
+ * without approval. Custom cwd outside the restriction suspends for approval.
+ */
+
+/**
+ * Create the glob tool for finding files by pattern.
+ */
+declare function createGlobTool(getEnv: () => Promise<ExecutionEnvironment>, pathConfig?: PathRestrictionConfig): ToolWorkflow;
+
+/**
+ * Grep tool — search file contents by pattern in the execution environment.
+ *
+ * When pathRestriction is set, searches within the restriction proceed
+ * without approval. Custom cwd outside the restriction suspends for approval.
+ */
+
+/**
+ * Create the grep tool for searching file contents.
+ */
+declare function createGrepTool(getEnv: () => Promise<ExecutionEnvironment>, pathConfig?: PathRestrictionConfig): ToolWorkflow;
+
+export { type Agent, type AgentConfig, type AgentContext, type AgentResult, AgentRunConfig, type AgentRunOptions, type AgentRunPayload, type AgentStep, type AgentStream, type AgentStreamEvent, type AgentStreamPayload, type AgentStreamResult, type AgentWorkflow, type BatchEventPayload, type BatchStepResult, type BatchWorkflowInput, type ClientBatchWorkflowInput, type ClientInvokeOptions, type CoreMessage$1 as CoreMessage, type DefineAgentConfig, type DefineGuardrailOptions, type DefineHookOptions, type DefineToolConfig, DockerEnvironment, type DockerEnvironmentConfig, DuplicateWorkflowError, type E2BEnvironmentConfig, type EnvironmentInfo, type Event, type EventData, type EventItem, type EventPayload, type EventTriggerPayload, type EventsApi, type ExecOptions, type ExecResult, type ExecToolConfig, type ExecuteGuardrailsOptions, type ExecuteHooksOptions, type ExecuteWorkflowOptions, type ExecutionContext, type ExecutionData, type ExecutionEnvironment, ExecutionHandle, type ExecutionHandleFields, type ExecutionResult, type FinishReason, type GenerateConfig, type GlobOptions, type GrepMatch, type GrepOptions, type Guardrail$1 as Guardrail, type GuardrailChainResult, type GuardrailContext$1 as GuardrailContext, GuardrailError, type GuardrailHandler, GuardrailResult$1 as GuardrailResult, type GuardrailResultType, type Hook, type HookChainResult, type HookContext, HookExecutionError, type HookHandler, HookResult, type HookResultType, type InferPayload, type InferResult, type InferState, type InvokeOptions, LLM, type LLMGenerateOptions, type LLMGeneratePayload, type LLMGenerateResult, type LLMProvider, type LLMResponse, type LLMStreamEvent, type LLMStreamPayload, type LLMToolCall, type LLMToolResult, type LLMUsage, type LlmToolDefinition, type LocalEnvironmentConfig, type Logger, type Guardrail as MiddlewareGuardrail, type GuardrailContext as MiddlewareGuardrailContext, GuardrailResult as MiddlewareGuardrailResult, OrchestratorApiError, OrchestratorClient, type OrchestratorClientConfig, type OtelConfig, PolosClient, type PolosClientConfig, type PublishEventFn, type PublishEventOptions, Queue, type QueueConfig$1 as QueueConfig, type QueueOptions, type ResumeOptions, type SandboxToolsConfig, type SandboxToolsResult, type ScheduleConfig, type SchedulePayload, type SchedulesApi, StateSizeError, StateValidationError, StepExecutionError, type StepHelper, type StepInfo, type StepOptions, type StepStore, type StopCondition, type StopConditionContext, type StreamEvent, StreamResult, type StreamTopicOptions, type StreamWorkflowOptions, type SuspendOptions, type TavilySearchConfig, type TextDeltaEvent, type TokenUsage, type Tool, type ToolApproval, type ToolCall, type ToolCallEvent, type ToolConfig, type ToolHandler, type ToolResult, type ToolResultInfo, type ToolWorkflow, WaitError, type WaitForEventOptions, type WaitForOptions, type WebSearchFunction, type WebSearchOptions, type WebSearchResult, type WebSearchResultItem, type WebSearchToolConfig, Worker, type WorkerConfig, type WorkerExecutionData, WorkerServer, type WorkerServerConfig, type Workflow, type WorkflowConfig, type WorkflowContext, type WorkflowEvent, type WorkflowHandle, type WorkflowHandler, WorkflowNotFoundError, type WorkflowRegistry, type WorkflowRunClient, type WorkflowRunOptions, type WorkflowStatus, agentStreamFunction, assertSafePath, batchAgentInvoke, batchInvoke, composeGuardrails, composeHooks, conditionalHook, convertFinishReason, convertMiddlewareToolCallToPython, convertPythonToolCallToMiddleware, convertToolResultsToMessages, convertToolsToVercel, convertVercelToolCallToPython, convertVercelUsageToPython, createAskUserTool, createEditTool, createExecTool, createGlobTool, createGrepTool, createLogger, createReadTool, createStepHelper, createStepStore, createWebSearchTool, createWorkflowRegistry, createWriteTool, defineAgent, defineGuardrail, defineHook, defineTool, defineWorkflow, evaluateAllowlist, executeGuardrailChain, executeGuardrailsOrThrow, executeHookChain, executeHooksOrThrow, executeWorkflow, executedTool, extractTraceparent, generateTraceIdFromExecutionId, getTracer, globalRegistry, hasText, initializeOtel, initializeState, isAgentWorkflow, isBinary, isGuardrail, isHook, isOtelAvailable, isToolWorkflow, isWaitError, llmGenerate, llmStream, maxSteps, maxTokens, normalizeGuardrail, normalizeGuardrails, normalizeHook, normalizeHooks, parseGrepOutput, retry, sandboxTools, serializeFinalState, sleep, stopCondition, stripAnsi, truncateOutput, validateState };