@agent-native/core 0.209.0-nightly-20261014124140 → 0.209.0

package/dist/cli/skills-content/turn-into-app-skill.js

@@ -328,14 +328,19 @@ On a browser host the host is an orchestrator, not the build environment:
    (archetype, direction, first viewport, sample-data plan, agent moments).
 2. Call \`start-workspace-app-creation\` on the Agent-Native Dispatch MCP
    connector (\`agent-native-dispatch\`). Put the brief and the design decisions
-   in \`prompt\`; pass an \`appId\`, a short \`description\`, the \`template\`, the
-   selected \`resourceIds\`, and source files as \`attachments\`
-   ([attachments.md](attachments.md)). The tool's schema describes each
-   argument. Reference resources by id; never paste whole knowledge files or
-   binary data into \`prompt\`, and do not assume an attachment becomes a file in
-   the generated workspace. A workbook cannot be attached (attachments take
-   images, PDF, text, and JSON): pass a bounded CSV rendering as text, or a
-   public URL, and say what was left out.
+   in \`prompt\`; pass an \`appId\`, a short \`description\`, and the \`template\`.
+   The tool's schema describes each argument. Send the Project's own text as
+   \`attachments\` ([attachments.md](attachments.md)), never as a summary: the
+   Project instructions as \`project-instructions.md\` and every knowledge file,
+   each verbatim as \`text/plain\`. Never paste whole knowledge files or binary
+   data into \`prompt\`. Attachments are model context
+   and are not copied into the generated workspace, so tell the Builder agent in
+   \`prompt\` to persist what the app needs: knowledge files as app resources, the
+   instructions as the in-app agent's instructions. If a file cannot be
+   reproduced verbatim (not in context, too large), say so in the brief and the
+   report; never swap in a digest silently. A workbook cannot be attached
+   (attachments take images, PDF, text, and JSON): pass a bounded CSV rendering
+   as text, or a public URL, and say what was left out.
 3. Report what Dispatch actually returned: the branch, the path, and the status.
    The browser host cannot run or inspect the app, and a returned path can 404
    until the branch merges and deploys, so the report ends at pending or
@@ -1180,7 +1185,7 @@ heading; write \`n/a\` where a heading does not apply.
 Source and provenance: type (thread, skill, Project, spreadsheet, export), file names, ids, what was read and what was not
 Project goal: the user and the repeatable job, in one sentence
 Configuration and constraints: audience, rules, output standards, approved tools
-Knowledge sources: reference files the app ships with, by name or id
+Knowledge sources: reference files the app ships with, by name
 Repeatable workflow: the job's trigger, steps, and outcome, in the source's own words
 Inputs and outputs: what comes in, what the user gets back, fixed output shapes
 Judgment and review points: 1-3 agent moments, each tied to the object it acts on; what the user confirms
@@ -1198,7 +1203,7 @@ App design: archetype, direction, first-viewport sketch, sample-data plan
 
 - Name the latest successful, repeatable job. A walkthrough of one example is
   evidence for the job, not the job.
-- Keep references bounded: a file name, URL, resource id, or short summary
+- Keep references bounded: a file name, URL, or short summary
   instead of a pasted document. No secrets, credentials, or customer data.
 - Corrections the user made in the source are product rules. Record each one
   as an invariant.

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

@@ -587,6 +587,7 @@ function runtimeMessageToProtocolMessage(message, fallbackTextFormat) {
         role: message.role,
         parts: message.content.map((part) => runtimePartToProtocolPart(part, textFormat)),
         createdAt: message.createdAt,
+        status: message.status,
         metadata: message.metadata,
     };
 }
@@ -677,6 +678,7 @@ function protocolMessageToRuntimeMessage(message) {
         role: message.role,
         content: message.parts.map(protocolPartToRuntimePart),
         createdAt: message.createdAt,
+        status: message.status,
         metadata: message.metadata,
     };
 }

package/dist/client/chat/runtime.d.ts

@@ -78,6 +78,7 @@ export interface AgentChatRuntimeMessage<TContentPart extends AgentChatRuntimeCo
     readonly role: AgentChatRuntimeRole;
     readonly content: readonly TContentPart[];
     readonly createdAt?: string;
+    readonly status?: "streaming" | "complete" | "error";
     readonly metadata?: AgentChatRuntimeMetadata;
 }
 export interface AgentChatRuntimeAttachment {

package/dist/client/chat/runtime.js

@@ -1,5 +1,6 @@
 import { AgentKitRunSlotBusyError } from "@agent-native/agentkit/client";
 import { AUTO_CONTINUE_OF_RUN_METADATA_KEY, CONTINUE_OF_RUN_METADATA_KEY, } from "../../agent/auto-continue.js";
+import { RUN_NOT_STARTED_METADATA_KEY } from "../../shared/agent-chat-run-not-started.js";
 import { agentEngineStatusUrlForChatApi, requireAgentEngineConfiguredForDispatch, } from "../agent-engine-readiness.js";
 import { getOrCreateAnalyticsSessionId } from "../analytics-session.js";
 import { agentChatStreamingUrl, agentNativePath } from "../api-path.js";
@@ -770,6 +771,36 @@ function isSyntheticToolHistoryOmissionMessage(message) {
         (message.id === AGENTKIT_TOOL_HISTORY_OMISSION_MESSAGE_ID_PREFIX ||
             /^agentkit-tool-history-omission-\d+$/.test(message.id)));
 }
+function isUnstartedNativeHistoryMessage(message) {
+    if (message.role === "user" && message.status === "error")
+        return true;
+    if (message.role !== "user" && message.role !== "assistant")
+        return false;
+    const custom = asRecord(asRecord(message.metadata)?.custom);
+    return custom?.[RUN_NOT_STARTED_METADATA_KEY] === true;
+}
+function nativeHistorySourceMessages(messages, currentPrompt) {
+    const source = messages ?? [];
+    let currentPromptMessageIndex;
+    for (let index = source.length - 1; index >= 0; index--) {
+        const message = source[index];
+        if (isSyntheticToolHistoryOmissionMessage(message))
+            continue;
+        if (message.role !== "user")
+            continue;
+        if (!currentPrompt.trim()) {
+            currentPromptMessageIndex = index;
+        }
+        else {
+            const match = runtimeMessageTextMatches(message, currentPrompt);
+            if (match.matches || !match.complete)
+                currentPromptMessageIndex = index;
+        }
+        break;
+    }
+    return source.filter((message, index) => index === currentPromptMessageIndex ||
+        !isUnstartedNativeHistoryMessage(message));
+}
 function equivalentRuntimeContent(left, right) {
     let remaining = 4096;
     const leftAncestors = new WeakSet();
@@ -818,7 +849,7 @@ function equivalentRuntimeContent(left, right) {
     return compare(left, right, 0);
 }
 function priorNativeHistoryMessages(messages, currentPrompt) {
-    const source = messages ?? [];
+    const source = nativeHistorySourceMessages(messages, currentPrompt);
     let currentPromptMessageIndex;
     for (let index = source.length - 1; index >= 0; index--) {
         const message = source[index];
@@ -1810,6 +1841,7 @@ function assertUnambiguousKeyOnlyApprovedHistory(sources, approvedToolCalls, app
 }
 function nativeStructuredHistoryFromMessages(messages, currentPrompt, currentAttachmentUrls, supplementalMessages = [], supplementalHistoryOmitted = false, supplementalToolHistoryOmitted = false, approvedToolCalls = [], approvedToolCallAskIds = []) {
     const structuredHistory = [];
+    const historyMessages = nativeHistorySourceMessages(messages, currentPrompt);
     const approvedToolCallSet = new Set(approvedToolCalls);
     const approvedToolCallAskIdSet = new Set(approvedToolCallAskIds);
     const callCandidates = [];
@@ -1820,9 +1852,9 @@ function nativeStructuredHistoryFromMessages(messages, currentPrompt, currentAtt
     const textCandidates = [];
     let toolHistoryPosition = 0;
     let hasToolHistory = false;
-    const sources = boundedStructuredHistorySources(messages, currentPrompt, supplementalMessages, currentAttachmentUrls);
+    const sources = boundedStructuredHistorySources(historyMessages, currentPrompt, supplementalMessages, currentAttachmentUrls);
     assertUnambiguousKeyOnlyApprovedHistory(sources.messages, approvedToolCalls, approvedToolCallAskIds);
-    const boundaryResultsToOmit = boundaryToolResultPartsToOmit(messages, supplementalMessages, sources, supplementalToolHistoryOmitted);
+    const boundaryResultsToOmit = boundaryToolResultPartsToOmit(historyMessages, supplementalMessages, sources, supplementalToolHistoryOmitted);
     for (const { message, parts, priority, textPriority } of sources.messages) {
         if (message.role !== "user" && message.role !== "assistant")
             continue;

package/dist/collab/routes.d.ts

@@ -13,16 +13,16 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
     };
 }>>;
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;
 }>>;
 export declare const postCollabText: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    text?: undefined;
     ok?: undefined;
     error: string;
+    text?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

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

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

package/dist/mcp/actions/call-mcp-tool.js

@@ -11,5 +11,5 @@ export default defineAction({
         toolName: z.string().trim().min(1),
         arguments: z.record(z.string(), z.unknown()).default({}),
     }),
-    run: ({ serverId, toolName, arguments: args }) => callMcpTool(serverId, toolName, args),
+    run: ({ serverId, toolName, arguments: args }, context) => callMcpTool(serverId, toolName, args, { context }),
 });

package/dist/mcp-client/app-api.d.ts

@@ -1,3 +1,4 @@
+import type { ActionRunContext } from "../action.js";
 export interface AppMcpTool {
     serverId: string;
     name: string;
@@ -20,6 +21,8 @@ export interface ListVisibleMcpToolsOptions {
 export interface CallMcpToolOptions {
     /** Refuse the call unless the server's URL belongs to this provider. */
     providerId?: string;
+    /** Caller identity and invocation source forwarded to MCP authorization. */
+    context?: ActionRunContext;
 }
 export declare class McpAppApiError extends Error {
     readonly statusCode: 401 | 403 | 503;

package/dist/mcp-client/app-api.js

@@ -36,7 +36,14 @@ export async function callMcpTool(serverId, originalToolName, args = {}, options
         !isServerForProvider(manager, serverId, options.providerId)) {
         throw new McpAppApiError("MCP tool is not available in this request scope.", 403);
     }
-    return manager.callTool(buildMcpToolName(serverId, originalToolName), args);
+    return manager.callTool(buildMcpToolName(serverId, originalToolName), args, {
+        context: {
+            ...options.context,
+            caller: options.context?.caller ?? "frontend",
+            userEmail: context.userEmail,
+            orgId: context.orgId ?? null,
+        },
+    });
 }
 function requireAuthenticatedRequest() {
     const context = getRequestContext();

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

@@ -1,5 +1,5 @@
 export { loadMcpConfig, autoDetectMcpConfig, type McpConfig, type McpServerConfig, } from "./config.js";
-export { McpClientManager, buildMcpToolName, parseMcpToolName, MCP_TOOL_PREFIX, type McpTool, type McpClientManagerOptions, } from "./manager.js";
+export { McpClientManager, buildMcpToolName, parseMcpToolName, MCP_TOOL_PREFIX, type McpTool, type McpToolCallOptions, type McpToolAuthorizationResolver, type McpClientManagerOptions, } from "./manager.js";
 export { listRemoteServers, addRemoteServer, addOAuthRemoteServer, addFirstPartyRemoteServer, isFirstPartyRemoteEndpointTrusted, removeRemoteServer, validateRemoteUrl, normalizeServerName, mergedConfigKey, parseMergedKey, hashEmail, toHttpServerConfig, toHttpServerConfigAsync, materializeHeaders, type RemoteMcpScope, type StoredRemoteMcpServer, } from "./remote-store.js";
 export { findConnectedMcpServersForProvider, type ConnectedMcpProviderResult, type ConnectedMcpProviderServer, } from "./provider-connections.js";
 export { finishMcpOAuthAuthorization, getMcpOAuthAccessToken, readMcpOAuthCredentials, saveMcpOAuthCredentials, startMcpOAuthAuthorization, type McpOAuthCallbackResult, type McpOAuthCredentialBundle, type McpOAuthDiscoveryState, type McpOAuthProviderOptions, type McpOAuthStartResult, } from "./oauth-client.js";
@@ -14,14 +14,19 @@ export { callMcpTool, listVisibleMcpTools, McpAppApiError, type AppMcpTool, type
 export { classifyMcpToolCall, evaluateMcpToolCallPolicy, type McpToolCallClassification, type McpToolEffect, type McpToolFamily, type McpToolInvocationPolicy, type McpToolPolicyDecision, } from "./tool-policy.js";
 export { configureScreenMemory, queryScreenMemoryForAgent, queryScreenMemoryContext, readScreenMemoryStatus, type ScreenMemoryConfig, type ScreenMemoryAgentQueryResult, type ScreenMemoryContextItem, type ScreenMemoryCoverageGap, type ScreenMemoryEvidenceItem, type ScreenMemoryEvidenceSourceType, type ScreenMemoryQueryResult, type ScreenMemoryRetrievalCoverage, type ScreenMemorySegmentReference, type ScreenMemoryStatus, type ScreenMemoryTimeRange, type ScreenMemoryTruncation, } from "./screen-memory-local.js";
 export { MCP_ACTION_RESULT_MARKER, isMcpActionResult, type AgentMcpAppPayload, type AgentMcpAppResourceContent, type McpActionResult, } from "./app-result.js";
+import { type ActionAuthorize } from "../action.js";
 import type { EngineToolResultImagePart } from "../agent/engine/types.js";
 import type { ActionEntry } from "../agent/production-agent.js";
 import type { McpClientManager, McpTool } from "./manager.js";
 import { type McpToolInvocationPolicy } from "./tool-policy.js";
+export interface McpActionEntryResolution extends Partial<Pick<ActionEntry, "needsApproval" | "allowPersistentApproval">> {
+    /** Authorization checked on every invocation immediately before the remote call. */
+    authorize?: ActionAuthorize<Record<string, unknown>>;
+}
 export interface McpActionEntryOptions {
     invocationPolicy?: McpToolInvocationPolicy;
     toolNames?: readonly string[];
-    resolveActionEntry?: (tool: McpTool) => Partial<Pick<ActionEntry, "needsApproval" | "allowPersistentApproval">> | undefined;
+    resolveActionEntry?: (tool: McpTool) => McpActionEntryResolution | undefined;
 }
 export declare function mcpToolsToActionEntries(manager: McpClientManager, options?: McpActionEntryOptions): Record<string, ActionEntry>;
 export declare function syncMcpActionEntries(manager: McpClientManager, target: Record<string, ActionEntry>, options?: McpActionEntryOptions): void;

package/dist/mcp-client/index.js

@@ -16,7 +16,7 @@ export { classifyMcpToolCall, evaluateMcpToolCallPolicy, } from "./tool-policy.j
 export { configureScreenMemory, queryScreenMemoryForAgent, queryScreenMemoryContext, readScreenMemoryStatus, } from "./screen-memory-local.js";
 export { MCP_ACTION_RESULT_MARKER, isMcpActionResult, } from "./app-result.js";
 import { getToolUiResourceUri, isToolVisibilityAppOnly, isToolVisibilityModelOnly, } from "@modelcontextprotocol/ext-apps/app-bridge";
-import { MCP_APP_MIME_TYPE } from "../action.js";
+import { MCP_APP_MIME_TYPE, } from "../action.js";
 import { normalizeToolResultImages } from "../agent/tool-result-images.js";
 import { MCP_ACTION_RESULT_MARKER, toolForMcpAppPayload, } from "./app-result.js";
 import { evaluateMcpToolCallPolicy, } from "./tool-policy.js";
@@ -45,7 +45,7 @@ export function syncMcpActionEntries(manager, target, options = {}) {
     }
 }
 function mcpToolToActionEntry(manager, tool, options = {}) {
-    const resolvedEntry = options.resolveActionEntry?.(tool);
+    const { authorize, ...resolvedEntry } = options.resolveActionEntry?.(tool) ?? {};
     return {
         tool: {
             description: tool.description,
@@ -59,7 +59,7 @@ function mcpToolToActionEntry(manager, tool, options = {}) {
         },
         ...(tool.annotations?.readOnlyHint === true ? { readOnly: true } : {}),
         ...resolvedEntry,
-        run: async (args) => {
+        run: async (args, context) => {
             // Defense-in-depth: even if a cross-scope MCP tool somehow makes it
             // into the LLM's visible tool list, reject invocation here so we never
             // execute a user's credentials on behalf of another user.
@@ -73,10 +73,16 @@ function mcpToolToActionEntry(manager, tool, options = {}) {
                 }
             }
             try {
-                const result = await manager.callTool(tool.name, args);
+                const result = await manager.callTool(tool.name, args, {
+                    context,
+                    authorize,
+                });
                 return await buildMcpActionResult(manager, tool, args, result);
             }
             catch (err) {
+                if (err?.statusCode === 403) {
+                    throw err;
+                }
                 return buildMcpErrorActionResult(tool, args, `Error calling MCP tool ${tool.name}: ${err?.message ?? err}`);
             }
         },

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

@@ -1,3 +1,4 @@
+import { type ActionAuthorize, type ActionRunContext } from "../action.js";
 import type { McpConfig, McpServerConfig } from "./config.js";
 export declare const MCP_TOOL_PREFIX = "mcp__";
 export interface McpTool {
@@ -21,6 +22,13 @@ export interface McpClientManagerOptions {
     debug?: boolean;
     connectTimeoutMs?: number;
 }
+export interface McpToolCallOptions {
+    /** Identity and invocation source forwarded to the authorization callback. */
+    context?: ActionRunContext;
+    /** Fallback used by standalone action wrappers without a manager resolver. */
+    authorize?: ActionAuthorize<Record<string, unknown>>;
+}
+export type McpToolAuthorizationResolver = (tool: McpTool) => ActionAuthorize<Record<string, unknown>> | undefined;
 export declare class McpClientManager {
     private readonly servers;
     private readonly debug;
@@ -29,8 +37,15 @@ export declare class McpClientManager {
     private config;
     private sdk;
     private readonly listeners;
+    private resolveToolAuthorization?;
     private reconfigureQueue;
     constructor(config: McpConfig | null, options?: McpClientManagerOptions);
+    /**
+     * Install the app-owned authorization resolver used by every MCP tool-call
+     * surface. Passing `undefined` restores the backwards-compatible no-policy
+     * behavior.
+     */
+    setToolAuthorizationResolver(resolver?: McpToolAuthorizationResolver): void;
     get enabled(): boolean;
     getConfig(): McpConfig | null;
     get configuredServers(): string[];
@@ -69,7 +84,7 @@ export declare class McpClientManager {
     /** The config the server's current tools were loaded from. */
     getServerConfig(serverId: string): McpServerConfig | null;
     hasServer(serverId: string): boolean;
-    callTool(prefixedName: string, args: unknown): Promise<unknown>;
+    callTool(prefixedName: string, args: unknown, options?: McpToolCallOptions): Promise<unknown>;
     readResource(serverId: string, uri: string): Promise<unknown>;
     readResourceForTool(prefixedName: string, uri: string): Promise<unknown>;
     stop(): Promise<void>;

package/dist/mcp-client/manager.js

@@ -1,4 +1,4 @@
-import { MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE } from "../action.js";
+import { MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, } from "../action.js";
 import { formatMcpConnectError, httpStatusFromError } from "./errors.js";
 import { isFirstPartyRemoteEndpointTrusted, parseMergedKey, } from "./remote-store.js";
 export const MCP_TOOL_PREFIX = "mcp__";
@@ -110,12 +110,21 @@ export class McpClientManager {
     config;
     sdk = null;
     listeners = new Set();
+    resolveToolAuthorization;
     reconfigureQueue = Promise.resolve();
     constructor(config, options = {}) {
         this.config = config;
         this.debug = !!options.debug;
         this.connectTimeoutMs = options.connectTimeoutMs;
     }
+    /**
+     * Install the app-owned authorization resolver used by every MCP tool-call
+     * surface. Passing `undefined` restores the backwards-compatible no-policy
+     * behavior.
+     */
+    setToolAuthorizationResolver(resolver) {
+        this.resolveToolAuthorization = resolver;
+    }
     get enabled() {
         return !!this.config && Object.keys(this.config.servers).length > 0;
     }
@@ -546,7 +555,7 @@ export class McpClientManager {
         const entry = this.servers.get(serverId);
         return !!entry?.client && !entry.error;
     }
-    async callTool(prefixedName, args) {
+    async callTool(prefixedName, args, options = {}) {
         const parsed = parseMcpToolName(prefixedName);
         if (!parsed) {
             throw new Error(`Tool name "${prefixedName}" does not look like an MCP tool (expected mcp__<server>__<tool>)`);
@@ -555,16 +564,35 @@ export class McpClientManager {
         if (!entry || !entry.client) {
             throw new Error(`MCP server "${parsed.serverId}" is not connected${entry?.error ? `: ${entry.error}` : ""}`);
         }
-        return this.withExpiredSessionRetry(entry, (current) => {
+        const normalizedArgs = args && typeof args === "object" ? args : {};
+        // The expired-session retry replays this attempt on a reconnected entry
+        // whose tool metadata was reloaded, so authorization must run per attempt.
+        return this.withExpiredSessionRetry(entry, async (current) => {
             const known = current.tools.find((t) => t.name === prefixedName);
             if (!known) {
                 throw new Error(`MCP server "${parsed.serverId}" does not expose tool "${parsed.toolName}"`);
             }
-            return current.client.callTool({
+            const client = current.client;
+            const authorize = this.resolveToolAuthorization?.(known) ?? options.authorize;
+            if (authorize) {
+                const verdict = await authorize(normalizedArgs, options.context);
+                if (verdict === false) {
+                    const error = new Error("Not authorized");
+                    error.name = "ForbiddenError";
+                    error.statusCode = 403;
+                    throw error;
+                }
+            }
+            const liveEntry = this.servers.get(parsed.serverId);
+            const liveTool = liveEntry?.tools.find((tool) => tool.name === prefixedName);
+            if (liveEntry !== current ||
+                liveEntry.client !== client ||
+                liveTool !== known) {
+                throw new Error(`MCP server "${parsed.serverId}" changed while authorizing tool "${parsed.toolName}"`);
+            }
+            return client.callTool({
                 name: parsed.toolName,
-                arguments: args && typeof args === "object"
-                    ? args
-                    : {},
+                arguments: normalizedArgs,
             });
         });
     }

package/dist/mcp-client/routes.js

@@ -404,10 +404,15 @@ async function withMcpAppRequestContext(event, fn) {
         setResponseStatus(event, 401);
         return { error: "Authentication required" };
     }
+    const context = {
+        caller: "frontend",
+        userEmail: email,
+        orgId: orgId ?? null,
+    };
     return runWithRequestContext({
         userEmail: email ?? undefined,
         orgId: orgId ?? undefined,
-    }, fn);
+    }, () => fn(context));
 }
 function serverHasVisibleTools(manager, serverId) {
     return manager
@@ -465,7 +470,7 @@ async function handleMcpAppCallTool(event, manager) {
         setResponseStatus(event, 400);
         return { error: "serverId and same-server toolName are required" };
     }
-    return withMcpAppRequestContext(event, async () => {
+    return withMcpAppRequestContext(event, async (context) => {
         const tool = mcpAppCallableTool(manager, serverId, originalToolName);
         if (!tool) {
             setResponseStatus(event, 403);
@@ -474,10 +479,10 @@ async function handleMcpAppCallTool(event, manager) {
         try {
             return await manager.callTool(tool.name, body.arguments && typeof body.arguments === "object"
                 ? body.arguments
-                : {});
+                : {}, { context });
         }
         catch (err) {
-            setResponseStatus(event, 400);
+            setResponseStatus(event, err?.statusCode === 403 ? 403 : 400);
             return { error: err?.message ?? "MCP tool call failed" };
         }
     });

package/dist/observability/metrics.d.ts

@@ -27,6 +27,8 @@ export interface GenAiChatMetric {
     supportedModels?: readonly string[];
     durationMs?: number;
     failed?: boolean;
+    /** The engine's error code for a failed call, bounded before it becomes `error.type`. */
+    errorCode?: string;
     inputTokens?: number;
     outputTokens?: number;
 }

package/dist/observability/metrics.js

@@ -7,6 +7,7 @@
  * a migration plan.
  */
 import { CORE_ACTION_GROUPS } from "../framework-tools.js";
+import { agentTroubleCauseForCode } from "../shared/analytics-events.js";
 import { getRegisteredObservabilityProvider, } from "./otel-provider.js";
 import { trackingIdentityProperties } from "./tracking-identity.js";
 const METER_NAME = "@agent-native/core";
@@ -120,6 +121,14 @@ function boundedModel(model, supportedModels) {
         ? model
         : "_OTHER";
 }
+// Error codes are thrower-supplied strings, so only HTTP statuses and the
+// closed trouble-cause set reach the label; everything else stays `_OTHER`.
+function boundedGenAiErrorType(errorCode) {
+    const normalized = errorCode?.trim().toLowerCase();
+    if (normalized && /^http_[45]\d\d$/.test(normalized))
+        return normalized;
+    return agentTroubleCauseForCode(normalized) ?? "_OTHER";
+}
 /** One model round trip (`gen_ai.operation.name=chat`). */
 export function recordGenAiChat(call) {
     const recorded = instruments();
@@ -131,7 +140,12 @@ export function recordGenAiChat(call) {
         ...(call.providerName ? { "gen_ai.provider.name": call.providerName } : {}),
     };
     if (call.durationMs !== undefined) {
-        recorded.genAiOperationDuration.record(Math.max(0, call.durationMs) / 1_000, call.failed ? { ...attributes, "error.type": "_OTHER" } : attributes);
+        recorded.genAiOperationDuration.record(Math.max(0, call.durationMs) / 1_000, call.failed
+            ? {
+                ...attributes,
+                "error.type": boundedGenAiErrorType(call.errorCode),
+            }
+            : attributes);
     }
     for (const [tokenType, tokens] of [
         ["input", call.inputTokens],

package/dist/observability/traces.js

@@ -523,7 +523,7 @@ export async function instrumentAgentLoop(opts) {
             finishOtelModelSpan(tripIndex, {
                 status: modelCallFailed ? "error" : "success",
                 errorMessage: modelErrorMessage,
-                errorCode: finalErrorCode,
+                errorCode: trip?.errorCode ?? finalErrorCode,
                 attributes: modelSpanAttributes(tripIndex),
                 endTime: modelRoundTrips[tripIndex]?.end,
             });
@@ -646,6 +646,8 @@ export async function instrumentAgentLoop(opts) {
                         trip.end = end;
                         if (event.reason)
                             trip.stopReason = event.reason;
+                        if (event.errorCode)
+                            trip.errorCode = event.errorCode;
                     }
                     if (event.reason === undefined || event.reason === "error") {
                         modelSpansAwaitingFinalError.add(tripIndex);
@@ -1362,6 +1364,11 @@ export async function instrumentAgentLoop(opts) {
                         failed: tripIndex === interruptedModelRoundTrip ||
                             !trip.stopReason ||
                             trip.stopReason === "error",
+                        // Only the last call's failure can be the one that ended the run.
+                        errorCode: trip.errorCode ??
+                            (tripIndex === modelRoundTrips.length - 1
+                                ? runTerminalCode
+                                : undefined),
                         inputTokens: trip.usage?.inputTokens,
                         outputTokens: trip.usage?.outputTokens,
                     });

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

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