@agent-native/core 0.52.0 → 0.54.0

package/dist/observability/traces.js

@@ -1,4 +1,5 @@
 import { DEFAULT_OBSERVABILITY_CONFIG } from "./types.js";
+import { endAgentSpan, startAgentSpan } from "./tracing.js";
 function spanId() {
     return `span-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -55,6 +56,17 @@ export async function instrumentAgentLoop(opts) {
     const { runAgentLoop, loopOpts, runId, threadId, userId, config } = opts;
     const runStart = Date.now();
     const parentSpanId = spanId();
+    // Optional OpenTelemetry root span for this run. No-ops unless a host has
+    // installed `@opentelemetry/api` and registered a provider. The promise is
+    // resolved before the loop runs so child tool/model spans can parent under
+    // it conceptually (we keep them flat in the same tracer, which is enough
+    // for the dashboards an embedding app would build).
+    const otelRunSpanPromise = startAgentSpan("agent.run", {
+        "agent.run_id": runId,
+        "agent.thread_id": threadId ?? undefined,
+        "agent.user_id": userId ?? undefined,
+        "agent.model": loopOpts.model,
+    });
     const spans = [];
     let toolInvocationCounter = 0;
     // Keyed by counter to handle concurrent calls to the same tool name
@@ -68,16 +80,43 @@ export async function instrumentAgentLoop(opts) {
     let toolCallCount = 0;
     let successfulTools = 0;
     let failedTools = 0;
+    // Track in-flight OTel tool spans so they're all ended even if the loop
+    // throws before a matching `tool_done` arrives.
+    const openOtelToolSpans = new Set();
     const instrumentedSend = (event) => {
         try {
             if (event.type === "tool_start") {
                 const counter = toolInvocationCounter++;
                 const sid = spanId();
-                pendingTools.set(counter, {
+                // Start the OTel tool span synchronously-ish: kick off the async
+                // resolution and stash the span once it lands. Tool spans are short
+                // and the api tracer is synchronous in practice, but we tolerate the
+                // microtask gap by recording the span on the pending entry when ready.
+                const entry = {
                     spanId: sid,
                     startMs: Date.now(),
                     toolName: event.tool,
                     input: event.input,
+                    otelSpan: null,
+                };
+                pendingTools.set(counter, entry);
+                void startAgentSpan("tool.call", {
+                    "tool.name": event.tool,
+                }).then((span) => {
+                    if (!span)
+                        return;
+                    // If `tool_done` already ran for this call, end the span now with the
+                    // status it recorded; otherwise stash it for the done handler.
+                    if (entry.endResult) {
+                        endAgentSpan(span, {
+                            status: entry.endResult.status,
+                            errorMessage: entry.endResult.errorMessage,
+                        });
+                    }
+                    else {
+                        entry.otelSpan = span;
+                        openOtelToolSpans.add(span);
+                    }
                 });
                 const queue = toolNameToCounters.get(event.tool);
                 if (queue)
@@ -102,6 +141,23 @@ export async function instrumentAgentLoop(opts) {
                     failedTools++;
                 else
                     successfulTools++;
+                // Finalize the OTel tool span. If the span promise hasn't resolved yet
+                // we record the result on the entry so its `.then` handler ends it.
+                const otelEndResult = {
+                    status: (isError ? "error" : "success"),
+                    errorMessage: isError ? event.result : null,
+                };
+                if (pending?.otelSpan) {
+                    openOtelToolSpans.delete(pending.otelSpan);
+                    endAgentSpan(pending.otelSpan, {
+                        status: otelEndResult.status,
+                        errorMessage: otelEndResult.errorMessage,
+                        attributes: { "tool.name": event.tool },
+                    });
+                }
+                else if (pending) {
+                    pending.endResult = otelEndResult;
+                }
                 const span = {
                     id: pending?.spanId ?? spanId(),
                     runId,
@@ -218,6 +274,49 @@ export async function instrumentAgentLoop(opts) {
             createdAt: runStart,
         };
         writeTraceData(spans, summary, runId, config).catch(() => { });
+        // OpenTelemetry export (no-op unless a provider is registered). Emit a
+        // self-contained `llm.call` span carrying model + token usage, end any
+        // tool spans still open (loop threw mid-tool), and end the run span. Awaited
+        // so the spans are emitted before the function returns; cheap when no-op.
+        try {
+            if (usage) {
+                endAgentSpan(await startAgentSpan("llm.call", {}), {
+                    status: runStatus,
+                    errorMessage,
+                    attributes: {
+                        "llm.model": usage.model,
+                        "llm.input_tokens": usage.inputTokens,
+                        "llm.output_tokens": usage.outputTokens,
+                        "llm.cache_read_tokens": usage.cacheReadTokens,
+                        "llm.cache_write_tokens": usage.cacheWriteTokens,
+                        "llm.cost_cents_x100": costCentsX100,
+                    },
+                });
+            }
+            for (const toolSpan of openOtelToolSpans) {
+                endAgentSpan(toolSpan, {
+                    status: "error",
+                    errorMessage: "Agent run ended before tool_done.",
+                });
+            }
+            openOtelToolSpans.clear();
+            endAgentSpan(await otelRunSpanPromise, {
+                status: runStatus,
+                errorMessage,
+                attributes: {
+                    "agent.tool_calls": toolCallCount,
+                    "agent.successful_tools": successfulTools,
+                    "agent.failed_tools": failedTools,
+                    "agent.duration_ms": totalDurationMs,
+                    "agent.input_tokens": usage?.inputTokens ?? 0,
+                    "agent.output_tokens": usage?.outputTokens ?? 0,
+                    "agent.cost_cents_x100": costCentsX100,
+                },
+            });
+        }
+        catch {
+            // OTel export must never break the run.
+        }
     }
     return usage;
 }

package/dist/observability/traces.js.map

@@ -1 +1 @@
-{"version":3,"file":"traces.js","sourceRoot":"","sources":["../../src/observability/traces.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentChatEvent } from \"../agent/types.js\";\nimport type { AgentLoopUsage } from \"../agent/production-agent.js\";\nimport type { TraceSpan, TraceSummary, ObservabilityConfig } from \"./types.js\";\nimport { DEFAULT_OBSERVABILITY_CONFIG } from \"./types.js\";\n\nfunction spanId(): string {\n  return `span-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n}\n\n/** Keys whose values are stripped from persisted tool inputs when\n *  `captureToolArgs` is enabled. Matched case-insensitively and tolerant\n *  of `_` / `-` separators. M14 in the MCP/A2A audit: tool calls\n *  routinely receive credentials verbatim (db-exec INSERTs, fetchTool\n *  Authorization headers, ad-hoc bearer tokens) — keeping those values\n *  out of agent_trace_spans.metadata avoids long-term storage of\n *  short-lived secrets. */\nconst SENSITIVE_FIELD_PATTERN =\n  /^(authorization|cookie|api[_-]?key|password|secret|token|access[_-]?token|refresh[_-]?token|bearer)$/i;\n\n/** Recursively walk a structured value and replace sensitive field\n *  values with the literal string \"[REDACTED]\". Pure (returns a copy);\n *  the original input is never mutated. Cycles are tolerated via a\n *  small WeakSet seen-tracker that returns \"[Circular]\" for repeats. */\nexport function redactSensitiveFields(value: unknown): unknown {\n  return redactWalk(value, new WeakSet<object>());\n}\n\nfunction redactWalk(value: unknown, seen: WeakSet<object>): unknown {\n  if (value === null || typeof value !== \"object\") return value;\n  if (seen.has(value as object)) return \"[Circular]\";\n  seen.add(value as object);\n  if (Array.isArray(value)) {\n    return value.map((v) => redactWalk(v, seen));\n  }\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n    if (SENSITIVE_FIELD_PATTERN.test(k)) {\n      out[k] = \"[REDACTED]\";\n    } else {\n      out[k] = redactWalk(v, seen);\n    }\n  }\n  return out;\n}\n\nexport async function getObservabilityConfig(): Promise<ObservabilityConfig> {\n  try {\n    const { getSetting } = await import(\"../settings/store.js\");\n    const stored = await getSetting(\"observability-config\");\n    if (stored) {\n      return {\n        ...DEFAULT_OBSERVABILITY_CONFIG,\n        ...stored,\n      } as ObservabilityConfig;\n    }\n  } catch {}\n  return DEFAULT_OBSERVABILITY_CONFIG;\n}\n\nexport async function instrumentAgentLoop(opts: {\n  runAgentLoop: (loopOpts: {\n    engine: any;\n    model: string;\n    systemPrompt: string;\n    tools: any[];\n    messages: any[];\n    actions: Record<string, any>;\n    send: (event: AgentChatEvent) => void;\n    signal: AbortSignal;\n    providerOptions?: any;\n  }) => Promise<AgentLoopUsage>;\n  loopOpts: {\n    engine: any;\n    model: string;\n    systemPrompt: string;\n    tools: any[];\n    messages: any[];\n    actions: Record<string, any>;\n    send: (event: AgentChatEvent) => void;\n    signal: AbortSignal;\n    providerOptions?: any;\n  };\n  runId: string;\n  threadId: string | null;\n  /** Owner of this run; persisted on every span + summary so dashboard\n   *  reads can filter to a single user. Null for unauthenticated callers\n   *  (background tasks, etc.) — those rows aren't returned by per-user\n   *  reads. */\n  userId: string | null;\n  config: ObservabilityConfig;\n}): Promise<AgentLoopUsage> {\n  const { runAgentLoop, loopOpts, runId, threadId, userId, config } = opts;\n  const runStart = Date.now();\n  const parentSpanId = spanId();\n\n  const spans: TraceSpan[] = [];\n  let toolInvocationCounter = 0;\n  // Keyed by counter to handle concurrent calls to the same tool name\n  const pendingTools = new Map<\n    number,\n    {\n      spanId: string;\n      startMs: number;\n      toolName: string;\n      input: Record<string, string>;\n    }\n  >();\n  // Secondary index: tool name → FIFO queue of pending invocation counters.\n  // tool_start/tool_done events carry only the tool name (no call id), so to\n  // pair starts and dones correctly when the agent runs concurrent calls to the\n  // same tool name (read-only / parallelSafe batches via Promise.all), we keep a\n  // queue per name and match each done to the OLDEST still-pending start.\n  const toolNameToCounters = new Map<string, number[]>();\n\n  let toolCallCount = 0;\n  let successfulTools = 0;\n  let failedTools = 0;\n\n  const instrumentedSend = (event: AgentChatEvent): void => {\n    try {\n      if (event.type === \"tool_start\") {\n        const counter = toolInvocationCounter++;\n        const sid = spanId();\n        pendingTools.set(counter, {\n          spanId: sid,\n          startMs: Date.now(),\n          toolName: event.tool,\n          input: event.input,\n        });\n        const queue = toolNameToCounters.get(event.tool);\n        if (queue) queue.push(counter);\n        else toolNameToCounters.set(event.tool, [counter]);\n      } else if (event.type === \"tool_done\") {\n        const queue = toolNameToCounters.get(event.tool);\n        const counter = queue?.shift();\n        const pending =\n          counter !== undefined ? pendingTools.get(counter) : undefined;\n        if (counter !== undefined) {\n          pendingTools.delete(counter);\n          if (queue && queue.length === 0)\n            toolNameToCounters.delete(event.tool);\n        }\n        toolCallCount++;\n\n        const isError =\n          typeof event.result === \"string\" &&\n          (event.result.startsWith(\"Error\") ||\n            event.result.startsWith(\"Error running \"));\n        if (isError) failedTools++;\n        else successfulTools++;\n\n        const span: TraceSpan = {\n          id: pending?.spanId ?? spanId(),\n          runId,\n          threadId,\n          userId,\n          parentSpanId,\n          spanType: \"tool_call\",\n          name: event.tool,\n          inputTokens: 0,\n          outputTokens: 0,\n          cacheReadTokens: 0,\n          cacheWriteTokens: 0,\n          costCentsX100: 0,\n          durationMs: pending ? Date.now() - pending.startMs : 0,\n          status: isError ? \"error\" : \"success\",\n          errorMessage: isError ? event.result : null,\n          metadata:\n            config.captureToolArgs && pending\n              ? // Strip Authorization/api-key/token-shaped values before\n                // persisting (M14 in the MCP/A2A audit). Tool-runtime\n                // execution still sees the unredacted input — only the\n                // long-lived span row is sanitized.\n                {\n                  input: redactSensitiveFields(pending.input) as Record<\n                    string,\n                    string\n                  >,\n                }\n              : null,\n          createdAt: Date.now(),\n        };\n        spans.push(span);\n      }\n    } catch {}\n\n    loopOpts.send(event);\n  };\n\n  let usage: AgentLoopUsage | undefined;\n  let runStatus: \"success\" | \"error\" = \"success\";\n  let errorMessage: string | null = null;\n  try {\n    usage = await runAgentLoop({ ...loopOpts, send: instrumentedSend });\n  } catch (err: any) {\n    runStatus = \"error\";\n    errorMessage = err?.message ?? String(err);\n    throw err;\n  } finally {\n    const runEnd = Date.now();\n    const totalDurationMs = runEnd - runStart;\n\n    let costCentsX100 = 0;\n    try {\n      const { calculateCost } = await import(\"../usage/store.js\");\n      if (usage) {\n        costCentsX100 = calculateCost(\n          usage.inputTokens,\n          usage.outputTokens,\n          usage.model,\n          usage.cacheReadTokens,\n          usage.cacheWriteTokens,\n        );\n      }\n    } catch {}\n\n    let llmCallCount = 0;\n    if (usage) {\n      llmCallCount = 1;\n      const llmSpan: TraceSpan = {\n        id: spanId(),\n        runId,\n        threadId,\n        userId,\n        parentSpanId,\n        spanType: \"llm_call\",\n        name: usage.model,\n        inputTokens: usage.inputTokens,\n        outputTokens: usage.outputTokens,\n        cacheReadTokens: usage.cacheReadTokens,\n        cacheWriteTokens: usage.cacheWriteTokens,\n        costCentsX100,\n        durationMs: totalDurationMs,\n        status: runStatus,\n        errorMessage,\n        metadata: null,\n        createdAt: runStart,\n      };\n      spans.push(llmSpan);\n    }\n\n    const parentSpan: TraceSpan = {\n      id: parentSpanId,\n      runId,\n      threadId,\n      userId,\n      parentSpanId: null,\n      spanType: \"agent_run\",\n      name: \"agent_run\",\n      inputTokens: usage?.inputTokens ?? 0,\n      outputTokens: usage?.outputTokens ?? 0,\n      cacheReadTokens: usage?.cacheReadTokens ?? 0,\n      cacheWriteTokens: usage?.cacheWriteTokens ?? 0,\n      costCentsX100,\n      durationMs: totalDurationMs,\n      status: runStatus,\n      errorMessage,\n      metadata: null,\n      createdAt: runStart,\n    };\n    spans.push(parentSpan);\n\n    const summary: TraceSummary = {\n      runId,\n      threadId,\n      userId,\n      totalSpans: spans.length,\n      llmCalls: llmCallCount,\n      toolCalls: toolCallCount,\n      successfulTools,\n      failedTools,\n      totalDurationMs,\n      totalCostCentsX100: costCentsX100,\n      totalInputTokens: usage?.inputTokens ?? 0,\n      totalOutputTokens: usage?.outputTokens ?? 0,\n      model: usage?.model ?? loopOpts.model,\n      createdAt: runStart,\n    };\n\n    writeTraceData(spans, summary, runId, config).catch(() => {});\n  }\n\n  return usage!;\n}\n\nasync function writeTraceData(\n  spans: TraceSpan[],\n  summary: TraceSummary,\n  runId: string,\n  config: ObservabilityConfig,\n): Promise<void> {\n  const { insertTraceSpan, upsertTraceSummary } = await import(\"./store.js\");\n  await Promise.all(spans.map((s) => insertTraceSpan(s).catch(() => {})));\n  await upsertTraceSummary(summary).catch(() => {});\n\n  // Fire automated evals after trace data is persisted\n  try {\n    const { evaluateRun } = await import(\"./evals.js\");\n    await evaluateRun(runId, { sampleRate: config.evalSampleRate });\n  } catch {}\n}\n"]}
+{"version":3,"file":"traces.js","sourceRoot":"","sources":["../../src/observability/traces.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentChatEvent } from \"../agent/types.js\";\nimport type { AgentLoopUsage } from \"../agent/production-agent.js\";\nimport type { TraceSpan, TraceSummary, ObservabilityConfig } from \"./types.js\";\nimport { DEFAULT_OBSERVABILITY_CONFIG } from \"./types.js\";\nimport { type AgentSpan, endAgentSpan, startAgentSpan } from \"./tracing.js\";\n\nfunction spanId(): string {\n  return `span-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;\n}\n\n/** Keys whose values are stripped from persisted tool inputs when\n *  `captureToolArgs` is enabled. Matched case-insensitively and tolerant\n *  of `_` / `-` separators. M14 in the MCP/A2A audit: tool calls\n *  routinely receive credentials verbatim (db-exec INSERTs, fetchTool\n *  Authorization headers, ad-hoc bearer tokens) — keeping those values\n *  out of agent_trace_spans.metadata avoids long-term storage of\n *  short-lived secrets. */\nconst SENSITIVE_FIELD_PATTERN =\n  /^(authorization|cookie|api[_-]?key|password|secret|token|access[_-]?token|refresh[_-]?token|bearer)$/i;\n\n/** Recursively walk a structured value and replace sensitive field\n *  values with the literal string \"[REDACTED]\". Pure (returns a copy);\n *  the original input is never mutated. Cycles are tolerated via a\n *  small WeakSet seen-tracker that returns \"[Circular]\" for repeats. */\nexport function redactSensitiveFields(value: unknown): unknown {\n  return redactWalk(value, new WeakSet<object>());\n}\n\nfunction redactWalk(value: unknown, seen: WeakSet<object>): unknown {\n  if (value === null || typeof value !== \"object\") return value;\n  if (seen.has(value as object)) return \"[Circular]\";\n  seen.add(value as object);\n  if (Array.isArray(value)) {\n    return value.map((v) => redactWalk(v, seen));\n  }\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n    if (SENSITIVE_FIELD_PATTERN.test(k)) {\n      out[k] = \"[REDACTED]\";\n    } else {\n      out[k] = redactWalk(v, seen);\n    }\n  }\n  return out;\n}\n\nexport async function getObservabilityConfig(): Promise<ObservabilityConfig> {\n  try {\n    const { getSetting } = await import(\"../settings/store.js\");\n    const stored = await getSetting(\"observability-config\");\n    if (stored) {\n      return {\n        ...DEFAULT_OBSERVABILITY_CONFIG,\n        ...stored,\n      } as ObservabilityConfig;\n    }\n  } catch {}\n  return DEFAULT_OBSERVABILITY_CONFIG;\n}\n\nexport async function instrumentAgentLoop(opts: {\n  runAgentLoop: (loopOpts: {\n    engine: any;\n    model: string;\n    systemPrompt: string;\n    tools: any[];\n    messages: any[];\n    actions: Record<string, any>;\n    send: (event: AgentChatEvent) => void;\n    signal: AbortSignal;\n    providerOptions?: any;\n  }) => Promise<AgentLoopUsage>;\n  loopOpts: {\n    engine: any;\n    model: string;\n    systemPrompt: string;\n    tools: any[];\n    messages: any[];\n    actions: Record<string, any>;\n    send: (event: AgentChatEvent) => void;\n    signal: AbortSignal;\n    providerOptions?: any;\n  };\n  runId: string;\n  threadId: string | null;\n  /** Owner of this run; persisted on every span + summary so dashboard\n   *  reads can filter to a single user. Null for unauthenticated callers\n   *  (background tasks, etc.) — those rows aren't returned by per-user\n   *  reads. */\n  userId: string | null;\n  config: ObservabilityConfig;\n}): Promise<AgentLoopUsage> {\n  const { runAgentLoop, loopOpts, runId, threadId, userId, config } = opts;\n  const runStart = Date.now();\n  const parentSpanId = spanId();\n\n  // Optional OpenTelemetry root span for this run. No-ops unless a host has\n  // installed `@opentelemetry/api` and registered a provider. The promise is\n  // resolved before the loop runs so child tool/model spans can parent under\n  // it conceptually (we keep them flat in the same tracer, which is enough\n  // for the dashboards an embedding app would build).\n  const otelRunSpanPromise = startAgentSpan(\"agent.run\", {\n    \"agent.run_id\": runId,\n    \"agent.thread_id\": threadId ?? undefined,\n    \"agent.user_id\": userId ?? undefined,\n    \"agent.model\": loopOpts.model,\n  });\n\n  const spans: TraceSpan[] = [];\n  let toolInvocationCounter = 0;\n  // Keyed by counter to handle concurrent calls to the same tool name\n  const pendingTools = new Map<\n    number,\n    {\n      spanId: string;\n      startMs: number;\n      toolName: string;\n      input: Record<string, string>;\n      otelSpan: AgentSpan | null;\n      endResult?: { status: \"success\" | \"error\"; errorMessage: string | null };\n    }\n  >();\n  // Secondary index: tool name → FIFO queue of pending invocation counters.\n  // tool_start/tool_done events carry only the tool name (no call id), so to\n  // pair starts and dones correctly when the agent runs concurrent calls to the\n  // same tool name (read-only / parallelSafe batches via Promise.all), we keep a\n  // queue per name and match each done to the OLDEST still-pending start.\n  const toolNameToCounters = new Map<string, number[]>();\n\n  let toolCallCount = 0;\n  let successfulTools = 0;\n  let failedTools = 0;\n\n  // Track in-flight OTel tool spans so they're all ended even if the loop\n  // throws before a matching `tool_done` arrives.\n  const openOtelToolSpans = new Set<AgentSpan>();\n\n  const instrumentedSend = (event: AgentChatEvent): void => {\n    try {\n      if (event.type === \"tool_start\") {\n        const counter = toolInvocationCounter++;\n        const sid = spanId();\n        // Start the OTel tool span synchronously-ish: kick off the async\n        // resolution and stash the span once it lands. Tool spans are short\n        // and the api tracer is synchronous in practice, but we tolerate the\n        // microtask gap by recording the span on the pending entry when ready.\n        const entry: {\n          spanId: string;\n          startMs: number;\n          toolName: string;\n          input: Record<string, string>;\n          otelSpan: AgentSpan | null;\n          // Set by the done handler if it fires before the span promise\n          // resolves, so the resolved span is ended with the correct status.\n          endResult?: {\n            status: \"success\" | \"error\";\n            errorMessage: string | null;\n          };\n        } = {\n          spanId: sid,\n          startMs: Date.now(),\n          toolName: event.tool,\n          input: event.input,\n          otelSpan: null,\n        };\n        pendingTools.set(counter, entry);\n        void startAgentSpan(\"tool.call\", {\n          \"tool.name\": event.tool,\n        }).then((span) => {\n          if (!span) return;\n          // If `tool_done` already ran for this call, end the span now with the\n          // status it recorded; otherwise stash it for the done handler.\n          if (entry.endResult) {\n            endAgentSpan(span, {\n              status: entry.endResult.status,\n              errorMessage: entry.endResult.errorMessage,\n            });\n          } else {\n            entry.otelSpan = span;\n            openOtelToolSpans.add(span);\n          }\n        });\n        const queue = toolNameToCounters.get(event.tool);\n        if (queue) queue.push(counter);\n        else toolNameToCounters.set(event.tool, [counter]);\n      } else if (event.type === \"tool_done\") {\n        const queue = toolNameToCounters.get(event.tool);\n        const counter = queue?.shift();\n        const pending =\n          counter !== undefined ? pendingTools.get(counter) : undefined;\n        if (counter !== undefined) {\n          pendingTools.delete(counter);\n          if (queue && queue.length === 0)\n            toolNameToCounters.delete(event.tool);\n        }\n        toolCallCount++;\n\n        const isError =\n          typeof event.result === \"string\" &&\n          (event.result.startsWith(\"Error\") ||\n            event.result.startsWith(\"Error running \"));\n        if (isError) failedTools++;\n        else successfulTools++;\n\n        // Finalize the OTel tool span. If the span promise hasn't resolved yet\n        // we record the result on the entry so its `.then` handler ends it.\n        const otelEndResult = {\n          status: (isError ? \"error\" : \"success\") as \"success\" | \"error\",\n          errorMessage: isError ? (event.result as string) : null,\n        };\n        if (pending?.otelSpan) {\n          openOtelToolSpans.delete(pending.otelSpan);\n          endAgentSpan(pending.otelSpan, {\n            status: otelEndResult.status,\n            errorMessage: otelEndResult.errorMessage,\n            attributes: { \"tool.name\": event.tool },\n          });\n        } else if (pending) {\n          pending.endResult = otelEndResult;\n        }\n\n        const span: TraceSpan = {\n          id: pending?.spanId ?? spanId(),\n          runId,\n          threadId,\n          userId,\n          parentSpanId,\n          spanType: \"tool_call\",\n          name: event.tool,\n          inputTokens: 0,\n          outputTokens: 0,\n          cacheReadTokens: 0,\n          cacheWriteTokens: 0,\n          costCentsX100: 0,\n          durationMs: pending ? Date.now() - pending.startMs : 0,\n          status: isError ? \"error\" : \"success\",\n          errorMessage: isError ? event.result : null,\n          metadata:\n            config.captureToolArgs && pending\n              ? // Strip Authorization/api-key/token-shaped values before\n                // persisting (M14 in the MCP/A2A audit). Tool-runtime\n                // execution still sees the unredacted input — only the\n                // long-lived span row is sanitized.\n                {\n                  input: redactSensitiveFields(pending.input) as Record<\n                    string,\n                    string\n                  >,\n                }\n              : null,\n          createdAt: Date.now(),\n        };\n        spans.push(span);\n      }\n    } catch {}\n\n    loopOpts.send(event);\n  };\n\n  let usage: AgentLoopUsage | undefined;\n  let runStatus: \"success\" | \"error\" = \"success\";\n  let errorMessage: string | null = null;\n  try {\n    usage = await runAgentLoop({ ...loopOpts, send: instrumentedSend });\n  } catch (err: any) {\n    runStatus = \"error\";\n    errorMessage = err?.message ?? String(err);\n    throw err;\n  } finally {\n    const runEnd = Date.now();\n    const totalDurationMs = runEnd - runStart;\n\n    let costCentsX100 = 0;\n    try {\n      const { calculateCost } = await import(\"../usage/store.js\");\n      if (usage) {\n        costCentsX100 = calculateCost(\n          usage.inputTokens,\n          usage.outputTokens,\n          usage.model,\n          usage.cacheReadTokens,\n          usage.cacheWriteTokens,\n        );\n      }\n    } catch {}\n\n    let llmCallCount = 0;\n    if (usage) {\n      llmCallCount = 1;\n      const llmSpan: TraceSpan = {\n        id: spanId(),\n        runId,\n        threadId,\n        userId,\n        parentSpanId,\n        spanType: \"llm_call\",\n        name: usage.model,\n        inputTokens: usage.inputTokens,\n        outputTokens: usage.outputTokens,\n        cacheReadTokens: usage.cacheReadTokens,\n        cacheWriteTokens: usage.cacheWriteTokens,\n        costCentsX100,\n        durationMs: totalDurationMs,\n        status: runStatus,\n        errorMessage,\n        metadata: null,\n        createdAt: runStart,\n      };\n      spans.push(llmSpan);\n    }\n\n    const parentSpan: TraceSpan = {\n      id: parentSpanId,\n      runId,\n      threadId,\n      userId,\n      parentSpanId: null,\n      spanType: \"agent_run\",\n      name: \"agent_run\",\n      inputTokens: usage?.inputTokens ?? 0,\n      outputTokens: usage?.outputTokens ?? 0,\n      cacheReadTokens: usage?.cacheReadTokens ?? 0,\n      cacheWriteTokens: usage?.cacheWriteTokens ?? 0,\n      costCentsX100,\n      durationMs: totalDurationMs,\n      status: runStatus,\n      errorMessage,\n      metadata: null,\n      createdAt: runStart,\n    };\n    spans.push(parentSpan);\n\n    const summary: TraceSummary = {\n      runId,\n      threadId,\n      userId,\n      totalSpans: spans.length,\n      llmCalls: llmCallCount,\n      toolCalls: toolCallCount,\n      successfulTools,\n      failedTools,\n      totalDurationMs,\n      totalCostCentsX100: costCentsX100,\n      totalInputTokens: usage?.inputTokens ?? 0,\n      totalOutputTokens: usage?.outputTokens ?? 0,\n      model: usage?.model ?? loopOpts.model,\n      createdAt: runStart,\n    };\n\n    writeTraceData(spans, summary, runId, config).catch(() => {});\n\n    // OpenTelemetry export (no-op unless a provider is registered). Emit a\n    // self-contained `llm.call` span carrying model + token usage, end any\n    // tool spans still open (loop threw mid-tool), and end the run span. Awaited\n    // so the spans are emitted before the function returns; cheap when no-op.\n    try {\n      if (usage) {\n        endAgentSpan(await startAgentSpan(\"llm.call\", {}), {\n          status: runStatus,\n          errorMessage,\n          attributes: {\n            \"llm.model\": usage.model,\n            \"llm.input_tokens\": usage.inputTokens,\n            \"llm.output_tokens\": usage.outputTokens,\n            \"llm.cache_read_tokens\": usage.cacheReadTokens,\n            \"llm.cache_write_tokens\": usage.cacheWriteTokens,\n            \"llm.cost_cents_x100\": costCentsX100,\n          },\n        });\n      }\n      for (const toolSpan of openOtelToolSpans) {\n        endAgentSpan(toolSpan, {\n          status: \"error\",\n          errorMessage: \"Agent run ended before tool_done.\",\n        });\n      }\n      openOtelToolSpans.clear();\n      endAgentSpan(await otelRunSpanPromise, {\n        status: runStatus,\n        errorMessage,\n        attributes: {\n          \"agent.tool_calls\": toolCallCount,\n          \"agent.successful_tools\": successfulTools,\n          \"agent.failed_tools\": failedTools,\n          \"agent.duration_ms\": totalDurationMs,\n          \"agent.input_tokens\": usage?.inputTokens ?? 0,\n          \"agent.output_tokens\": usage?.outputTokens ?? 0,\n          \"agent.cost_cents_x100\": costCentsX100,\n        },\n      });\n    } catch {\n      // OTel export must never break the run.\n    }\n  }\n\n  return usage!;\n}\n\nasync function writeTraceData(\n  spans: TraceSpan[],\n  summary: TraceSummary,\n  runId: string,\n  config: ObservabilityConfig,\n): Promise<void> {\n  const { insertTraceSpan, upsertTraceSummary } = await import(\"./store.js\");\n  await Promise.all(spans.map((s) => insertTraceSpan(s).catch(() => {})));\n  await upsertTraceSummary(summary).catch(() => {});\n\n  // Fire automated evals after trace data is persisted\n  try {\n    const { evaluateRun } = await import(\"./evals.js\");\n    await evaluateRun(runId, { sampleRate: config.evalSampleRate });\n  } catch {}\n}\n"]}

package/dist/observability/tracing.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Optional OpenTelemetry layer for the agent loop.
+ *
+ * The framework's primary trace store is the in-house `agent_trace_spans` /
+ * `agent_trace_summaries` tables (see `traces.ts`). This module adds an
+ * OPTIONAL, no-op-unless-configured OpenTelemetry export on top of that, so a
+ * host that already runs an OTel collector can see agent runs, model calls, and
+ * tool calls alongside the rest of their distributed traces.
+ *
+ * Design constraints:
+ *   - `@opentelemetry/api` is an OPTIONAL dependency. If it isn't installed the
+ *     helpers degrade to silent no-ops — nothing here ever throws into the agent
+ *     loop.
+ *   - The API package ships a default NO-OP tracer. Until a host registers a
+ *     real `TracerProvider` (via `@opentelemetry/sdk-node` or similar, which
+ *     core deliberately does NOT depend on), `tracer.startSpan(...)` returns a
+ *     no-op span and the cost is a couple of property reads. We never register a
+ *     provider ourselves — instrumentation is opt-in by the embedding app.
+ *   - Heavy SDK packages (`@opentelemetry/sdk-*`, exporters) are NOT added to
+ *     core. The host owns the provider/exporter wiring; core only emits spans.
+ */
+/**
+ * Minimal structural subset of the OpenTelemetry `Span` we use. Declared
+ * locally so this module type-checks even when `@opentelemetry/api` isn't
+ * installed (it's an optional dependency).
+ */
+export interface AgentSpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setAttributes(attributes: Record<string, string | number | boolean>): void;
+    /** OTel `SpanStatusCode`: 1 = OK, 2 = ERROR. */
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(exception: {
+        name?: string;
+        message: string;
+    }): void;
+    end(): void;
+}
+/** OTel `SpanStatusCode` values, inlined so we don't need the api types here. */
+export declare const SPAN_STATUS_OK = 1;
+export declare const SPAN_STATUS_ERROR = 2;
+interface AgentTracer {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): AgentSpan;
+}
+/**
+ * Start a span. When OTel isn't installed (or no provider is registered) this
+ * returns `null` and the caller simply skips span bookkeeping — there is no
+ * runtime cost beyond the cached null check.
+ */
+export declare function startAgentSpan(name: string, attributes?: Record<string, string | number | boolean | null | undefined>): Promise<AgentSpan | null>;
+/**
+ * Finish a span, setting OK/ERROR status and recording the error message when
+ * present. Safe to call with `null` (no-op) and never throws.
+ */
+export declare function endAgentSpan(span: AgentSpan | null, result?: {
+    status?: "success" | "error";
+    errorMessage?: string | null;
+    attributes?: Record<string, string | number | boolean | null | undefined>;
+}): void;
+/** For tests — reset the cached tracer so a fresh provider can be detected. */
+export declare function __resetAgentTracerCache(): void;
+/**
+ * For tests — inject a tracer directly (e.g. an in-memory test provider's
+ * tracer) without going through the `@opentelemetry/api` global. Pass `null`
+ * to simulate "no tracer available".
+ */
+export declare function __setAgentTracerForTests(tracer: AgentTracer | null): void;
+export {};
+//# sourceMappingURL=tracing.d.ts.map

package/dist/observability/tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../../src/observability/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClE,aAAa,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3E,gDAAgD;IAChD,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,eAAe,CAAC,SAAS,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrE,GAAG,IAAI,IAAI,CAAC;CACb;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAQnC,UAAU,WAAW;IACnB,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;KAAE,GACnE,SAAS,CAAC;CACd;AAgCD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAM,GAC5E,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAU3B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,GAAG,IAAI,EACtB,MAAM,GAAE;IACN,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACtE,GACL,IAAI,CA0BN;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEzE"}

package/dist/observability/tracing.js

@@ -0,0 +1,126 @@
+/**
+ * Optional OpenTelemetry layer for the agent loop.
+ *
+ * The framework's primary trace store is the in-house `agent_trace_spans` /
+ * `agent_trace_summaries` tables (see `traces.ts`). This module adds an
+ * OPTIONAL, no-op-unless-configured OpenTelemetry export on top of that, so a
+ * host that already runs an OTel collector can see agent runs, model calls, and
+ * tool calls alongside the rest of their distributed traces.
+ *
+ * Design constraints:
+ *   - `@opentelemetry/api` is an OPTIONAL dependency. If it isn't installed the
+ *     helpers degrade to silent no-ops — nothing here ever throws into the agent
+ *     loop.
+ *   - The API package ships a default NO-OP tracer. Until a host registers a
+ *     real `TracerProvider` (via `@opentelemetry/sdk-node` or similar, which
+ *     core deliberately does NOT depend on), `tracer.startSpan(...)` returns a
+ *     no-op span and the cost is a couple of property reads. We never register a
+ *     provider ourselves — instrumentation is opt-in by the embedding app.
+ *   - Heavy SDK packages (`@opentelemetry/sdk-*`, exporters) are NOT added to
+ *     core. The host owns the provider/exporter wiring; core only emits spans.
+ */
+const TRACER_NAME = "@agent-native/core/agent-loop";
+/** OTel `SpanStatusCode` values, inlined so we don't need the api types here. */
+export const SPAN_STATUS_OK = 1;
+export const SPAN_STATUS_ERROR = 2;
+/**
+ * Cached tracer. `undefined` = not yet resolved; `null` = resolved to
+ * "no tracer available" (api package missing or load failed).
+ */
+let cachedTracer;
+/**
+ * Resolve the OpenTelemetry tracer if `@opentelemetry/api` is installed.
+ * Returns `null` (cached) when the package is unavailable so callers can
+ * branch to a no-op cheaply on every subsequent call.
+ */
+async function resolveTracer() {
+    if (cachedTracer !== undefined)
+        return cachedTracer;
+    try {
+        // Optional dependency — guarded import. Absent ⇒ no-op everywhere.
+        const otel = await import("@opentelemetry/api");
+        const tracer = otel?.trace?.getTracer?.(TRACER_NAME);
+        cachedTracer = tracer ?? null;
+    }
+    catch {
+        cachedTracer = null;
+    }
+    return cachedTracer;
+}
+/** Drop sentinel/zero token counts so spans aren't cluttered with noise. */
+function pruneAttributes(attributes) {
+    const out = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value === null || value === undefined)
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Start a span. When OTel isn't installed (or no provider is registered) this
+ * returns `null` and the caller simply skips span bookkeeping — there is no
+ * runtime cost beyond the cached null check.
+ */
+export async function startAgentSpan(name, attributes = {}) {
+    const tracer = await resolveTracer();
+    if (!tracer)
+        return null;
+    try {
+        return tracer.startSpan(name, {
+            attributes: pruneAttributes(attributes),
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Finish a span, setting OK/ERROR status and recording the error message when
+ * present. Safe to call with `null` (no-op) and never throws.
+ */
+export function endAgentSpan(span, result = {}) {
+    if (!span)
+        return;
+    try {
+        if (result.attributes) {
+            span.setAttributes(pruneAttributes(result.attributes));
+        }
+        if (result.status === "error") {
+            span.setStatus({
+                code: SPAN_STATUS_ERROR,
+                message: result.errorMessage ?? undefined,
+            });
+            if (result.errorMessage) {
+                span.recordException({ message: result.errorMessage });
+            }
+        }
+        else {
+            span.setStatus({ code: SPAN_STATUS_OK });
+        }
+    }
+    catch {
+        // Never let span finalization break the agent loop.
+    }
+    finally {
+        try {
+            span.end();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/** For tests — reset the cached tracer so a fresh provider can be detected. */
+export function __resetAgentTracerCache() {
+    cachedTracer = undefined;
+}
+/**
+ * For tests — inject a tracer directly (e.g. an in-memory test provider's
+ * tracer) without going through the `@opentelemetry/api` global. Pass `null`
+ * to simulate "no tracer available".
+ */
+export function __setAgentTracerForTests(tracer) {
+    cachedTracer = tracer;
+}
+//# sourceMappingURL=tracing.js.map

package/dist/observability/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../../src/observability/tracing.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Optional OpenTelemetry layer for the agent loop.\n *\n * The framework's primary trace store is the in-house `agent_trace_spans` /\n * `agent_trace_summaries` tables (see `traces.ts`). This module adds an\n * OPTIONAL, no-op-unless-configured OpenTelemetry export on top of that, so a\n * host that already runs an OTel collector can see agent runs, model calls, and\n * tool calls alongside the rest of their distributed traces.\n *\n * Design constraints:\n *   - `@opentelemetry/api` is an OPTIONAL dependency. If it isn't installed the\n *     helpers degrade to silent no-ops — nothing here ever throws into the agent\n *     loop.\n *   - The API package ships a default NO-OP tracer. Until a host registers a\n *     real `TracerProvider` (via `@opentelemetry/sdk-node` or similar, which\n *     core deliberately does NOT depend on), `tracer.startSpan(...)` returns a\n *     no-op span and the cost is a couple of property reads. We never register a\n *     provider ourselves — instrumentation is opt-in by the embedding app.\n *   - Heavy SDK packages (`@opentelemetry/sdk-*`, exporters) are NOT added to\n *     core. The host owns the provider/exporter wiring; core only emits spans.\n */\n\nconst TRACER_NAME = \"@agent-native/core/agent-loop\";\n\n/**\n * Minimal structural subset of the OpenTelemetry `Span` we use. Declared\n * locally so this module type-checks even when `@opentelemetry/api` isn't\n * installed (it's an optional dependency).\n */\nexport interface AgentSpan {\n  setAttribute(key: string, value: string | number | boolean): void;\n  setAttributes(attributes: Record<string, string | number | boolean>): void;\n  /** OTel `SpanStatusCode`: 1 = OK, 2 = ERROR. */\n  setStatus(status: { code: number; message?: string }): void;\n  recordException(exception: { name?: string; message: string }): void;\n  end(): void;\n}\n\n/** OTel `SpanStatusCode` values, inlined so we don't need the api types here. */\nexport const SPAN_STATUS_OK = 1;\nexport const SPAN_STATUS_ERROR = 2;\n\n/**\n * Cached tracer. `undefined` = not yet resolved; `null` = resolved to\n * \"no tracer available\" (api package missing or load failed).\n */\nlet cachedTracer: AgentTracer | null | undefined;\n\ninterface AgentTracer {\n  startSpan(\n    name: string,\n    options?: { attributes?: Record<string, string | number | boolean> },\n  ): AgentSpan;\n}\n\n/**\n * Resolve the OpenTelemetry tracer if `@opentelemetry/api` is installed.\n * Returns `null` (cached) when the package is unavailable so callers can\n * branch to a no-op cheaply on every subsequent call.\n */\nasync function resolveTracer(): Promise<AgentTracer | null> {\n  if (cachedTracer !== undefined) return cachedTracer;\n  try {\n    // Optional dependency — guarded import. Absent ⇒ no-op everywhere.\n    const otel: any = await import(\"@opentelemetry/api\");\n    const tracer = otel?.trace?.getTracer?.(TRACER_NAME);\n    cachedTracer = (tracer as AgentTracer) ?? null;\n  } catch {\n    cachedTracer = null;\n  }\n  return cachedTracer;\n}\n\n/** Drop sentinel/zero token counts so spans aren't cluttered with noise. */\nfunction pruneAttributes(\n  attributes: Record<string, string | number | boolean | null | undefined>,\n): Record<string, string | number | boolean> {\n  const out: Record<string, string | number | boolean> = {};\n  for (const [key, value] of Object.entries(attributes)) {\n    if (value === null || value === undefined) continue;\n    out[key] = value;\n  }\n  return out;\n}\n\n/**\n * Start a span. When OTel isn't installed (or no provider is registered) this\n * returns `null` and the caller simply skips span bookkeeping — there is no\n * runtime cost beyond the cached null check.\n */\nexport async function startAgentSpan(\n  name: string,\n  attributes: Record<string, string | number | boolean | null | undefined> = {},\n): Promise<AgentSpan | null> {\n  const tracer = await resolveTracer();\n  if (!tracer) return null;\n  try {\n    return tracer.startSpan(name, {\n      attributes: pruneAttributes(attributes),\n    });\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Finish a span, setting OK/ERROR status and recording the error message when\n * present. Safe to call with `null` (no-op) and never throws.\n */\nexport function endAgentSpan(\n  span: AgentSpan | null,\n  result: {\n    status?: \"success\" | \"error\";\n    errorMessage?: string | null;\n    attributes?: Record<string, string | number | boolean | null | undefined>;\n  } = {},\n): void {\n  if (!span) return;\n  try {\n    if (result.attributes) {\n      span.setAttributes(pruneAttributes(result.attributes));\n    }\n    if (result.status === \"error\") {\n      span.setStatus({\n        code: SPAN_STATUS_ERROR,\n        message: result.errorMessage ?? undefined,\n      });\n      if (result.errorMessage) {\n        span.recordException({ message: result.errorMessage });\n      }\n    } else {\n      span.setStatus({ code: SPAN_STATUS_OK });\n    }\n  } catch {\n    // Never let span finalization break the agent loop.\n  } finally {\n    try {\n      span.end();\n    } catch {\n      // ignore\n    }\n  }\n}\n\n/** For tests — reset the cached tracer so a fresh provider can be detected. */\nexport function __resetAgentTracerCache(): void {\n  cachedTracer = undefined;\n}\n\n/**\n * For tests — inject a tracer directly (e.g. an in-memory test provider's\n * tracer) without going through the `@opentelemetry/api` global. Pass `null`\n * to simulate \"no tracer available\".\n */\nexport function __setAgentTracerForTests(tracer: AgentTracer | null): void {\n  cachedTracer = tracer;\n}\n"]}

package/dist/onboarding/default-steps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default-steps.d.ts","sourceRoot":"","sources":["../../src/onboarding/default-steps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6RH,6DAA6D;AAC7D,wBAAgB,8BAA8B,IAAI,IAAI,CAOrD"}
+{"version":3,"file":"default-steps.d.ts","sourceRoot":"","sources":["../../src/onboarding/default-steps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAsSH,6DAA6D;AAC7D,wBAAgB,8BAA8B,IAAI,IAAI,CAOrD"}

package/dist/onboarding/default-steps.js

@@ -8,6 +8,7 @@
 import { registerOnboardingStep } from "./registry.js";
 import { PROVIDER_ENV_META, PROVIDER_ENV_VARS, } from "../agent/engine/provider-env-vars.js";
 import { detectEngineFromUserSecrets, isAgentEngineSettingConfigured, } from "../agent/engine/registry.js";
+import { canUseDeployCredentialFallbackForRequest, readDeployCredentialEnv, } from "../server/credential-provider.js";
 import { getSetting } from "../settings/store.js";
 const LLM_KEY_METHODS = [
     {
@@ -110,8 +111,10 @@ const llmStep = {
         catch {
             // Fall through to legacy/env detection.
         }
-        if (PROVIDER_ENV_VARS.some((k) => !!process.env[k]))
+        if (canUseDeployCredentialFallbackForRequest() &&
+            PROVIDER_ENV_VARS.some((k) => !!readDeployCredentialEnv(k))) {
             return true;
+        }
         try {
             return isAgentEngineSettingConfigured(await getSetting("agent-engine"));
         }

package/dist/onboarding/default-steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"default-steps.js","sourceRoot":"","sources":["../../src/onboarding/default-steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Default framework-level onboarding steps.\n *\n * Registered when `createOnboardingPlugin()` mounts (auto-mount or explicit).\n * Templates can override any step by registering another step with the same\n * `id` after these have been registered.\n */\n\nimport { registerOnboardingStep } from \"./registry.js\";\nimport type { OnboardingStep } from \"./types.js\";\nimport {\n  PROVIDER_ENV_META,\n  PROVIDER_ENV_VARS,\n} from \"../agent/engine/provider-env-vars.js\";\nimport {\n  detectEngineFromUserSecrets,\n  isAgentEngineSettingConfigured,\n} from \"../agent/engine/registry.js\";\nimport { getSetting } from \"../settings/store.js\";\n\ntype LlmKeyMethod = {\n  provider: keyof typeof PROVIDER_ENV_META;\n  id: string;\n  label: string;\n  description: string;\n  primary?: boolean;\n};\n\nconst LLM_KEY_METHODS: LlmKeyMethod[] = [\n  {\n    provider: \"anthropic\",\n    id: \"anthropic-key\",\n    label: \"Anthropic\",\n    description: \"Claude models with your own Anthropic key.\",\n  },\n  {\n    provider: \"openai\",\n    id: \"openai-key\",\n    label: \"OpenAI\",\n    description: \"GPT models with your own OpenAI key.\",\n  },\n  {\n    provider: \"google\",\n    id: \"google-key\",\n    label: \"Google Gemini\",\n    description: \"Gemini models with your own Google AI key.\",\n  },\n  {\n    provider: \"openrouter\",\n    id: \"openrouter-key\",\n    label: \"OpenRouter\",\n    description: \"OpenRouter models with your own OpenRouter key.\",\n  },\n  {\n    provider: \"groq\",\n    id: \"groq-key\",\n    label: \"Groq\",\n    description: \"Groq-hosted models with your own Groq key.\",\n  },\n  {\n    provider: \"mistral\",\n    id: \"mistral-key\",\n    label: \"Mistral\",\n    description: \"Mistral models with your own Mistral key.\",\n  },\n  {\n    provider: \"cohere\",\n    id: \"cohere-key\",\n    label: \"Cohere\",\n    description: \"Cohere models with your own Cohere key.\",\n  },\n];\n\nconst llmStep: OnboardingStep = {\n  id: \"llm\",\n  order: 10,\n  required: true,\n  title: \"Connect an AI engine\",\n  description: \"Use Builder's managed gateway, or bring your own provider key.\",\n  methods: [\n    {\n      id: \"builder\",\n      kind: \"builder-cli-auth\",\n      label: \"Connect Builder\",\n      description:\n        \"Connect the Builder space where this app should run. This unlocks managed LLM credits, web search, browser automation, and file uploads. Cloud code changes appear when Builder Cloud Agents are available for the workspace.\",\n      primary: true,\n      payload: {\n        scope: \"llm\",\n      },\n    },\n    ...LLM_KEY_METHODS.map(({ provider, id, label, description, primary }) => {\n      const meta = PROVIDER_ENV_META[provider];\n      return {\n        id,\n        kind: \"form\" as const,\n        label,\n        description,\n        ...(primary ? { primary: true } : {}),\n        payload: {\n          writeScope: \"workspace\" as const,\n          fields: [\n            {\n              key: meta.envVar,\n              label: meta.envVar,\n              placeholder: meta.placeholder,\n              secret: true,\n            },\n          ],\n        },\n      };\n    }),\n  ],\n  isComplete: async () => {\n    try {\n      const { resolveHasCompleteBuilderConnection } =\n        await import(\"../server/credential-provider.js\");\n      if (await resolveHasCompleteBuilderConnection()) return true;\n    } catch {\n      if (process.env.BUILDER_PRIVATE_KEY && process.env.BUILDER_PUBLIC_KEY) {\n        return true;\n      }\n    }\n    try {\n      if (await detectEngineFromUserSecrets()) return true;\n    } catch {\n      // Fall through to legacy/env detection.\n    }\n    if (PROVIDER_ENV_VARS.some((k) => !!process.env[k])) return true;\n    try {\n      return isAgentEngineSettingConfigured(await getSetting(\"agent-engine\"));\n    } catch {\n      return false;\n    }\n  },\n};\n\n/** Step 2 — where application data lives. The default DB is non-blocking. */\nconst databaseStep: OnboardingStep = {\n  id: \"database\",\n  order: 20,\n  required: false,\n  title: \"Database\",\n  description:\n    \"Agent-native stores app data in SQL. Set DATABASE_URL when you want to point this app at a specific database.\",\n  methods: [\n    {\n      id: \"database-url\",\n      kind: \"form\",\n      label: \"Set DATABASE_URL\",\n      description: \"Paste the SQL connection string this app should use.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          {\n            key: \"DATABASE_URL\",\n            label: \"DATABASE_URL\",\n            placeholder: \"postgres://..., libsql://..., file:./data/app.db\",\n          },\n          {\n            key: \"DATABASE_AUTH_TOKEN\",\n            label: \"DATABASE_AUTH_TOKEN (if needed)\",\n            placeholder: \"Token for providers such as Turso/libSQL\",\n            secret: true,\n          },\n        ],\n      },\n    },\n  ],\n  // The default local database means this step is always satisfied.\n  isComplete: () => true,\n};\n\n/** Step 3 — how users sign in. Built-in account auth is non-blocking. */\nconst authStep: OnboardingStep = {\n  id: \"auth\",\n  order: 30,\n  required: false,\n  title: \"Authentication\",\n  description:\n    \"Built-in email/password accounts work by default. Add OAuth or access tokens only if you want another sign-in path.\",\n  methods: [\n    {\n      id: \"google-oauth\",\n      kind: \"form\",\n      label: \"Google OAuth\",\n      description: \"Add Google as an optional sign-in provider.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          { key: \"GOOGLE_CLIENT_ID\", label: \"GOOGLE_CLIENT_ID\" },\n          {\n            key: \"GOOGLE_CLIENT_SECRET\",\n            label: \"GOOGLE_CLIENT_SECRET\",\n            secret: true,\n          },\n        ],\n      },\n    },\n    {\n      id: \"github-oauth\",\n      kind: \"form\",\n      label: \"GitHub OAuth\",\n      description: \"Add GitHub as an optional sign-in provider.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          { key: \"GITHUB_CLIENT_ID\", label: \"GITHUB_CLIENT_ID\" },\n          {\n            key: \"GITHUB_CLIENT_SECRET\",\n            label: \"GITHUB_CLIENT_SECRET\",\n            secret: true,\n          },\n        ],\n      },\n    },\n  ],\n  isComplete: () => true,\n};\n\n/** Step 4 — transactional email (password resets, invitations). Optional. */\nconst emailStep: OnboardingStep = {\n  id: \"email\",\n  order: 40,\n  required: false,\n  title: \"Email delivery\",\n  description:\n    \"Optional for local work. Before deploying with password resets, invitations, or share notifications, connect an email provider.\",\n  methods: [\n    {\n      id: \"resend\",\n      kind: \"form\",\n      label: \"Resend\",\n      description: \"Use Resend for transactional email.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          {\n            key: \"RESEND_API_KEY\",\n            label: \"RESEND_API_KEY\",\n            placeholder: \"re_...\",\n            secret: true,\n          },\n          {\n            key: \"EMAIL_FROM\",\n            label: \"EMAIL_FROM (from address)\",\n            placeholder: \"Agent Native <noreply@yourdomain.com>\",\n          },\n          {\n            key: \"APP_NAME\",\n            label: \"APP_NAME (shown in invite emails)\",\n            placeholder: \"Acme Forms\",\n          },\n        ],\n      },\n    },\n    {\n      id: \"sendgrid\",\n      kind: \"form\",\n      label: \"SendGrid\",\n      description: \"Use SendGrid for transactional email.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          {\n            key: \"SENDGRID_API_KEY\",\n            label: \"SENDGRID_API_KEY\",\n            placeholder: \"SG....\",\n            secret: true,\n          },\n          {\n            key: \"EMAIL_FROM\",\n            label: \"EMAIL_FROM (from address)\",\n            placeholder: \"Agent Native <noreply@yourdomain.com>\",\n          },\n        ],\n      },\n    },\n  ],\n  isComplete: () => {\n    if (process.env.RESEND_API_KEY) return true;\n    // SendGrid rejects Resend's sandbox sender, so EMAIL_FROM must also be\n    // set — otherwise sendEmail() throws at runtime even though the API key\n    // is configured.\n    if (process.env.SENDGRID_API_KEY) return !!process.env.EMAIL_FROM;\n    return false;\n  },\n};\n\nlet registered = false;\n\n/** Idempotent. Safe to call from every plugin-mount call. */\nexport function registerDefaultOnboardingSteps(): void {\n  if (registered) return;\n  registered = true;\n  registerOnboardingStep(llmStep);\n  registerOnboardingStep(databaseStep);\n  registerOnboardingStep(authStep);\n  registerOnboardingStep(emailStep);\n}\n"]}
+{"version":3,"file":"default-steps.js","sourceRoot":"","sources":["../../src/onboarding/default-steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Default framework-level onboarding steps.\n *\n * Registered when `createOnboardingPlugin()` mounts (auto-mount or explicit).\n * Templates can override any step by registering another step with the same\n * `id` after these have been registered.\n */\n\nimport { registerOnboardingStep } from \"./registry.js\";\nimport type { OnboardingStep } from \"./types.js\";\nimport {\n  PROVIDER_ENV_META,\n  PROVIDER_ENV_VARS,\n} from \"../agent/engine/provider-env-vars.js\";\nimport {\n  detectEngineFromUserSecrets,\n  isAgentEngineSettingConfigured,\n} from \"../agent/engine/registry.js\";\nimport {\n  canUseDeployCredentialFallbackForRequest,\n  readDeployCredentialEnv,\n} from \"../server/credential-provider.js\";\nimport { getSetting } from \"../settings/store.js\";\n\ntype LlmKeyMethod = {\n  provider: keyof typeof PROVIDER_ENV_META;\n  id: string;\n  label: string;\n  description: string;\n  primary?: boolean;\n};\n\nconst LLM_KEY_METHODS: LlmKeyMethod[] = [\n  {\n    provider: \"anthropic\",\n    id: \"anthropic-key\",\n    label: \"Anthropic\",\n    description: \"Claude models with your own Anthropic key.\",\n  },\n  {\n    provider: \"openai\",\n    id: \"openai-key\",\n    label: \"OpenAI\",\n    description: \"GPT models with your own OpenAI key.\",\n  },\n  {\n    provider: \"google\",\n    id: \"google-key\",\n    label: \"Google Gemini\",\n    description: \"Gemini models with your own Google AI key.\",\n  },\n  {\n    provider: \"openrouter\",\n    id: \"openrouter-key\",\n    label: \"OpenRouter\",\n    description: \"OpenRouter models with your own OpenRouter key.\",\n  },\n  {\n    provider: \"groq\",\n    id: \"groq-key\",\n    label: \"Groq\",\n    description: \"Groq-hosted models with your own Groq key.\",\n  },\n  {\n    provider: \"mistral\",\n    id: \"mistral-key\",\n    label: \"Mistral\",\n    description: \"Mistral models with your own Mistral key.\",\n  },\n  {\n    provider: \"cohere\",\n    id: \"cohere-key\",\n    label: \"Cohere\",\n    description: \"Cohere models with your own Cohere key.\",\n  },\n];\n\nconst llmStep: OnboardingStep = {\n  id: \"llm\",\n  order: 10,\n  required: true,\n  title: \"Connect an AI engine\",\n  description: \"Use Builder's managed gateway, or bring your own provider key.\",\n  methods: [\n    {\n      id: \"builder\",\n      kind: \"builder-cli-auth\",\n      label: \"Connect Builder\",\n      description:\n        \"Connect the Builder space where this app should run. This unlocks managed LLM credits, web search, browser automation, and file uploads. Cloud code changes appear when Builder Cloud Agents are available for the workspace.\",\n      primary: true,\n      payload: {\n        scope: \"llm\",\n      },\n    },\n    ...LLM_KEY_METHODS.map(({ provider, id, label, description, primary }) => {\n      const meta = PROVIDER_ENV_META[provider];\n      return {\n        id,\n        kind: \"form\" as const,\n        label,\n        description,\n        ...(primary ? { primary: true } : {}),\n        payload: {\n          writeScope: \"workspace\" as const,\n          fields: [\n            {\n              key: meta.envVar,\n              label: meta.envVar,\n              placeholder: meta.placeholder,\n              secret: true,\n            },\n          ],\n        },\n      };\n    }),\n  ],\n  isComplete: async () => {\n    try {\n      const { resolveHasCompleteBuilderConnection } =\n        await import(\"../server/credential-provider.js\");\n      if (await resolveHasCompleteBuilderConnection()) return true;\n    } catch {\n      if (process.env.BUILDER_PRIVATE_KEY && process.env.BUILDER_PUBLIC_KEY) {\n        return true;\n      }\n    }\n    try {\n      if (await detectEngineFromUserSecrets()) return true;\n    } catch {\n      // Fall through to legacy/env detection.\n    }\n    if (\n      canUseDeployCredentialFallbackForRequest() &&\n      PROVIDER_ENV_VARS.some((k) => !!readDeployCredentialEnv(k))\n    ) {\n      return true;\n    }\n    try {\n      return isAgentEngineSettingConfigured(await getSetting(\"agent-engine\"));\n    } catch {\n      return false;\n    }\n  },\n};\n\n/** Step 2 — where application data lives. The default DB is non-blocking. */\nconst databaseStep: OnboardingStep = {\n  id: \"database\",\n  order: 20,\n  required: false,\n  title: \"Database\",\n  description:\n    \"Agent-native stores app data in SQL. Set DATABASE_URL when you want to point this app at a specific database.\",\n  methods: [\n    {\n      id: \"database-url\",\n      kind: \"form\",\n      label: \"Set DATABASE_URL\",\n      description: \"Paste the SQL connection string this app should use.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          {\n            key: \"DATABASE_URL\",\n            label: \"DATABASE_URL\",\n            placeholder: \"postgres://..., libsql://..., file:./data/app.db\",\n          },\n          {\n            key: \"DATABASE_AUTH_TOKEN\",\n            label: \"DATABASE_AUTH_TOKEN (if needed)\",\n            placeholder: \"Token for providers such as Turso/libSQL\",\n            secret: true,\n          },\n        ],\n      },\n    },\n  ],\n  // The default local database means this step is always satisfied.\n  isComplete: () => true,\n};\n\n/** Step 3 — how users sign in. Built-in account auth is non-blocking. */\nconst authStep: OnboardingStep = {\n  id: \"auth\",\n  order: 30,\n  required: false,\n  title: \"Authentication\",\n  description:\n    \"Built-in email/password accounts work by default. Add OAuth or access tokens only if you want another sign-in path.\",\n  methods: [\n    {\n      id: \"google-oauth\",\n      kind: \"form\",\n      label: \"Google OAuth\",\n      description: \"Add Google as an optional sign-in provider.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          { key: \"GOOGLE_CLIENT_ID\", label: \"GOOGLE_CLIENT_ID\" },\n          {\n            key: \"GOOGLE_CLIENT_SECRET\",\n            label: \"GOOGLE_CLIENT_SECRET\",\n            secret: true,\n          },\n        ],\n      },\n    },\n    {\n      id: \"github-oauth\",\n      kind: \"form\",\n      label: \"GitHub OAuth\",\n      description: \"Add GitHub as an optional sign-in provider.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          { key: \"GITHUB_CLIENT_ID\", label: \"GITHUB_CLIENT_ID\" },\n          {\n            key: \"GITHUB_CLIENT_SECRET\",\n            label: \"GITHUB_CLIENT_SECRET\",\n            secret: true,\n          },\n        ],\n      },\n    },\n  ],\n  isComplete: () => true,\n};\n\n/** Step 4 — transactional email (password resets, invitations). Optional. */\nconst emailStep: OnboardingStep = {\n  id: \"email\",\n  order: 40,\n  required: false,\n  title: \"Email delivery\",\n  description:\n    \"Optional for local work. Before deploying with password resets, invitations, or share notifications, connect an email provider.\",\n  methods: [\n    {\n      id: \"resend\",\n      kind: \"form\",\n      label: \"Resend\",\n      description: \"Use Resend for transactional email.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          {\n            key: \"RESEND_API_KEY\",\n            label: \"RESEND_API_KEY\",\n            placeholder: \"re_...\",\n            secret: true,\n          },\n          {\n            key: \"EMAIL_FROM\",\n            label: \"EMAIL_FROM (from address)\",\n            placeholder: \"Agent Native <noreply@yourdomain.com>\",\n          },\n          {\n            key: \"APP_NAME\",\n            label: \"APP_NAME (shown in invite emails)\",\n            placeholder: \"Acme Forms\",\n          },\n        ],\n      },\n    },\n    {\n      id: \"sendgrid\",\n      kind: \"form\",\n      label: \"SendGrid\",\n      description: \"Use SendGrid for transactional email.\",\n      payload: {\n        writeScope: \"workspace\",\n        fields: [\n          {\n            key: \"SENDGRID_API_KEY\",\n            label: \"SENDGRID_API_KEY\",\n            placeholder: \"SG....\",\n            secret: true,\n          },\n          {\n            key: \"EMAIL_FROM\",\n            label: \"EMAIL_FROM (from address)\",\n            placeholder: \"Agent Native <noreply@yourdomain.com>\",\n          },\n        ],\n      },\n    },\n  ],\n  isComplete: () => {\n    if (process.env.RESEND_API_KEY) return true;\n    // SendGrid rejects Resend's sandbox sender, so EMAIL_FROM must also be\n    // set — otherwise sendEmail() throws at runtime even though the API key\n    // is configured.\n    if (process.env.SENDGRID_API_KEY) return !!process.env.EMAIL_FROM;\n    return false;\n  },\n};\n\nlet registered = false;\n\n/** Idempotent. Safe to call from every plugin-mount call. */\nexport function registerDefaultOnboardingSteps(): void {\n  if (registered) return;\n  registered = true;\n  registerOnboardingStep(llmStep);\n  registerOnboardingStep(databaseStep);\n  registerOnboardingStep(authStep);\n  registerOnboardingStep(emailStep);\n}\n"]}

package/dist/provider-api/actions/query-staged-dataset.d.ts

@@ -3,7 +3,7 @@ declare const _default: import("../../action.js").ActionDefinition<{
     appId: string;
     where?: {
         column: string;
-        op: "equals" | "lt" | "gt" | "lte" | "gte" | "not_equals" | "contains" | "not_contains" | "exists" | "not_exists";
+        op: "equals" | "lt" | "gt" | "lte" | "gte" | "contains" | "not_equals" | "not_contains" | "exists" | "not_exists";
         value?: unknown;
     }[] | undefined;
     groupBy?: string[] | undefined;