@axlsdk/axl 0.10.3 → 0.11.0

package/dist/index.d.cts

@@ -969,6 +969,12 @@ declare class WorkflowContext<TInput = unknown> {
     readonly input: TInput;
     readonly executionId: string;
     readonly metadata: Record<string, unknown>;
+    /**
+     * Total cost accumulated by agent calls in this context.
+     * Inside a `ctx.budget()` block, returns only that block's cost.
+     * After the block completes, the nested cost is rolled up into the parent total.
+     */
+    get totalCost(): number;
     private config;
     private providerRegistry;
     private sessionHistory;
@@ -1236,6 +1242,19 @@ declare class Session {
 type ExecuteOptions = {
     metadata?: Record<string, unknown>;
 };
+type CreateContextOptions = {
+    metadata?: Record<string, unknown>;
+    /** Cost budget for the context (e.g., '$0.50'). Enforced via finish_and_stop policy. */
+    budget?: string;
+    /** Abort signal for cancellation/timeouts. */
+    signal?: AbortSignal;
+    /** Prior conversation history for multi-turn eval testing. */
+    sessionHistory?: ChatMessage[];
+    /** Token streaming callback. */
+    onToken?: (token: string) => void;
+    /** Handler for tool approval requests. Called when an agent invokes a tool with requireApproval. */
+    awaitHumanHandler?: (options: AwaitHumanOptions) => Promise<HumanDecision>;
+};
 /**
  * The main entry point for executing Axl workflows.
  * Manages workflow registration, provider resolution, state storage, tracing, MCP servers,
@@ -1320,13 +1339,11 @@ declare class AxlRuntime extends EventEmitter {
     /** 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.
+     * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
+     * The context has access to the runtime's providers, state store, MCP manager,
+     * and automatically emits trace events and tracks cost.
      */
-    createContext(options?: {
-        metadata?: Record<string, unknown>;
-    }): WorkflowContext;
+    createContext(options?: CreateContextOptions): WorkflowContext;
     /** Register a custom provider instance. */
     registerProvider(name: string, provider: Provider): void;
     /** Execute a workflow and return the result. */
@@ -1385,6 +1402,19 @@ declare class AxlRuntime extends EventEmitter {
      * @see Spec Section 13.6
      */
     evalCompare(baseline: unknown, candidate: unknown): Promise<unknown>;
+    /**
+     * Track cost across any runtime operations within the given function.
+     * Uses AsyncLocalStorage to scope cost attribution to specific execution IDs,
+     * making it correct with concurrent calls.
+     *
+     * Works with both `createContext()` and `execute()` calls inside `fn`.
+     */
+    trackCost<T>(fn: () => Promise<T>): Promise<{
+        result: T;
+        cost: number;
+    }>;
+    /** Register an execution ID with the active cost scope for trackCost() attribution. */
+    private registerWithCostScope;
     /**
      * Handle trace event output based on configuration.
      *
@@ -1847,4 +1877,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-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 OutputValidator, 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 ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, 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 CreateContextOptions, 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 OutputValidator, 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 ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };

package/dist/index.d.ts

@@ -969,6 +969,12 @@ declare class WorkflowContext<TInput = unknown> {
     readonly input: TInput;
     readonly executionId: string;
     readonly metadata: Record<string, unknown>;
+    /**
+     * Total cost accumulated by agent calls in this context.
+     * Inside a `ctx.budget()` block, returns only that block's cost.
+     * After the block completes, the nested cost is rolled up into the parent total.
+     */
+    get totalCost(): number;
     private config;
     private providerRegistry;
     private sessionHistory;
@@ -1236,6 +1242,19 @@ declare class Session {
 type ExecuteOptions = {
     metadata?: Record<string, unknown>;
 };
+type CreateContextOptions = {
+    metadata?: Record<string, unknown>;
+    /** Cost budget for the context (e.g., '$0.50'). Enforced via finish_and_stop policy. */
+    budget?: string;
+    /** Abort signal for cancellation/timeouts. */
+    signal?: AbortSignal;
+    /** Prior conversation history for multi-turn eval testing. */
+    sessionHistory?: ChatMessage[];
+    /** Token streaming callback. */
+    onToken?: (token: string) => void;
+    /** Handler for tool approval requests. Called when an agent invokes a tool with requireApproval. */
+    awaitHumanHandler?: (options: AwaitHumanOptions) => Promise<HumanDecision>;
+};
 /**
  * The main entry point for executing Axl workflows.
  * Manages workflow registration, provider resolution, state storage, tracing, MCP servers,
@@ -1320,13 +1339,11 @@ declare class AxlRuntime extends EventEmitter {
     /** 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.
+     * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
+     * The context has access to the runtime's providers, state store, MCP manager,
+     * and automatically emits trace events and tracks cost.
      */
-    createContext(options?: {
-        metadata?: Record<string, unknown>;
-    }): WorkflowContext;
+    createContext(options?: CreateContextOptions): WorkflowContext;
     /** Register a custom provider instance. */
     registerProvider(name: string, provider: Provider): void;
     /** Execute a workflow and return the result. */
@@ -1385,6 +1402,19 @@ declare class AxlRuntime extends EventEmitter {
      * @see Spec Section 13.6
      */
     evalCompare(baseline: unknown, candidate: unknown): Promise<unknown>;
+    /**
+     * Track cost across any runtime operations within the given function.
+     * Uses AsyncLocalStorage to scope cost attribution to specific execution IDs,
+     * making it correct with concurrent calls.
+     *
+     * Works with both `createContext()` and `execute()` calls inside `fn`.
+     */
+    trackCost<T>(fn: () => Promise<T>): Promise<{
+        result: T;
+        cost: number;
+    }>;
+    /** Register an execution ID with the active cost scope for trackCost() attribution. */
+    private registerWithCostScope;
     /**
      * Handle trace event output based on configuration.
      *
@@ -1847,4 +1877,4 @@ declare class NoopSpanManager implements SpanManager {
  */
 declare function createSpanManager(config?: TelemetryConfig): Promise<SpanManager>;
 
-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 OutputValidator, 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 ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, 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 CreateContextOptions, 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 OutputValidator, 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 ValidateResult, ValidationError, type VectorEntry, type VectorResult, type VectorStore, VerifyError, type VerifyOptions, type VerifyRetry, type VoteOptions, type Workflow, type WorkflowConfig, WorkflowContext, type WorkflowContextInit, agent, createSpanManager, defineConfig, resolveThinkingOptions, tool, workflow, zodToJsonSchema };

package/dist/index.js

@@ -2135,6 +2135,14 @@ var WorkflowContext = class _WorkflowContext {
   input;
   executionId;
   metadata;
+  /**
+   * Total cost accumulated by agent calls in this context.
+   * Inside a `ctx.budget()` block, returns only that block's cost.
+   * After the block completes, the nested cost is rolled up into the parent total.
+   */
+  get totalCost() {
+    return this.budgetContext?.totalCost ?? 0;
+  }
   config;
   providerRegistry;
   sessionHistory;
@@ -3634,6 +3642,11 @@ ${summaryResponse.content}`
       });
       return decision2;
     }
+    if (!this.pendingDecisions) {
+      throw new Error(
+        "Tool requires approval but no approval handler is configured. Provide awaitHumanHandler to createContext() or use runtime.execute() with workflow infrastructure."
+      );
+    }
     if (this.stateStore) {
       await this.stateStore.savePendingDecision(this.executionId, {
         executionId: this.executionId,
@@ -3659,7 +3672,7 @@ ${summaryResponse.content}`
       data: { event: "await_human", channel: options.channel, prompt: options.prompt }
     });
     const decision = await new Promise((resolve) => {
-      this.pendingDecisions?.set(this.executionId, resolve);
+      this.pendingDecisions.set(this.executionId, resolve);
     });
     if (this.stateStore) {
       await this.stateStore.saveExecutionState(this.executionId, {
@@ -3877,6 +3890,7 @@ function workflow(config) {
 // src/runtime.ts
 import { EventEmitter as EventEmitter2 } from "events";
 import { randomUUID as randomUUID2 } from "crypto";
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 import { appendFileSync, mkdirSync as mkdirSync2 } from "fs";
 import { dirname } from "path";
 
@@ -5095,6 +5109,7 @@ function hashInput(input) {
   }
   return (hash >>> 0).toString(16);
 }
+var costScopeStorage = new AsyncLocalStorage2();
 var AxlRuntime = class extends EventEmitter2 {
   config;
   workflows = /* @__PURE__ */ new Map();
@@ -5240,8 +5255,14 @@ var AxlRuntime = class extends EventEmitter2 {
           "axl-eval is required for AxlRuntime.runRegisteredEval(). Install it with: npm install @axlsdk/eval"
         );
       }
-      const executeFn = entry.executeWorkflow;
-      return runEvalFn(entry.config, executeFn, void 0, this);
+      const originalExecuteFn = entry.executeWorkflow;
+      const wrappedExecuteFn = async (input, runtime) => {
+        const { result, cost: trackedCost } = await this.trackCost(async () => {
+          return originalExecuteFn(input, runtime);
+        });
+        return { output: result.output, cost: result.cost ?? trackedCost };
+      };
+      return runEvalFn(entry.config, wrappedExecuteFn, void 0, this);
     }
     return this.eval(
       entry.config
@@ -5252,21 +5273,38 @@ var AxlRuntime = class extends EventEmitter2 {
     return [...this.executions.values()];
   }
   /**
-   * 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.
+   * Create a WorkflowContext for ad-hoc use (evals, tool testing, prototyping).
+   * The context has access to the runtime's providers, state store, MCP manager,
+   * and automatically emits trace events and tracks cost.
    */
   createContext(options) {
+    const executionId = randomUUID2();
+    const budgetLimit = options?.budget ? parseCost(options.budget) : Infinity;
+    this.registerWithCostScope(executionId);
     return new WorkflowContext({
       input: void 0,
-      executionId: randomUUID2(),
+      executionId,
       metadata: options?.metadata,
       config: this.config,
       providerRegistry: this.providerRegistry,
       stateStore: this.stateStore,
       mcpManager: this.mcpManager,
       spanManager: this.spanManager,
-      memoryManager: this.memoryManager
+      memoryManager: this.memoryManager,
+      sessionHistory: options?.sessionHistory,
+      signal: options?.signal,
+      onToken: options?.onToken,
+      awaitHumanHandler: options?.awaitHumanHandler,
+      onTrace: (event) => {
+        this.emit("trace", event);
+        this.outputTraceEvent(event);
+      },
+      budgetContext: {
+        totalCost: 0,
+        limit: budgetLimit,
+        exceeded: false,
+        policy: "finish_and_stop"
+      }
     });
   }
   /** Register a custom provider instance. */
@@ -5285,6 +5323,7 @@ var AxlRuntime = class extends EventEmitter2 {
     const executionId = randomUUID2();
     const controller = new AbortController();
     this.abortControllers.set(executionId, controller);
+    this.registerWithCostScope(executionId);
     const execInfo = {
       executionId,
       workflow: name,
@@ -5329,7 +5368,13 @@ var AxlRuntime = class extends EventEmitter2 {
       mcpManager: this.mcpManager,
       memoryManager: this.memoryManager,
       resumeMode: !!options?.metadata?.resumeMode,
-      spanManager: this.spanManager
+      spanManager: this.spanManager,
+      budgetContext: {
+        totalCost: 0,
+        limit: Infinity,
+        exceeded: false,
+        policy: "finish_and_stop"
+      }
     });
     ctx.log("workflow_start", { workflow: name, executionId });
     return this.spanManager.withSpanAsync(
@@ -5384,6 +5429,7 @@ var AxlRuntime = class extends EventEmitter2 {
       const executionId = randomUUID2();
       this.abortControllers.set(executionId, controller);
       const sessionHistory = options?.metadata?.sessionHistory ?? void 0;
+      this.registerWithCostScope(executionId);
       execInfo = {
         executionId,
         workflow: name,
@@ -5474,7 +5520,13 @@ var AxlRuntime = class extends EventEmitter2 {
         mcpManager: this.mcpManager,
         memoryManager: this.memoryManager,
         resumeMode: !!options?.metadata?.resumeMode,
-        spanManager: this.spanManager
+        spanManager: this.spanManager,
+        budgetContext: {
+          totalCost: 0,
+          limit: Infinity,
+          exceeded: false,
+          policy: "finish_and_stop"
+        }
       });
       return this.spanManager.withSpanAsync(
         "axl.workflow.execute",
@@ -5646,28 +5698,21 @@ var AxlRuntime = class extends EventEmitter2 {
    * @see Spec Section 13.5
    */
   async eval(config) {
-    let runEval;
+    let runEvalFn;
     try {
-      ({ runEval } = await import("@axlsdk/eval"));
+      ({ runEval: runEvalFn } = await import("@axlsdk/eval"));
     } catch {
       throw new Error(
         "axl-eval is required for AxlRuntime.eval(). Install it with: npm install @axlsdk/eval"
       );
     }
     const executeWorkflow = async (input) => {
-      let cost = 0;
-      const costListener = (event) => {
-        if (event.cost) cost += event.cost;
-      };
-      this.on("trace", costListener);
-      try {
-        const output = await this.execute(config.workflow, input);
-        return { output, cost };
-      } finally {
-        this.off("trace", costListener);
-      }
+      const { result, cost } = await this.trackCost(async () => {
+        return this.execute(config.workflow, input);
+      });
+      return { output: result, cost };
     };
-    return runEval(config, executeWorkflow, void 0, this);
+    return runEvalFn(config, executeWorkflow, void 0, this);
   }
   /**
    * Compare two evaluation results to detect regressions and improvements.
@@ -5686,6 +5731,46 @@ var AxlRuntime = class extends EventEmitter2 {
     }
     return evalCompareFn(baseline, candidate);
   }
+  /**
+   * Track cost across any runtime operations within the given function.
+   * Uses AsyncLocalStorage to scope cost attribution to specific execution IDs,
+   * making it correct with concurrent calls.
+   *
+   * Works with both `createContext()` and `execute()` calls inside `fn`.
+   */
+  async trackCost(fn) {
+    const parentScope = costScopeStorage.getStore();
+    const scope = {
+      totalCost: 0,
+      trackedIds: /* @__PURE__ */ new Set(),
+      parent: parentScope
+    };
+    const costListener = (event) => {
+      if (event.cost && scope.trackedIds.has(event.executionId)) {
+        scope.totalCost += event.cost;
+      }
+    };
+    this.setMaxListeners(this.getMaxListeners() + 1);
+    this.on("trace", costListener);
+    try {
+      const result = await costScopeStorage.run(scope, fn);
+      return { result, cost: scope.totalCost };
+    } finally {
+      this.off("trace", costListener);
+      this.setMaxListeners(this.getMaxListeners() - 1);
+    }
+  }
+  /** Register an execution ID with the active cost scope for trackCost() attribution. */
+  registerWithCostScope(executionId) {
+    const costScope = costScopeStorage.getStore();
+    if (costScope) {
+      let scope = costScope;
+      while (scope) {
+        scope.trackedIds.add(executionId);
+        scope = scope.parent;
+      }
+    }
+  }
   /**
    * Handle trace event output based on configuration.
    *