@radaros/core 0.3.7 → 0.3.8

package/dist/index.d.ts

@@ -151,6 +151,23 @@ interface ToolCacheConfig {
     /** Time-to-live in milliseconds. Cached results expire after this duration. */
     ttl: number;
 }
+interface SandboxConfig {
+    /** Explicit on/off toggle. Defaults to true when config object is provided. */
+    enabled?: boolean;
+    /** Execution timeout in milliseconds. Default: 30000 (30s). */
+    timeout?: number;
+    /** Maximum heap memory in MB. Default: 256. */
+    maxMemoryMB?: number;
+    /** Allow outbound network from the sandbox. Default: false. */
+    allowNetwork?: boolean;
+    /** Allow filesystem access. Default: false. */
+    allowFS?: boolean | {
+        readOnly?: string[];
+        readWrite?: string[];
+    };
+    /** Whitelisted environment variables forwarded to the sandbox. */
+    env?: Record<string, string>;
+}
 interface ToolDef {
     name: string;
     description: string;
@@ -160,6 +177,10 @@ interface ToolDef {
     rawJsonSchema?: Record<string, unknown>;
     /** Enable result caching for this tool. */
     cache?: ToolCacheConfig;
+    /** Run this tool in a sandboxed subprocess. Off by default. */
+    sandbox?: boolean | SandboxConfig;
+    /** Require human approval before executing this tool. */
+    requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
 }
 interface ToolCallResult {
     toolCallId: string;
@@ -304,6 +325,44 @@ interface RetryConfig {
 }
 declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<T>;
 
+interface ApprovalRequest {
+    requestId: string;
+    toolName: string;
+    args: unknown;
+    agentName: string;
+    runId: string;
+}
+interface ApprovalDecision {
+    approved: boolean;
+    reason?: string;
+}
+interface ApprovalConfig {
+    /** Which tools require approval: "none" (default), "all", or an array of tool names. */
+    policy: "none" | "all" | string[];
+    /** Callback invoked when approval is needed. Return a decision. */
+    onApproval?: (request: ApprovalRequest) => Promise<ApprovalDecision>;
+    /** Timeout in ms for waiting on human response. Default: 300000 (5 min). Auto-deny on timeout. */
+    timeout?: number;
+}
+declare class ApprovalManager {
+    private policy;
+    private onApproval?;
+    private timeout;
+    private eventBus?;
+    private pending;
+    constructor(config: ApprovalConfig & {
+        eventBus?: EventBus;
+    });
+    needsApproval(toolName: string, args: Record<string, unknown>, toolRequiresApproval?: boolean | ((args: Record<string, unknown>) => boolean)): boolean;
+    check(toolName: string, args: unknown, ctx: RunContext, agentName: string): Promise<ApprovalDecision>;
+    /** Externally approve a pending request (for event-driven mode). */
+    approve(requestId: string, reason?: string): void;
+    /** Externally deny a pending request (for event-driven mode). */
+    deny(requestId: string, reason?: string): void;
+    private callbackMode;
+    private eventMode;
+}
+
 interface AgentConfig {
     name: string;
     model: ModelProvider;
@@ -334,6 +393,10 @@ interface AgentConfig {
     retry?: Partial<RetryConfig>;
     /** Maximum context window tokens. History is auto-trimmed to fit. */
     maxContextTokens?: number;
+    /** Default sandbox config applied to ALL tools unless the tool explicitly sets sandbox: false. Off by default. */
+    sandbox?: boolean | SandboxConfig;
+    /** Human-in-the-loop approval configuration for tool calls. */
+    approval?: ApprovalConfig;
 }
 interface RunOpts {
     sessionId?: string;
@@ -440,6 +503,38 @@ type AgentEventMap = {
     "voice.disconnected": {
         agentName: string;
     };
+    "browser.screenshot": {
+        data: Buffer;
+    };
+    "browser.action": {
+        action: unknown;
+    };
+    "browser.step": {
+        index: number;
+        action: unknown;
+        pageUrl: string;
+        screenshot: Buffer;
+    };
+    "browser.done": {
+        result: string;
+        success: boolean;
+        steps: unknown[];
+    };
+    "browser.error": {
+        error: Error;
+    };
+    "tool.approval.request": {
+        requestId: string;
+        toolName: string;
+        args: unknown;
+        agentName: string;
+        runId: string;
+    };
+    "tool.approval.response": {
+        requestId: string;
+        approved: boolean;
+        reason?: string;
+    };
 };
 
 type EventKey = keyof AgentEventMap;
@@ -462,10 +557,12 @@ declare class Agent {
     private llmLoop;
     private logger;
     private storageInitPromise;
+    private _toolExecutor;
     get tools(): ToolDef[];
     get modelId(): string;
     get providerId(): string;
     get hasStructuredOutput(): boolean;
+    get approvalManager(): ApprovalManager | null;
     get structuredOutputSchema(): zod.ZodSchema | undefined;
     constructor(config: AgentConfig);
     run(input: MessageContent, opts?: RunOpts): Promise<RunOutput>;
@@ -475,12 +572,24 @@ declare class Agent {
     private trimHistoryByTokens;
 }
 
+interface ToolExecutorConfig {
+    concurrency?: number;
+    sandbox?: boolean | SandboxConfig;
+    approval?: ApprovalConfig & {
+        eventBus?: EventBus;
+    };
+    agentName?: string;
+}
 declare class ToolExecutor {
     private tools;
     private concurrency;
     private cache;
     private cachedDefs;
-    constructor(tools: ToolDef[], concurrency?: number);
+    private agentSandbox?;
+    private approvalManager?;
+    private agentName;
+    constructor(tools: ToolDef[], configOrConcurrency?: number | ToolExecutorConfig);
+    getApprovalManager(): ApprovalManager | undefined;
     clearCache(): void;
     private getCacheKey;
     private getCached;
@@ -609,6 +718,135 @@ declare class Workflow<TState extends Record<string, unknown> = Record<string, u
     }): Promise<WorkflowResult<TState>>;
 }
 
+type AudioFormat = "pcm16" | "g711_ulaw" | "g711_alaw";
+interface TurnDetectionConfig {
+    /** Server-side VAD type. */
+    type: "server_vad";
+    /** Activation threshold (0-1). Lower = more sensitive. */
+    threshold?: number;
+    /** Duration of speech (ms) required to open the turn. */
+    prefixPaddingMs?: number;
+    /** Duration of silence (ms) required to close the turn. */
+    silenceDurationMs?: number;
+}
+interface RealtimeSessionConfig {
+    instructions?: string;
+    voice?: string;
+    tools?: ToolDefinition[];
+    inputAudioFormat?: AudioFormat;
+    outputAudioFormat?: AudioFormat;
+    turnDetection?: TurnDetectionConfig | null;
+    temperature?: number;
+    maxResponseOutputTokens?: number | "inf";
+    apiKey?: string;
+}
+interface RealtimeToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+type RealtimeEventMap = {
+    audio: {
+        data: Buffer;
+        mimeType?: string;
+    };
+    text: {
+        text: string;
+    };
+    transcript: {
+        text: string;
+        role: "user" | "assistant";
+    };
+    tool_call: RealtimeToolCall;
+    interrupted: {};
+    error: {
+        error: Error;
+    };
+    connected: {};
+    disconnected: {};
+};
+type RealtimeEvent = keyof RealtimeEventMap;
+interface RealtimeConnection {
+    sendAudio(data: Buffer): void;
+    sendText(text: string): void;
+    sendToolResult(callId: string, result: string): void;
+    interrupt(): void;
+    close(): Promise<void>;
+    on<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
+    off<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
+}
+interface RealtimeProvider {
+    readonly providerId: string;
+    readonly modelId: string;
+    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
+}
+interface VoiceAgentConfig {
+    name: string;
+    provider: RealtimeProvider;
+    instructions?: string;
+    tools?: ToolDef[];
+    voice?: string;
+    turnDetection?: TurnDetectionConfig | null;
+    inputAudioFormat?: AudioFormat;
+    outputAudioFormat?: AudioFormat;
+    temperature?: number;
+    maxResponseOutputTokens?: number | "inf";
+    eventBus?: EventBus;
+    logLevel?: LogLevel;
+    /** User-scoped memory — persists facts about a user across sessions. */
+    userMemory?: UserMemory;
+    /** LLM model used for auto-extracting user facts from transcripts (required if userMemory is set). */
+    model?: ModelProvider;
+    /** Default session ID (can be overridden per connect()). */
+    sessionId?: string;
+    /** Default user ID (can be overridden per connect()). */
+    userId?: string;
+}
+type VoiceSessionEventMap = RealtimeEventMap & {
+    tool_call_start: {
+        name: string;
+        args: unknown;
+    };
+    tool_result: {
+        name: string;
+        result: string;
+    };
+};
+type VoiceSessionEvent = keyof VoiceSessionEventMap;
+interface VoiceSession {
+    sendAudio(data: Buffer): void;
+    sendText(text: string): void;
+    interrupt(): void;
+    close(): Promise<void>;
+    on<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
+    off<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
+}
+
+interface OpenAIRealtimeConfig {
+    apiKey?: string;
+    baseURL?: string;
+}
+declare class OpenAIRealtimeProvider implements RealtimeProvider {
+    readonly providerId = "openai-realtime";
+    readonly modelId: string;
+    private apiKey?;
+    private baseURL?;
+    constructor(modelId?: string, config?: OpenAIRealtimeConfig);
+    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
+    private buildSessionPayload;
+}
+
+interface GoogleLiveConfig {
+    apiKey?: string;
+}
+declare class GoogleLiveProvider implements RealtimeProvider {
+    readonly providerId = "google-live";
+    readonly modelId: string;
+    private apiKey?;
+    constructor(modelId?: string, config?: GoogleLiveConfig);
+    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
+}
+
 type ProviderFactory = (modelId: string, config?: Record<string, unknown>) => ModelProvider;
 declare class ModelRegistry {
     private factories;
@@ -635,6 +873,24 @@ declare function vertex(modelId: string, config?: {
     location?: string;
     credentials?: string;
 }): ModelProvider;
+/**
+ * Shorthand for `new OpenAIRealtimeProvider(modelId, config)`.
+ *
+ * @example
+ * const agent = new VoiceAgent({
+ *   provider: openaiRealtime("gpt-4o-realtime-preview"),
+ * });
+ */
+declare function openaiRealtime(modelId?: string, config?: OpenAIRealtimeConfig): RealtimeProvider;
+/**
+ * Shorthand for `new GoogleLiveProvider(modelId, config)`.
+ *
+ * @example
+ * const agent = new VoiceAgent({
+ *   provider: googleLive(),
+ * });
+ */
+declare function googleLive(modelId?: string, config?: GoogleLiveConfig): RealtimeProvider;
 
 interface OpenAIConfig {
     apiKey?: string;
@@ -770,8 +1026,18 @@ declare function defineTool<T extends z.ZodObject<any>>(config: {
     parameters: T;
     execute: (args: z.infer<T>, ctx: RunContext) => Promise<string | ToolResult>;
     cache?: ToolCacheConfig;
+    sandbox?: boolean | SandboxConfig;
+    requiresApproval?: boolean | ((args: Record<string, unknown>) => boolean);
 }): ToolDef;
 
+declare function resolveSandboxConfig(toolLevel?: boolean | SandboxConfig, agentLevel?: boolean | SandboxConfig): SandboxConfig | null;
+declare class Sandbox {
+    private config;
+    constructor(config: SandboxConfig);
+    execute(toolExecuteFn: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>, args: Record<string, unknown>, ctx: RunContext): Promise<string | ToolResult>;
+    private getWorkerPath;
+}
+
 declare class InMemoryStorage implements StorageDriver {
     private store;
     private makeKey;
@@ -1392,110 +1658,6 @@ declare class A2ARemoteAgent {
     private partsToText;
 }
 
-type AudioFormat = "pcm16" | "g711_ulaw" | "g711_alaw";
-interface TurnDetectionConfig {
-    /** Server-side VAD type. */
-    type: "server_vad";
-    /** Activation threshold (0-1). Lower = more sensitive. */
-    threshold?: number;
-    /** Duration of speech (ms) required to open the turn. */
-    prefixPaddingMs?: number;
-    /** Duration of silence (ms) required to close the turn. */
-    silenceDurationMs?: number;
-}
-interface RealtimeSessionConfig {
-    instructions?: string;
-    voice?: string;
-    tools?: ToolDefinition[];
-    inputAudioFormat?: AudioFormat;
-    outputAudioFormat?: AudioFormat;
-    turnDetection?: TurnDetectionConfig | null;
-    temperature?: number;
-    maxResponseOutputTokens?: number | "inf";
-    apiKey?: string;
-}
-interface RealtimeToolCall {
-    id: string;
-    name: string;
-    arguments: string;
-}
-type RealtimeEventMap = {
-    audio: {
-        data: Buffer;
-        mimeType?: string;
-    };
-    text: {
-        text: string;
-    };
-    transcript: {
-        text: string;
-        role: "user" | "assistant";
-    };
-    tool_call: RealtimeToolCall;
-    interrupted: {};
-    error: {
-        error: Error;
-    };
-    connected: {};
-    disconnected: {};
-};
-type RealtimeEvent = keyof RealtimeEventMap;
-interface RealtimeConnection {
-    sendAudio(data: Buffer): void;
-    sendText(text: string): void;
-    sendToolResult(callId: string, result: string): void;
-    interrupt(): void;
-    close(): Promise<void>;
-    on<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
-    off<K extends RealtimeEvent>(event: K, handler: (data: RealtimeEventMap[K]) => void): void;
-}
-interface RealtimeProvider {
-    readonly providerId: string;
-    readonly modelId: string;
-    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
-}
-interface VoiceAgentConfig {
-    name: string;
-    provider: RealtimeProvider;
-    instructions?: string;
-    tools?: ToolDef[];
-    voice?: string;
-    turnDetection?: TurnDetectionConfig | null;
-    inputAudioFormat?: AudioFormat;
-    outputAudioFormat?: AudioFormat;
-    temperature?: number;
-    maxResponseOutputTokens?: number | "inf";
-    eventBus?: EventBus;
-    logLevel?: LogLevel;
-    /** User-scoped memory — persists facts about a user across sessions. */
-    userMemory?: UserMemory;
-    /** LLM model used for auto-extracting user facts from transcripts (required if userMemory is set). */
-    model?: ModelProvider;
-    /** Default session ID (can be overridden per connect()). */
-    sessionId?: string;
-    /** Default user ID (can be overridden per connect()). */
-    userId?: string;
-}
-type VoiceSessionEventMap = RealtimeEventMap & {
-    tool_call_start: {
-        name: string;
-        args: unknown;
-    };
-    tool_result: {
-        name: string;
-        result: string;
-    };
-};
-type VoiceSessionEvent = keyof VoiceSessionEventMap;
-interface VoiceSession {
-    sendAudio(data: Buffer): void;
-    sendText(text: string): void;
-    interrupt(): void;
-    close(): Promise<void>;
-    on<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
-    off<K extends VoiceSessionEvent>(event: K, handler: (data: VoiceSessionEventMap[K]) => void): void;
-}
-
 declare class VoiceAgent {
     readonly name: string;
     private config;
@@ -1519,31 +1681,6 @@ declare class VoiceAgent {
     private handleToolCall;
 }
 
-interface OpenAIRealtimeConfig {
-    apiKey?: string;
-    baseURL?: string;
-}
-declare class OpenAIRealtimeProvider implements RealtimeProvider {
-    readonly providerId = "openai-realtime";
-    readonly modelId: string;
-    private apiKey?;
-    private baseURL?;
-    constructor(modelId?: string, config?: OpenAIRealtimeConfig);
-    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
-    private buildSessionPayload;
-}
-
-interface GoogleLiveConfig {
-    apiKey?: string;
-}
-declare class GoogleLiveProvider implements RealtimeProvider {
-    readonly providerId = "google-live";
-    readonly modelId: string;
-    private apiKey?;
-    constructor(modelId?: string, config?: GoogleLiveConfig);
-    connect(config: RealtimeSessionConfig): Promise<RealtimeConnection>;
-}
-
 /**
  * Base class for all RadarOS Toolkits.
  * A Toolkit is a collection of related tools that share configuration.
@@ -1708,4 +1845,4 @@ declare class DuckDuckGoToolkit extends Toolkit {
     private searchNews;
 }
 
-export { type A2AAgentCard, type A2AArtifact, type A2ADataPart, type A2AFilePart, type A2AJsonRpcRequest, type A2AJsonRpcResponse, type A2AMessage, type A2APart, A2ARemoteAgent, type A2ARemoteAgentConfig, type A2ASendParams, type A2ASkill, type A2ATask, type A2ATaskQueryParams, type A2ATaskState, type A2ATextPart, Agent, type AgentConfig, type AgentEventMap, type AgentHooks, type AgentStep, AnthropicProvider, type AppendResult, type Artifact, type AudioFormat, type AudioPart, type BM25Document, BM25Index, type BM25Result, BaseVectorStore, type ChatMessage, type ConditionStep, type ContentPart, type DuckDuckGoConfig, DuckDuckGoToolkit, type EmbeddingProvider, EventBus, type FilePart, type FunctionStep, type GmailConfig, GmailToolkit, GoogleEmbedding, type GoogleEmbeddingConfig, type GoogleLiveConfig, GoogleLiveProvider, GoogleProvider, type GuardrailResult, type HackerNewsConfig, HackerNewsToolkit, type HybridSearchConfig, type ImagePart, InMemoryStorage, InMemoryVectorStore, type InputGuardrail, KnowledgeBase, type KnowledgeBaseConfig, type KnowledgeBaseToolConfig, LLMLoop, type LogLevel, Logger, type LoggerConfig, MCPToolProvider, type MCPToolProviderConfig, Memory, type MemoryConfig, type MemoryEntry, type MessageContent, type MessageRole, type ModelConfig, type ModelProvider, ModelRegistry, type ModelResponse, MongoDBStorage, type MongoDBVectorConfig, MongoDBVectorStore, OllamaProvider, OpenAIEmbedding, type OpenAIEmbeddingConfig, OpenAIProvider, type OpenAIRealtimeConfig, OpenAIRealtimeProvider, type OutputGuardrail, type ParallelStep, type PgVectorConfig, PgVectorStore, PostgresStorage, type QdrantConfig, QdrantVectorStore, type RRFOptions, type RankedItem, type RealtimeConnection, type RealtimeEvent, type RealtimeEventMap, type RealtimeProvider, type RealtimeSessionConfig, type RealtimeToolCall, type ReasoningConfig, type RetryConfig, RunContext, type RunOpts, type RunOutput, type SearchMode, type Session, SessionManager, type SessionManagerConfig, SqliteStorage, type StepDef, type StepResult, type StorageDriver, type StreamChunk, Team, type TeamConfig, TeamMode, type TextPart, type TokenUsage, type ToolCacheConfig, type ToolCall, type ToolCallResult, type ToolDef, type ToolDefinition, ToolExecutor, type ToolResult, Toolkit, type TurnDetectionConfig, type UserFact, UserMemory, type UserMemoryConfig, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, type VertexAIConfig, VertexAIProvider, VoiceAgent, type VoiceAgentConfig, type VoiceSession, type VoiceSessionEvent, type VoiceSessionEventMap, type WebSearchConfig, WebSearchToolkit, type WhatsAppConfig, WhatsAppToolkit, Workflow, type WorkflowConfig, type WorkflowResult, anthropic, defineTool, getTextContent, google, isMultiModal, ollama, openai, reciprocalRankFusion, registry, vertex, withRetry };
+export { type A2AAgentCard, type A2AArtifact, type A2ADataPart, type A2AFilePart, type A2AJsonRpcRequest, type A2AJsonRpcResponse, type A2AMessage, type A2APart, A2ARemoteAgent, type A2ARemoteAgentConfig, type A2ASendParams, type A2ASkill, type A2ATask, type A2ATaskQueryParams, type A2ATaskState, type A2ATextPart, Agent, type AgentConfig, type AgentEventMap, type AgentHooks, type AgentStep, AnthropicProvider, type AppendResult, type ApprovalConfig, type ApprovalDecision, ApprovalManager, type ApprovalRequest, type Artifact, type AudioFormat, type AudioPart, type BM25Document, BM25Index, type BM25Result, BaseVectorStore, type ChatMessage, type ConditionStep, type ContentPart, type DuckDuckGoConfig, DuckDuckGoToolkit, type EmbeddingProvider, EventBus, type FilePart, type FunctionStep, type GmailConfig, GmailToolkit, GoogleEmbedding, type GoogleEmbeddingConfig, type GoogleLiveConfig, GoogleLiveProvider, GoogleProvider, type GuardrailResult, type HackerNewsConfig, HackerNewsToolkit, type HybridSearchConfig, type ImagePart, InMemoryStorage, InMemoryVectorStore, type InputGuardrail, KnowledgeBase, type KnowledgeBaseConfig, type KnowledgeBaseToolConfig, LLMLoop, type LogLevel, Logger, type LoggerConfig, MCPToolProvider, type MCPToolProviderConfig, Memory, type MemoryConfig, type MemoryEntry, type MessageContent, type MessageRole, type ModelConfig, type ModelProvider, ModelRegistry, type ModelResponse, MongoDBStorage, type MongoDBVectorConfig, MongoDBVectorStore, OllamaProvider, OpenAIEmbedding, type OpenAIEmbeddingConfig, OpenAIProvider, type OpenAIRealtimeConfig, OpenAIRealtimeProvider, type OutputGuardrail, type ParallelStep, type PgVectorConfig, PgVectorStore, PostgresStorage, type QdrantConfig, QdrantVectorStore, type RRFOptions, type RankedItem, type RealtimeConnection, type RealtimeEvent, type RealtimeEventMap, type RealtimeProvider, type RealtimeSessionConfig, type RealtimeToolCall, type ReasoningConfig, type RetryConfig, RunContext, type RunOpts, type RunOutput, Sandbox, type SandboxConfig, type SearchMode, type Session, SessionManager, type SessionManagerConfig, SqliteStorage, type StepDef, type StepResult, type StorageDriver, type StreamChunk, Team, type TeamConfig, TeamMode, type TextPart, type TokenUsage, type ToolCacheConfig, type ToolCall, type ToolCallResult, type ToolDef, type ToolDefinition, ToolExecutor, type ToolResult, Toolkit, type TurnDetectionConfig, type UserFact, UserMemory, type UserMemoryConfig, type VectorDocument, type VectorSearchOptions, type VectorSearchResult, type VectorStore, type VertexAIConfig, VertexAIProvider, VoiceAgent, type VoiceAgentConfig, type VoiceSession, type VoiceSessionEvent, type VoiceSessionEventMap, type WebSearchConfig, WebSearchToolkit, type WhatsAppConfig, WhatsAppToolkit, Workflow, type WorkflowConfig, type WorkflowResult, anthropic, defineTool, getTextContent, google, googleLive, isMultiModal, ollama, openai, openaiRealtime, reciprocalRankFusion, registry, resolveSandboxConfig, vertex, withRetry };