@agent-native/core 0.198.2 → 0.198.3-nightly-20260930124743

package/dist/catalog.json

@@ -62,6 +62,6 @@
   "vite": "8.1.0",
   "vitest": "^4.1.5",
   "y-protocols": "^1.0.7",
-  "yjs": "^13.6.32",
+  "yjs": "^13.6.33",
   "zod": "^4.3.6"
 }

package/dist/client/chat/agentkit-protocol.js

@@ -1528,7 +1528,10 @@ export function createAgentKitProtocolAdapter(runtime, options = {}) {
                     {
                         type: "suggestions.updated",
                         ...base,
-                        suggestions: event.suggestions,
+                        suggestions: event.suggestions.map((suggestion) => ({
+                            ...suggestion,
+                            runId: run.runId,
+                        })),
                     },
                 ];
             case "annotation": {

package/dist/collab/struct-routes.d.ts

@@ -1,6 +1,6 @@
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/framework-tools.js

@@ -132,6 +132,8 @@ export const CORE_ACTION_GROUPS = {
     "get-usage-alerts": "automation",
     "manage-usage-alert": "automation",
     "get-usage-metrics": "automation",
+    "get-usage-insights": "automation",
+    "get-usage-run": "automation",
     "get-builder-credit-usage": "automation",
     "get-builder-credit-status": "automation",
     "get-builder-referral-info": "automation",

package/dist/observability/routes.d.ts

@@ -59,6 +59,6 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/progress/routes.d.ts

@@ -2,6 +2,6 @@ export declare function createProgressHandler(): import("h3").EventHandlerWithFe
     error: string;
     ok?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

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

@@ -75,9 +75,9 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    message?: undefined;
     id?: undefined;
     deleted?: undefined;
+    found?: undefined;
     providers: {
         id: string;
         label: string;
@@ -89,11 +89,10 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     }[];
     count: number;
     provider?: undefined;
-    found?: undefined;
     registered?: undefined;
     label?: undefined;
-} | {
     message?: undefined;
+} | {
     id?: undefined;
     deleted?: undefined;
     count?: undefined;
@@ -102,8 +101,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     provider: import("../custom-registry.js").CustomProviderConfig;
     registered?: undefined;
     label?: undefined;
-} | {
     message?: undefined;
+} | {
     deleted?: undefined;
     count?: undefined;
     providers?: undefined;
@@ -112,22 +111,23 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     id: string;
     registered?: undefined;
     label?: undefined;
-} | {
     message?: undefined;
+} | {
+    found?: undefined;
     count?: undefined;
     providers?: undefined;
     provider?: undefined;
-    found?: undefined;
     deleted: boolean;
     id: string;
     registered?: undefined;
     label?: undefined;
+    message?: undefined;
 } | {
     deleted?: undefined;
+    found?: undefined;
     count?: undefined;
     providers?: undefined;
     provider?: undefined;
-    found?: undefined;
     registered: boolean;
     id: string;
     label: string;

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

@@ -311,10 +311,9 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
         notes?: string | undefined;
         scope?: "org" | "user" | undefined;
     }, {
-        provider?: undefined;
-        deleted?: undefined;
         id?: undefined;
         message?: undefined;
+        found?: undefined;
         providers: {
             id: string;
             label: string;
@@ -325,45 +324,46 @@ export declare function createProviderApiActions(runtime: Pick<ProviderApiRuntim
             updatedAt: number;
         }[];
         count: number;
-        found?: undefined;
+        provider?: undefined;
+        deleted?: undefined;
         registered?: undefined;
         label?: undefined;
     } | {
-        deleted?: undefined;
         id?: undefined;
-        count?: undefined;
         message?: undefined;
         providers?: undefined;
+        count?: undefined;
         found: boolean;
         provider: import("../custom-registry.js").CustomProviderConfig;
+        deleted?: undefined;
         registered?: undefined;
         label?: undefined;
     } | {
-        provider?: undefined;
-        deleted?: undefined;
-        count?: undefined;
         message?: undefined;
         providers?: undefined;
+        count?: undefined;
+        provider?: undefined;
         found: boolean;
         id: string;
+        deleted?: undefined;
         registered?: undefined;
         label?: undefined;
     } | {
-        provider?: undefined;
-        count?: undefined;
         message?: undefined;
-        providers?: undefined;
         found?: undefined;
+        providers?: undefined;
+        count?: undefined;
+        provider?: undefined;
         deleted: boolean;
         id: string;
         registered?: undefined;
         label?: undefined;
     } | {
+        found?: undefined;
+        providers?: undefined;
+        count?: undefined;
         provider?: undefined;
         deleted?: undefined;
-        count?: undefined;
-        providers?: undefined;
-        found?: undefined;
         registered: boolean;
         id: string;
         label: string;

package/dist/resources/handlers.d.ts

@@ -39,8 +39,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
     error: string;
 }>;
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/server/action-discovery.js

@@ -633,6 +633,11 @@ export async function mergeCoreSharingActions(registry) {
             "get-usage-metrics",
             () => import("../usage/actions/get-usage-metrics.js"),
         ],
+        [
+            "get-usage-insights",
+            () => import("../usage/actions/get-usage-insights.js"),
+        ],
+        ["get-usage-run", () => import("../usage/actions/get-usage-run.js")],
         [
             "get-builder-credit-usage",
             () => import("../usage/actions/get-builder-credit-usage.js"),

package/dist/server/agent-engine-default-model-route.d.ts

@@ -8,17 +8,17 @@ export declare const AGENT_ENGINE_API_KEY_ACTION_NAME = "agent-engine-api-key";
  * resolveEngine's credential detection.
  */
 export declare function createAgentEngineDisconnectHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     scope?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     error: any;
     scope?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     scope: "org" | "user";
+    error?: undefined;
 }>>;
 export interface DefaultModelSelectionRequest {
     engine: string;

package/dist/server/core-routes-plugin.d.ts

@@ -581,8 +581,8 @@ export declare function createPublicRemoteAgentsHandler(discover?: PublicAgentDi
     error: string;
     agents?: undefined;
 } | {
-    agents: Omit<import("./agent-discovery.js").DiscoveredAgent, "auth" | "kind">[];
     error?: undefined;
+    agents: Omit<import("./agent-discovery.js").DiscoveredAgent, "auth" | "kind">[];
 }>>;
 export declare function getBuilderConnectErrorDisposition(error: unknown, connectAttemptId: string | null): "correlated" | "legacy" | null;
 export declare function getBuilderConnectErrorKey(ownerEmail: string, connectAttemptId?: string | null): string;

package/dist/server/realtime-token.d.ts

@@ -54,8 +54,8 @@ export declare function createRealtimeTokenHandler(): import("h3").EventHandlerW
     expiresAt?: undefined;
     ttlSeconds?: undefined;
 } | {
+    error?: undefined;
     token: string;
     expiresAt: string;
     ttlSeconds: number;
-    error?: undefined;
 }>>;

package/dist/usage/actions/get-usage-insights.d.ts

@@ -0,0 +1,7 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    sinceDays?: unknown;
+    scope?: "me" | "workspace";
+    userEmail?: string;
+    appId?: string;
+}, import("../insights-store.js").UsageInsights>;
+export default _default;

package/dist/usage/actions/get-usage-insights.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getUsageInsights } from "../insights-store.js";
+import { resolveUsageAppKey } from "../store.js";
+export default defineAction({
+    description: "Get the Usage page's performance breakdown for an app: spend split by cache reads, cache writes, fresh input and output, savings versus no prompt caching, and recent prompts with per-run LLM calls, tool calls, tool lookups and cache misses.",
+    http: { method: "GET" },
+    schema: z.object({
+        sinceDays: z.coerce.number().int().min(1).max(365).default(30),
+        scope: z.enum(["me", "workspace"]).default("me"),
+        userEmail: z.string().trim().min(1).optional(),
+        appId: z.string().trim().max(200).optional(),
+    }),
+    run: async ({ sinceDays, scope, userEmail, appId }, ctx) => {
+        if (!ctx?.userEmail)
+            throw new Error("Not authenticated.");
+        return getUsageInsights({ sinceDays, scope, userEmail }, {
+            ownerEmail: ctx.userEmail,
+            orgId: ctx.orgId,
+            app: resolveUsageAppKey(appId),
+        });
+    },
+});

package/dist/usage/actions/get-usage-run.d.ts

@@ -0,0 +1,7 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    runId: string;
+    scope?: "me" | "workspace";
+    userEmail?: string;
+    appId?: string;
+}, import("../insights-store.js").UsageRunDetail>;
+export default _default;

package/dist/usage/actions/get-usage-run.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getUsageRun } from "../insights-store.js";
+import { resolveUsageAppKey } from "../store.js";
+export default defineAction({
+    description: "Get one prompt's step-by-step cost breakdown for the Usage page: every LLM call with tokens, cache hit and cost, every tool call with status, cache misses with their likely cause, and automated eval scores.",
+    http: { method: "GET" },
+    schema: z.object({
+        runId: z.string().trim().min(1).max(200),
+        scope: z.enum(["me", "workspace"]).default("me"),
+        userEmail: z.string().trim().min(1).optional(),
+        appId: z.string().trim().max(200).optional(),
+    }),
+    run: async ({ runId, scope, userEmail, appId }, ctx) => {
+        if (!ctx?.userEmail)
+            throw new Error("Not authenticated.");
+        return getUsageRun({ runId, scope, userEmail }, {
+            ownerEmail: ctx.userEmail,
+            orgId: ctx.orgId,
+            app: resolveUsageAppKey(appId),
+        });
+    },
+});

package/dist/usage/insights-store.d.ts

@@ -0,0 +1,127 @@
+import { type UsageMetricsAccessInput, type UsageMetricsScope } from "./metrics-store.js";
+/** Run insights are always read for one app, never across all apps. */
+type RunAccessInput = UsageMetricsAccessInput & {
+    app: string;
+};
+/** Spend split by how the provider billed each token, in cents. */
+export interface UsageCostBreakdown {
+    cacheReadCents: number;
+    cacheWriteCents: number;
+    uncachedInputCents: number;
+    outputCents: number;
+    /** Recorded spend for the rows; the category splits above are token-priced estimates. */
+    totalCents: number;
+    /** The same tokens priced at list rates, so it is comparable to `noCacheCents`. */
+    estimatedCents: number;
+    /** What the same tokens would have cost with no prompt caching. */
+    noCacheCents: number;
+}
+export interface UsageTokenTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+export type UsageScoreSource = "heuristic" | "judge" | "human";
+export interface UsageRunScore {
+    source: UsageScoreSource;
+    criteria: string;
+    score: number;
+    reasoning: string | null;
+}
+export interface UsageRunTool {
+    name: string;
+    calls: number;
+    failed: number;
+    error: string | null;
+}
+/**
+ * The context was re-sent in full when the cache could have been re-used.
+ * `tool-lookup`: new tools were loaded; `prefix-changed`: something else at
+ * the start of the prompt changed.
+ */
+export type UsageRestartCause = "tool-lookup" | "prefix-changed";
+export interface UsageRunRestarts {
+    count: number;
+    cents: number;
+    byCause: Record<UsageRestartCause, {
+        count: number;
+        cents: number;
+    }>;
+}
+export interface UsageRunListItem {
+    runId: string;
+    threadId: string | null;
+    createdAt: number;
+    ownerEmail: string;
+    label: string;
+    model: string;
+    prompt: string | null;
+    /** `unknown` when the trace was never written or has been cleaned up. */
+    status: "success" | "error" | "unknown";
+    tokens: UsageTokenTotals;
+    cost: UsageCostBreakdown;
+    modelCalls: number;
+    tools: UsageRunTool[];
+    restarts: UsageRunRestarts;
+    /** Tool calls that overlapped another call in the same step, and the time that saved. */
+    parallel: {
+        calls: number;
+        savedMs: number;
+    };
+    /** Failed tool calls in a run that still finished. */
+    recoveredErrors: number;
+    durationMs: number | null;
+    feedback: "up" | "down" | null;
+}
+export interface UsagePeriodTotals {
+    runs: number;
+    tokens: UsageTokenTotals;
+    cost: UsageCostBreakdown;
+}
+export interface UsageInsights {
+    sinceDays: number;
+    current: UsagePeriodTotals;
+    previous: UsagePeriodTotals;
+    runs: UsageRunListItem[];
+}
+export interface UsageRunToolCall {
+    name: string;
+    startedAt: number;
+    durationMs: number;
+    status: string;
+    errorMessage: string | null;
+}
+/** One model call and the tools it asked for. */
+export interface UsageRunTurn {
+    index: number;
+    model: string;
+    durationMs: number;
+    tokens: UsageTokenTotals;
+    cost: UsageCostBreakdown;
+    status: string;
+    /** Set only when re-sending the context cost a meaningful amount. */
+    restart: {
+        cause: UsageRestartCause;
+        cents: number;
+    } | null;
+    /** The provider cache had expired after an idle gap; expected, not a fault. */
+    cacheExpired: boolean;
+    toolCalls: UsageRunToolCall[];
+}
+export interface UsageRunDetail extends UsageRunListItem {
+    reply: string | null;
+    turns: UsageRunTurn[];
+    scores: UsageRunScore[];
+}
+export declare function getUsageInsights(input: {
+    sinceDays?: number;
+    scope?: UsageMetricsScope;
+    userEmail?: string | null;
+}, accessInput: RunAccessInput): Promise<UsageInsights>;
+export declare function getUsageRun(input: {
+    runId: string;
+    scope?: UsageMetricsScope;
+    userEmail?: string | null;
+}, accessInput: RunAccessInput): Promise<UsageRunDetail | null>;
+export {};

package/dist/usage/insights-store.js

@@ -0,0 +1,462 @@
+import { stablePrefixCacheControl } from "../agent/engine/prompt-cache.js";
+import { getDbExec } from "../db/client.js";
+import { ensureObservabilityTables } from "../observability/store.js";
+import { loadRunExchanges, numberField, resolveScope, stringField, usageAppScope, } from "./metrics-store.js";
+import { calculateCost, ensureUsageTable } from "./store.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RUN_LIMIT = 25;
+// A restart cheaper than this is provider noise, not something to act on.
+const MIN_RESTART_CENTS = 0.5;
+function costBreakdown(tokens, model) {
+    const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } = tokens;
+    const uncached = Math.max(0, inputTokens - cacheReadTokens - cacheWriteTokens);
+    const cents = (centicents) => centicents / 100;
+    const breakdown = {
+        cacheReadCents: cents(calculateCost(cacheReadTokens, 0, model, cacheReadTokens, 0)),
+        cacheWriteCents: cents(calculateCost(cacheWriteTokens, 0, model, 0, cacheWriteTokens)),
+        uncachedInputCents: cents(calculateCost(uncached, 0, model)),
+        outputCents: cents(calculateCost(0, outputTokens, model)),
+        noCacheCents: cents(calculateCost(inputTokens, outputTokens, model)),
+    };
+    const estimatedCents = breakdown.cacheReadCents +
+        breakdown.cacheWriteCents +
+        breakdown.uncachedInputCents +
+        breakdown.outputCents;
+    return { ...breakdown, estimatedCents, totalCents: estimatedCents };
+}
+/**
+ * Token-priced breakdown for one model's rows, carrying their recorded spend.
+ * Unpriced rows are stored as 0, so they fall back to the token estimate.
+ */
+function recordedBreakdown(row) {
+    const estimate = costBreakdown(tokensFromRow(row), stringField(row, "model"));
+    if (numberField(row, "unpriced") > 0)
+        return estimate;
+    return { ...estimate, totalCents: numberField(row, "cost_cents_x100") / 100 };
+}
+const UNPRICED = `CASE WHEN cost_source = 'unavailable' THEN 1 ELSE 0 END`;
+function addBreakdown(a, b) {
+    return {
+        cacheReadCents: a.cacheReadCents + b.cacheReadCents,
+        cacheWriteCents: a.cacheWriteCents + b.cacheWriteCents,
+        uncachedInputCents: a.uncachedInputCents + b.uncachedInputCents,
+        outputCents: a.outputCents + b.outputCents,
+        totalCents: a.totalCents + b.totalCents,
+        estimatedCents: a.estimatedCents + b.estimatedCents,
+        noCacheCents: a.noCacheCents + b.noCacheCents,
+    };
+}
+const EMPTY_BREAKDOWN = {
+    cacheReadCents: 0,
+    cacheWriteCents: 0,
+    uncachedInputCents: 0,
+    outputCents: 0,
+    totalCents: 0,
+    estimatedCents: 0,
+    noCacheCents: 0,
+};
+function emptyTokens() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+    };
+}
+function addTokens(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+        cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+    };
+}
+function tokensFromRow(row) {
+    return {
+        inputTokens: numberField(row, "input_tokens"),
+        outputTokens: numberField(row, "output_tokens"),
+        cacheReadTokens: numberField(row, "cache_read_tokens"),
+        cacheWriteTokens: numberField(row, "cache_write_tokens"),
+    };
+}
+const SCORE_SOURCE = {
+    automated: "heuristic",
+    llm_judge: "judge",
+    human: "human",
+};
+/**
+ * Extra spend versus the call re-using the previous call's context from cache.
+ * Providers that bill no cache writes (OpenAI) only lose the read discount.
+ */
+function restartCents(model, tokens, previousInput) {
+    const reusable = Math.min(previousInput, tokens.inputTokens);
+    const writesBilled = tokens.cacheWriteTokens > 0;
+    const ifCached = calculateCost(tokens.inputTokens, 0, model, reusable, writesBilled ? tokens.inputTokens - reusable : 0);
+    const actual = calculateCost(tokens.inputTokens, 0, model, tokens.cacheReadTokens, tokens.cacheWriteTokens);
+    return Math.max(0, actual - ifCached) / 100;
+}
+function buildTurns(spans) {
+    const turns = [];
+    // A model that never reports cache tokens has no cache to miss.
+    const cachingModels = new Set(spans
+        .filter((span) => span.spanType === "llm_call" &&
+        span.tokens.cacheReadTokens + span.tokens.cacheWriteTokens > 0)
+        .map((span) => span.name));
+    // A longer gap than the prompt-cache TTL re-writes the prefix.
+    const cacheTtlMs = stablePrefixCacheControl().ttl === "1h" ? 60 * 60 * 1000 : 5 * 60 * 1000;
+    let previousStartedAt = 0;
+    let toolLookupSinceLastTurn = false;
+    for (const span of spans) {
+        if (span.spanType === "tool_call") {
+            if (span.name === "tool-search")
+                toolLookupSinceLastTurn = true;
+            turns.at(-1)?.toolCalls.push({
+                name: span.name,
+                startedAt: span.createdAt,
+                durationMs: span.durationMs,
+                status: span.status,
+                errorMessage: span.errorMessage,
+            });
+            continue;
+        }
+        if (span.spanType !== "llm_call")
+            continue;
+        const previous = turns.at(-1);
+        const missed = cachingModels.has(span.name) &&
+            previous?.model === span.name &&
+            span.tokens.cacheReadTokens < span.tokens.inputTokens / 2;
+        const expired = missed && span.createdAt - previousStartedAt > cacheTtlMs;
+        let restart = null;
+        if (missed && !expired) {
+            const cents = restartCents(span.name, span.tokens, previous.tokens.inputTokens);
+            if (cents >= MIN_RESTART_CENTS) {
+                restart = {
+                    cause: toolLookupSinceLastTurn ? "tool-lookup" : "prefix-changed",
+                    cents,
+                };
+            }
+        }
+        turns.push({
+            index: turns.length + 1,
+            model: span.name,
+            durationMs: span.durationMs,
+            tokens: span.tokens,
+            cost: costBreakdown(span.tokens, span.name),
+            status: span.status,
+            restart,
+            cacheExpired: expired,
+            toolCalls: [],
+        });
+        previousStartedAt = span.createdAt;
+        toolLookupSinceLastTurn = false;
+    }
+    return turns;
+}
+function parallelSavings(turns) {
+    let calls = 0;
+    let savedMs = 0;
+    for (const { toolCalls } of turns) {
+        if (toolCalls.length < 2)
+            continue;
+        const start = Math.min(...toolCalls.map((call) => call.startedAt));
+        const end = Math.max(...toolCalls.map((call) => call.startedAt + call.durationMs));
+        const sequential = toolCalls.reduce((sum, call) => sum + call.durationMs, 0);
+        if (sequential - (end - start) <= 0)
+            continue;
+        savedMs += sequential - (end - start);
+        calls += toolCalls.filter((call) => toolCalls.some((other) => other !== call &&
+            other.startedAt < call.startedAt + call.durationMs &&
+            call.startedAt < other.startedAt + other.durationMs)).length;
+    }
+    return { calls, savedMs };
+}
+function summarizeTurns(turns) {
+    const tools = new Map();
+    const restarts = {
+        count: 0,
+        cents: 0,
+        byCause: {
+            "tool-lookup": { count: 0, cents: 0 },
+            "prefix-changed": { count: 0, cents: 0 },
+        },
+    };
+    for (const turn of turns) {
+        if (turn.restart) {
+            restarts.count += 1;
+            restarts.cents += turn.restart.cents;
+            restarts.byCause[turn.restart.cause].count += 1;
+            restarts.byCause[turn.restart.cause].cents += turn.restart.cents;
+        }
+        for (const call of turn.toolCalls) {
+            const tool = tools.get(call.name) ?? {
+                name: call.name,
+                calls: 0,
+                failed: 0,
+                error: null,
+            };
+            tool.calls += 1;
+            if (call.status === "error") {
+                tool.failed += 1;
+                tool.error ??= call.errorMessage;
+            }
+            tools.set(call.name, tool);
+        }
+    }
+    return {
+        tools: [...tools.values()].sort((a, b) => b.calls - a.calls),
+        restarts,
+    };
+}
+async function tracesByRun(runIds) {
+    const traces = new Map();
+    if (runIds.length === 0)
+        return traces;
+    await ensureObservabilityTables();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT run_id, span_type, name, status, error_message, duration_ms,
+        created_at, input_tokens, output_tokens, cache_read_tokens,
+        cache_write_tokens
+      FROM agent_trace_spans
+      WHERE run_id IN (${runIds.map(() => "?").join(", ")})
+      ORDER BY created_at ASC`,
+        args: runIds,
+    });
+    const spansByRun = new Map();
+    const runSpans = new Map();
+    for (const row of rows) {
+        const runId = String(row.run_id);
+        if (row.span_type === "agent_run") {
+            runSpans.set(runId, {
+                status: String(row.status),
+                durationMs: numberField(row, "duration_ms"),
+            });
+            continue;
+        }
+        const spans = spansByRun.get(runId) ?? [];
+        spans.push({
+            spanType: String(row.span_type),
+            name: String(row.name),
+            status: String(row.status),
+            errorMessage: typeof row.error_message === "string" ? row.error_message : null,
+            durationMs: numberField(row, "duration_ms"),
+            createdAt: numberField(row, "created_at"),
+            tokens: tokensFromRow(row),
+        });
+        spansByRun.set(runId, spans);
+    }
+    for (const runId of runIds) {
+        const run = runSpans.get(runId);
+        traces.set(runId, {
+            status: !run ? "unknown" : run.status === "error" ? "error" : "success",
+            durationMs: run?.durationMs || null,
+            turns: buildTurns(spansByRun.get(runId) ?? []),
+        });
+    }
+    return traces;
+}
+async function scoresByRun(runIds) {
+    const scores = new Map();
+    if (runIds.length === 0)
+        return scores;
+    await ensureObservabilityTables();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT run_id, eval_type, criteria, score, reasoning FROM agent_evals
+      WHERE run_id IN (${runIds.map(() => "?").join(", ")})
+      ORDER BY created_at ASC`,
+        args: runIds,
+    });
+    for (const row of rows) {
+        const runId = String(row.run_id);
+        const list = scores.get(runId) ?? [];
+        list.push({
+            source: SCORE_SOURCE[String(row.eval_type)] ?? "heuristic",
+            criteria: String(row.criteria),
+            score: numberField(row, "score"),
+            reasoning: typeof row.reasoning === "string" ? row.reasoning : null,
+        });
+        scores.set(runId, list);
+    }
+    return scores;
+}
+async function feedbackByRun(runIds) {
+    const feedback = new Map();
+    if (runIds.length === 0)
+        return feedback;
+    await ensureObservabilityTables();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT run_id, feedback_type FROM agent_feedback
+      WHERE run_id IN (${runIds.map(() => "?").join(", ")})
+        AND feedback_type IN ('thumbs_up', 'thumbs_down')
+      ORDER BY created_at ASC`,
+        args: runIds,
+    });
+    // Ordered oldest first, so the latest vote wins.
+    for (const row of rows) {
+        feedback.set(String(row.run_id), row.feedback_type === "thumbs_up" ? "up" : "down");
+    }
+    return feedback;
+}
+const RUN_COLUMNS = `MIN(id) AS id, MIN(created_at) AS created_at,
+  MAX(owner_email) AS owner_email, MAX(app) AS app, MAX(label) AS label,
+  MAX(model) AS model, MAX(thread_id) AS thread_id, MAX(task_id) AS task_id,
+  SUM(input_tokens) AS input_tokens, SUM(output_tokens) AS output_tokens,
+  SUM(cache_read_tokens) AS cache_read_tokens,
+  SUM(cache_write_tokens) AS cache_write_tokens,
+  SUM(cost_cents_x100) AS cost_cents_x100`;
+function runListItem(row, cost, trace, prompt, feedback) {
+    const tokens = tokensFromRow(row);
+    const turns = trace?.turns ?? [];
+    const { tools, restarts } = summarizeTurns(turns);
+    const status = trace?.status ?? "unknown";
+    return {
+        runId: String(row.run_id),
+        threadId: stringField(row, "thread_id") || null,
+        createdAt: numberField(row, "created_at"),
+        ownerEmail: stringField(row, "owner_email"),
+        label: stringField(row, "label") || "chat",
+        model: stringField(row, "model") || "unknown",
+        prompt,
+        status,
+        tokens,
+        cost,
+        modelCalls: turns.length,
+        tools,
+        restarts,
+        parallel: parallelSavings(turns),
+        recoveredErrors: status === "success"
+            ? tools.reduce((sum, tool) => sum + tool.failed, 0)
+            : 0,
+        durationMs: trace?.durationMs ?? null,
+        feedback,
+    };
+}
+/** Per-run spend, pricing each model's tokens at that model's rate. */
+async function costsByRun(runIds, scope) {
+    const costs = new Map();
+    if (runIds.length === 0)
+        return costs;
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT run_id, model, ${UNPRICED} AS unpriced,
+        SUM(input_tokens) AS input_tokens,
+        SUM(output_tokens) AS output_tokens,
+        SUM(cache_read_tokens) AS cache_read_tokens,
+        SUM(cache_write_tokens) AS cache_write_tokens,
+        SUM(cost_cents_x100) AS cost_cents_x100
+      FROM token_usage
+      WHERE run_id IN (${runIds.map(() => "?").join(", ")}) AND ${scope.where}
+      GROUP BY 1, 2, 3`,
+        args: [...runIds, ...scope.args],
+    });
+    for (const row of rows) {
+        const runId = String(row.run_id);
+        costs.set(runId, addBreakdown(costs.get(runId) ?? EMPTY_BREAKDOWN, recordedBreakdown(row)));
+    }
+    return costs;
+}
+export async function getUsageInsights(input, accessInput) {
+    await ensureUsageTable();
+    const sinceDays = Math.max(1, Math.min(365, input.sinceDays ?? 30));
+    const sinceMs = Date.now() - sinceDays * DAY_MS;
+    const previousSinceMs = sinceMs - sinceDays * DAY_MS;
+    const appScope = usageAppScope(accessInput.app.trim());
+    const resolved = await resolveScope(accessInput, input.scope === "workspace" ? "workspace" : "me", input.userEmail);
+    const scopeWhere = `${appScope.where} AND ${resolved.ownerScope.where}`;
+    const scopeArgs = [...appScope.args, ...resolved.ownerScope.args];
+    // Only prompt-linked usage, so "spent on N prompts" divides like with like.
+    const period = "CASE WHEN created_at >= ? THEN 'current' ELSE 'previous' END";
+    const periodWhere = `${scopeWhere} AND created_at >= ? AND run_id IS NOT NULL`;
+    const periodArgs = [sinceMs, ...scopeArgs, previousSinceMs];
+    const [periodRows, periodRunRows, runRows] = await Promise.all([
+        getDbExec().execute({
+            sql: `SELECT ${period} AS period, model, ${UNPRICED} AS unpriced,
+          SUM(input_tokens) AS input_tokens, SUM(output_tokens) AS output_tokens,
+          SUM(cache_read_tokens) AS cache_read_tokens,
+          SUM(cache_write_tokens) AS cache_write_tokens,
+          SUM(cost_cents_x100) AS cost_cents_x100
+        FROM token_usage WHERE ${periodWhere}
+        GROUP BY 1, 2, 3`,
+            args: periodArgs,
+        }),
+        getDbExec().execute({
+            sql: `SELECT ${period} AS period, COUNT(DISTINCT run_id) AS runs
+        FROM token_usage WHERE ${periodWhere}
+        GROUP BY 1`,
+            args: periodArgs,
+        }),
+        getDbExec().execute({
+            sql: `SELECT run_id, ${RUN_COLUMNS}
+        FROM token_usage
+        WHERE ${scopeWhere} AND created_at >= ? AND run_id IS NOT NULL
+        GROUP BY run_id
+        ORDER BY MIN(created_at) DESC
+        LIMIT ${RUN_LIMIT}`,
+            args: [...scopeArgs, sinceMs],
+        }),
+    ]);
+    const periods = {
+        current: { runs: 0, tokens: emptyTokens(), cost: EMPTY_BREAKDOWN },
+        previous: { runs: 0, tokens: emptyTokens(), cost: EMPTY_BREAKDOWN },
+    };
+    for (const row of periodRows.rows) {
+        const totals = periods[row.period === "current" ? "current" : "previous"];
+        totals.tokens = addTokens(totals.tokens, tokensFromRow(row));
+        totals.cost = addBreakdown(totals.cost, recordedBreakdown(row));
+    }
+    for (const row of periodRunRows.rows) {
+        periods[row.period === "current" ? "current" : "previous"].runs =
+            numberField(row, "runs");
+    }
+    const rawRuns = runRows.rows;
+    const runIds = rawRuns.map((row) => String(row.run_id));
+    const [exchanges, traces, feedback, costs] = await Promise.all([
+        loadRunExchanges(rawRuns),
+        tracesByRun(runIds),
+        feedbackByRun(runIds),
+        costsByRun(runIds, { where: scopeWhere, args: scopeArgs }),
+    ]);
+    return {
+        sinceDays,
+        current: periods.current,
+        previous: periods.previous,
+        runs: rawRuns.map((row) => {
+            const runId = String(row.run_id);
+            return runListItem(row, costs.get(runId) ?? recordedBreakdown(row), traces.get(runId), exchanges.get(runId)?.prompt ?? null, feedback.get(runId) ?? null);
+        }),
+    };
+}
+export async function getUsageRun(input, accessInput) {
+    await ensureUsageTable();
+    const appScope = usageAppScope(accessInput.app.trim());
+    const resolved = await resolveScope(accessInput, input.scope === "workspace" ? "workspace" : "me", input.userEmail);
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT run_id, ${RUN_COLUMNS}, COUNT(*) AS row_count
+      FROM token_usage
+      WHERE run_id = ? AND ${appScope.where} AND ${resolved.ownerScope.where}
+      GROUP BY run_id`,
+        args: [input.runId, ...appScope.args, ...resolved.ownerScope.args],
+    });
+    const row = rows[0];
+    // The usage row is the access check: spans are only read for a run the
+    // caller's scope can already see.
+    if (!row || numberField(row, "row_count") === 0)
+        return null;
+    const runScope = {
+        where: `${appScope.where} AND ${resolved.ownerScope.where}`,
+        args: [...appScope.args, ...resolved.ownerScope.args],
+    };
+    const [exchanges, traces, scores, feedback, costs] = await Promise.all([
+        loadRunExchanges([row]),
+        tracesByRun([input.runId]),
+        scoresByRun([input.runId]),
+        feedbackByRun([input.runId]),
+        costsByRun([input.runId], runScope),
+    ]);
+    const exchange = exchanges.get(input.runId);
+    const trace = traces.get(input.runId);
+    return {
+        ...runListItem(row, costs.get(input.runId) ?? recordedBreakdown(row), trace, exchange?.prompt ?? null, feedback.get(input.runId) ?? null),
+        reply: exchange?.reply ?? null,
+        turns: trace?.turns ?? [],
+        scores: scores.get(input.runId) ?? [],
+    };
+}

package/dist/usage/metrics-store.d.ts

@@ -189,13 +189,34 @@ export interface UsageMetricsAccessInput {
     orgId?: string | null;
     app: UsageAppSelection;
 }
+interface MemberRecord {
+    email: string;
+    role: string | null;
+}
 interface QueryScope {
     where: string;
     args: unknown[];
 }
+export declare function numberField(row: Record<string, unknown>, key: string): number;
+export declare function stringField(row: Record<string, unknown>, key: string): string;
 export declare function normalizeUsageAppKey(value: string): string;
 export declare function usageAppScope(app: string): QueryScope;
 export declare function canViewWorkspaceUsage(input: Pick<UsageMetricsAccessInput, "ownerEmail" | "orgId">): Promise<boolean>;
+export declare function resolveScope(input: UsageMetricsAccessInput, scope: UsageMetricsScope, requestedUserEmail?: string | null): Promise<{
+    ownerScope: QueryScope;
+    /** The lowercased owner emails `ownerScope` selects. */
+    ownerEmails: string[];
+    /** The org predicate inside `ownerScope`, for tables with an `org_id`. */
+    orgScope: QueryScope;
+    selectedUserEmail: string | null;
+    members: MemberRecord[];
+    access: UsageMetricsAccess;
+}>;
+/** Each run's own prompt and the agent's reply to it, keyed by run id. */
+export declare function loadRunExchanges(rows: Array<Record<string, unknown>>): Promise<Map<string, {
+    prompt: string | null;
+    reply: string | null;
+}>>;
 export declare function listAppUsageMetrics(input: {
     sinceDays?: number;
     scope?: UsageMetricsScope;

package/dist/usage/metrics-store.js

@@ -1,5 +1,6 @@
 import { getAppConfig } from "../app-config/index.js";
 import { getDbExec } from "../db/client.js";
+import { splitAgentChatContextFromMessage } from "../shared/agent-chat-context.js";
 import { ForbiddenError } from "../sharing/access.js";
 import { isSelfScopedUsageRead, usageOrgScope } from "./org-scope.js";
 import { builderCreditsFromCostCents, ensureUsageTable, resolveUsageAppKey, usageBillingForEngine, MIXED_USAGE_BILLING, } from "./store.js";
@@ -15,10 +16,10 @@ export const USAGE_APP_FILTER_CURRENT = "current";
 /** Key of the series that folds every key past a breakdown's limit. */
 export const USAGE_OTHER_BREAKDOWN_KEY = "other";
 const NO_APP_FILTER = { where: "", args: [] };
-function numberField(row, key) {
+export function numberField(row, key) {
     return Number(row[key] ?? 0) || 0;
 }
-function stringField(row, key) {
+export function stringField(row, key) {
     return String(row[key] ?? "");
 }
 function nullableStringField(row, key) {
@@ -123,7 +124,7 @@ export async function canViewWorkspaceUsage(input) {
     const role = await getOrgRole(input.orgId?.trim() || null, normalizeEmail(input.ownerEmail));
     return role === "owner" || role === "admin";
 }
-async function resolveScope(input, scope, requestedUserEmail) {
+export async function resolveScope(input, scope, requestedUserEmail) {
     const viewerEmail = normalizeEmail(input.ownerEmail);
     const orgId = input.orgId?.trim() || null;
     const role = await getOrgRole(orgId, viewerEmail);
@@ -525,7 +526,11 @@ function parseJson(value) {
         return null;
     }
 }
+/** Message text without the hidden `<context>` block apps append to prompts. */
 function promptText(value) {
+    return splitAgentChatContextFromMessage(rawMessageText(value)).message;
+}
+function rawMessageText(value) {
     if (typeof value === "string")
         return value.trim();
     if (!Array.isArray(value))
@@ -649,6 +654,65 @@ function promptForTurn(index, taskId, usageCreatedAt) {
         ? (index.timestampedPrompts[low - 1]?.prompt ?? null)
         : index.soleUntimestampedPrompt;
 }
+/** Each run's own prompt and the agent's reply to it, keyed by run id. */
+export async function loadRunExchanges(rows) {
+    const exchanges = new Map();
+    const threadRefs = [
+        ...new Map(rows
+            .map((row) => ({
+            id: nullableStringField(row, "thread_id"),
+            ownerEmail: nullableStringField(row, "owner_email"),
+        }))
+            .filter((ref) => Boolean(ref.id && ref.ownerEmail))
+            .map((ref) => [JSON.stringify([ref.id, ref.ownerEmail]), ref])).values(),
+    ];
+    if (threadRefs.length === 0)
+        return exchanges;
+    let threadRows = [];
+    try {
+        const result = await getDbExec().execute({
+            sql: `SELECT id, thread_data FROM chat_threads WHERE ${threadRefs.map(() => "(id = ? AND LOWER(owner_email) = LOWER(?))").join(" OR ")}`,
+            args: threadRefs.flatMap((ref) => [ref.id, ref.ownerEmail]),
+        });
+        threadRows = result.rows;
+    }
+    catch {
+        return exchanges;
+    }
+    const threads = new Map(threadRows.map((row) => [String(row.id), row.thread_data]));
+    for (const row of rows) {
+        const runId = nullableStringField(row, "run_id");
+        const threadId = nullableStringField(row, "thread_id");
+        const threadData = threadId ? threads.get(threadId) : undefined;
+        if (!runId || threadData === undefined)
+            continue;
+        const taskId = nullableStringField(row, "task_id");
+        const index = indexThreadPrompts(threadData);
+        const prompt = index
+            ? promptForTurn(index, taskId, numberField(row, "created_at"))
+            : null;
+        exchanges.set(runId, {
+            prompt: prompt?.prompt ?? null,
+            reply: taskId ? replyForTurn(threadData, taskId) : null,
+        });
+    }
+    return exchanges;
+}
+function replyForTurn(threadData, taskId) {
+    const messages = parseJson(threadData)?.messages;
+    if (!Array.isArray(messages))
+        return null;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messageRecord(messages[i]);
+        if (message?.role !== "assistant" || messageTurnId(message) !== taskId) {
+            continue;
+        }
+        const text = promptText(message.content);
+        if (text)
+            return text.length > 1200 ? `${text.slice(0, 1199).trimEnd()}…` : text;
+    }
+    return null;
+}
 async function hydrateRecentPrompts(rows, builderCreditsEnabled, legacyRowsUseBuilder) {
     const recentLimit = 12;
     const threadRefs = [

package/dist/vite/action-types-plugin.js

@@ -189,6 +189,14 @@ const CORE_SHARING_ACTIONS = [
         name: "get-usage-metrics",
         specifier: "@agent-native/core/usage/actions/get-usage-metrics",
     },
+    {
+        name: "get-usage-insights",
+        specifier: "@agent-native/core/usage/actions/get-usage-insights",
+    },
+    {
+        name: "get-usage-run",
+        specifier: "@agent-native/core/usage/actions/get-usage-run",
+    },
     {
         name: "get-builder-credit-usage",
         specifier: "@agent-native/core/usage/actions/get-builder-credit-usage",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.198.2",
+  "version": "0.198.3-nightly-20260930124743",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -389,6 +389,8 @@
     "./usage/actions/get-usage-alerts": "./dist/usage/actions/get-usage-alerts.js",
     "./usage/actions/manage-usage-alert": "./dist/usage/actions/manage-usage-alert.js",
     "./usage/actions/get-usage-metrics": "./dist/usage/actions/get-usage-metrics.js",
+    "./usage/actions/get-usage-insights": "./dist/usage/actions/get-usage-insights.js",
+    "./usage/actions/get-usage-run": "./dist/usage/actions/get-usage-run.js",
     "./usage/actions/get-builder-credit-usage": "./dist/usage/actions/get-builder-credit-usage.js",
     "./usage/actions/get-builder-credit-status": "./dist/usage/actions/get-builder-credit-status.js",
     "./usage/actions/get-builder-referral-info": "./dist/usage/actions/get-builder-referral-info.js",
@@ -655,9 +657,9 @@
     "undici": "^7.28.0",
     "y-protocols": "^1.0.7",
     "yaml": "^2.9.0",
-    "yjs": "^13.6.32",
+    "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.198.2",
+    "@agent-native/agentkit": "^0.198.3-nightly-20260930124743",
     "@agent-native/recap-cli": "^0.5.52"
   },
   "devDependencies": {
@@ -730,7 +732,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@agent-native/core-corpus": ">=0.196.0",
+    "@agent-native/core-corpus": "0.198.3-nightly-20260930124743",
     "@ai-sdk/anthropic": ">=3",
     "@ai-sdk/cohere": ">=3",
     "@ai-sdk/google": ">=3",