@agent-native/core 0.169.1 → 0.171.0

package/dist/mcp-client/oauth-client.d.ts

@@ -74,6 +74,7 @@ export declare class McpOAuthClientProvider implements OAuthClientProvider {
 }
 export declare function startMcpOAuthAuthorization(options: McpOAuthProviderOptions & {
     scope?: string;
+    resourceMetadataUrl?: string;
 }): Promise<McpOAuthStartResult>;
 export declare function finishMcpOAuthAuthorization(options: McpOAuthProviderOptions & {
     authorizationCode: string;
@@ -99,6 +100,12 @@ export declare function getMcpOAuthConnectionState(options: {
     scopeId: string;
     serverUrl: string;
 }): Promise<OAuthCredentialState<McpOAuthCredentialBundle>>;
+export declare function markMcpOAuthReconnectRequired(options: {
+    key: string;
+    scope: "user" | "org";
+    scopeId: string;
+    serverUrl: string;
+}): Promise<boolean>;
 export declare function deleteMcpOAuthCredentials(options: {
     key: string;
     scope: "user" | "org";

package/dist/mcp-client/oauth-client.js

@@ -8,7 +8,7 @@
  */
 import { auth, refreshAuthorization, validateAuthorizationResponseIssuer, } from "@modelcontextprotocol/client";
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
-import { readOAuthCredentialState, resolveOAuthCredentialAccess, revokeOAuthCredential, saveOAuthCredential, } from "../oauth-tokens/lifecycle.js";
+import { readOAuthCredentialState, resolveOAuthCredentialAccess, markOAuthReconnectRequired, revokeOAuthCredential, saveOAuthCredential, } from "../oauth-tokens/lifecycle.js";
 import { validateRemoteUrl } from "./remote-url.js";
 const TOKEN_EXPIRY_SKEW_MS = 60_000;
 const MAX_OAUTH_REDIRECTS = 5;
@@ -312,6 +312,9 @@ export async function startMcpOAuthAuthorization(options) {
     const result = await auth(provider, {
         serverUrl: options.serverUrl,
         scope: options.scope,
+        ...(options.resourceMetadataUrl
+            ? { resourceMetadataUrl: new URL(options.resourceMetadataUrl) }
+            : {}),
         fetchFn: guardedOAuthFetch(),
     });
     if (result !== "REDIRECT" || !provider.authorizationRedirect) {
@@ -408,6 +411,14 @@ export async function getMcpOAuthConnectionState(options) {
         validateCredential: (credential) => serverUrlsMatch(credential.serverUrl, serverUrl),
     });
 }
+export async function markMcpOAuthReconnectRequired(options) {
+    const serverUrl = canonicalServerUrl(options.serverUrl);
+    return markOAuthReconnectRequired(credentialIdentity({ ...options, serverUrl }), {
+        allowLegacy: true,
+        legacyAccountKey: true,
+        validateCredential: (credential) => serverUrlsMatch(credential.serverUrl, serverUrl),
+    });
+}
 export async function deleteMcpOAuthCredentials(options) {
     if (!options.serverUrl)
         return false;

package/dist/oauth-tokens/index.d.ts

@@ -1,3 +1,3 @@
 export { getOAuthTokens, getOAuthTokenSnapshot, OAuthAccountOwnedByOtherUserError, saveOAuthTokens, replaceOAuthTokensIfRevision, deleteOAuthTokens, deleteOAuthTokensIfRevision, listOAuthAccounts, listOAuthAccountsByOwner, hasOAuthTokens, setOAuthDisplayName, } from "./store.js";
-export { readOAuthCredentialState, resolveOAuthCredentialAccess, revokeOAuthCredential, saveOAuthCredential, type OAuthCredential, type OAuthCredentialIdentity, type OAuthCredentialOwner, type OAuthCredentialState, type OAuthRevocationResult, } from "./lifecycle.js";
+export { readOAuthCredentialState, resolveOAuthCredentialAccess, markOAuthReconnectRequired, revokeOAuthCredential, saveOAuthCredential, type OAuthCredential, type OAuthCredentialIdentity, type OAuthCredentialOwner, type OAuthCredentialState, type OAuthRevocationResult, } from "./lifecycle.js";
 export { refreshExpiringGoogleTokens, startGoogleTokenRefreshLoop, } from "./google-refresh.js";

package/dist/oauth-tokens/index.js

@@ -1,3 +1,3 @@
 export { getOAuthTokens, getOAuthTokenSnapshot, OAuthAccountOwnedByOtherUserError, saveOAuthTokens, replaceOAuthTokensIfRevision, deleteOAuthTokens, deleteOAuthTokensIfRevision, listOAuthAccounts, listOAuthAccountsByOwner, hasOAuthTokens, setOAuthDisplayName, } from "./store.js";
-export { readOAuthCredentialState, resolveOAuthCredentialAccess, revokeOAuthCredential, saveOAuthCredential, } from "./lifecycle.js";
+export { readOAuthCredentialState, resolveOAuthCredentialAccess, markOAuthReconnectRequired, revokeOAuthCredential, saveOAuthCredential, } from "./lifecycle.js";
 export { refreshExpiringGoogleTokens, startGoogleTokenRefreshLoop, } from "./google-refresh.js";

package/dist/oauth-tokens/lifecycle.d.ts

@@ -67,6 +67,17 @@ export declare function readOAuthCredentialState<T extends OAuthCredential = OAu
     now?: number;
     validateCredential?: (credential: T) => boolean;
 }): Promise<OAuthCredentialState<T>>;
+/**
+ * Force a stored credential into `reconnect_required` without a refresh attempt.
+ * For a token the provider rejected server-side (e.g. a 401/403) while it still
+ * looks valid locally, so the credential itself carries the reconnect signal
+ * instead of a side channel. Returns false when there is nothing to mark.
+ */
+export declare function markOAuthReconnectRequired<T extends OAuthCredential = OAuthCredential>(identity: OAuthCredentialIdentity, options?: {
+    allowLegacy?: boolean;
+    legacyAccountKey?: boolean;
+    validateCredential?: (credential: T) => boolean;
+}): Promise<boolean>;
 export declare function resolveOAuthCredentialAccess<T extends OAuthCredential = OAuthCredential>(identity: OAuthCredentialIdentity, options: {
     refresh: (context: OAuthRefreshContext<T>) => Promise<T>;
     allowLegacy?: boolean;

package/dist/oauth-tokens/lifecycle.js

@@ -232,6 +232,23 @@ export async function readOAuthCredentialState(identity, options = {}) {
 async function markReconnectRequired(identity, snapshot, legacyAccountKey) {
     await replaceOAuthTokensIfRevision(identity.provider, storageAccountId(identity, legacyAccountKey), snapshot.storageOwner, snapshot.revision, snapshot.legacyRevision, snapshot.storageVersion, withLifecycle(identity, snapshot.credential, "refresh_failed"));
 }
+/**
+ * Force a stored credential into `reconnect_required` without a refresh attempt.
+ * For a token the provider rejected server-side (e.g. a 401/403) while it still
+ * looks valid locally, so the credential itself carries the reconnect signal
+ * instead of a side channel. Returns false when there is nothing to mark.
+ */
+export async function markOAuthReconnectRequired(identity, options = {}) {
+    const stored = await readStoredOAuthCredentialState(identity, {
+        allowLegacy: options.allowLegacy,
+        legacyAccountKey: options.legacyAccountKey,
+        validateCredential: options.validateCredential,
+    });
+    if (stored.kind === "missing" || stored.kind === "malformed")
+        return false;
+    await markReconnectRequired(identity, stored, options.legacyAccountKey === true);
+    return true;
+}
 export async function resolveOAuthCredentialAccess(identity, options) {
     assertIdentity(identity);
     const dependencies = { ...defaultDependencies, ...options.dependencies };

package/dist/oauth-tokens/store.js

@@ -318,6 +318,13 @@ export async function saveOAuthTokens(provider, accountId, tokens, owner) {
         ...(existingTokens ?? {}),
         ...cleanedIncomingTokens,
     };
+    const existingScope = existingTokens?.scope;
+    const incomingScope = cleanedIncomingTokens.scope;
+    if (typeof existingScope === "string" && typeof incomingScope === "string") {
+        tokensToStore.scope = Array.from(new Set(`${existingScope} ${incomingScope}`
+            .split(/[\s,]+/)
+            .filter((scope) => scope.length > 0))).join(" ");
+    }
     const result = await client.execute({
         sql: isPostgres()
             ? `INSERT INTO ${table} (provider, account_id, owner, display_name, tokens, updated_at, revision) VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT (provider, account_id) DO UPDATE SET owner=EXCLUDED.owner, display_name=COALESCE(EXCLUDED.display_name, ${table}.display_name), tokens=EXCLUDED.tokens, updated_at=EXCLUDED.updated_at, revision=GREATEST(COALESCE(${table}.revision, 0) + 1, EXCLUDED.revision) WHERE ${table}.owner = EXCLUDED.owner OR (LOWER(${table}.owner) = LOWER(EXCLUDED.owner) AND LOWER(${table}.owner) LIKE 'user:%' AND LOWER(EXCLUDED.owner) LIKE 'user:%')`

package/dist/observability/posthog-ai.d.ts

@@ -12,6 +12,18 @@
  * PostHog's `$session_id`: the latter is the browser session used for session
  * replay, and the two are different lifetimes.
  *
+ * PostHog DERIVES a trace's latency, tokens and cost from its children — its
+ * trace query sums `$ai_latency` over every event whose `$ai_parent_id` is the
+ * trace or absent, and sums tokens/cost over `$ai_generation` / `$ai_embedding`
+ * only. So the `$ai_trace` event carries none of those: an `$ai_latency` here
+ * was counted *in addition to* the generation's and reported roughly twice the
+ * real duration. Run totals ride along under plain names for the non-PostHog
+ * backends, which have no such aggregation.
+ *
+ * Custom properties do NOT take an `$ai_` prefix. That namespace is PostHog's
+ * schema, and a name it does not define today it may define tomorrow with
+ * different meaning — `input_truncated` / `spans_dropped` cannot collide.
+ *
  * Content (`$ai_input` / `$ai_output_choices` / `$ai_input_state` /
  * `$ai_output_state`) is gated on config and always OMITTED when disabled.
  * Sending `[]` instead would be indistinguishable from a run that genuinely had
@@ -49,7 +61,9 @@ export interface AiTraceEventInput {
     spanName: string;
     model: string;
     provider: string;
-    latencySeconds: number;
+    /** Wall-clock duration of the whole run. Reported under `duration_ms`, not
+     *  `$ai_latency` — see the aggregation note at the top of this file. */
+    durationMs: number;
     isError: boolean;
     error?: AiErrorDetail;
     inputTokens?: number;

package/dist/observability/posthog-ai.js

@@ -12,6 +12,18 @@
  * PostHog's `$session_id`: the latter is the browser session used for session
  * replay, and the two are different lifetimes.
  *
+ * PostHog DERIVES a trace's latency, tokens and cost from its children — its
+ * trace query sums `$ai_latency` over every event whose `$ai_parent_id` is the
+ * trace or absent, and sums tokens/cost over `$ai_generation` / `$ai_embedding`
+ * only. So the `$ai_trace` event carries none of those: an `$ai_latency` here
+ * was counted *in addition to* the generation's and reported roughly twice the
+ * real duration. Run totals ride along under plain names for the non-PostHog
+ * backends, which have no such aggregation.
+ *
+ * Custom properties do NOT take an `$ai_` prefix. That namespace is PostHog's
+ * schema, and a name it does not define today it may define tomorrow with
+ * different meaning — `input_truncated` / `spans_dropped` cannot collide.
+ *
  * Content (`$ai_input` / `$ai_output_choices` / `$ai_input_state` /
  * `$ai_output_state`) is gated on config and always OMITTED when disabled.
  * Sending `[]` instead would be indistinguishable from a run that genuinely had
@@ -26,7 +38,7 @@ import { boundedText } from "../tracking/redaction.js";
 export const MAX_AI_CONTENT_BYTES = 128 * 1024;
 /** Hard ceiling on emitted `$ai_span` events per run. */
 export const MAX_AI_SPANS_PER_RUN = 100;
-function trackAiEvent(name, properties, userId) {
+function trackAiEvent(name, properties, userId, occurredAt) {
     for (const key of Object.keys(properties)) {
         if (properties[key] === undefined)
             delete properties[key];
@@ -34,7 +46,7 @@ function trackAiEvent(name, properties, userId) {
     try {
         void import("../tracking/registry.js")
             .then(({ track }) => {
-            track(name, properties, { userId: userId ?? undefined });
+            track(name, properties, { userId: userId ?? undefined, occurredAt });
         })
             .catch(() => { });
         // coercion-ok: a throw here would break the run it is observing
@@ -84,19 +96,19 @@ export function emitAiTraceEvent(input) {
         $ai_span_name: input.spanName,
         $ai_model: input.model,
         $ai_provider: input.provider,
-        $ai_latency: input.latencySeconds,
         $ai_is_error: input.isError,
         $ai_error: input.error,
-        $ai_input_tokens: input.inputTokens,
-        $ai_output_tokens: input.outputTokens,
-        $ai_total_cost_usd: input.costUsd,
+        duration_ms: Math.round(input.durationMs),
+        input_tokens: input.inputTokens,
+        output_tokens: input.outputTokens,
+        cost_usd: input.costUsd,
         $ai_input_state: inputContent?.value,
         $ai_output_state: outputContent?.value,
-        $ai_input_truncated: inputContent?.truncated || undefined,
-        $ai_output_truncated: outputContent?.truncated || undefined,
+        input_truncated: inputContent?.truncated || undefined,
+        output_truncated: outputContent?.truncated || undefined,
         $session_id: input.browserSessionId,
         created_at: new Date(input.createdAt).toISOString(),
-    }, input.userId);
+    }, input.userId, input.createdAt);
 }
 export function emitAiSpanEvent(input) {
     const inputContent = input.inputState === undefined
@@ -117,11 +129,11 @@ export function emitAiSpanEvent(input) {
         $ai_error: input.error,
         $ai_input_state: inputContent?.value,
         $ai_output_state: outputContent?.value,
-        $ai_input_truncated: inputContent?.truncated || undefined,
-        $ai_output_truncated: outputContent?.truncated || undefined,
+        input_truncated: inputContent?.truncated || undefined,
+        output_truncated: outputContent?.truncated || undefined,
         $session_id: input.browserSessionId,
         created_at: new Date(input.createdAt).toISOString(),
-    }, input.userId);
+    }, input.userId, input.createdAt);
 }
 /**
  * Emit PostHog's documented manual feedback event for an LLM trace.

package/dist/observability/traces.js

@@ -24,6 +24,37 @@ function llmProviderFromEngine(engineName, model) {
 function costUsdFromCenticents(value) {
     return Math.round((value / 10_000) * 1_000_000) / 1_000_000;
 }
+/**
+ * Wall-clock time covered by these intervals, counting overlap once.
+ *
+ * Tools run concurrently, so summing durations reports more elapsed time than
+ * actually passed — enough to drive a derived remainder to zero on a parallel
+ * fan-out.
+ */
+function coveredDurationMs(intervals) {
+    if (intervals.length === 0)
+        return 0;
+    const sorted = [...intervals].sort((a, b) => a.start - b.start);
+    let covered = 0;
+    let { start: openStart, end: openEnd } = sorted[0];
+    for (const { start, end } of sorted.slice(1)) {
+        if (start > openEnd) {
+            covered += openEnd - openStart;
+            openStart = start;
+            openEnd = end;
+        }
+        else if (end > openEnd) {
+            openEnd = end;
+        }
+    }
+    return covered + (openEnd - openStart);
+}
+function spanIntervals(spans) {
+    return spans.map((s) => ({
+        start: s.createdAt,
+        end: s.createdAt + Math.max(0, s.durationMs),
+    }));
+}
 /**
  * Project run metadata onto flat PostHog trace properties.
  *
@@ -144,7 +175,7 @@ function emitLlmGenerationTrackingEvent(args) {
         $ai_provider: provider,
         $ai_input_tokens: args.inputTokens,
         $ai_output_tokens: args.outputTokens,
-        $ai_latency: Math.round((args.durationMs / 1000) * 1000) / 1000,
+        $ai_latency: Math.round(args.llmDurationMs) / 1000,
         $ai_is_error: args.status === "error",
         $ai_error: args.status === "error"
             ? toAiErrorDetail(error, {
@@ -153,16 +184,24 @@ function emitLlmGenerationTrackingEvent(args) {
                 retryable: terminalRetryable,
             })
             : undefined,
+        // Every engine here streams (`messages.stream`, `streamText`, gateway SSE),
+        // which is also what makes `$ai_time_to_first_token` meaningful.
+        $ai_stream: true,
         $ai_cache_read_input_tokens: args.cacheReadTokens,
         $ai_cache_creation_input_tokens: args.cacheWriteTokens,
-        $ai_request_count: 1,
+        $ai_request_count: args.llmCallCount,
         $ai_total_cost_usd: costUsd,
         $ai_input: args.aiInput,
         $ai_output_choices: args.aiOutputChoices,
         $ai_tools: args.aiTools,
-        $ai_input_truncated: args.aiInputTruncated || undefined,
-        $ai_output_truncated: args.aiOutputTruncated || undefined,
-        $ai_time_to_first_token: args.firstTokenMs,
+        input_truncated: args.aiInputTruncated || undefined,
+        output_truncated: args.aiOutputTruncated || undefined,
+        latency_source: args.llmDurationMeasured ? "measured" : "derived",
+        // Seconds, per PostHog's schema — `time_to_first_token_ms` above is the
+        // millisecond field this framework's own dashboards read.
+        $ai_time_to_first_token: args.firstTokenMs === undefined
+            ? undefined
+            : Math.round(args.firstTokenMs) / 1000,
         $session_id: args.browserSessionId,
     };
     if (args.experimentAssignments?.length) {
@@ -188,6 +227,7 @@ function emitLlmGenerationTrackingEvent(args) {
             .then(({ track }) => {
             track("$ai_generation", properties, {
                 userId: args.userId ?? undefined,
+                occurredAt: args.createdAt,
             });
         })
             .catch(() => { });
@@ -212,6 +252,10 @@ function emitLlmGenerationTrackingEvent(args) {
  */
 function buildGenerationContent(args) {
     const { config } = args;
+    // `$ai_input` is the conversation, not the system prompt. PostHog accepts a
+    // `system` role, but the prompt is app configuration rather than content and
+    // is near-identical on every run — shipping it would repeat kilobytes on each
+    // generation for no analytical gain.
     const input = config.capturePrompts
         ? boundAiContent(redactSensitiveFields(args.messages))
         : undefined;
@@ -364,6 +408,13 @@ export async function instrumentAgentLoop(opts) {
     let toolCallCount = 0;
     let successfulTools = 0;
     let failedTools = 0;
+    // One `model_stream` start/end bracket is emitted per LLM round-trip, and it
+    // closes before any tool of that turn is started — so these intervals ARE the
+    // model's wall clock, not an estimate of it. Recording them is what lets the
+    // generation report a measured `$ai_latency` instead of backing tool time out
+    // of the run duration.
+    const modelStreamIntervals = [];
+    let modelStreamOpenedAt = null;
     // 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();
@@ -447,6 +498,20 @@ export async function instrumentAgentLoop(opts) {
                 runStatus = "error";
                 errorMessage = "Missing API key";
             }
+            if (event.type === "model_stream") {
+                // 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") {
+                    modelStreamOpenedAt ??= Date.now();
+                }
+                else if (modelStreamOpenedAt !== null) {
+                    modelStreamIntervals.push({
+                        start: modelStreamOpenedAt,
+                        end: Date.now(),
+                    });
+                    modelStreamOpenedAt = null;
+                }
+            }
             if (event.type === "tool_start") {
                 const counter = toolInvocationCounter++;
                 const sid = spanId();
@@ -563,6 +628,25 @@ export async function instrumentAgentLoop(opts) {
                 else if (pending) {
                     pending.endResult = otelEndResult;
                 }
+                const spanMetadataFields = {};
+                if (config.captureToolArgs && pending) {
+                    // Strip Authorization/api-key/token-shaped values before persisting
+                    // (M14 in the MCP/A2A audit). Tool-runtime execution still sees the
+                    // unredacted input — only the long-lived span row is sanitized.
+                    spanMetadataFields.input = redactSensitiveFields(pending.input);
+                }
+                // A failed tool's content reaches the span through `errorMessage`; a
+                // successful one had nowhere to go, so every healthy tool span shipped
+                // an input and no output — indistinguishable from a tool that returned
+                // nothing. Same redaction and truncation as the error path.
+                if (!isError &&
+                    config.captureToolResults &&
+                    typeof event.result === "string") {
+                    spanMetadataFields.output = truncateToolErrorMessage(redactToolErrorMessage(event.result));
+                }
+                const spanMetadata = Object.keys(spanMetadataFields).length
+                    ? spanMetadataFields
+                    : null;
                 const span = {
                     id: pending?.spanId ?? spanId(),
                     runId,
@@ -579,16 +663,11 @@ export async function instrumentAgentLoop(opts) {
                     durationMs: pending ? Math.max(0, finishedAt - pending.startMs) : 0,
                     status: isError ? "error" : "success",
                     errorMessage: isError ? event.result : null,
-                    metadata: config.captureToolArgs && pending
-                        ? // Strip Authorization/api-key/token-shaped values before
-                            // persisting (M14 in the MCP/A2A audit). Tool-runtime
-                            // execution still sees the unredacted input — only the
-                            // long-lived span row is sanitized.
-                            {
-                                input: redactSensitiveFields(pending.input),
-                            }
-                        : null,
-                    createdAt: Date.now(),
+                    metadata: spanMetadata,
+                    // The span's start, not its completion: `durationMs` is measured from
+                    // here, so stamping the end instead places the tool after the run
+                    // ended in any timeline that plots start + duration.
+                    createdAt: pending?.startMs ?? finishedAt,
                 };
                 spans.push(span);
             }
@@ -629,6 +708,19 @@ export async function instrumentAgentLoop(opts) {
         try {
             const runEnd = Date.now();
             const totalDurationMs = runEnd - runStart;
+            // The loop threw or was killed mid-stream, so no `end` ever arrived. The
+            // model was still running when the run stopped, so the interval closes at
+            // the run's end rather than being dropped.
+            if (modelStreamOpenedAt !== null) {
+                modelStreamIntervals.push({ start: modelStreamOpenedAt, end: runEnd });
+                modelStreamOpenedAt = null;
+            }
+            // Undefined means the engine never bracketed its model calls, NOT that
+            // the model took no time — the two must stay distinguishable, because
+            // only the first may fall back to backing tool time out of the run.
+            const measuredModelDurationMs = modelStreamIntervals.length
+                ? coveredDurationMs(modelStreamIntervals)
+                : undefined;
             if (pendingTools.size > 0) {
                 if (runStatus === "success") {
                     runStatus = "error";
@@ -681,7 +773,7 @@ export async function instrumentAgentLoop(opts) {
                         status: "error",
                         errorMessage: interruptedMessage,
                         metadata: null,
-                        createdAt: runEnd,
+                        createdAt: pending.startMs,
                     });
                 }
                 pendingTools.clear();
@@ -712,6 +804,15 @@ export async function instrumentAgentLoop(opts) {
                         message: `Agent run was cut off before finishing (${cutOffReason}).`,
                     }
                     : undefined);
+            const collectedToolSpans = spans.filter((s) => s.spanType === "tool_call");
+            // Resolved before the generation event, not just before the span events:
+            // the generation's latency is the run minus the tool time PostHog will
+            // actually see, so it has to be computed against the same set. Tools
+            // dropped by `captureLlmSpans` or the per-run cap have no sibling span to
+            // hold their time, and subtracting them would lose it from the trace.
+            const emittedToolSpans = (config.captureLlmSpans ? collectedToolSpans : []).slice(0, MAX_AI_SPANS_PER_RUN);
+            const droppedToolSpans = (config.captureLlmSpans ? collectedToolSpans.length : 0) -
+                emittedToolSpans.length;
             let llmCallCount = 0;
             if (usage || runStatus === "error") {
                 llmCallCount =
@@ -736,12 +837,23 @@ export async function instrumentAgentLoop(opts) {
                     ? Math.max(0, usage.firstEngineEventAtMs - runStart)
                     : undefined;
                 const llmSpanId = spanId();
+                const generationToolSpans = collectedToolSpans;
+                // Measured model time when the engine bracketed its round-trips.
+                //
+                // The fallback backs tool time out of the run instead, which is an
+                // estimate and behaves like one: it has to net out overlapping tools,
+                // skip tools PostHog will not receive, and clamp at zero. Engines that
+                // report `model_stream` need none of that, so `latency_source` records
+                // which of the two a given `$ai_latency` came from.
+                const llmDurationMs = measuredModelDurationMs ??
+                    Math.max(0, totalDurationMs -
+                        coveredDurationMs(spanIntervals(emittedToolSpans)));
                 const generationContent = buildGenerationContent({
                     config,
                     messages: loopOpts.messages,
                     tools: loopOpts.tools,
                     assistantText: assistantTextParts.join(""),
-                    toolSpans: spans.filter((s) => s.spanType === "tool_call"),
+                    toolSpans: generationToolSpans,
                 });
                 const llmSpan = {
                     id: llmSpanId,
@@ -785,6 +897,9 @@ export async function instrumentAgentLoop(opts) {
                         : undefined,
                     costCentsX100: usageReported ? costCentsX100 : undefined,
                     durationMs: totalDurationMs,
+                    llmDurationMs,
+                    llmDurationMeasured: measuredModelDurationMs !== undefined,
+                    llmCallCount,
                     firstTokenMs,
                     status: runStatus,
                     errorMessage,
@@ -844,11 +959,22 @@ export async function instrumentAgentLoop(opts) {
                 const provider = llmProviderFromEngine(typeof loopOpts.engine?.name === "string"
                     ? loopOpts.engine.name
                     : undefined, usage?.model ?? loopOpts.model);
-                const toolSpans = config.captureLlmSpans
-                    ? spans.filter((s) => s.spanType === "tool_call")
-                    : [];
-                const emittedToolSpans = toolSpans.slice(0, MAX_AI_SPANS_PER_RUN);
-                const droppedToolSpans = toolSpans.length - emittedToolSpans.length;
+                // PostHog reads a trace's input/output state ONLY from the `$ai_trace`
+                // event — never from its children — so a trace whose detail view should
+                // show what the run was asked and what it answered has to carry them
+                // here. Gated on `capturePrompts` and omitted, not emptied, when off.
+                const traceInputState = config.capturePrompts
+                    ? redactSensitiveFields(loopOpts.messages)
+                    : undefined;
+                const traceAssistantText = assistantTextParts.join("");
+                const traceOutputState = config.capturePrompts && traceAssistantText
+                    ? [
+                        {
+                            role: "assistant",
+                            content: redactToolErrorMessage(traceAssistantText),
+                        },
+                    ]
+                    : undefined;
                 emitAiTraceEvent({
                     runId,
                     threadId,
@@ -856,7 +982,7 @@ export async function instrumentAgentLoop(opts) {
                     spanName,
                     model: usage?.model ?? loopOpts.model,
                     provider,
-                    latencySeconds: Math.round(totalDurationMs) / 1000,
+                    durationMs: totalDurationMs,
                     isError: runStatus === "error",
                     error: aiError,
                     inputTokens: usage?.usageReported ? usage.inputTokens : undefined,
@@ -866,6 +992,8 @@ export async function instrumentAgentLoop(opts) {
                         : undefined,
                     createdAt: runStart,
                     browserSessionId,
+                    inputState: traceInputState,
+                    outputState: traceOutputState,
                     extraProperties: {
                         ...trackingIdentityProperties(),
                         source: "agent_observability",
@@ -879,8 +1007,8 @@ export async function instrumentAgentLoop(opts) {
                         // A truncated run must not read as a complete one.
                         ...(droppedToolSpans > 0
                             ? {
-                                $ai_spans_dropped: droppedToolSpans,
-                                $ai_spans_emitted: emittedToolSpans.length,
+                                spans_dropped: droppedToolSpans,
+                                spans_emitted: emittedToolSpans.length,
                             }
                             : {}),
                     },
@@ -911,10 +1039,12 @@ export async function instrumentAgentLoop(opts) {
                             : undefined,
                         createdAt: span.createdAt,
                         browserSessionId,
-                        // `metadata.input` is already redacted and only present when
-                        // `captureToolArgs` is on; absent stays absent.
+                        // `metadata.input` / `metadata.output` are already redacted and
+                        // only present when `captureToolArgs` / `captureToolResults` are
+                        // on; absent stays absent.
                         inputState: span.metadata?.input,
-                        outputState: toolErrorMessage,
+                        outputState: toolErrorMessage ??
+                            span.metadata?.output,
                         extraProperties: {
                             ...trackingIdentityProperties(),
                             source: "agent_observability",

package/dist/onboarding/app-profile.js

@@ -292,8 +292,8 @@ const PROFILES = {
                 label: "Gmail",
                 required: true,
                 builderIncluded: false,
-                keySummary: "Google OAuth client ID and secret",
-                why: "Mail needs OAuth access to read, send, and organize the mailbox.",
+                keySummary: "Connect Gmail with OAuth",
+                why: "Mail uses the workspace's managed Google connection; no key is pasted here.",
             },
             {
                 id: "attachment-storage",

package/dist/onboarding/plugin.js

@@ -13,6 +13,7 @@ import { deleteCookie, defineEventHandler, getCookie, getMethod, getQuery, setRe
 import { appStateGet, appStatePut } from "../application-state/store.js";
 import { getOrgContext } from "../org/context.js";
 import { getSession } from "../server/auth.js";
+import { CredentialStoreUnavailableError } from "../server/credential-provider.js";
 import { awaitBootstrap, getH3App, markDefaultPluginProvided, } from "../server/framework-request-handler.js";
 import { runWithRequestContext } from "../server/request-context.js";
 import { FIRST_RUN_ONBOARDING_COMPLETED_KEY, FIRST_RUN_ONBOARDING_COOKIE, FIRST_RUN_ONBOARDING_ELIGIBLE_KEY, } from "../shared/first-run-onboarding.js";
@@ -57,7 +58,11 @@ async function serializeSteps(context, options = {}) {
     // chain of credential/settings reads — walking them one at a time made this
     // route cost the SUM of every step's round trips against a remote database
     // instead of the slowest one. `Promise.all` preserves `steps` order.
-    return Promise.all(steps.map(async (step) => {
+    const serialized = await Promise.all(steps.map(async (step) => {
+        if (!options.preview && step.isAvailable) {
+            if (!(await step.isAvailable(context)))
+                return null;
+        }
         let complete = false;
         if (!options.preview) {
             try {
@@ -80,6 +85,7 @@ async function serializeSteps(context, options = {}) {
             methods: step.methods,
         };
     }));
+    return serialized.filter((step) => step !== null);
 }
 function withOnboardingRequestContext(context, fn) {
     return runWithRequestContext({
@@ -180,7 +186,9 @@ export function createOnboardingPlugin(options = {}) {
                     };
                 });
             }
-            catch {
+            catch (error) {
+                if (error instanceof CredentialStoreUnavailableError)
+                    throw error;
                 return { dismissed: false, allComplete: false };
             }
         }));

package/dist/onboarding/types.d.ts

@@ -66,6 +66,8 @@ export interface OnboardingStep {
     /** Required steps block onboarding dismissal when incomplete. */
     required?: boolean;
     methods: OnboardingMethod[];
+    /** Hide the step when its backing capability is not configured. */
+    isAvailable?: (context?: OnboardingResolveContext) => boolean | Promise<boolean>;
     /** Resolver — called on every `GET /_agent-native/onboarding/steps` request. */
     isComplete: (context?: OnboardingResolveContext) => boolean | Promise<boolean>;
 }

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -93,8 +93,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
-    id?: undefined;
     count?: undefined;
+    id?: undefined;
     deleted?: undefined;
     providers?: undefined;
     found: boolean;