@axlsdk/axl 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -2,6 +2,153 @@ import { z, ZodError } from 'zod';
 import { EventEmitter } from 'node:events';
 import { Readable } from 'node:stream';
 
+/**
+ * Tool definition in OpenAI-compatible format.
+ * All providers normalize to this format internally.
+ */
+type ToolDefinition = {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: unknown;
+        strict?: boolean;
+    };
+};
+/**
+ * Unified effort level controlling how thoroughly the model responds.
+ *
+ * - `'none'` — Disable thinking/reasoning. On Gemini 3.x, maps to the model's
+ *   minimum thinking level (3.1 Pro: 'low', others: 'minimal'). On other providers,
+ *   fully disables reasoning.
+ * - `'low'` through `'max'` — Increasing levels of reasoning depth and token spend.
+ *
+ * Provider mapping:
+ * - Anthropic 4.6: adaptive thinking + output_config.effort
+ * - Anthropic Opus 4.5: output_config.effort (no adaptive)
+ * - Anthropic older: thinking.budget_tokens fallback
+ * - OpenAI o-series: reasoning_effort
+ * - OpenAI GPT-5.x: reasoning.effort / reasoning_effort
+ * - Gemini 3.x: thinkingLevel (`'none'` → model min: `'minimal'` or `'low'` for 3.1 Pro)
+ * - Gemini 2.x: thinkingBudget (`'none'` → 0; some models have minimums)
+ */
+type Effort = 'none' | 'low' | 'medium' | 'high' | 'max';
+/** Tool choice strategy for LLM calls. */
+type ToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+/**
+ * Options passed to provider chat/stream calls.
+ */
+type ChatOptions = {
+    model: string;
+    temperature?: number;
+    tools?: ToolDefinition[];
+    maxTokens?: number;
+    responseFormat?: ResponseFormat;
+    stop?: string[];
+    signal?: AbortSignal;
+    /** How hard should the model try? Primary param for cost/quality tradeoff.
+     *  'none' disables thinking/reasoning (Gemini 3.x: maps to minimal).
+     *  Omit to use provider defaults. */
+    effort?: Effort;
+    /** Precise thinking token budget (advanced). When set alongside `effort`, overrides the
+     *  thinking/reasoning allocation. On Anthropic 4.6, `effort` still controls output quality
+     *  independently. On all other providers, `thinkingBudget` fully overrides `effort` for
+     *  reasoning behavior. Set to 0 to disable thinking while keeping effort for output control
+     *  (Anthropic-specific optimization; on other providers, simply disables reasoning). */
+    thinkingBudget?: number;
+    /** Show reasoning summaries in responses (thinking_content / thinking_delta).
+     *  Supported on OpenAI Responses API and Gemini. No-op on Anthropic. */
+    includeThoughts?: boolean;
+    toolChoice?: ToolChoice;
+    /** Provider-specific options merged LAST into the raw API request body.
+     *  Can override any computed field including model and messages — use with care.
+     *  NOT portable across providers — use effort/thinkingBudget/includeThoughts for cross-provider behavior. */
+    providerOptions?: Record<string, unknown>;
+};
+/**
+ * Response format for structured output (JSON mode).
+ */
+type ResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        name: string;
+        strict?: boolean;
+        schema: unknown;
+    };
+};
+/**
+ * Chunks emitted during streaming.
+ */
+type StreamChunk = {
+    type: 'text_delta';
+    content: string;
+} | {
+    type: 'thinking_delta';
+    content: string;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    name?: string;
+    arguments?: string;
+} | {
+    type: 'done';
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+        reasoning_tokens?: number;
+        cached_tokens?: number;
+    };
+    /** Provider-specific opaque metadata (e.g. raw Gemini parts with thought signatures). */
+    providerMetadata?: Record<string, unknown>;
+};
+/**
+ * Core provider interface. Every LLM adapter must implement this.
+ */
+interface Provider {
+    /** Human-readable name for the provider (e.g. "openai", "anthropic") */
+    readonly name?: string;
+    /**
+     * Send a chat completion request and return the full response.
+     */
+    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
+    /**
+     * Stream a chat completion, yielding chunks as they arrive.
+     */
+    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
+}
+/**
+ * Alias for Provider. Used for backward compatibility with index.ts exports.
+ */
+type ProviderAdapter = Provider;
+/** Normalized thinking options computed once, used by all providers. */
+type ResolvedThinkingOptions = {
+    /** Raw effort value from user. */
+    effort: Effort | undefined;
+    /** Raw thinking budget from user. */
+    thinkingBudget: number | undefined;
+    /** Whether to include thought summaries in responses. */
+    includeThoughts: boolean;
+    /** True when thinking/reasoning should be disabled (effort: 'none' or thinkingBudget: 0). */
+    thinkingDisabled: boolean;
+    /** Effort level with 'none' stripped (undefined when effort is 'none' or unset). */
+    activeEffort: Exclude<Effort, 'none'> | undefined;
+    /** True when an explicit positive budget overrides effort-based allocation. */
+    hasBudgetOverride: boolean;
+};
+/** Resolve effort/thinkingBudget/includeThoughts into normalized form.
+ *  Validates inputs and computes derived flags used by all provider adapters. */
+declare function resolveThinkingOptions(options: Pick<ChatOptions, 'effort' | 'thinkingBudget' | 'includeThoughts'>): ResolvedThinkingOptions;
+
 /** Result type for concurrent operations (spawn, map) */
 type Result<T> = {
     ok: true;
@@ -64,6 +211,33 @@ type AskOptions<T = unknown> = {
     retries?: number;
     /** Per-call metadata passed to dynamic model/system selector functions. */
     metadata?: Record<string, unknown>;
+    /** Override temperature for this call. */
+    temperature?: number;
+    /** Override max tokens for this call (default: 4096). */
+    maxTokens?: number;
+    /** How hard should the model try? Primary param for cost/quality tradeoff. */
+    effort?: Effort;
+    /** Precise thinking token budget (advanced). Overrides effort-based thinking allocation. */
+    thinkingBudget?: number;
+    /** Show reasoning summaries in responses. */
+    includeThoughts?: boolean;
+    /** Tool choice strategy for this call. */
+    toolChoice?: ToolChoice;
+    /** Stop sequences for this call. */
+    stop?: string[];
+    /** Provider-specific options merged into API requests. Not portable across providers. */
+    providerOptions?: Record<string, unknown>;
+};
+/** Delegate options */
+type DelegateOptions<T = unknown> = {
+    /** Zod schema for structured output from the selected agent. */
+    schema?: z.ZodType<T>;
+    /** Model URI for the internal router agent (default: first candidate's model). */
+    routerModel?: string;
+    /** Additional metadata passed to the router and selected agent. */
+    metadata?: Record<string, unknown>;
+    /** Number of retries for structured output validation (passed to the final ask). */
+    retries?: number;
 };
 /** Race options */
 type RaceOptions<T = unknown> = {
@@ -76,7 +250,7 @@ type ExecutionStatus = 'running' | 'completed' | 'failed' | 'waiting';
 type TraceEvent = {
     executionId: string;
     step: number;
-    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail';
+    type: 'agent_call' | 'tool_call' | 'verify' | 'handoff' | 'delegate' | 'tool_denied' | 'log' | 'workflow_start' | 'workflow_end' | 'guardrail';
     workflow?: string;
     agent?: string;
     tool?: string;
@@ -173,6 +347,25 @@ type HandoffRecord = {
     timestamp: number;
     duration?: number;
 };
+/** Information about a completed agent call, emitted via onAgentCallComplete. */
+type AgentCallInfo = {
+    agent: string;
+    prompt: string;
+    response: string;
+    model: string;
+    cost: number;
+    duration: number;
+    promptVersion?: string;
+    temperature?: number;
+    maxTokens?: number;
+    effort?: Effort;
+    thinkingBudget?: number;
+    includeThoughts?: boolean;
+    toolChoice?: ToolChoice;
+    stop?: string[];
+    /** Provider-specific options merged into API requests. Not portable across providers. */
+    providerOptions?: Record<string, unknown>;
+};
 /** Chat message types for provider communication */
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
 type ChatMessage = {
@@ -181,6 +374,8 @@ type ChatMessage = {
     name?: string;
     tool_calls?: ToolCallMessage[];
     tool_call_id?: string;
+    /** Provider-specific opaque metadata that must round-trip through conversation history. */
+    providerMetadata?: Record<string, unknown>;
 };
 type ToolCallMessage = {
     id: string;
@@ -193,6 +388,7 @@ type ToolCallMessage = {
 /** Provider response */
 type ProviderResponse = {
     content: string;
+    thinking_content?: string;
     tool_calls?: ToolCallMessage[];
     usage?: {
         prompt_tokens: number;
@@ -202,6 +398,8 @@ type ProviderResponse = {
         cached_tokens?: number;
     };
     cost?: number;
+    /** Provider-specific opaque metadata that needs to round-trip through conversation history. */
+    providerMetadata?: Record<string, unknown>;
 };
 
 /** Descriptor for a handoff target agent with optional description. */
@@ -221,10 +419,20 @@ type AgentConfig = {
         metadata?: Record<string, unknown>;
     }) => string);
     tools?: Tool<any, any>[];
-    handoffs?: HandoffDescriptor[];
+    handoffs?: HandoffDescriptor[] | ((ctx: {
+        metadata?: Record<string, unknown>;
+    }) => HandoffDescriptor[]);
     mcp?: string[];
     mcpTools?: string[];
     temperature?: number;
+    maxTokens?: number;
+    effort?: Effort;
+    thinkingBudget?: number;
+    includeThoughts?: boolean;
+    toolChoice?: ToolChoice;
+    stop?: string[];
+    /** Provider-specific options merged into API requests. Not portable across providers. */
+    providerOptions?: Record<string, unknown>;
     maxTurns?: number;
     timeout?: string;
     maxContext?: number;
@@ -254,94 +462,6 @@ type Agent = {
  */
 declare function agent(config: AgentConfig): Agent;
 
-/**
- * Tool definition in OpenAI-compatible format.
- * All providers normalize to this format internally.
- */
-type ToolDefinition = {
-    type: 'function';
-    function: {
-        name: string;
-        description: string;
-        parameters: unknown;
-        strict?: boolean;
-    };
-};
-/**
- * Options passed to provider chat/stream calls.
- */
-type ChatOptions = {
-    model: string;
-    temperature?: number;
-    tools?: ToolDefinition[];
-    maxTokens?: number;
-    responseFormat?: ResponseFormat;
-    stop?: string[];
-    signal?: AbortSignal;
-    reasoningEffort?: 'low' | 'medium' | 'high';
-    toolChoice?: 'auto' | 'none' | 'required' | {
-        type: 'function';
-        function: {
-            name: string;
-        };
-    };
-};
-/**
- * Response format for structured output (JSON mode).
- */
-type ResponseFormat = {
-    type: 'text';
-} | {
-    type: 'json_object';
-} | {
-    type: 'json_schema';
-    json_schema: {
-        name: string;
-        strict?: boolean;
-        schema: unknown;
-    };
-};
-/**
- * Chunks emitted during streaming.
- */
-type StreamChunk = {
-    type: 'text_delta';
-    content: string;
-} | {
-    type: 'tool_call_delta';
-    id: string;
-    name?: string;
-    arguments?: string;
-} | {
-    type: 'done';
-    usage?: {
-        prompt_tokens: number;
-        completion_tokens: number;
-        total_tokens: number;
-        reasoning_tokens?: number;
-        cached_tokens?: number;
-    };
-};
-/**
- * Core provider interface. Every LLM adapter must implement this.
- */
-interface Provider {
-    /** Human-readable name for the provider (e.g. "openai", "anthropic") */
-    readonly name?: string;
-    /**
-     * Send a chat completion request and return the full response.
-     */
-    chat(messages: ChatMessage[], options: ChatOptions): Promise<ProviderResponse>;
-    /**
-     * Stream a chat completion, yielding chunks as they arrive.
-     */
-    stream(messages: ChatMessage[], options: ChatOptions): AsyncGenerator<StreamChunk>;
-}
-/**
- * Alias for Provider. Used for backward compatibility with index.ts exports.
- */
-type ProviderAdapter = Provider;
-
 /** Configuration for OpenTelemetry integration. */
 type TelemetryConfig = {
     /** Whether telemetry is enabled. Defaults to false. */
@@ -799,15 +919,7 @@ type WorkflowContextInit = {
         model: string;
     }) => void;
     /** Callback fired after each ctx.ask() completes (once per ask invocation). */
-    onAgentCallComplete?: (call: {
-        agent: string;
-        prompt: string;
-        response: string;
-        model: string;
-        cost: number;
-        duration: number;
-        promptVersion?: string;
-    }) => void;
+    onAgentCallComplete?: (call: AgentCallInfo) => void;
 };
 /**
  * The central coordination object for all Axl primitives.
@@ -840,6 +952,14 @@ declare class WorkflowContext<TInput = unknown> {
     private onAgentStart?;
     private onAgentCallComplete?;
     constructor(init: WorkflowContextInit);
+    /**
+     * Create a child context for nested agent invocations (e.g., agent-as-tool).
+     * Shares: budget tracking, abort signals, trace emission, provider registry,
+     *         state store, span manager, memory manager, MCP manager, config,
+     *         awaitHuman handler, pending decisions, tool overrides.
+     * Isolates: session history, step counter, streaming callbacks (onToken, onAgentStart, onToolCall).
+     */
+    createChildContext(): WorkflowContext;
     /**
      * Resolve the current abort signal.
      * Branch-scoped signals (from race/spawn/map/budget) in AsyncLocalStorage
@@ -848,6 +968,11 @@ declare class WorkflowContext<TInput = unknown> {
     private get currentSignal();
     ask<T = string>(agent: Agent, prompt: string, options?: AskOptions<T>): Promise<T>;
     private executeAgentCall;
+    /**
+     * Push the final assistant message into session history, preserving providerMetadata
+     * (e.g., Gemini thought signatures needed for multi-turn reasoning context).
+     */
+    private pushAssistantToSessionHistory;
     private buildToolDefs;
     /**
      * Summarize old messages to fit within context window.
@@ -908,6 +1033,18 @@ declare class WorkflowContext<TInput = unknown> {
     forget(key: string, options?: {
         scope?: 'session' | 'global';
     }): Promise<void>;
+    /**
+     * Select the best agent from a list of candidates and invoke it.
+     * Creates a temporary router agent that uses handoffs to pick the right specialist.
+     *
+     * This is convenience sugar over creating a router agent with dynamic handoffs.
+     * For full control over the router's behavior, create the router agent explicitly.
+     *
+     * @param agents - Candidate agents to choose from (at least 1)
+     * @param prompt - The prompt to send to the selected agent
+     * @param options - Optional: schema, routerModel, metadata, retries
+     */
+    delegate<T = string>(agents: Agent[], prompt: string, options?: DelegateOptions<T>): Promise<T>;
     private emitTrace;
 }
 
@@ -931,7 +1068,7 @@ type ToolConfig<TInput extends z.ZodTypeAny, TOutput = unknown> = {
     name: string;
     description: string;
     input: TInput;
-    handler: (input: z.infer<TInput>) => TOutput | Promise<TOutput>;
+    handler: (input: z.infer<TInput>, ctx: WorkflowContext) => TOutput | Promise<TOutput>;
     retry?: RetryPolicy;
     sensitive?: boolean;
     /** Maximum string length for any string argument. Default: 10000. Set to 0 to disable. */
@@ -953,7 +1090,7 @@ type Tool<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput = unknown> = {
     /** Run the tool directly from workflow code */
     run(ctx: WorkflowContext, input: z.infer<TInput>): Promise<TOutput>;
     /** Execute the handler (internal use — includes retry logic) */
-    _execute(input: z.infer<TInput>): Promise<TOutput>;
+    _execute(input: z.infer<TInput>, ctx?: WorkflowContext): Promise<TOutput>;
 };
 /**
  * Define a tool with Zod-validated input, a handler function, and optional retry policy.
@@ -1142,6 +1279,14 @@ declare class AxlRuntime extends EventEmitter {
     runRegisteredEval(name: string): Promise<unknown>;
     /** Get all execution info (running + completed). */
     getExecutions(): ExecutionInfo[];
+    /**
+     * Create a lightweight WorkflowContext for ad-hoc use (tool testing, prototyping).
+     * The context has access to the runtime's providers, state store, and MCP manager
+     * but no session history, streaming callbacks, or budget tracking.
+     */
+    createContext(options?: {
+        metadata?: Record<string, unknown>;
+    }): WorkflowContext;
     /** Register a custom provider instance. */
     registerProvider(name: string, provider: Provider): void;
     /** Execute a workflow and return the result. */
@@ -1377,6 +1522,16 @@ declare class AnthropicProvider implements Provider {
      * Map an OpenAI-format ToolDefinition to Anthropic's tool format.
      */
     private mapToolDefinition;
+    /**
+     * Map Axl's ToolChoice to Anthropic's tool_choice format.
+     *
+     * Axl (OpenAI format)          → Anthropic format
+     * 'auto'                       → { type: 'auto' }
+     * 'none'                       → { type: 'none' }
+     * 'required'                   → { type: 'any' }
+     * { type:'function', function: { name } } → { type: 'tool', name }
+     */
+    private mapToolChoice;
     private parseResponse;
     private parseSSEStream;
 }
@@ -1427,6 +1582,15 @@ declare class GeminiProvider implements Provider {
      * Gemini requires alternating user/model turns.
      */
     private mergeConsecutiveRoles;
+    /**
+     * Map Axl's ToolChoice to Gemini's functionCallingConfig format.
+     *
+     * - 'auto'     → { mode: 'AUTO' }
+     * - 'none'     → { mode: 'NONE' }
+     * - 'required' → { mode: 'ANY' }
+     * - { type: 'function', function: { name } } → { mode: 'ANY', allowedFunctionNames: [name] }
+     */
+    private mapToolChoice;
     private mapToolDefinition;
     private parseResponse;
     private parseSSEStream;
@@ -1630,4 +1794,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-export { type Agent, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, tool, workflow, zodToJsonSchema };
+export { type Agent, type AgentCallInfo, type AgentConfig, AnthropicProvider, type AskOptions, type AwaitHumanOptions, type AxlConfig, AxlError, AxlRuntime, AxlStream, BudgetExceededError, type BudgetOptions, type BudgetResult, type ChatMessage, type ChatOptions, type DelegateOptions, type Effort, type Embedder, type ExecutionInfo, type ExecutionState, GeminiProvider, type GuardrailBlockHandler, GuardrailError, type GuardrailResult, type GuardrailsConfig, type HandoffDescriptor, type HandoffRecord, type HumanDecision, InMemoryVectorStore, type InputGuardrail, type MapOptions, MaxTurnsError, McpManager, type McpServer, type McpServerConfig, type McpToolDefinition, type McpToolResult, type MemoryConfig, MemoryManager, MemoryStore, NoConsensus, NoopSpanManager, OpenAIEmbedder, OpenAIProvider, OpenAIResponsesProvider, type OutputGuardrail, type PendingDecision, type Provider, type ProviderAdapter, ProviderRegistry, type ProviderResponse, QuorumNotMet, type RaceOptions, type RecallOptions, RedisStore, type RememberOptions, type ResolvedThinkingOptions, type Result, type RetryPolicy, SQLiteStore, Session, type SessionOptions, type SpanHandle, type SpanManager, type SpawnOptions, SqliteVectorStore, type StateStore, type StreamChunk, type StreamEvent, type TelemetryConfig, TimeoutError, type Tool, type ToolCallMessage, type ToolChoice, type ToolConfig, ToolDenied, type ToolHooks, type TraceEvent, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };