@axlsdk/axl 0.13.8 → 0.15.0

package/dist/index.js

@@ -1965,6 +1965,21 @@ var TimeoutError = class extends AxlError {
     this.name = "TimeoutError";
   }
 };
+function formatBudgetCost(cost) {
+  if (Number.isNaN(cost)) return "$NaN";
+  if (cost === Infinity) return "$Infinity";
+  if (cost === -Infinity) return "-$Infinity";
+  if (cost === 0) return "$0.00";
+  const sign = cost < 0 ? "-" : "";
+  const abs = Math.abs(cost);
+  if (abs < 1e-6) return `${sign}< $0.000001`;
+  if (abs < 1e-4) {
+    const [mantissa, exponent] = abs.toExponential(2).split("e");
+    return `${sign}$${mantissa}e${parseInt(exponent, 10)}`;
+  }
+  if (abs < 0.01) return `${sign}$${abs.toFixed(6)}`;
+  return `${sign}$${abs.toFixed(2)}`;
+}
 var BudgetExceededError = class extends AxlError {
   limit;
   spent;
@@ -1972,7 +1987,9 @@ var BudgetExceededError = class extends AxlError {
   constructor(limit, spent, policy) {
     super(
       "BUDGET_EXCEEDED",
-      `Budget exceeded: spent $${spent.toFixed(4)} of $${limit.toFixed(4)} limit (policy: ${policy})`
+      `Budget exceeded: spent ${formatBudgetCost(spent)} of ${formatBudgetCost(
+        limit
+      )} limit (policy: ${policy})`
     );
     this.name = "BudgetExceededError";
     this.limit = limit;
@@ -2160,6 +2177,14 @@ function extractBalanced(str, start, openChar, closeChar) {
   }
   return null;
 }
+function appendRetryMessages(messages, content, feedbackMessage, providerMetadata) {
+  messages.push({
+    role: "assistant",
+    content,
+    ...providerMetadata ? { providerMetadata } : {}
+  });
+  messages.push({ role: "system", content: feedbackMessage });
+}
 function estimateMessagesTokens(messages) {
   let total = 0;
   for (const msg of messages) {
@@ -2207,6 +2232,7 @@ var WorkflowContext = class _WorkflowContext {
   awaitHumanHandler;
   onAgentStart;
   onAgentCallComplete;
+  parentToolCallId;
   constructor(init) {
     this.input = init.input;
     this.executionId = init.executionId;
@@ -2230,6 +2256,7 @@ var WorkflowContext = class _WorkflowContext {
     this.awaitHumanHandler = init.awaitHumanHandler;
     this.onAgentStart = init.onAgentStart;
     this.onAgentCallComplete = init.onAgentCallComplete;
+    this.parentToolCallId = init.parentToolCallId;
     if (init.metadata?.summaryCache) {
       this.summaryCache = init.metadata.summaryCache;
     }
@@ -2240,8 +2267,13 @@ var WorkflowContext = class _WorkflowContext {
    *         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).
+   *
+   * @param parentToolCallId - The `callId` of the outer `tool_call` that
+   *   spawned this child. When set, every trace event emitted by the child
+   *   will carry this id as `parentToolCallId`, so consumers can join nested
+   *   agent calls back to the outer tool call that invoked them.
    */
-  createChildContext() {
+  createChildContext(parentToolCallId) {
     return new _WorkflowContext({
       input: this.input,
       executionId: this.executionId,
@@ -2260,7 +2292,11 @@ var WorkflowContext = class _WorkflowContext {
       pendingDecisions: this.pendingDecisions,
       toolOverrides: this.toolOverrides,
       signal: this.signal,
-      workflowName: this.workflowName
+      workflowName: this.workflowName,
+      // Join key for nested event correlation. Inherit the parent's
+      // `parentToolCallId` when this child is itself nested inside another
+      // child — so grand-children still point to the outermost tool call.
+      parentToolCallId: parentToolCallId ?? this.parentToolCallId
       // Isolated: sessionHistory (empty), stepCounter (0),
       // onToken (null), onAgentStart (null), onToolCall (null)
     });
@@ -2430,11 +2466,22 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       this.emitTrace({
         type: "guardrail",
         agent: agent2._name,
-        data: { guardrailType: "input", blocked: inputResult.block, reason: inputResult.reason }
+        data: {
+          guardrailType: "input",
+          blocked: inputResult.block,
+          ...inputResult.reason ? { reason: inputResult.reason } : {},
+          // Input guardrails can't retry (prompt is user-supplied), so attempt
+          // and maxAttempts are always 1 — emit them for shape consistency with
+          // output guardrails so consumers don't need two narrowers.
+          attempt: 1,
+          maxAttempts: 1
+        }
       });
       this.spanManager?.addEventToActiveSpan("axl.guardrail.check", {
         "axl.guardrail.type": "input",
         "axl.guardrail.blocked": inputResult.block,
+        "axl.guardrail.attempt": 1,
+        "axl.guardrail.maxAttempts": 1,
         ...inputResult.reason ? { "axl.guardrail.reason": inputResult.reason } : {}
       });
       if (inputResult.block) {
@@ -2461,11 +2508,15 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
     let guardrailOutputRetries = 0;
     let schemaRetries = 0;
     let validateRetries = 0;
+    const maxGuardrailRetries = guardrails?.maxRetries ?? 2;
+    let pendingRetryReason;
+    const verboseTrace = this.config.trace?.level === "full";
     while (turns < maxTurns) {
       if (Date.now() - startTime > timeoutMs) {
         throw new TimeoutError("ctx.ask()", timeoutMs);
       }
       turns++;
+      const turnStart = Date.now();
       const chatOptions = {
         model,
         temperature: options?.temperature ?? agent2._config.temperature,
@@ -2546,16 +2597,22 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
         usageCapture.value = response.usage;
       }
       if (response.cost) {
-        if (this.budgetContext) {
-          this.budgetContext.totalCost += response.cost;
-          if (this.budgetContext.totalCost >= this.budgetContext.limit) {
-            this.budgetContext.exceeded = true;
-            if (this.budgetContext.policy === "hard_stop" && this.budgetContext.abortController) {
-              this.budgetContext.abortController.abort();
-            }
-          }
+        this._accumulateBudgetCost(response.cost);
+      }
+      let messagesSnapshot;
+      if (verboseTrace) {
+        try {
+          messagesSnapshot = structuredClone(currentMessages);
+        } catch (err) {
+          console.warn(
+            "[axl] verbose trace messages snapshot failed to clone; emitting shallow copy:",
+            err instanceof Error ? err.message : String(err)
+          );
+          messagesSnapshot = [...currentMessages];
         }
       }
+      const retryReason = pendingRetryReason;
+      pendingRetryReason = void 0;
       this.emitTrace({
         type: "agent_call",
         agent: agent2._name,
@@ -2567,8 +2624,25 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           output: response.usage.completion_tokens,
           reasoning: response.usage.reasoning_tokens
         } : void 0,
-        duration: Date.now() - startTime,
-        data: { prompt, response: response.content }
+        duration: Date.now() - turnStart,
+        data: {
+          prompt,
+          response: response.content,
+          ...systemPrompt ? { system: systemPrompt } : {},
+          ...response.thinking_content ? { thinking: response.thinking_content } : {},
+          params: {
+            ...chatOptions.temperature !== void 0 ? { temperature: chatOptions.temperature } : {},
+            maxTokens: chatOptions.maxTokens,
+            ...chatOptions.effort !== void 0 ? { effort: chatOptions.effort } : {},
+            ...chatOptions.thinkingBudget !== void 0 ? { thinkingBudget: chatOptions.thinkingBudget } : {},
+            ...chatOptions.includeThoughts !== void 0 ? { includeThoughts: chatOptions.includeThoughts } : {},
+            ...chatOptions.toolChoice !== void 0 ? { toolChoice: chatOptions.toolChoice } : {},
+            ...chatOptions.stop !== void 0 ? { stop: chatOptions.stop } : {}
+          },
+          turn: turns,
+          ...retryReason ? { retryReason } : {},
+          ...messagesSnapshot ? { messages: messagesSnapshot } : {}
+        }
       });
       if (response.tool_calls && response.tool_calls.length > 0) {
         currentMessages.push({
@@ -2633,7 +2707,13 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                       this.emitTrace({
                         type: "handoff",
                         agent: agent2._name,
-                        data: { target: targetName, mode, duration }
+                        data: {
+                          target: targetName,
+                          mode,
+                          duration,
+                          source: agent2._name,
+                          ...handoffPrompt !== prompt ? { message: handoffPrompt } : {}
+                        }
                       });
                       return result;
                     }
@@ -2643,7 +2723,13 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                   this.emitTrace({
                     type: "handoff",
                     agent: agent2._name,
-                    data: { target: targetName, mode, duration: Date.now() - handoffStart }
+                    data: {
+                      target: targetName,
+                      mode,
+                      duration: Date.now() - handoffStart,
+                      source: agent2._name,
+                      ...handoffPrompt !== prompt ? { message: handoffPrompt } : {}
+                    }
                   });
                 }
                 continue;
@@ -2663,7 +2749,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                     this.emitTrace({
                       type: "handoff",
                       agent: agent2._name,
-                      data: { target: targetName, mode, duration }
+                      data: { target: targetName, mode, duration, source: agent2._name }
                     });
                     return result;
                   }
@@ -2673,7 +2759,12 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               this.emitTrace({
                 type: "handoff",
                 agent: agent2._name,
-                data: { target: targetName, mode, duration: Date.now() - handoffStart }
+                data: {
+                  target: targetName,
+                  mode,
+                  duration: Date.now() - handoffStart,
+                  source: agent2._name
+                }
               });
               return onewayResult;
             }
@@ -2766,24 +2857,18 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
               });
               if (!decision.approved) {
                 const reason = decision.reason ?? "Denied by human";
-                this.emitTrace({
-                  type: "tool_denied",
-                  agent: agent2._name,
-                  tool: toolName,
-                  data: { denied: true, reason, args: toolArgs }
-                });
                 currentMessages.push({
                   role: "tool",
                   content: JSON.stringify({ error: `Tool denied by human: ${reason}` }),
                   tool_call_id: toolCall.id
                 });
-                return false;
+                return { approved: false, reason };
               }
-              return true;
+              return { approved: true };
             };
-            let approved;
+            let approvalOutcome;
             if (this.spanManager) {
-              approved = await this.spanManager.withSpanAsync(
+              approvalOutcome = await this.spanManager.withSpanAsync(
                 "axl.tool.approval",
                 {
                   "axl.tool.name": toolName,
@@ -2791,20 +2876,24 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 },
                 async (span) => {
                   const result = await approvalFn();
-                  span.setAttribute("axl.tool.approval.approved", result);
+                  span.setAttribute("axl.tool.approval.approved", result.approved);
                   return result;
                 }
               );
             } else {
-              approved = await approvalFn();
+              approvalOutcome = await approvalFn();
             }
-            if (!approved) continue;
             this.emitTrace({
-              type: "tool_denied",
+              type: "tool_approval",
               agent: agent2._name,
               tool: toolName,
-              data: { denied: false, args: toolArgs }
+              data: {
+                approved: approvalOutcome.approved,
+                args: toolArgs,
+                ...approvalOutcome.reason ? { reason: approvalOutcome.reason } : {}
+              }
             });
+            if (!approvalOutcome.approved) continue;
           }
           if (tool2 && tool2.hooks?.before) {
             try {
@@ -2837,7 +2926,7 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
                 resultContent2 = JSON.stringify(toolResult2);
               }
             } else if (tool2) {
-              const childCtx = this.createChildContext();
+              const childCtx = this.createChildContext(toolCall.id);
               try {
                 toolResult2 = await tool2._execute(toolArgs, childCtx);
               } catch (err) {
@@ -2897,37 +2986,43 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       const content = response.content;
       if (guardrails?.output) {
         const outputResult = await guardrails.output(content, { metadata: this.metadata });
+        const attempt = guardrailOutputRetries + 1;
+        const maxAttempts = maxGuardrailRetries + 1;
+        const onBlock = guardrails.onBlock ?? "throw";
+        let feedbackMessage;
+        if (outputResult.block && onBlock === "retry" && guardrailOutputRetries < maxGuardrailRetries) {
+          feedbackMessage = `Your previous response was blocked by a safety guardrail: ${outputResult.reason ?? "Output blocked"}. Please provide a different response that complies with the guidelines.`;
+        }
         this.emitTrace({
           type: "guardrail",
           agent: agent2._name,
           data: {
             guardrailType: "output",
             blocked: outputResult.block,
-            reason: outputResult.reason
+            ...outputResult.reason ? { reason: outputResult.reason } : {},
+            attempt,
+            maxAttempts,
+            ...feedbackMessage ? { feedbackMessage } : {}
           }
         });
         this.spanManager?.addEventToActiveSpan("axl.guardrail.check", {
           "axl.guardrail.type": "output",
           "axl.guardrail.blocked": outputResult.block,
+          "axl.guardrail.attempt": attempt,
+          "axl.guardrail.maxAttempts": maxAttempts,
           ...outputResult.reason ? { "axl.guardrail.reason": outputResult.reason } : {}
         });
         if (outputResult.block) {
-          const onBlock = guardrails.onBlock ?? "throw";
-          if (onBlock === "retry") {
-            const maxGuardrailRetries = guardrails.maxRetries ?? 2;
-            if (guardrailOutputRetries < maxGuardrailRetries) {
-              guardrailOutputRetries++;
-              currentMessages.push({
-                role: "assistant",
-                content,
-                ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
-              });
-              currentMessages.push({
-                role: "system",
-                content: `Your previous response was blocked by a safety guardrail: ${outputResult.reason ?? "Output blocked"}. Please provide a different response that complies with the guidelines.`
-              });
-              continue;
-            }
+          if (feedbackMessage) {
+            guardrailOutputRetries++;
+            appendRetryMessages(
+              currentMessages,
+              content,
+              feedbackMessage,
+              response.providerMetadata
+            );
+            pendingRetryReason = "guardrail";
+            continue;
           }
           if (typeof onBlock === "function") {
             return onBlock(outputResult.reason ?? "Output blocked by guardrail", {
@@ -2939,30 +3034,58 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
       }
       let validated = void 0;
       if (options?.schema) {
+        const maxSchemaRetries = options.retries ?? 3;
+        const schemaAttempt = schemaRetries + 1;
+        const schemaMaxAttempts = maxSchemaRetries + 1;
+        let schemaValid = false;
+        let schemaReason;
+        let schemaFeedback;
+        let schemaErr;
         try {
           const parsed = JSON.parse(extractJson(content));
           validated = options.schema.parse(parsed);
+          schemaValid = true;
         } catch (err) {
-          const maxSchemaRetries = options.retries ?? 3;
+          schemaErr = err;
+          schemaReason = err instanceof Error ? err.message : String(err);
           if (schemaRetries < maxSchemaRetries) {
+            schemaFeedback = `Your response was not valid JSON or did not match the required schema: ${schemaReason}. Please fix and try again.`;
+          }
+        }
+        this.emitTrace({
+          type: "schema_check",
+          agent: agent2._name,
+          data: {
+            valid: schemaValid,
+            ...schemaReason ? { reason: schemaReason } : {},
+            attempt: schemaAttempt,
+            maxAttempts: schemaMaxAttempts,
+            ...schemaFeedback ? { feedbackMessage: schemaFeedback } : {}
+          }
+        });
+        this.spanManager?.addEventToActiveSpan("axl.schema.check", {
+          "axl.schema.valid": schemaValid,
+          "axl.schema.attempt": schemaAttempt,
+          "axl.schema.maxAttempts": schemaMaxAttempts,
+          ...schemaReason ? { "axl.schema.reason": schemaReason } : {}
+        });
+        if (!schemaValid) {
+          if (schemaFeedback) {
             schemaRetries++;
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            currentMessages.push({
-              role: "assistant",
+            appendRetryMessages(
+              currentMessages,
               content,
-              ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
-            });
-            currentMessages.push({
-              role: "system",
-              content: `Your response was not valid JSON or did not match the required schema: ${errorMsg}. Please fix and try again.`
-            });
+              schemaFeedback,
+              response.providerMetadata
+            );
+            pendingRetryReason = "schema";
             continue;
           }
-          const zodErr = err instanceof ZodError ? err : new ZodError([
+          const zodErr = schemaErr instanceof ZodError ? schemaErr : new ZodError([
             {
               code: "custom",
               path: [],
-              message: err instanceof Error ? err.message : String(err)
+              message: schemaReason ?? "Schema parse failed"
             }
           ]);
           throw new VerifyError(content, zodErr, maxSchemaRetries);
@@ -2978,31 +3101,40 @@ ${JSON.stringify(jsonSchema, null, 2)}`;
           const reason = err instanceof Error ? err.message : String(err);
           validateResult = { valid: false, reason: `Validator error: ${reason}` };
         }
+        const maxValidateRetries = options.validateRetries ?? 2;
+        const validateAttempt = validateRetries + 1;
+        const validateMaxAttempts = maxValidateRetries + 1;
+        let validateFeedback;
+        if (!validateResult.valid && validateRetries < maxValidateRetries) {
+          validateFeedback = `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`;
+        }
         this.emitTrace({
           type: "validate",
           agent: agent2._name,
           data: {
             valid: validateResult.valid,
-            ...validateResult.reason ? { reason: validateResult.reason } : {}
+            ...validateResult.reason ? { reason: validateResult.reason } : {},
+            attempt: validateAttempt,
+            maxAttempts: validateMaxAttempts,
+            ...validateFeedback ? { feedbackMessage: validateFeedback } : {}
           }
         });
         this.spanManager?.addEventToActiveSpan("axl.validate.check", {
           "axl.validate.valid": validateResult.valid,
+          "axl.validate.attempt": validateAttempt,
+          "axl.validate.maxAttempts": validateMaxAttempts,
           ...validateResult.reason ? { "axl.validate.reason": validateResult.reason } : {}
         });
         if (!validateResult.valid) {
-          const maxValidateRetries = options.validateRetries ?? 2;
-          if (validateRetries < maxValidateRetries) {
+          if (validateFeedback) {
             validateRetries++;
-            currentMessages.push({
-              role: "assistant",
+            appendRetryMessages(
+              currentMessages,
               content,
-              ...response.providerMetadata ? { providerMetadata: response.providerMetadata } : {}
-            });
-            currentMessages.push({
-              role: "system",
-              content: `Your response parsed correctly but failed validation: ${validateResult.reason ?? "Validation failed"}. Previous attempts are visible above. Please fix and try again.`
-            });
+              validateFeedback,
+              response.providerMetadata
+            );
+            pendingRetryReason = "validate";
             continue;
           }
           throw new ValidationError(
@@ -3371,6 +3503,17 @@ ${summaryResponse.content}`
   async verify(fn, schema, options) {
     const maxRetries = options?.retries ?? 3;
     let lastRetry = void 0;
+    const emitVerifyOutcome = (passed, attempts, lastError) => {
+      this.emitTrace({
+        type: "verify",
+        agent: void 0,
+        data: {
+          passed,
+          attempts,
+          ...lastError ? { lastError } : {}
+        }
+      });
+    };
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       let rawOutput;
       try {
@@ -3389,12 +3532,14 @@ ${summaryResponse.content}`
             const errorMsg = validateResult.reason ?? "Validation failed";
             lastRetry = { error: errorMsg, output: rawOutput, parsed };
             if (attempt === maxRetries) {
+              emitVerifyOutcome(false, attempt + 1, errorMsg);
               if (options?.fallback !== void 0) return options.fallback;
               throw new ValidationError(parsed, errorMsg, maxRetries);
             }
             continue;
           }
         }
+        emitVerifyOutcome(true, attempt + 1);
         return parsed;
       } catch (err) {
         if (err instanceof ValidationError) {
@@ -3404,6 +3549,7 @@ ${summaryResponse.content}`
             parsed: err.lastOutput
           };
           if (attempt === maxRetries) {
+            emitVerifyOutcome(false, attempt + 1, err.reason);
             if (options?.fallback !== void 0) return options.fallback;
             throw err;
           }
@@ -3412,6 +3558,7 @@ ${summaryResponse.content}`
         if (err instanceof VerifyError) {
           lastRetry = { error: err.message, output: rawOutput ?? err.lastOutput };
           if (attempt === maxRetries) {
+            emitVerifyOutcome(false, attempt + 1, err.message);
             if (options?.fallback !== void 0) return options.fallback;
             throw err;
           }
@@ -3420,12 +3567,14 @@ ${summaryResponse.content}`
         const errorMsg = err instanceof ZodError ? err.message : err instanceof Error ? err.message : String(err);
         lastRetry = { error: errorMsg, output: rawOutput };
         if (attempt === maxRetries) {
+          emitVerifyOutcome(false, attempt + 1, errorMsg);
           if (options?.fallback !== void 0) return options.fallback;
           const zodErr = err instanceof ZodError ? err : new ZodError([{ code: "custom", path: [], message: errorMsg }]);
           throw new VerifyError(rawOutput, zodErr, maxRetries);
         }
       }
     }
+    emitVerifyOutcome(false, maxRetries + 1, lastRetry?.error ?? "Verify failed");
     if (options?.fallback !== void 0) return options.fallback;
     throw new VerifyError(
       lastRetry?.output,
@@ -3731,6 +3880,76 @@ ${summaryResponse.content}`
     }
     return decision;
   }
+  /**
+   * Compose an `AbortSignal` for a memory operation's underlying embedder
+   * fetch. Combines the parent context signal (user cancellation,
+   * `runtime.execute({ signal })`) with the budget hard_stop abort so
+   * that either cause correctly aborts an in-flight embed call.
+   *
+   * Returns `undefined` if there's nothing to cancel on — the embedder
+   * runs without a signal in that case, matching its prior behavior.
+   *
+   * @internal
+   */
+  _composeMemorySignal() {
+    const budgetSignal = this.budgetContext?.abortController?.signal;
+    if (this.signal && budgetSignal) return AbortSignal.any([this.signal, budgetSignal]);
+    return this.signal ?? budgetSignal;
+  }
+  /**
+   * Accumulate a cost amount into the active `budgetContext` and trip the
+   * `exceeded` flag if we've crossed the limit. On `hard_stop` policy,
+   * also fires the abort controller so in-flight operations cancel.
+   *
+   * Called from every code path that spends money: the `agent_call` loop,
+   * semantic memory operations (`ctx.remember({embed:true})`, `ctx.recall({query})`),
+   * and any future cost-emitting primitive. Centralizing the logic here
+   * means `ctx.budget({ limit, policy })` accurately enforces the limit
+   * across ALL cost sources — not just agent calls.
+   *
+   * @internal
+   */
+  _accumulateBudgetCost(amount) {
+    if (!this.budgetContext) return;
+    if (!Number.isFinite(amount) || amount <= 0) return;
+    this.budgetContext.totalCost += amount;
+    if (this.budgetContext.totalCost >= this.budgetContext.limit) {
+      this.budgetContext.exceeded = true;
+      if (this.budgetContext.policy === "hard_stop" && this.budgetContext.abortController) {
+        this.budgetContext.abortController.abort();
+      }
+    }
+  }
+  // ── workflow lifecycle trace emission ──────────────────────────────────
+  //
+  // These are called by the runtime at execution boundaries. They emit
+  // first-class `workflow_start` / `workflow_end` trace events instead of
+  // the previous `ctx.log('workflow_start', ...)` indirection — so consumers
+  // that narrow via `event.type === 'workflow_start'` actually see them.
+  // Internal: the runtime is the only caller, user workflows never call these.
+  /** @internal */
+  _emitWorkflowStart(input) {
+    this.emitTrace({
+      type: "workflow_start",
+      workflow: this.workflowName,
+      data: { input }
+    });
+  }
+  /** @internal */
+  _emitWorkflowEnd(info) {
+    this.emitTrace({
+      type: "workflow_end",
+      workflow: this.workflowName,
+      duration: info.duration,
+      data: {
+        status: info.status,
+        duration: info.duration,
+        ...info.result !== void 0 ? { result: info.result } : {},
+        ...info.error !== void 0 ? { error: info.error } : {},
+        ...info.aborted ? { aborted: true } : {}
+      }
+    });
+  }
   // ── ctx.log() ─────────────────────────────────────────────────────────
   log(event, data) {
     this.emitTrace({
@@ -3766,8 +3985,59 @@ ${summaryResponse.content}`
     if (!this.stateStore) {
       throw new Error("A state store is required for memory operations.");
     }
+    if (this.budgetContext?.exceeded) {
+      const { limit, totalCost: spent, policy } = this.budgetContext;
+      if (policy !== "warn") {
+        throw new BudgetExceededError(limit, spent, policy);
+      }
+    }
     const sessionId = this.metadata?.sessionId;
-    await this.memoryManager.remember(key, value, this.stateStore, sessionId, options);
+    const scope = options?.scope ?? (sessionId ? "session" : "global");
+    try {
+      const memorySignal = this._composeMemorySignal();
+      const { usage } = await this.memoryManager.remember(
+        key,
+        value,
+        this.stateStore,
+        sessionId,
+        options,
+        memorySignal
+      );
+      if (usage?.cost != null) {
+        this._accumulateBudgetCost(usage.cost);
+      }
+      this.emitTrace({
+        type: "log",
+        ...usage?.cost != null ? { cost: usage.cost } : {},
+        ...usage?.tokens != null ? { tokens: { input: usage.tokens } } : {},
+        data: {
+          event: "memory_remember",
+          key,
+          scope,
+          embed: options?.embed === true,
+          ...usage ? { usage } : {}
+        }
+      });
+    } catch (err) {
+      const partialUsage = err.axlEmbedUsage;
+      if (partialUsage?.cost != null) {
+        this._accumulateBudgetCost(partialUsage.cost);
+      }
+      this.emitTrace({
+        type: "log",
+        ...partialUsage?.cost != null ? { cost: partialUsage.cost } : {},
+        ...partialUsage?.tokens != null ? { tokens: { input: partialUsage.tokens } } : {},
+        data: {
+          event: "memory_remember",
+          key,
+          scope,
+          embed: options?.embed === true,
+          ...partialUsage ? { usage: partialUsage } : {},
+          error: err instanceof Error ? err.message : String(err)
+        }
+      });
+      throw err;
+    }
   }
   /**
    * Recall a value from memory by key, or perform semantic search if query option is provided.
@@ -3781,8 +4051,64 @@ ${summaryResponse.content}`
     if (!this.stateStore) {
       throw new Error("A state store is required for memory operations.");
     }
+    if (this.budgetContext?.exceeded) {
+      const { limit, totalCost: spent, policy } = this.budgetContext;
+      if (policy !== "warn") {
+        throw new BudgetExceededError(limit, spent, policy);
+      }
+    }
     const sessionId = this.metadata?.sessionId;
-    return this.memoryManager.recall(key, this.stateStore, sessionId, options);
+    const scope = options?.scope ?? (sessionId ? "session" : "global");
+    const semantic = options?.query !== void 0;
+    try {
+      const memorySignal = this._composeMemorySignal();
+      const { data, usage } = await this.memoryManager.recall(
+        key,
+        this.stateStore,
+        sessionId,
+        options,
+        memorySignal
+      );
+      let hit;
+      let resultCount;
+      if (semantic) {
+        resultCount = Array.isArray(data) ? data.length : 0;
+        hit = resultCount > 0;
+      } else {
+        hit = data !== null && data !== void 0;
+      }
+      if (usage?.cost != null) {
+        this._accumulateBudgetCost(usage.cost);
+      }
+      this.emitTrace({
+        type: "log",
+        ...usage?.cost != null ? { cost: usage.cost } : {},
+        ...usage?.tokens != null ? { tokens: { input: usage.tokens } } : {},
+        data: {
+          event: "memory_recall",
+          key,
+          scope,
+          semantic,
+          hit,
+          ...resultCount !== void 0 ? { resultCount } : {},
+          ...usage ? { usage } : {}
+        }
+      });
+      return data;
+    } catch (err) {
+      this.emitTrace({
+        type: "log",
+        data: {
+          event: "memory_recall",
+          key,
+          scope,
+          semantic,
+          hit: false,
+          error: err instanceof Error ? err.message : String(err)
+        }
+      });
+      throw err;
+    }
   }
   /** Delete a memory entry by key. */
   async forget(key, options) {
@@ -3795,7 +4121,25 @@ ${summaryResponse.content}`
       throw new Error("A state store is required for memory operations.");
     }
     const sessionId = this.metadata?.sessionId;
-    await this.memoryManager.forget(key, this.stateStore, sessionId, options);
+    const scope = options?.scope ?? (sessionId ? "session" : "global");
+    try {
+      await this.memoryManager.forget(key, this.stateStore, sessionId, options);
+      this.emitTrace({
+        type: "log",
+        data: { event: "memory_forget", key, scope }
+      });
+    } catch (err) {
+      this.emitTrace({
+        type: "log",
+        data: {
+          event: "memory_forget",
+          key,
+          scope,
+          error: err instanceof Error ? err.message : String(err)
+        }
+      });
+      throw err;
+    }
   }
   // ── ctx.delegate() ──────────────────────────────────────────────────
   /**
@@ -3823,6 +4167,15 @@ ${summaryResponse.content}`
       names.add(a._name);
     }
     if (agents.length === 1) {
+      this.emitTrace({
+        type: "delegate",
+        agent: agents[0]._name,
+        data: {
+          candidates: [agents[0]._name],
+          selected: agents[0]._name,
+          reason: "single_candidate"
+        }
+      });
       return this.ask(agents[0], prompt, {
         schema: options?.schema,
         retries: options?.retries,
@@ -3863,7 +4216,8 @@ ${summaryResponse.content}`
       agent: "_delegate_router",
       data: {
         candidates: agents.map((a) => a._name),
-        routerModel: routerModelUri
+        routerModel: routerModelUri,
+        reason: "routed"
       }
     });
     return this.ask(routerAgent, prompt, {
@@ -3875,19 +4229,117 @@ ${summaryResponse.content}`
     });
   }
   // ── Private ───────────────────────────────────────────────────────────
+  /**
+   * Internal emitter input — intentionally loose so call sites don't need to
+   * build a perfectly-narrowed discriminated-union member. The resulting
+   * `TraceEvent` (exported type) remains strict, and TypeScript narrows it at
+   * consumer sites via the `type` discriminator.
+   */
   emitTrace(partial) {
     let data = partial.data;
-    if (this.config.trace?.redact && partial.type === "agent_call" && data) {
-      data = { ...data, prompt: "[redacted]", response: "[redacted]" };
+    if (this.config.trace?.redact && data) {
+      if (partial.type === "agent_call") {
+        const d = data;
+        const redacted = {
+          ...d,
+          prompt: "[redacted]",
+          response: "[redacted]"
+        };
+        if (d.system !== void 0) redacted.system = "[redacted]";
+        if (d.thinking !== void 0) redacted.thinking = "[redacted]";
+        if (Array.isArray(d.messages)) {
+          redacted.messages = [
+            { role: "system", content: `[${d.messages.length} messages redacted]` }
+          ];
+        }
+        data = redacted;
+      } else if (partial.type === "guardrail" || partial.type === "schema_check" || partial.type === "validate") {
+        const d = data;
+        const needsRedact = d.feedbackMessage !== void 0 || d.reason !== void 0;
+        if (needsRedact) {
+          data = {
+            ...d,
+            ...d.reason !== void 0 ? { reason: "[redacted]" } : {},
+            ...d.feedbackMessage !== void 0 ? { feedbackMessage: "[redacted]" } : {}
+          };
+        }
+      } else if (partial.type === "tool_call") {
+        const d = data;
+        data = {
+          ...d,
+          args: "[redacted]",
+          result: "[redacted]"
+        };
+      } else if (partial.type === "tool_approval") {
+        const d = data;
+        data = {
+          ...d,
+          args: "[redacted]",
+          ...d.reason !== void 0 ? { reason: "[redacted]" } : {}
+        };
+      } else if (partial.type === "handoff") {
+        const d = data;
+        if (d.message !== void 0) {
+          data = { ...d, message: "[redacted]" };
+        }
+      } else if (partial.type === "workflow_start") {
+        const d = data;
+        if (d.input !== void 0) {
+          data = { ...d, input: "[redacted]" };
+        }
+      } else if (partial.type === "workflow_end") {
+        const d = data;
+        const redacted = { ...d };
+        if (d.result !== void 0) redacted.result = "[redacted]";
+        if (d.error !== void 0) redacted.error = "[redacted]";
+        data = redacted;
+      } else if (partial.type === "log") {
+        const d = data;
+        const redacted = {};
+        for (const [k, v] of Object.entries(d)) {
+          if (k === "event" || typeof v === "number" || typeof v === "boolean") {
+            redacted[k] = v;
+          } else if (typeof v === "string") {
+            redacted[k] = "[redacted]";
+          } else if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            const inner = v;
+            const innerRedacted = {};
+            for (const [ik, iv] of Object.entries(inner)) {
+              if (typeof iv === "number" || typeof iv === "boolean") {
+                innerRedacted[ik] = iv;
+              } else if (typeof iv === "string") {
+                innerRedacted[ik] = "[redacted]";
+              } else {
+                innerRedacted[ik] = "[redacted]";
+              }
+            }
+            redacted[k] = innerRedacted;
+          } else {
+            redacted[k] = "[redacted]";
+          }
+        }
+        data = redacted;
+      }
     }
     const event = {
       executionId: this.executionId,
       step: this.stepCounter++,
       timestamp: Date.now(),
+      ...this.workflowName ? { workflow: this.workflowName } : {},
+      ...this.parentToolCallId ? { parentToolCallId: this.parentToolCallId } : {},
       ...partial,
       data
     };
-    this.onTrace?.(event);
+    if (this.onTrace) {
+      try {
+        this.onTrace(event);
+      } catch (err) {
+        console.error(
+          "[axl] onTrace handler threw; trace event dropped:",
+          err instanceof Error ? err.message : String(err)
+        );
+      }
+    }
   }
 };
 
@@ -4082,6 +4534,9 @@ var MemoryStore = class {
     const result = limit ? sorted.slice(0, limit) : sorted;
     return result.map((e) => structuredClone(e));
   }
+  async deleteEvalResult(id) {
+    return this.evalHistory.delete(id);
+  }
   // ── Sessions (Studio introspection) ─────────────────────────────────
   async listSessions() {
     return [...this.sessions.keys()];
@@ -4390,6 +4845,10 @@ var SQLiteStore = class {
       data: safeJsonParse(r.data)
     }));
   }
+  async deleteEvalResult(id) {
+    const result = this.db.prepare("DELETE FROM eval_history WHERE id = ?").run(id);
+    return result.changes > 0;
+  }
   // ── Sessions (Studio introspection) ────────────────────────────────────
   async listSessions() {
     const rows = this.db.prepare("SELECT session_id FROM sessions").all();
@@ -5122,6 +5581,18 @@ var McpManager = class {
 };
 
 // src/memory/manager.ts
+function assertEmbedResult(result) {
+  if (Array.isArray(result)) {
+    throw new Error(
+      "Embedder.embed() returned a bare number[][] (legacy shape). As of @axlsdk/axl 0.15, Embedder.embed() must return { vectors: number[][]; usage?: { tokens?, cost?, model? } }. Wrap your existing return value: `return { vectors: await old() }`."
+    );
+  }
+  if (!result || typeof result !== "object" || !Array.isArray(result.vectors)) {
+    throw new Error(
+      `Embedder.embed() must return { vectors: number[][]; usage?: EmbedUsage }. Got ${result === null ? "null" : typeof result}.`
+    );
+  }
+}
 var MemoryManager = class {
   vectorStore;
   embedder;
@@ -5136,8 +5607,11 @@ var MemoryManager = class {
    * Store a key-value pair in memory.
    * If a vector store and embedder are configured and embed is true,
    * also embeds the value for semantic search.
+   *
+   * Returns `{ usage }` when embedding happened, carrying the embedder's
+   * cost/token reporting out to the caller for cost attribution.
    */
-  async remember(key, value, stateStore, sessionId, options) {
+  async remember(key, value, stateStore, sessionId, options, signal) {
     const scope = options?.scope ?? "session";
     if (scope === "session" && !sessionId) {
       throw new Error(
@@ -5156,23 +5630,44 @@ var MemoryManager = class {
     }
     if (options?.embed === true && this.vectorStore && this.embedder) {
       const text = typeof value === "string" ? value : JSON.stringify(value);
-      const [embedding] = await this.embedder.embed([text]);
-      await this.vectorStore.upsert([
-        {
-          id: `${storeScope}:${key}`,
-          content: text,
-          embedding,
-          metadata: { key, scope, ...options?.metadata }
+      const raw = await this.embedder.embed([text], signal);
+      assertEmbedResult(raw);
+      const { vectors, usage } = raw;
+      try {
+        await this.vectorStore.upsert([
+          {
+            id: `${storeScope}:${key}`,
+            content: text,
+            embedding: vectors[0],
+            metadata: { key, scope, ...options?.metadata }
+          }
+        ]);
+      } catch (err) {
+        if (usage && typeof err === "object" && err !== null) {
+          Object.defineProperty(err, "axlEmbedUsage", {
+            value: usage,
+            enumerable: false,
+            writable: true,
+            configurable: true
+          });
         }
-      ]);
+        throw err;
+      }
+      return usage ? { usage } : {};
     }
+    return {};
   }
   /**
    * Recall a value from memory by key, or perform semantic search if query is provided.
+   *
+   * Always returns `{ data }`; semantic recalls additionally include
+   * `usage` from the embedder (when the embedder reported it).
    */
-  async recall(key, stateStore, sessionId, options) {
+  async recall(key, stateStore, sessionId, options, signal) {
     if (options?.query && this.vectorStore && this.embedder) {
-      const [embedding] = await this.embedder.embed([options.query]);
+      const raw = await this.embedder.embed([options.query], signal);
+      assertEmbedResult(raw);
+      const { vectors, usage } = raw;
       const topK = options?.topK ?? 5;
       const searchScope = options?.scope ?? "session";
       if (searchScope === "session" && !sessionId) {
@@ -5180,13 +5675,14 @@ var MemoryManager = class {
           'sessionId is required for session-scoped memory. Use { scope: "global" } or provide a sessionId in metadata.'
         );
       }
-      const rawResults = await this.vectorStore.search(embedding, topK * 3);
+      const rawResults = await this.vectorStore.search(vectors[0], topK * 3);
       const filtered = rawResults.filter((r) => {
         if (r.id.startsWith("global:")) return true;
         if (searchScope === "session") return r.id.startsWith(`session:${sessionId}:`);
         return true;
       });
-      return filtered.slice(0, topK);
+      const data = filtered.slice(0, topK);
+      return usage ? { data, usage } : { data };
     }
     const scope = options?.scope ?? "session";
     if (scope === "session" && !sessionId) {
@@ -5196,10 +5692,10 @@ var MemoryManager = class {
     }
     const storeScope = scope === "session" ? `session:${sessionId}` : "global";
     if (stateStore.getMemory) {
-      return stateStore.getMemory(storeScope, key);
+      return { data: await stateStore.getMemory(storeScope, key) };
     }
     const storeKey = `memory:${storeScope}:${key}`;
-    return stateStore.getSessionMeta(storeKey, "value");
+    return { data: await stateStore.getSessionMeta(storeKey, "value") };
   }
   /** Delete a memory entry. If a vector store is configured, also removes the embedding. */
   async forget(key, stateStore, sessionId, options) {
@@ -5299,6 +5795,22 @@ var AxlRuntime = class extends EventEmitter2 {
       });
     }
   }
+  /**
+   * Whether `config.trace.redact` is enabled on this runtime. A narrow
+   * boolean getter is preferred over exposing the full config because:
+   * (a) `Readonly<AxlConfig>` is shallow so the config would be mutable
+   * at runtime through sub-objects, subverting any compliance guarantee;
+   * (b) observability consumers like Studio only need the boolean, not
+   * the whole config tree; (c) if future observability config needs to
+   * expand, each new flag gets its own narrow getter.
+   *
+   * Studio's server-side redaction helpers (executions, memory, sessions,
+   * evals, decisions, tools, playground, workflows) all route through
+   * this accessor to decide whether to scrub response payloads.
+   */
+  isRedactEnabled() {
+    return this.config.trace?.redact === true;
+  }
   /**
    * Initialize MCP servers configured in the config.
    * Call this before executing workflows that use MCP tools.
@@ -5448,10 +5960,19 @@ var AxlRuntime = class extends EventEmitter2 {
           metadata: result2.metadata ?? metadata
         };
       };
-      result = await runEvalFn(entry.config, wrappedExecuteFn, this);
+      result = await runEvalFn(entry.config, wrappedExecuteFn, this, {
+        onProgress: options?.onProgress,
+        signal: options?.signal,
+        captureTraces: options?.captureTraces
+      });
     } else {
       result = await this.eval(
-        entry.config
+        entry.config,
+        {
+          onProgress: options?.onProgress,
+          signal: options?.signal,
+          captureTraces: options?.captureTraces
+        }
       );
     }
     const resultObj = result;
@@ -5589,6 +6110,7 @@ var AxlRuntime = class extends EventEmitter2 {
         }
       },
       pendingDecisions: this.pendingDecisionResolvers,
+      awaitHumanHandler: options?.awaitHumanHandler,
       stateStore: this.stateStore,
       workflowName: name,
       mcpManager: this.mcpManager,
@@ -5602,7 +6124,6 @@ var AxlRuntime = class extends EventEmitter2 {
         policy: "finish_and_stop"
       }
     });
-    ctx.log("workflow_start", { workflow: name, executionId });
     return this.spanManager.withSpanAsync(
       "axl.workflow.execute",
       {
@@ -5612,17 +6133,17 @@ var AxlRuntime = class extends EventEmitter2 {
       },
       async (span) => {
         try {
+          ctx._emitWorkflowStart(validated);
           const result = await workflow2.handler(ctx);
           const output = workflow2.outputSchema ? workflow2.outputSchema.parse(result) : result;
           execInfo.status = "completed";
           execInfo.completedAt = Date.now();
           execInfo.duration = execInfo.completedAt - execInfo.startedAt;
           execInfo.result = output;
-          ctx.log("workflow_end", {
-            workflow: name,
+          ctx._emitWorkflowEnd({
             status: "completed",
             duration: execInfo.duration,
-            cost: execInfo.totalCost
+            result: output
           });
           if (this.stateStore.deleteCheckpoints) {
             await this.stateStore.deleteCheckpoints(executionId);
@@ -5632,11 +6153,17 @@ var AxlRuntime = class extends EventEmitter2 {
           this.persistExecution(execInfo);
           return output;
         } catch (err) {
+          const aborted = typeof err === "object" && err !== null && err.name === "AbortError";
           execInfo.status = "failed";
           execInfo.completedAt = Date.now();
           execInfo.duration = execInfo.completedAt - execInfo.startedAt;
           execInfo.error = err instanceof Error ? err.message : String(err);
-          ctx.log("workflow_end", { workflow: name, status: "failed", error: execInfo.error });
+          ctx._emitWorkflowEnd({
+            status: "failed",
+            duration: execInfo.duration,
+            error: execInfo.error,
+            ...aborted ? { aborted: true } : {}
+          });
           this.persistExecution(execInfo);
           throw err;
         } finally {
@@ -5701,24 +6228,16 @@ var AxlRuntime = class extends EventEmitter2 {
                 duration: data?.duration ?? void 0
               });
             }
-          } else if (event.type === "tool_denied") {
+          } else if (event.type === "tool_approval") {
             const data = event.data;
-            if (data?.denied === false) {
-              axlStream._push({
-                type: "tool_approval",
-                name: event.tool ?? "",
-                args: data?.args,
-                approved: true
-              });
-            } else {
-              axlStream._push({
-                type: "tool_approval",
-                name: event.tool ?? "",
-                args: data?.args,
-                approved: false,
-                reason: data?.reason ?? void 0
-              });
-            }
+            axlStream._push({
+              type: "tool_approval",
+              name: event.tool ?? "",
+              args: data?.args,
+              approved: data?.approved === true,
+              ...data?.reason ? { reason: data.reason } : {}
+            });
+          } else if (event.type === "tool_denied") {
           } else if (event.type === "agent_call") {
             axlStream._push({
               type: "agent_end",
@@ -5751,6 +6270,7 @@ var AxlRuntime = class extends EventEmitter2 {
           axlStream._push({ type: "agent_start", agent: info.agent, model: info.model });
         },
         pendingDecisions: this.pendingDecisionResolvers,
+        awaitHumanHandler: options?.awaitHumanHandler,
         stateStore: this.stateStore,
         workflowName: name,
         mcpManager: this.mcpManager,
@@ -5774,17 +6294,17 @@ var AxlRuntime = class extends EventEmitter2 {
         },
         async (span) => {
           try {
+            wfCtx._emitWorkflowStart(validated);
             const rawResult = await workflow2.handler(wfCtx);
             const result = workflow2.outputSchema ? workflow2.outputSchema.parse(rawResult) : rawResult;
             execInfo.status = "completed";
             execInfo.completedAt = Date.now();
             execInfo.duration = execInfo.completedAt - execInfo.startedAt;
             execInfo.result = result;
-            wfCtx.log("workflow_end", {
-              workflow: name,
+            wfCtx._emitWorkflowEnd({
               status: "completed",
               duration: execInfo.duration,
-              cost: execInfo.totalCost
+              result
             });
             if (this.stateStore.deleteCheckpoints) {
               await this.stateStore.deleteCheckpoints(executionId);
@@ -5801,14 +6321,16 @@ var AxlRuntime = class extends EventEmitter2 {
     };
     run().then((result) => axlStream._done(result)).catch((err) => {
       if (execInfo) {
+        const aborted = typeof err === "object" && err !== null && err.name === "AbortError";
         execInfo.status = "failed";
         execInfo.completedAt = Date.now();
         execInfo.duration = execInfo.completedAt - execInfo.startedAt;
         execInfo.error = err instanceof Error ? err.message : String(err);
-        ctx?.log("workflow_end", {
-          workflow: name,
+        ctx?._emitWorkflowEnd({
           status: "failed",
-          error: execInfo.error
+          duration: execInfo.duration,
+          error: execInfo.error,
+          ...aborted ? { aborted: true } : {}
         });
         this.persistExecution(execInfo);
       }
@@ -5873,6 +6395,25 @@ var AxlRuntime = class extends EventEmitter2 {
     if (this.stateStore.saveEvalResult) {
       await this.stateStore.saveEvalResult(entry);
     }
+    this.emit("eval_result", entry);
+  }
+  /**
+   * Delete an eval history entry by id. Removes from in-memory cache and
+   * the configured StateStore. Returns true if an entry was actually removed.
+   *
+   * Ensures lazy-loaded history is loaded first so the in-memory cache and
+   * the store can't drift apart on the deletion path.
+   */
+  async deleteEvalResult(id) {
+    await this.getEvalHistory();
+    const beforeLength = this.evalHistory.length;
+    this.evalHistory = this.evalHistory.filter((e) => e.id !== id);
+    const removedFromMemory = this.evalHistory.length < beforeLength;
+    let removedFromStore = false;
+    if (this.stateStore.deleteEvalResult) {
+      removedFromStore = await this.stateStore.deleteEvalResult(id);
+    }
+    return removedFromMemory || removedFromStore;
   }
   /** Get eval result history (most recent first). */
   async getEvalHistory() {
@@ -5986,7 +6527,7 @@ var AxlRuntime = class extends EventEmitter2 {
    *
    * @see Spec Section 13.5
    */
-  async eval(config) {
+  async eval(config, options) {
     let runEvalFn;
     try {
       ({ runEval: runEvalFn } = await import("@axlsdk/eval"));
@@ -6001,7 +6542,7 @@ var AxlRuntime = class extends EventEmitter2 {
       });
       return { output: result, cost, metadata };
     };
-    return runEvalFn(config, executeWorkflow, this);
+    return runEvalFn(config, executeWorkflow, this, options);
   }
   /**
    * Compare two evaluation results to detect regressions and improvements.
@@ -6039,9 +6580,31 @@ var AxlRuntime = class extends EventEmitter2 {
    * Returns cost (same as `trackCost`) plus metadata extracted from trace events:
    * models (unique URIs), tokens (input/output/reasoning sums), and agent call count.
    *
+   * ## Cost vs tokens semantics
+   *
+   * - `cost` is the full aggregate across EVERY event with a top-level
+   *   `event.cost` set: agent calls, tool calls, semantic memory ops, etc.
+   *   This is the number to reconcile against your provider bill.
+   *
+   * - `metadata.tokens` is narrowly scoped to **agent** prompt/completion/
+   *   reasoning tokens. Embedder tokens from semantic `ctx.remember({embed:true})`
+   *   / `ctx.recall({query})` are deliberately NOT summed here — they're a
+   *   different category (input-only, different pricing, different model).
+   *   Conflating them would make "prompt tokens" misleading in the UI. If you
+   *   need embedder token counts, subscribe to `runtime.on('trace', ...)` and
+   *   read `data.usage.tokens` on `memory_remember` / `memory_recall` events.
+   *
+   * Pass `{ captureTraces: true }` to also collect the raw `TraceEvent[]` observed
+   * during `fn()`. This is opt-in because it keeps every event in memory for the
+   * duration of the call — useful for eval per-item capture, debugging, and test
+   * assertions, but overhead grows with trace volume. When enabled, verbose-mode
+   * `agent_call.data.messages` snapshots are omitted from captured events (still
+   * broadcast via onTrace) to keep memory bounded — callers who need the full
+   * verbose snapshot should subscribe to `runtime.on('trace', ...)` directly.
+   *
    * Works with both `createContext()` and `execute()` calls inside `fn`.
    */
-  async trackExecution(fn) {
+  async trackExecution(fn, options) {
     const parentScope = costScopeStorage.getStore();
     const scope = {
       totalCost: 0,
@@ -6049,8 +6612,10 @@ var AxlRuntime = class extends EventEmitter2 {
       parent: parentScope
     };
     const modelCalls = /* @__PURE__ */ new Map();
+    const workflowCalls = /* @__PURE__ */ new Map();
     const tokens = { input: 0, output: 0, reasoning: 0 };
     let agentCalls = 0;
+    const capturedTraces = options?.captureTraces ? [] : void 0;
     const listener = (event) => {
       if (!scope.trackedIds.has(event.executionId)) return;
       if (event.cost) scope.totalCost += event.cost;
@@ -6063,6 +6628,23 @@ var AxlRuntime = class extends EventEmitter2 {
           tokens.reasoning += event.tokens.reasoning ?? 0;
         }
       }
+      if (event.type === "workflow_start" && event.workflow) {
+        workflowCalls.set(event.workflow, (workflowCalls.get(event.workflow) ?? 0) + 1);
+      }
+      if (capturedTraces) {
+        if (event.type === "agent_call" && event.data) {
+          const d = event.data;
+          if ("messages" in d) {
+            const rest = {};
+            for (const k of Object.keys(d)) {
+              if (k !== "messages") rest[k] = d[k];
+            }
+            capturedTraces.push({ ...event, data: rest });
+            return;
+          }
+        }
+        capturedTraces.push(event);
+      }
     };
     this.setMaxListeners(this.getMaxListeners() + 1);
     this.on("trace", listener);
@@ -6071,13 +6653,26 @@ var AxlRuntime = class extends EventEmitter2 {
       return {
         result,
         cost: scope.totalCost,
+        ...capturedTraces ? { traces: capturedTraces } : {},
         metadata: {
           models: [...modelCalls.keys()],
           modelCallCounts: modelCalls.size > 0 ? Object.fromEntries(modelCalls) : void 0,
           tokens,
-          agentCalls
+          agentCalls,
+          workflows: [...workflowCalls.keys()],
+          workflowCallCounts: workflowCalls.size > 0 ? Object.fromEntries(workflowCalls) : void 0
         }
       };
+    } catch (err) {
+      if (capturedTraces && typeof err === "object" && err !== null) {
+        Object.defineProperty(err, "axlCapturedTraces", {
+          value: capturedTraces,
+          enumerable: false,
+          writable: true,
+          configurable: true
+        });
+      }
+      throw err;
     } finally {
       this.off("trace", listener);
       this.setMaxListeners(this.getMaxListeners() - 1);
@@ -6132,11 +6727,13 @@ var AxlRuntime = class extends EventEmitter2 {
     const level = this.config.trace?.level ?? "steps";
     const workflowPrefix = event.workflow ? `workflow:${event.workflow} | ` : "";
     const parts = [`[axl] execution:${event.executionId}`];
-    const data = event.data;
     if (event.type === "workflow_start") {
-      parts.push(`${workflowPrefix}workflow:${data?.workflow ?? "unknown"} | started`);
+      parts.push(`${workflowPrefix}started`);
     } else if (event.type === "workflow_end") {
-      parts.push(`${workflowPrefix}workflow:${data?.workflow ?? "unknown"} | completed`);
+      const d = event.data;
+      const status = d?.aborted ? "aborted" : d?.status ?? "completed";
+      parts.push(`${workflowPrefix}${status}`);
+      if (event.duration != null) parts.push(`${(event.duration / 1e3).toFixed(1)}s`);
     } else if (event.type === "agent_call") {
       parts.push(`${workflowPrefix}step:${event.step} agent_call`);
       if (event.agent) parts.push(`agent:${event.agent}`);
@@ -6353,6 +6950,11 @@ var RedisStore = class _RedisStore {
     entries.sort((a, b) => b.timestamp - a.timestamp);
     return limit ? entries.slice(0, limit) : entries;
   }
+  async deleteEvalResult(id) {
+    await this.client.sRem(this.evalHistorySetKey(), id);
+    const deleted = await this.client.del(this.evalHistoryKey(id));
+    return deleted > 0;
+  }
   // ── Sessions (Studio introspection) ────────────────────────────────────
   async listSessions() {
     return this.client.sMembers("axl:session-ids");
@@ -6367,6 +6969,16 @@ var RedisStore = class _RedisStore {
 };
 
 // src/memory/embedder-openai.ts
+var EMBEDDING_PRICE_PER_1M_TOKENS = {
+  "text-embedding-3-small": 0.02,
+  "text-embedding-3-large": 0.13,
+  "text-embedding-ada-002": 0.1
+};
+function computeCost(model, tokens) {
+  const pricePerMillion = EMBEDDING_PRICE_PER_1M_TOKENS[model];
+  if (pricePerMillion == null) return void 0;
+  return tokens / 1e6 * pricePerMillion;
+}
 var OpenAIEmbedder = class {
   apiKey;
   model;
@@ -6381,8 +6993,8 @@ var OpenAIEmbedder = class {
     this.baseUrl = options.baseUrl ?? "https://api.openai.com";
     this.dimensions = options.dimensions ?? 1536;
   }
-  async embed(texts) {
-    const response = await fetch(`${this.baseUrl}/v1/embeddings`, {
+  async embed(texts, signal) {
+    const response = await fetchWithRetry(`${this.baseUrl}/v1/embeddings`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -6392,14 +7004,28 @@ var OpenAIEmbedder = class {
         model: this.model,
         input: texts,
         dimensions: this.dimensions
-      })
+      }),
+      signal
     });
     if (!response.ok) {
       const body = await response.text();
       throw new Error(`OpenAI embeddings API error (${response.status}): ${body}`);
     }
     const json = await response.json();
-    return json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+    const vectors = json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+    const tokens = json.usage?.prompt_tokens ?? json.usage?.total_tokens;
+    const cost = tokens != null ? computeCost(this.model, tokens) : void 0;
+    if (tokens == null && cost == null) {
+      return { vectors };
+    }
+    return {
+      vectors,
+      usage: {
+        ...tokens != null ? { tokens } : {},
+        ...cost != null ? { cost } : {},
+        model: this.model
+      }
+    };
   }
 };