@agent-native/core 0.169.0 → 0.170.0

package/dist/localization/core-messages/pt-BR.js

@@ -31,6 +31,8 @@ const messages = {
     "aboutAgentNative.copyDiagnostics": "Copiar diagnósticos",
     "aboutAgentNative.unknown": "Desconhecida",
     "common.agent": "Agente",
+    "agentPanel.mode": "Modo",
+    "agentPanel.uiMode": "Interface",
     "common.cancel": "Cancelar",
     "common.collapse": "Recolher",
     "common.connect": "Conectar",
@@ -406,7 +408,7 @@ const messages = {
     "errorMessages.gatewayNoDetails": "O gateway do modelo não retornou detalhes do erro, e o chat não pôde ser recuperado. Aguarde um momento e tente novamente. Se o problema persistir, inicie um novo chat.",
     "errorMessages.inactivityTimeout": "A conexão com o agente expirou antes da conclusão. Você pode continuar a partir do trabalho parcial ou tentar novamente.",
     "errorMessages.invalidToolSchema": "O esquema de uma ferramenta era inválido, então o modelo rejeitou a solicitação antes de iniciá-la. Você pode ignorar a ferramenta inválida e tentar novamente.",
-    "errorMessages.noProviderConnected": "Nenhum provedor de LLM está conectado. Abra “Gerenciar agente” → “LLM” para este app e conecte o Builder.io ou adicione uma chave de provedor.",
+    "errorMessages.noProviderConnected": "Nenhum provedor de LLM está conectado. Abra Configurações > Agente > Provedores de IA e conecte o Builder.io (nível gratuito disponível) ou adicione uma chave de provedor.",
     "errorMessages.openBuilderSpaceSettings": "Abrir as configurações do espaço do Builder",
     "errorMessages.providerAuthentication": "O provedor do modelo rejeitou a chave de API salva. Atualize-a em Configurações → Integrações → Chaves de API e tente novamente.",
     "errorMessages.providerConfiguration": "Este modelo não pode usar ferramentas com as configurações atuais. Troque de modelo em Configurações e tente novamente.",
@@ -505,6 +507,7 @@ const messages = {
     "share.linkCanStillOpen": "Pessoas com o link ainda podem abrir isto.",
     "share.loading": "Carregando...",
     "share.loadMore": "Ver mais",
+    "share.loadFailed": "Não foi possível carregar as configurações de compartilhamento.",
     "share.loadPeopleFailed": "Não foi possível carregar pessoas.",
     "share.noAccess": "Ninguém tem acesso ainda.",
     "share.noMatches": "Nenhuma correspondência.",

package/dist/localization/core-messages/zh-CN.js

@@ -31,6 +31,8 @@ const messages = {
     "aboutAgentNative.copyDiagnostics": "复制诊断信息",
     "aboutAgentNative.unknown": "未知",
     "common.agent": "智能体",
+    "agentPanel.mode": "模式",
+    "agentPanel.uiMode": "界面",
     "common.cancel": "取消",
     "common.collapse": "收起",
     "common.connect": "连接",
@@ -260,7 +262,7 @@ const messages = {
     "errorMessages.gatewayNoDetails": "模型网关未返回错误详情，聊天无法恢复。请稍等片刻后重试；如果问题持续出现，请开始新聊天。",
     "errorMessages.inactivityTimeout": "智能体连接在完成前超时。您可以从已完成的部分继续，也可以重试。",
     "errorMessages.invalidToolSchema": "工具架构无效，因此模型在请求开始前拒绝了该请求。可以跳过无效工具并重试请求。",
-    "errorMessages.noProviderConnected": "尚未连接任何 LLM 提供商。打开此应用的“管理智能体”→“LLM”，然后连接 Builder.io 或添加提供商密钥。",
+    "errorMessages.noProviderConnected": "尚未连接任何 LLM 提供商。打开设置 > 智能体 > AI 提供商，然后连接 Builder.io（提供免费套餐）或添加提供商密钥。",
     "errorMessages.openBuilderSpaceSettings": "打开 Builder 空间设置",
     "errorMessages.providerAuthentication": "模型提供商拒绝了已保存的 API 密钥。请在设置 → 集成 → API 密钥中更新密钥，然后重试。",
     "errorMessages.providerConfiguration": "此模型无法在当前设置下使用工具。请在设置中切换模型，然后重试。",
@@ -442,6 +444,7 @@ const messages = {
     "share.hideInSearch": "在搜索中隐藏",
     "share.linkCanStillOpen": "拥有链接的人员仍可打开此内容。",
     "share.loadMore": "加载更多",
+    "share.loadFailed": "无法加载共享设置。",
     "share.loadPeopleFailed": "无法加载人员。",
     "share.loading": "正在加载...",
     "share.noAccess": "尚无任何人拥有访问权限。",

package/dist/localization/core-messages/zh-TW.js

@@ -31,6 +31,8 @@ const messages = {
     "aboutAgentNative.copyDiagnostics": "複製診斷資訊",
     "aboutAgentNative.unknown": "未知",
     "common.agent": "代理",
+    "agentPanel.mode": "模式",
+    "agentPanel.uiMode": "介面",
     "common.cancel": "取消",
     "common.collapse": "收合",
     "common.connect": "連線",
@@ -260,7 +262,7 @@ const messages = {
     "errorMessages.gatewayNoDetails": "模型閘道未傳回錯誤詳細資訊，聊天無法復原。請稍候再試；如果問題持續發生，請開始新聊天。",
     "errorMessages.inactivityTimeout": "代理連線在完成前逾時。您可以從已完成的部分繼續，也可以重試。",
     "errorMessages.invalidToolSchema": "工具結構描述無效，因此模型在要求開始前便拒絕了要求。您可以略過無效工具並重試要求。",
-    "errorMessages.noProviderConnected": "尚未連接任何 LLM 提供商。開啟此應用程式的「管理代理程式」→「LLM」，然後連接 Builder.io 或新增提供商金鑰。",
+    "errorMessages.noProviderConnected": "尚未連接任何 LLM 提供商。開啟設定 > 代理程式 > AI 提供商，然後連接 Builder.io（提供免費方案）或新增提供商金鑰。",
     "errorMessages.openBuilderSpaceSettings": "開啟 Builder 空間設定",
     "errorMessages.providerAuthentication": "模型供應商拒絕了已儲存的 API 金鑰。請在設定 → 整合 → API 金鑰中更新金鑰，然後重試。",
     "errorMessages.providerConfiguration": "這個模型無法在目前設定下使用工具。請在設定中切換模型，然後重試。",
@@ -442,6 +444,7 @@ const messages = {
     "share.hideInSearch": "在搜尋中隱藏",
     "share.linkCanStillOpen": "擁有連結的人員仍可開啟這個項目。",
     "share.loadMore": "載入更多",
+    "share.loadFailed": "無法載入分享設定。",
     "share.loadPeopleFailed": "無法載入人員。",
     "share.loading": "載入中...",
     "share.noAccess": "尚無任何人擁有存取權。",

package/dist/localization/core-messages.d.ts

@@ -33,6 +33,8 @@ export declare const englishAgentChatMessages: {
     readonly "aboutAgentNative.copyDiagnostics": "Copy diagnostics";
     readonly "aboutAgentNative.unknown": "Unknown";
     readonly "common.agent": "Agent";
+    readonly "agentPanel.mode": "Mode";
+    readonly "agentPanel.uiMode": "UI";
     readonly "common.cancel": "Cancel";
     readonly "common.collapse": "Collapse";
     readonly "common.connect": "Connect";
@@ -264,7 +266,7 @@ export declare const englishAgentChatMessages: {
     readonly "errorMessages.gatewayNoDetails": "The model gateway returned no error details and the chat couldn't recover. Wait a moment and retry, or start a new chat if it keeps happening.";
     readonly "errorMessages.inactivityTimeout": "The agent connection timed out before it could finish. You can continue from the partial work or retry.";
     readonly "errorMessages.invalidToolSchema": "A tool schema was invalid, so the model rejected the request before it started. The invalid tool can be skipped and the request retried.";
-    readonly "errorMessages.noProviderConnected": "No LLM provider is connected. Open this app's Manage agent > LLM, then connect Builder.io or add a provider key.";
+    readonly "errorMessages.noProviderConnected": "No LLM provider is connected. Open Settings > Agent > AI providers, then connect Builder.io (free tier available) or add a provider key.";
     readonly "errorMessages.openBuilderSpaceSettings": "Open Builder space settings";
     readonly "errorMessages.providerAuthentication": "The model provider rejected the saved API key. Update the key in Settings → Integrations → API keys, then retry.";
     readonly "errorMessages.providerConfiguration": "This model can't use tools with the current settings. Switch models in Settings, then retry.";
@@ -449,6 +451,7 @@ export declare const englishAgentChatMessages: {
     readonly "share.linkCanStillOpen": "People with the link can still open this.";
     readonly "share.loading": "Loading...";
     readonly "share.loadMore": "Load more";
+    readonly "share.loadFailed": "Couldn't load sharing settings.";
     readonly "share.loadPeopleFailed": "Could not load people.";
     readonly "share.noAccess": "No one has access yet.";
     readonly "share.noMatches": "No matches.";

package/dist/localization/default-messages.d.ts

@@ -422,6 +422,8 @@ declare const messages: {
         downloadDesktop: string;
         chatMode: string;
         chat: string;
+        mode: string;
+        uiMode: string;
         cliTerminalMode: string;
         cli: string;
         workspaceMode: string;
@@ -1126,11 +1128,6 @@ declare const messages: {
                 useCase: string;
                 setupNote: string;
             };
-            googleWorkspace: {
-                description: string;
-                useCase: string;
-                setupNote: string;
-            };
             gitlab: {
                 description: string;
                 useCase: string;

package/dist/localization/default-messages.js

@@ -428,6 +428,8 @@ const messages = {
         downloadDesktop: "Download Desktop",
         chatMode: "Chat mode",
         chat: "Chat",
+        mode: "Mode",
+        uiMode: "UI",
         cliTerminalMode: "CLI terminal mode",
         cli: "CLI",
         workspaceMode: "Files, agents, skills, and tasks",
@@ -1132,11 +1134,6 @@ const messages = {
                 useCase: "Observability, metrics, logs, traces, dashboards",
                 setupNote: "Grafana Cloud MCP is in public preview and requires Grafana Cloud Assistant MCP access. It is hosted Grafana Cloud only; self-hosted Grafana needs the local MCP server.",
             },
-            googleWorkspace: {
-                description: "Search Google Workspace data through its remote MCP server.",
-                useCase: "Workspace search across Gmail, Drive, Calendar, Chat, Docs, Sheets, Slides",
-                setupNote: "Google Workspace MCP is in Developer Preview. Enable the relevant Google Workspace and MCP APIs, configure an OAuth consent screen and client, then authorize the products you want to use.",
-            },
             gitlab: {
                 description: "Read and manage GitLab projects, issues, and merge requests.",
                 useCase: "Repositories, issues, merge requests, CI/CD, code analytics",

package/dist/mcp/build-server.d.ts

@@ -189,6 +189,15 @@ export interface MCPRequestMeta {
  * results simply fall back to their deep-link text.
  */
 export declare function isMcpAppsInlineEnabled(identity: MCPCallerIdentity | undefined): boolean;
+/**
+ * Connector-catalog membership declared on the actions themselves.
+ *
+ * This is `mcp.connectorCatalog` with the list inverted into the action files,
+ * so a rename moves the declaration with the action instead of stranding a
+ * dead string in a plugin config. Both forms feed the same set and an app can
+ * run either or both while it migrates.
+ */
+export declare function declaredMcpToolNames(actions: Record<string, ActionEntry>): string[];
 export declare function isAuthenticatedReadAction(entry: ActionEntry): boolean;
 export declare function isAutoReadExcludedActionName(name: string): boolean;
 /**

package/dist/mcp/build-server.js

@@ -18,6 +18,7 @@
  * — it can be bundled into the serverless function alongside `mountMCP`.
  */
 import { MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, } from "../action.js";
+import { isActionExposedToExternalAgents } from "../action.js";
 import { isMcpActionResult } from "../mcp-client/app-result.js";
 import { getConfiguredAppBasePath } from "../server/app-base-path.js";
 import { buildDeepLink, toAbsoluteOpenUrl, toDesktopOpenUrl, toVsCodeOpenUrl, } from "../server/deep-link.js";
@@ -177,6 +178,34 @@ function scopeToolSearchToAdvertised(advertised) {
         },
     };
 }
+/**
+ * Drop every action this request's surface must not reach at all.
+ *
+ * Applied to `actions` — the whole surface this request can reach — and not
+ * just to the advertised listing, because on the `--full-catalog` tier
+ * `actions` IS the callable set (see the `tools/call` handler below). An
+ * external-agent opt-out that only hid the schema would leave the action
+ * callable by name, which is the same "hidden but reachable" bug the
+ * `withoutToolSearch` comment above exists to prevent.
+ *
+ * The in-app agent never comes through here, so its tool list is unaffected.
+ */
+function withoutExternalOptOuts(actions) {
+    return Object.fromEntries(Object.entries(actions).filter(([, entry]) => isActionExposedToExternalAgents(entry)));
+}
+/**
+ * Connector-catalog membership declared on the actions themselves.
+ *
+ * This is `mcp.connectorCatalog` with the list inverted into the action files,
+ * so a rename moves the declaration with the action instead of stranding a
+ * dead string in a plugin config. Both forms feed the same set and an app can
+ * run either or both while it migrates.
+ */
+export function declaredMcpToolNames(actions) {
+    return Object.entries(actions)
+        .filter(([, entry]) => entry.mcpTool === true)
+        .map(([name]) => name);
+}
 const COMPACT_MCP_APP_CATALOG_BUILTINS = new Set([
     "list_apps",
     "open_app",
@@ -1170,9 +1199,7 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     // Strip from `actions`, not just the advertised set: on the full-catalog tier
     // `actions` IS the callable surface, so filtering only the listing would
     // leave `tool-search` callable but invisible.
-    const actions = flatCatalog
-        ? withoutToolSearch(mergedActions)
-        : mergedActions;
+    const actions = withoutExternalOptOuts(flatCatalog ? withoutToolSearch(mergedActions) : mergedActions);
     const visibleActions = Object.fromEntries(Object.entries(actions).filter(([, entry]) => isActionVisibleForOAuthScope(entry, effectiveIdentity?.oauthScopes)));
     // Compact/connector is the DEFAULT for every caller — hosted connectors,
     // code clients (Claude Code / Cursor / Codex), and the local CLI alike. The
@@ -1187,15 +1214,17 @@ export async function createMCPServerForRequest(config, identity, requestMeta) {
     const autoReadNames = autoAuthenticatedReadNames(visibleActions, config);
     const connectorNames = new Set([
         ...(config.connectorCatalog ?? []),
+        ...declaredMcpToolNames(visibleActions),
         ...autoReadNames,
     ]);
     const denyNames = externalAgentDenySet(config);
     const automaticConnectorPolicyActive = config.externalAgents?.authenticatedReads === "auto";
-    // Connector-catalog tier: when a template declares a connector allow-list,
-    // serve exactly that curated surface plus any explicitly annotated
-    // authenticated reads from `externalAgents.authenticatedReads: "auto"`.
-    // This stays compact by default and keeps db-exec / seed-* / extension /
-    // browser-session footguns off the external surface.
+    // Connector-catalog tier: when a template declares a connector allow-list —
+    // as `mcp.connectorCatalog` names or as `mcpTool: true` on the actions
+    // themselves — serve exactly that curated surface plus any explicitly
+    // annotated authenticated reads from `externalAgents.authenticatedReads:
+    // "auto"`. This stays compact by default and keeps db-exec / seed-* /
+    // extension / browser-session footguns off the external surface.
     const connectorCatalogActive = !appCatalog &&
         (connectorNames.size > 0 || automaticConnectorPolicyActive) &&
         !fullCatalogRequested;

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/notifications/routes.d.ts

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

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.