@agent-native/core 0.176.5 → 0.176.6-nightly-20260903200904

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 8901
+- template files: 8902

package/corpus/templates/content/app/global.css

@@ -587,6 +587,7 @@
 .notion-editor .notion-task-list li label {
   display: flex;
   align-items: center;
+  align-self: start;
   min-height: 1.7em;
   margin-top: 0;
 }

package/corpus/templates/content/app/hooks/content-action-refresh.ts

@@ -0,0 +1,93 @@
+interface ActionQuery {
+  queryKey: readonly unknown[];
+}
+
+interface ActionEvent {
+  source?: string;
+  key?: string;
+}
+
+const COMMENT_MUTATIONS = new Set([
+  "add-comment",
+  "delete-comment",
+  "sync-notion-comments",
+  "update-comment",
+]);
+
+const DOCUMENT_MUTATIONS = new Set([
+  "create-and-link-notion-page",
+  "delete-document",
+  "delete-document-property",
+  "duplicate-document-property",
+  "edit-document",
+  "execute-builder-source-batch",
+  "execute-builder-source-execution",
+  "import-content-source",
+  "migrate-content-database-rows",
+  "move-document",
+  "mutate-content-database-block",
+  "process-builder-body-hydration",
+  "pull-builder-doc",
+  "pull-document",
+  "pull-notion-page",
+  "push-builder-doc",
+  "push-notion-page",
+  "reorder-document-property",
+  "resolve-local-folder-conflict",
+  "resolve-notion-sync-conflict",
+  "restore-document",
+  "restore-document-version",
+  "set-document-discoverability",
+  "set-document-property",
+  "set-image-alt-text",
+  "sync-local-folder-source",
+  "sync-manifest-local-folder-source",
+  "transcribe-media",
+  "update-document",
+]);
+
+const CONTENT_MUTATIONS = new Set([
+  ...COMMENT_MUTATIONS,
+  ...DOCUMENT_MUTATIONS,
+]);
+
+function queryTargetsDocument(query: ActionQuery, documentId: string): boolean {
+  if (query.queryKey[0] !== "action") return false;
+  if (
+    query.queryKey[1] !== "get-document" &&
+    query.queryKey[1] !== "list-comments"
+  ) {
+    return false;
+  }
+  const args = query.queryKey[2];
+  return (
+    !!args &&
+    typeof args === "object" &&
+    (("id" in args && args.id === documentId) ||
+      ("documentId" in args && args.documentId === documentId))
+  );
+}
+
+export function contentDocumentIdFromPathname(
+  pathname: string,
+): string | undefined {
+  const match = /^\/page\/([^/]+)\/?$/.exec(pathname);
+  return match?.[1] ? decodeURIComponent(match[1]) : undefined;
+}
+
+export function contentActionInvalidatePredicate(
+  pathname: string,
+): (query: ActionQuery, events: readonly ActionEvent[]) => boolean {
+  const documentId = contentDocumentIdFromPathname(pathname);
+  return (query, events) => {
+    if (documentId === undefined || !queryTargetsDocument(query, documentId)) {
+      return false;
+    }
+    return events.some(
+      (event) =>
+        event.source === "action" &&
+        typeof event.key === "string" &&
+        CONTENT_MUTATIONS.has(event.key),
+    );
+  };
+}

package/corpus/templates/content/app/hooks/use-db-sync.ts

@@ -1,20 +1,21 @@
-import { useDbSync as useCoreDbSync } from "@agent-native/core/client/hooks";
+import {
+  getBrowserTabId,
+  useDbSync as useCoreDbSync,
+} from "@agent-native/core/client/hooks";
 import { useQueryClient } from "@tanstack/react-query";
 
+import { contentActionInvalidatePredicate } from "./content-action-refresh";
+
 export function useDbSync() {
   const queryClient = useQueryClient();
+  const browserTabId = getBrowserTabId();
 
   useCoreDbSync({
     queryClient,
-    // refresh-notion-sync-status is a POST behind an ["action"]-keyed query
-    // (useDocumentSyncStatus). Without suppression its own action-change event
-    // invalidates all action queries, which refetches the POST, which emits
-    // the next event — a self-sustaining refetch storm on every poll tick.
-    suppressActionInvalidationFor: [
-      "process-builder-body-hydration",
-      "refresh-content-database-source",
-      "refresh-notion-sync-status",
-    ],
+    ignoreSource: browserTabId,
+    actionInvalidatePredicate: contentActionInvalidatePredicate(
+      typeof window === "undefined" ? "" : window.location.pathname,
+    ),
     queryKeys: [
       "action",
       "document-sync",

package/dist/client/ClientOnly.js

@@ -1,4 +1,5 @@
-import { useState, useEffect } from "react";
+import { useEffect, useLayoutEffect, useState } from "react";
+const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
 /**
  * Renders children only on the client (after hydration).
  *
@@ -9,7 +10,9 @@ import { useState, useEffect } from "react";
  */
 export function ClientOnly({ children, fallback, }) {
     const [mounted, setMounted] = useState(false);
-    useEffect(() => setMounted(true), []);
+    // The static shell and client tree must hand off before paint or the loader
+    // flashes again while the authenticated app mounts.
+    useBrowserLayoutEffect(() => setMounted(true), []);
     if (!mounted)
         return fallback ?? null;
     return children;

package/dist/client/app-providers.js

@@ -57,6 +57,7 @@ import { useEffect, useRef } from "react";
 import { useInRouterContext } from "react-router";
 import { isHumanReadableDocumentTitle, normalizeDocumentTitle, } from "../shared/document-title.js";
 import { getSsrBetaRedirectScriptBody } from "../shared/ssr-beta-redirect.js";
+import { agentNativePath } from "./api-path.js";
 import { ClientOnly } from "./ClientOnly.js";
 import { DefaultSpinner } from "./DefaultSpinner.js";
 import { EnvironmentBadge } from "./EnvironmentBadge.js";
@@ -70,7 +71,9 @@ import { EMBEDDED_THEME_CHANGE_EVENT, applyEmbeddedThemeUpdate, parseEmbeddedThe
 import { createAgentNativeServerActionWebMcpRegistration } from "./webmcp.js";
 const DEFAULT_TOASTER = (_jsx(Toaster, { richColors: true, position: "bottom-left", offset: { bottom: 44, left: 32 }, mobileOffset: { bottom: 44, left: 16 } }));
 function EarlyBetaRedirectScript() {
-    return (_jsx("script", { "data-agent-native-beta-redirect": "1", dangerouslySetInnerHTML: { __html: getSsrBetaRedirectScriptBody() } }));
+    return (_jsx("script", { "data-agent-native-beta-redirect": "1", dangerouslySetInnerHTML: {
+            __html: getSsrBetaRedirectScriptBody(agentNativePath("/_agent-native/auth/session")),
+        } }));
 }
 function RoutedAppEnhancements() {
     const isInRouter = useInRouterContext();

package/dist/client/use-db-sync.d.ts

@@ -101,7 +101,8 @@ export declare function subscribeSyncEvents(options: SubscribeSyncEventsOptions)
  *   value. Use a per-tab ID so the UI ignores its own writes while still
  *   picking up changes from other tabs, agents, and scripts.
  * @param options.actionInvalidatePredicate - Optional filter for the broad
- *   compatibility invalidate triggered by `action` events. Use this to keep
+ *   compatibility invalidate triggered by sync events. The current event batch
+ *   is provided so apps can preserve action-level targeting. Use this to keep
  *   expensive active queries on explicit-refresh semantics while still letting
  *   normal source-versioned queries react through `useChangeVersion`.
  * @param options.suppressActionInvalidationFor - Action names whose sync events
@@ -120,7 +121,7 @@ export declare function useDbSync(options?: {
     fallbackInterval?: number;
     pauseWhenHidden?: boolean;
     ignoreSource?: string;
-    actionInvalidatePredicate?: (query: Query) => boolean;
+    actionInvalidatePredicate?: (query: Query, events: readonly SyncEvent[]) => boolean;
     suppressActionInvalidationFor?: string[];
 }): void;
 /** @deprecated Use useDbSync instead */

package/dist/client/use-db-sync.js

@@ -1174,7 +1174,8 @@ export function subscribeSyncEvents(options) {
  *   value. Use a per-tab ID so the UI ignores its own writes while still
  *   picking up changes from other tabs, agents, and scripts.
  * @param options.actionInvalidatePredicate - Optional filter for the broad
- *   compatibility invalidate triggered by `action` events. Use this to keep
+ *   compatibility invalidate triggered by sync events. The current event batch
+ *   is provided so apps can preserve action-level targeting. Use this to keep
  *   expensive active queries on explicit-refresh semantics while still letting
  *   normal source-versioned queries react through `useChangeVersion`.
  * @param options.suppressActionInvalidationFor - Action names whose sync events
@@ -1351,7 +1352,10 @@ export function useDbSync(options = {}) {
                     // makes one agent write fan out across unrelated provider reads,
                     // dashboards, and background status checks. Older apps that still
                     // need broad compatibility can opt in with a predicate.
-                    const predicate = actionInvalidatePredicateRef.current;
+                    const appPredicate = actionInvalidatePredicateRef.current;
+                    const predicate = appPredicate
+                        ? (query) => appPredicate(query, invalidating)
+                        : undefined;
                     invalidateWithoutCancel(predicate ? { predicate } : { queryKey: ["action"] });
                 }
                 // Framework-level invalidate: a small, fixed list of query-key
@@ -1394,7 +1398,10 @@ export function useDbSync(options = {}) {
                             // ["action"] query regardless of what the app opted out of — and
                             // an app cannot work around it, because both the prefix and this
                             // call are framework-owned.
-                            const predicate = actionInvalidatePredicateRef.current;
+                            const appPredicate = actionInvalidatePredicateRef.current;
+                            const predicate = appPredicate
+                                ? (query) => appPredicate(query, invalidating)
+                                : undefined;
                             invalidateWithoutCancel(predicate ? { predicate } : { queryKey: ["action"] });
                         }
                         if (!hasActionEvent || hasFrameworkPrefixEvent) {

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
-    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
+    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
-    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
+    error?: undefined;
 }>>;

package/dist/notifications/routes.d.ts

@@ -16,18 +16,18 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
     error?: undefined;
     ok?: undefined;
 } | {
-    count?: undefined;
     updated: number;
     error?: undefined;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
     error: string;
     ok?: undefined;
-} | {
     count?: undefined;
+} | {
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
+    count?: undefined;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
+    error?: undefined;
+    ok?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
+} | {
     error?: undefined;
     ok?: undefined;
-} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-    error?: undefined;
-    ok?: undefined;
 } | {
+    ok?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
-    ok?: undefined;
 } | {
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    error?: undefined;
     ok: boolean;
 }>>;

package/dist/observability/traces.js

@@ -1,7 +1,7 @@
 import { captureError } from "../server/capture-error.js";
 import { getRequestContext } from "../server/request-context.js";
 import { MAX_AI_CONTENT_BYTES, MAX_AI_SPANS_PER_RUN, boundAiContent, emitAiSpanEvent, emitAiTraceEvent, resolveAiError, toAiErrorDetail, toPostHogMessages, } from "./posthog-ai.js";
-import { endAgentSpan, startAgentSpan } from "./tracing.js";
+import { endAgentSpan, startAgentSpan, withAgentSpanContext, } from "./tracing.js";
 import { trackingIdentityProperties } from "./tracking-identity.js";
 function spanId() {
     return `span-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -384,10 +384,9 @@ export async function instrumentAgentLoop(opts) {
     // don't have to thread it down by hand.
     const browserSessionId = opts.browserSessionId ?? getRequestContext()?.browserSessionId;
     // 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).
+    // installed `@opentelemetry/api` and registered a provider. The root is
+    // installed as the active context while the loop runs so child tool/model
+    // spans have a real parent relationship in the exported trace.
     const otelRunSpanPromise = startAgentSpan("agent.run", {
         "agent.run_id": runId,
         "agent.thread_id": threadId ?? undefined,
@@ -401,6 +400,7 @@ export async function instrumentAgentLoop(opts) {
             ? opts.experimentAssignments[0].variantId
             : undefined,
     });
+    let otelRunSpan = null;
     const spans = [];
     let toolInvocationCounter = 0;
     // Keyed by counter to handle concurrent calls to the same tool name
@@ -433,6 +433,82 @@ export async function instrumentAgentLoop(opts) {
     /** The call currently streaming, or the last one that streamed — text and
      *  usage arriving between calls belong to the call that just finished. */
     const currentRoundTrip = () => modelRoundTrips[modelRoundTrips.length - 1];
+    let calculateCost;
+    const calculateUsageCost = (callUsage) => {
+        if (!calculateCost || !callUsage)
+            return undefined;
+        try {
+            return calculateCost(callUsage.inputTokens, callUsage.outputTokens, callUsage.model, callUsage.cacheReadTokens, callUsage.cacheWriteTokens);
+        }
+        catch {
+            // coercion-ok: cost estimation is enrichment and cannot fail tracing.
+            return undefined;
+        }
+    };
+    const pendingOtelModelSpans = new Map();
+    const openOtelModelSpans = new Set();
+    const modelSpansAwaitingFinalError = new Set();
+    const modelSpanAttributes = (index) => {
+        const trip = modelRoundTrips[index];
+        const callUsage = trip?.usage;
+        return {
+            "llm.model": callUsage?.model ?? loopOpts.model,
+            "llm.call_index": index,
+            "llm.stop_reason": trip?.stopReason,
+            "llm.input_tokens": callUsage?.inputTokens,
+            "llm.output_tokens": callUsage?.outputTokens,
+            "llm.cache_read_tokens": callUsage?.cacheReadTokens,
+            "llm.cache_write_tokens": callUsage?.cacheWriteTokens,
+            "llm.cost_cents_x100": calculateUsageCost(callUsage),
+        };
+    };
+    const startOtelModelSpan = (index) => {
+        const entry = {
+            spanPromise: Promise.resolve(null),
+            span: null,
+            endResult: undefined,
+            ended: false,
+        };
+        entry.spanPromise = startAgentSpan("llm.call", {
+            "llm.model": loopOpts.model,
+            "llm.call_index": index,
+        }, otelRunSpan);
+        pendingOtelModelSpans.set(index, entry);
+        void entry.spanPromise.then((span) => {
+            if (!span || entry.ended)
+                return;
+            if (entry.endResult) {
+                entry.ended = true;
+                endAgentSpan(span, entry.endResult);
+            }
+            else {
+                entry.span = span;
+                openOtelModelSpans.add(span);
+            }
+        });
+    };
+    const finishOtelModelSpan = (index, result) => {
+        const entry = pendingOtelModelSpans.get(index);
+        if (!entry || entry.ended)
+            return;
+        entry.endResult = result;
+        if (!entry.span)
+            return;
+        entry.ended = true;
+        openOtelModelSpans.delete(entry.span);
+        endAgentSpan(entry.span, result);
+    };
+    const finishAwaitingOtelModelSpans = (finalErrorMessage = null) => {
+        for (const tripIndex of modelSpansAwaitingFinalError) {
+            finishOtelModelSpan(tripIndex, {
+                status: "error",
+                errorMessage: finalErrorMessage ?? "Model stream ended before completion.",
+                attributes: modelSpanAttributes(tripIndex),
+                endTime: modelRoundTrips[tripIndex]?.end,
+            });
+        }
+        modelSpansAwaitingFinalError.clear();
+    };
     const modelStreamIntervals = [];
     let modelStreamOpenedAt = null;
     /** Tool span id → the round-trip that requested it. */
@@ -507,6 +583,7 @@ export async function instrumentAgentLoop(opts) {
             // counted as a successful delegated generation. A later clear/done means
             // the wrapper recovered and finished cleanly, so reset in that case.
             if (event.type === "clear" || event.type === "done") {
+                finishAwaitingOtelModelSpans();
                 runStatus = "success";
                 errorMessage = null;
                 cutOffReason = null;
@@ -539,8 +616,13 @@ export async function instrumentAgentLoop(opts) {
                 // The emitter brackets these itself, so a repeated start or an
                 // unmatched end is a no-op here rather than a fabricated interval.
                 if (event.status === "start") {
+                    // A reasonless closure is emitted before the agent loop decides
+                    // whether to retry. If another attempt starts, the old attempt is
+                    // definitely final and must not span the retry backoff.
+                    finishAwaitingOtelModelSpans();
                     if (modelStreamOpenedAt === null) {
                         modelStreamOpenedAt = Date.now();
+                        const tripIndex = modelRoundTrips.length;
                         modelRoundTrips.push({
                             spanId: spanId(),
                             start: modelStreamOpenedAt,
@@ -561,17 +643,25 @@ export async function instrumentAgentLoop(opts) {
                                 : {}),
                             assistantText: [],
                         });
+                        startOtelModelSpan(tripIndex);
                     }
                 }
                 else if (modelStreamOpenedAt !== null) {
                     const end = Date.now();
                     modelStreamIntervals.push({ start: modelStreamOpenedAt, end });
+                    const tripIndex = modelRoundTrips.length - 1;
                     const trip = currentRoundTrip();
                     if (trip) {
                         trip.end = end;
                         if (event.reason)
                             trip.stopReason = event.reason;
                     }
+                    if (event.reason === undefined || event.reason === "error") {
+                        // The engine emits this from a `finally`, before the outer catch
+                        // has classified a provider error. Defer ending the span so that
+                        // the real error message wins over a generic stream-ended value.
+                        modelSpansAwaitingFinalError.add(tripIndex);
+                    }
                     modelStreamOpenedAt = null;
                 }
             }
@@ -604,7 +694,7 @@ export async function instrumentAgentLoop(opts) {
                     toolCallIdToCounter.set(event.id, counter);
                 void startAgentSpan("tool.call", {
                     "tool.name": event.tool,
-                }).then((span) => {
+                }, otelRunSpan).then((span) => {
                     if (!span)
                         return;
                     // If `tool_done` already ran for this call, end the span now with the
@@ -769,7 +859,8 @@ export async function instrumentAgentLoop(opts) {
         ? [...loopOpts.messages]
         : loopOpts.messages;
     try {
-        usage = await runAgentLoop({
+        otelRunSpan = await otelRunSpanPromise;
+        usage = await withAgentSpanContext(otelRunSpan, () => runAgentLoop({
             ...loopOpts,
             runId,
             send: instrumentedSend,
@@ -782,7 +873,7 @@ export async function instrumentAgentLoop(opts) {
                     trip.usage = callUsage;
                 loopOpts.onUsage?.(callUsage);
             },
-        });
+        }));
     }
     catch (err) {
         const classification = opts.classifyError?.(err) ?? null;
@@ -814,6 +905,9 @@ export async function instrumentAgentLoop(opts) {
             // model was still running when the run stopped, so the interval closes at
             // the run's end rather than being dropped.
             const failedInsideModelCall = modelStreamOpenedAt !== null;
+            const interruptedModelRoundTrip = modelStreamOpenedAt !== null && modelRoundTrips.length > 0
+                ? modelRoundTrips.length - 1
+                : null;
             if (modelStreamOpenedAt !== null) {
                 modelStreamIntervals.push({ start: modelStreamOpenedAt, end: runEnd });
                 const trip = currentRoundTrip();
@@ -890,7 +984,6 @@ export async function instrumentAgentLoop(opts) {
             let costCentsX100 = 0;
             // Held for the per-generation costs below, which price each round-trip
             // from its own tokens rather than splitting the run total.
-            let calculateCost;
             try {
                 ({ calculateCost } = await import("../usage/store.js"));
                 if (usage) {
@@ -937,8 +1030,8 @@ export async function instrumentAgentLoop(opts) {
                 llmCallCount =
                     usage?.llmCalls ??
                         // Compatibility for custom loop implementations that predate the
-                        // attempt counter: a measured run still counts as one call.
-                        1;
+                        // attempt counter: observed brackets still count every attempt.
+                        (modelRoundTrips.length > 0 ? modelRoundTrips.length : 1);
                 const runUsage = usage ?? {
                     inputTokens: 0,
                     outputTokens: 0,
@@ -1308,13 +1401,34 @@ 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.
+            // OpenTelemetry export (no-op unless a provider is registered). Bracketed
+            // model calls have already emitted live spans; engines without brackets
+            // get one aggregate generation. End any tool/model spans still open and
+            // then end the run span. Awaited so spans are emitted before return.
             try {
-                if (usage) {
-                    endAgentSpan(await startAgentSpan("llm.call", {}), {
+                if (interruptedModelRoundTrip !== null) {
+                    finishOtelModelSpan(interruptedModelRoundTrip, {
+                        status: "error",
+                        errorMessage: errorMessage ?? "Model stream interrupted before completion.",
+                        attributes: modelSpanAttributes(interruptedModelRoundTrip),
+                        endTime: runEnd,
+                    });
+                }
+                for (const [tripIndex, trip] of modelRoundTrips.entries()) {
+                    if (trip.stopReason && trip.stopReason !== "error") {
+                        finishOtelModelSpan(tripIndex, {
+                            status: "success",
+                            errorMessage: null,
+                            attributes: modelSpanAttributes(tripIndex),
+                            endTime: trip.end,
+                        });
+                    }
+                }
+                finishAwaitingOtelModelSpans(errorMessage);
+                await Promise.all([...pendingOtelModelSpans.values()].map((entry) => entry.spanPromise));
+                if (usage && modelRoundTrips.length === 0) {
+                    const aggregateLlmSpan = await withAgentSpanContext(otelRunSpan, () => startAgentSpan("llm.call", {}, otelRunSpan));
+                    endAgentSpan(aggregateLlmSpan, {
                         status: runStatus,
                         errorMessage,
                         attributes: {
@@ -1327,6 +1441,13 @@ export async function instrumentAgentLoop(opts) {
                         },
                     });
                 }
+                for (const modelSpan of openOtelModelSpans) {
+                    endAgentSpan(modelSpan, {
+                        status: "error",
+                        errorMessage: "Agent run ended before model_stream completed.",
+                    });
+                }
+                openOtelModelSpans.clear();
                 for (const toolSpan of openOtelToolSpans) {
                     endAgentSpan(toolSpan, {
                         status: "error",
@@ -1334,10 +1455,11 @@ export async function instrumentAgentLoop(opts) {
                     });
                 }
                 openOtelToolSpans.clear();
-                endAgentSpan(await otelRunSpanPromise, {
+                endAgentSpan(otelRunSpan, {
                     status: runStatus,
                     errorMessage,
                     attributes: {
+                        "agent.llm_calls": llmCallCount,
                         "agent.tool_calls": toolCallCount,
                         "agent.successful_tools": successfulTools,
                         "agent.failed_tools": failedTools,

package/dist/observability/tracing.d.ts

@@ -36,7 +36,7 @@ export interface AgentSpan {
         name?: string;
         message: string;
     }): void;
-    end(): void;
+    end(endTime?: unknown): void;
 }
 /** OTel `SpanStatusCode` values, inlined so we don't need the api types here. */
 export declare const SPAN_STATUS_OK = 1;
@@ -44,14 +44,30 @@ export declare const SPAN_STATUS_ERROR = 2;
 interface AgentTracer {
     startSpan(name: string, options?: {
         attributes?: Record<string, string | number | boolean>;
-    }): AgentSpan;
+    }, context?: unknown): AgentSpan;
+}
+interface AgentTraceRuntime {
+    tracer: AgentTracer;
+    context?: {
+        active(): unknown;
+        with<T>(context: unknown, callback: () => T): T;
+    };
+    trace?: {
+        setSpan(context: unknown, span: AgentSpan): unknown;
+    };
 }
 /**
  * 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>;
+export declare function startAgentSpan(name: string, attributes?: Record<string, string | number | boolean | null | undefined>, parentSpan?: AgentSpan | null): Promise<AgentSpan | null>;
+/**
+ * Run a callback with the supplied span installed as the active OTel span so
+ * spans created by the callback become descendants of it. The bridge is
+ * deliberately best-effort: telemetry setup must never change agent behavior.
+ */
+export declare function withAgentSpanContext<T>(span: AgentSpan | null, callback: () => T): T;
 /**
  * Finish a span, setting OK/ERROR status and recording the error message when
  * present. Safe to call with `null` (no-op) and never throws.
@@ -60,6 +76,7 @@ export declare function endAgentSpan(span: AgentSpan | null, result?: {
     status?: "success" | "error";
     errorMessage?: string | null;
     attributes?: Record<string, string | number | boolean | null | undefined>;
+    endTime?: number;
 }): void;
 /** For tests — reset the cached tracer so a fresh provider can be detected. */
 export declare function __resetAgentTracerCache(): void;
@@ -69,4 +86,6 @@ export declare function __resetAgentTracerCache(): void;
  * to simulate "no tracer available".
  */
 export declare function __setAgentTracerForTests(tracer: AgentTracer | null): void;
+/** For tests — inject a runtime with an active-context implementation. */
+export declare function __setAgentTraceRuntimeForTests(runtime: AgentTraceRuntime | null): void;
 export {};