@agent-native/core 0.154.4 → 0.154.5

package/corpus/templates/content/app/components/editor/database/DatabaseView.tsx

@@ -1631,6 +1631,11 @@ function DatabaseTable({
   ) {
     if (!databaseId) return null;
     if (isWorkspaceCatalog) return null;
+    const mutationContract = data?.mutationContract;
+    if (!mutationContract) {
+      toast.error(dbText("failedToCreateRow"));
+      return null;
+    }
     const propertyValues = {
       ...databasePropertyValuesForNewItem(filters, properties, filterMode),
       ...propertyValueOverrides,
@@ -1638,8 +1643,10 @@ function DatabaseTable({
     let response;
     try {
       response = await addItem.mutateAsync({
-        databaseId,
-        title,
+        target: mutationContract.target,
+        expectedSchemaRevision: mutationContract.schemaRevision,
+        idempotencyKey: crypto.randomUUID(),
+        ...(title.trim() ? { title } : {}),
         propertyValues:
           Object.keys(propertyValues).length > 0 ? propertyValues : undefined,
       });
@@ -1650,12 +1657,7 @@ function DatabaseTable({
       });
       return null;
     }
-    const createdItem = databaseCreatedItemForImmediatePreview(response, {
-      databaseId,
-      parentDocument: document,
-      title,
-      propertyValues,
-    });
+    const createdItem = response.createdItem ?? null;
     const needsPreview =
       !!createdItem &&
       databaseCreatedItemNeedsPreview(items, createdItem, options);

package/corpus/templates/content/app/hooks/use-content-database.ts

@@ -12,6 +12,7 @@ import type {
   CancelPreparedBuilderSourceUpdateResponse,
   ChangeContentDatabaseSourceRoleRequest,
   ContentDatabaseResponse,
+  ContentDatabaseRowMutationResult,
   ContentDatabaseSourceAttachmentAck,
   ContentDatabaseSourceAttachmentResult,
   ContentDatabaseItemsPageResponse,
@@ -819,40 +820,40 @@ export function useTrashedContentDatabases() {
 
 export function useAddDatabaseItem(documentId: string) {
   const queryClient = useQueryClient();
-  return useActionMutation<ContentDatabaseResponse, AddDatabaseItemRequest>(
-    "add-database-item",
-    {
-      skipActionQueryInvalidation: true,
-      onSuccess: (data) => {
-        if (data.createdItem) {
-          queryClient.setQueriesData<ContentDatabaseResponse>(
-            {
-              queryKey: ["action", "get-content-database"],
-              predicate: (query) => {
-                if (
-                  !isContentDatabaseQueryForDocument(query.queryKey, documentId)
-                ) {
-                  return false;
-                }
-                const params = query.queryKey[2] as {
-                  tableQuery?: unknown;
-                };
-                return params.tableQuery === undefined;
-              },
+  return useActionMutation<
+    ContentDatabaseRowMutationResult,
+    AddDatabaseItemRequest
+  >("add-database-item", {
+    skipActionQueryInvalidation: true,
+    onSuccess: (data) => {
+      if (data.createdItem) {
+        queryClient.setQueriesData<ContentDatabaseResponse>(
+          {
+            queryKey: ["action", "get-content-database"],
+            predicate: (query) => {
+              if (
+                !isContentDatabaseQueryForDocument(query.queryKey, documentId)
+              ) {
+                return false;
+              }
+              const params = query.queryKey[2] as {
+                tableQuery?: unknown;
+              };
+              return params.tableQuery === undefined;
             },
-            (current) =>
-              applyOptimisticItemToContentDatabase(current, data.createdItem!),
-          );
-        }
-        queryClient.invalidateQueries({
-          queryKey: contentDatabaseQueryKey(documentId),
-        });
-        queryClient.invalidateQueries({
-          queryKey: ["action", "list-documents"],
-        });
-      },
+          },
+          (current) =>
+            applyOptimisticItemToContentDatabase(current, data.createdItem!),
+        );
+      }
+      queryClient.invalidateQueries({
+        queryKey: contentDatabaseQueryKey(documentId),
+      });
+      queryClient.invalidateQueries({
+        queryKey: ["action", "list-documents"],
+      });
     },
-  );
+  });
 }
 
 export function useSubmitContentDatabaseForm(documentId: string) {

package/corpus/templates/content/changelog/2026-08-10-database-row-actions-now-validate-exact-schemas-and-safe-ret.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Database row actions now validate exact schemas and safe retries before changing data.

package/corpus/templates/content/parity/matrix.md

@@ -9,7 +9,7 @@ This generated matrix tracks whether high-value Content UI operations use the sa
 | database.lifecycle-and-trash                       | database    | Create, soft-delete, restore, list, and inspect content databases                                         | action-backed         | `create-content-database`, `create-inline-content-database`, `delete-content-database`, `get-content-database`, `list-content-databases`, `list-trashed-content-databases`, `restore-content-database`                                                                                                                                                                                                      | `app/components/editor/SlashCommandMenu.tsx`, `app/hooks/use-content-database.ts`, `app/hooks/use-documents.ts`                                                                           | Database pages and database records are created, read, soft-deleted, restored, and listed.                                                                                                                                                                                                | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`                                                                                                                                                                         | `database-source-scope`          | -                              |
 | database.private-preview-drafts                    | database    | Persist and reconcile a user's private database-page preview draft                                        | action-backed         | `get-preview-document-draft`, `update-preview-document-draft`                                                                                                                                                                                                                                                                                                                                               | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-documents.ts`                                                                                                           | A user's private preview draft is read, saved, conflict-checked, or deleted without changing the shared database page until the normal save flow applies it.                                                                                                                              | These per-user editor-state actions are intentionally hidden from agent tools because preview drafts are a private UI recovery mechanism.                                                                                                  | -                | P1             | covered       | `actions/preview-document-draft.db.test.ts`                                                                                                                                                                             | -                                | -                              |
 | database.properties-and-view-config                | database    | Configure properties, values, ordering, and saved views                                                   | action-backed         | `configure-document-property`, `delete-document-property`, `duplicate-document-property`, `get-content-database-personal-view`, `list-document-properties`, `reorder-document-property`, `set-document-property`, `update-content-database-personal-view`, `update-content-database-view`                                                                                                                   | `app/components/editor/DocumentProperties.tsx`, `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-document-properties.ts`   | Property schemas, property values, property order, filters, sorts, grouping, hidden columns, view type, and view settings are stored.                                                                                                                                                     | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/bind-content-database-source-field.db.test.ts`, `actions/content-database-source-actions.test.ts`, `actions/resync-content-database-source.db.test.ts`                                                         | `database-source-scope`          | -                              |
-| database.rows                                      | database    | Add, duplicate, move, open, edit, and remove database rows                                                | action-backed         | `add-database-item`, `upsert-database-item-by-key`, `remove-database-items`, `duplicate-database-items`, `duplicate-database-item`, `migrate-content-database-rows`, `move-database-item`, `set-document-property`                                                                                                                                                                                          | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row memberships and ordering are created, duplicated, moved, edited, and removed without deleting the backing page; bounded migrations atomically update row bodies and properties through the same canonical data model.                                                        | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `actions/migrate-content-database-rows.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`                                                          | `database-bulk-row-reliability`  | -                              |
+| database.rows                                      | database    | Add, duplicate, move, open, edit, and remove database rows                                                | action-backed         | `add-database-item`, `update-database-item`, `upsert-database-item-by-key`, `remove-database-items`, `duplicate-database-items`, `duplicate-database-item`, `migrate-content-database-rows`, `move-database-item`, `set-document-property`                                                                                                                                                                  | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row memberships and ordering are created, duplicated, moved, edited, and removed without deleting the backing page; bounded migrations atomically update row bodies and properties through the same canonical data model.                                                        | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `actions/upsert-database-item-by-key.db.test.ts`, `actions/migrate-content-database-rows.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`        | `database-bulk-row-reliability`  | -                              |
 | database.table-query-page                          | database    | Query one constrained page while retaining database metadata                                              | action-backed         | `query-content-database-items`                                                                                                                                                                                                                                                                                                                                                                              | `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`                                                                                                    | -                                                                                                                                                                                                                                                                                         | This UI-only bounded projection is intentionally hidden with agentTool: false; agents use get-content-database for the complete database contract.                                                                                         | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`, `app/hooks/use-content-database.test.ts`                                                                                                                               | -                                | -                              |
 | editor.agent-assist-prompts                        | editor      | Ask AI from slash generation or comment context                                                           | client-assist         | -                                                                                                                                                                                                                                                                                                                                                                                                           | `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/CommentsSidebar.tsx`                                                                                                 | No direct durable mutation; the prompt asks the agent to use document actions when it decides to write.                                                                                                                                                                                   | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                                                                                       | -                                | -                              |
 | editor.client-formatting-and-insertions            | editor      | Rich text formatting, selection state, slash block insertion, and copy actions                            | client-only-ephemeral | -                                                                                                                                                                                                                                                                                                                                                                                                           | `app/components/editor/BubbleToolbar.tsx`, `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/DocumentToolbar.tsx`                                                      | -                                                                                                                                                                                                                                                                                         | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                                                                                       | -                                | -                              |

package/corpus/templates/content/parity/matrix.ts

@@ -345,6 +345,7 @@ export const parityMatrix: ParityRow[] = [
     status: "action-backed",
     actions: [
       "add-database-item",
+      "update-database-item",
       "upsert-database-item-by-key",
       "remove-database-items",
       "duplicate-database-items",
@@ -360,6 +361,7 @@ export const parityMatrix: ParityRow[] = [
     followUpPR: null,
     coverageRefs: [
       "actions/database-row-batch-actions.db.test.ts",
+      "actions/upsert-database-item-by-key.db.test.ts",
       "actions/migrate-content-database-rows.db.test.ts",
       "parity/__tests__/database-row-batch-reliability.test.ts",
     ],

package/corpus/templates/content/server/db/schema.ts

@@ -234,6 +234,7 @@ export const contentDatabases = table(
     ownerBlockId: text("owner_block_id"),
     title: text("title").notNull().default("Untitled database"),
     systemRole: text("system_role"),
+    naturalKeyPropertyId: text("natural_key_property_id"),
     viewConfigJson: text("view_config_json").notNull().default("{}"),
     filesSystemPropertiesSeeded: integer("files_system_properties_seeded")
       .notNull()
@@ -287,9 +288,9 @@ export const contentDatabaseItems = table(
   ],
 );
 
-// Opt-in stable-key claims are the durable concurrency fence for the generic
-// database-row upsert action. They intentionally do not constrain ordinary
-// property editing or change add-database-item behavior.
+// Opt-in stable-key claims are the durable concurrency fence for configured
+// natural-key upserts. Ordinary property editing stays independent until a
+// text property is explicitly selected as the database's natural key.
 export const contentDatabaseItemKeyClaims = table(
   "content_database_item_key_claims",
   {
@@ -494,6 +495,41 @@ export const contentDatabaseMigrationReceipts = table(
   ],
 );
 
+export const contentDatabaseRowMutationReceipts = table(
+  "content_database_row_mutation_receipts",
+  {
+    id: text("id").primaryKey(),
+    ownerEmail: text("owner_email").notNull().default("local@localhost"),
+    orgId: text("org_id"),
+    spaceId: text("space_id").notNull(),
+    databaseId: text("database_id").notNull(),
+    databaseDocumentId: text("database_document_id").notNull(),
+    operation: text("operation").notNull(),
+    itemId: text("item_id").notNull(),
+    documentId: text("document_id").notNull(),
+    idempotencyKey: text("idempotency_key").notNull(),
+    payloadDigest: text("payload_digest").notNull(),
+    schemaRevision: text("schema_revision").notNull(),
+    preRowRevision: text("pre_row_revision"),
+    postRowRevision: text("post_row_revision").notNull(),
+    resultJson: text("result_json").notNull().default("{}"),
+    createdAt: text("created_at").notNull().default(now()),
+    updatedAt: text("updated_at").notNull().default(now()),
+  },
+  (receipt) => [
+    uniqueIndex(
+      "content_database_row_mutation_receipts_database_key_unique",
+    ).on(receipt.databaseId, receipt.idempotencyKey),
+    index("content_database_row_mutation_receipts_owner_database_idx").on(
+      receipt.ownerEmail,
+      receipt.databaseId,
+    ),
+    index("content_database_row_mutation_receipts_document_idx").on(
+      receipt.documentId,
+    ),
+  ],
+);
+
 export const documentPropertyValues = table("document_property_values", {
   id: text("id").primaryKey(),
   ownerEmail: text("owner_email").notNull().default("local@localhost"),

package/corpus/templates/content/server/plugins/db.ts

@@ -1011,6 +1011,36 @@ export const runContentMigrations = runMigrations(
         ALTER TABLE document_blocks ALTER COLUMN addressable SET DEFAULT true`,
       },
     },
+    {
+      version: 84,
+      name: "content-database-row-mutation-contract",
+      sql: `ALTER TABLE content_databases ADD COLUMN IF NOT EXISTS natural_key_property_id TEXT;
+      CREATE TABLE IF NOT EXISTS content_database_row_mutation_receipts (
+        id TEXT PRIMARY KEY,
+        owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+        org_id TEXT,
+        space_id TEXT NOT NULL,
+        database_id TEXT NOT NULL,
+        database_document_id TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        item_id TEXT NOT NULL,
+        document_id TEXT NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        payload_digest TEXT NOT NULL,
+        schema_revision TEXT NOT NULL,
+        pre_row_revision TEXT,
+        post_row_revision TEXT NOT NULL,
+        result_json TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE UNIQUE INDEX IF NOT EXISTS content_database_row_mutation_receipts_database_key_unique
+        ON content_database_row_mutation_receipts (database_id, idempotency_key);
+      CREATE INDEX IF NOT EXISTS content_database_row_mutation_receipts_owner_database_idx
+        ON content_database_row_mutation_receipts (owner_email, database_id);
+      CREATE INDEX IF NOT EXISTS content_database_row_mutation_receipts_document_idx
+        ON content_database_row_mutation_receipts (document_id)`,
+    },
   ],
   { table: "content_migrations" },
 );

package/corpus/templates/content/shared/api.ts

@@ -225,6 +225,7 @@ export interface ConfigureDocumentPropertyRequest {
   description?: string;
   visibility?: DocumentPropertyVisibility;
   options?: DocumentPropertyOptions;
+  naturalKey?: boolean;
 }
 
 export interface SetDocumentPropertyRequest {
@@ -258,8 +259,10 @@ export interface ReorderDocumentPropertyRequest {
 export interface ContentDatabase {
   id: string;
   documentId: string;
+  spaceId?: string | null;
   title: string;
   systemRole?: string | null;
+  naturalKeyPropertyId?: string | null;
   description?: string;
   viewConfig: ContentDatabaseViewConfig;
   createdAt: string;
@@ -469,6 +472,62 @@ export interface ContentDatabaseItem {
   // a secondary source contributes on top of it. Absent for non-federated rows.
   canonicalKey?: string | null;
   sourceOverlays?: ContentDatabaseSourceOverlay[];
+  rowRevision?: string;
+}
+
+export interface ContentDatabaseMutationTarget {
+  authorityScope:
+    | { kind: "personal"; id: string }
+    | { kind: "organization"; id: string };
+  spaceId: string;
+  databaseId: string;
+  databaseDocumentId: string;
+}
+
+export interface ContentDatabaseMutationContract {
+  target: ContentDatabaseMutationTarget;
+  schemaRevision: string;
+  naturalKeyPropertyId: string | null;
+  properties: Array<{
+    id: string;
+    name: string;
+    type: DocumentPropertyType;
+    writable: boolean;
+    sourceManaged: boolean;
+    acceptedShape: string | null;
+    options: DocumentPropertyOptions;
+  }>;
+}
+
+export interface ContentDatabaseRowMutationReceipt {
+  receiptId: string;
+  operation: "create" | "update" | "upsert";
+  outcome: "created" | "updated" | "unchanged";
+  target: ContentDatabaseMutationTarget;
+  schemaRevision: string;
+  row: {
+    itemId: string;
+    documentId: string;
+    urlPath: string;
+    rowRevision: string;
+  };
+  affected: { title: boolean; propertyIds: string[] };
+  idempotency: {
+    key: string;
+    result: "applied" | "replayed";
+    payloadDigest: string;
+  };
+  revisions: { before: string | null; after: string };
+  readback: {
+    verified: true;
+    title: string;
+    propertyValues: Record<string, DocumentPropertyValue>;
+  };
+}
+
+export interface ContentDatabaseRowMutationResult {
+  receipt: ContentDatabaseRowMutationReceipt;
+  createdItem?: ContentDatabaseItem;
 }
 
 // A secondary source's read-only contribution to a federated row, matched on the
@@ -828,6 +887,7 @@ export interface ContentDatabaseResponse {
   removedCount?: number;
   timings?: BuilderActionTiming[];
   tableQueryMode?: "server" | "client-required";
+  mutationContract?: ContentDatabaseMutationContract;
   /** Client-only optimistic state while real provider rows are being attached. */
   attachPreview?: {
     sourceTable: string;
@@ -892,9 +952,22 @@ export interface CreateInlineDatabaseResponse {
 }
 
 export interface AddDatabaseItemRequest {
-  databaseId: string;
+  target: ContentDatabaseMutationTarget;
+  expectedSchemaRevision: string;
+  idempotencyKey: string;
   title?: string;
-  propertyValues?: Record<string, DocumentPropertyValue>;
+  propertyValues?: Record<string, unknown>;
+}
+
+export interface UpdateDatabaseItemRequest extends AddDatabaseItemRequest {
+  itemId: string;
+  documentId: string;
+  expectedRowRevision: string;
+}
+
+export interface UpsertDatabaseItemByKeyRequest extends AddDatabaseItemRequest {
+  keyValue: string;
+  expectedRowRevision: string | null;
 }
 
 export interface SubmitContentDatabaseFormRequest {

package/dist/action.d.ts

@@ -135,6 +135,28 @@ export interface AgentActionStopOptions {
     /** Optional short tool-result text. Defaults to the user-facing message. */
     toolResult?: string;
 }
+export interface ActionContractErrorOptions {
+    /** Stable machine-readable code safe to expose on every action transport. */
+    errorCode: string;
+    /** Safe structured context for callers. Never include secrets or raw driver errors. */
+    details?: Record<string, unknown>;
+    /** HTTP status for the action route. Contract conflicts normally use 409. */
+    statusCode?: number;
+}
+/**
+ * A deterministic, caller-correctable action contract failure.
+ *
+ * Unlike an ordinary Error, its code and explicitly safe details survive the
+ * framework HTTP transport. Internal failures remain generic 500 responses.
+ */
+export declare class ActionContractError extends Error {
+    readonly actionContractError = true;
+    readonly errorCode: string;
+    readonly details?: Record<string, unknown>;
+    readonly statusCode: number;
+    constructor(message: string, options: ActionContractErrorOptions);
+}
+export declare function isActionContractError(error: unknown): error is ActionContractError;
 /**
  * Throw from an action when the agent should stop the current turn instead of
  * feeding the failure back to the model for another retry.

package/dist/action.js

@@ -1,5 +1,32 @@
 import { normalizeActionChatUIConfig, } from "./action-ui.js";
 import { normalizeAuditConfig, resolveAuditAttach } from "./audit/config.js";
+/**
+ * A deterministic, caller-correctable action contract failure.
+ *
+ * Unlike an ordinary Error, its code and explicitly safe details survive the
+ * framework HTTP transport. Internal failures remain generic 500 responses.
+ */
+export class ActionContractError extends Error {
+    actionContractError = true;
+    errorCode;
+    details;
+    statusCode;
+    constructor(message, options) {
+        super(message);
+        this.name = "ActionContractError";
+        this.errorCode = options.errorCode;
+        this.details = options.details;
+        this.statusCode = options.statusCode ?? 409;
+    }
+}
+export function isActionContractError(error) {
+    return (error instanceof ActionContractError ||
+        (!!error &&
+            typeof error === "object" &&
+            error.actionContractError ===
+                true &&
+            typeof error.errorCode === "string"));
+}
 /**
  * Throw from an action when the agent should stop the current turn instead of
  * feeding the failure back to the model for another retry.

package/dist/collab/awareness.d.ts

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

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/index.browser.d.ts

@@ -2,7 +2,7 @@ export * from "./config.js";
 export { addContextToAgentChat, appendAgentChatContextToMessage, clearAgentChatContext, formatAgentChatContextItemsForPrompt, listAgentChatContext, refreshAgentChatContext, removeAgentChatContextItem, sendToAgentChat, sendToAgentChatAndConfirm, setAgentChatContextItem, setContextToAgentChat, isEmbedMcpChatBridgeActive, useAgentChatContext, useAgentChatGenerating, useDevMode, useSendToAgentChat, AGENT_NATIVE_MCP_APP_HOST_MESSAGE_TYPES, getMcpAppHostContext, openMcpAppHostLink, requestMcpAppDisplayMode, sendMcpAppHostMessage, updateMcpAppModelContext, useMcpAppHostContext, CodeRequiredDialog, AgentNativeI18nProvider, LanguagePicker, getLocaleInitScript, localeDirection, normalizeLocaleCode, normalizeLocalePreference, normalizeLocalizationPreference, resolveLocaleFromCandidates, resolveLocaleFromPreference, useFormatters, useLocale, useT, DEFAULT_LOCALE, LOCALE_HYDRATION_GLOBAL, LOCALE_METADATA, LOCALE_STORAGE_KEY, SUPPORTED_LOCALES, useDbSync, useFileWatcher, useSession, cn, ApiKeySettings, type AgentChatContextItem, type AgentChatContextMessage, type AgentChatContextMutationOptions, type AgentChatContextRemoveOptions, type AgentChatContextSetOptions, type AgentChatContextState, type AgentChatMessage, type AgentNativeMcpAppHostMessageType, type McpAppDisplayMode, type McpAppHostChatMessage, type McpAppHostCapabilities, type McpAppHostContext, type McpAppHostContextSnapshot, type McpAppModelContextContentPart, type McpAppModelContextUpdate, type CodeRequiredDialogProps, type AuthSession, type UseAgentChatContextResult, type AgentNativeI18nCatalog, type AgentNativeI18nProviderProps, type LocaleCode, type LocaleHydrationPayload, type LocaleMessages, type LocaleMetadata, type LocalePreference, type LocalizationPreference, } from "./client/index.js";
 export { agentChat } from "./shared/index.js";
 export { parseArgs, camelCaseArgs } from "./scripts/parse-args.js";
-export { defineAction, AgentActionStopError, isAgentActionStopError, type ActionHttpConfig, type AgentActionStopOptions, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, type ActionMcpAppConfig, type ActionMcpAppCsp, type ActionMcpAppCspBuilder, type ActionMcpAppHtmlBuilder, type ActionMcpAppPermissions, type ActionMcpAppResourceConfig, type ActionMcpAppResourceMeta, } from "./action.js";
+export { defineAction, ActionContractError, isActionContractError, type ActionContractErrorOptions, AgentActionStopError, isAgentActionStopError, type ActionHttpConfig, type AgentActionStopOptions, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, type ActionMcpAppConfig, type ActionMcpAppCsp, type ActionMcpAppCspBuilder, type ActionMcpAppHtmlBuilder, type ActionMcpAppPermissions, type ActionMcpAppResourceConfig, type ActionMcpAppResourceMeta, } from "./action.js";
 export { normalizeUserProfileName, USER_PROFILE_SETTING_KEY, type UserProfile, } from "./user-profile/index.js";
 export { ACTION_CHAT_UI_DATA_CHART_RENDERER, ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER, ACTION_CHAT_UI_DATA_TABLE_RENDERER, ACTION_CHAT_UI_DATA_WIDGET_RENDERER, ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER, ACTION_CHAT_UI_WORKSPACE_FILE_RENDERER, type ActionChatUIConfig, } from "./action-ui.js";
 export { DATA_CHART_WIDGET, DATA_INSIGHTS_WIDGET, DATA_TABLE_WIDGET, createDataChartWidgetResult, createDataInsightsWidgetResult, createDataTableWidgetResult, dataChartWidgetResultSchema, dataChartWidgetSchema, dataInsightsWidgetResultSchema, dataTableWidgetResultSchema, dataTableWidgetSchema, dataWidgetResultSchema, isDataChartWidget, isDataTableWidget, isDataWidgetResult, normalizeDataWidgetKind, normalizeDataWidgetResult, type DataChartSeriesDefinition, type DataChartWidget, type DataChartWidgetResult, type DataChartWidgetResultInput, type DataInsightsWidgetResult, type DataInsightsWidgetResultInput, type DataTableColumn, type DataTableWidget, type DataTableWidgetResult, type DataTableWidgetResultInput, type DataWidgetDisplay, type DataWidgetKind, type DataWidgetResult, type DataWidgetResultMetadata, } from "./data-widgets/index.js";

package/dist/index.browser.js

@@ -9,7 +9,7 @@ export { agentChat } from "./shared/index.js";
 // Pure utilities (no Node.js deps — safe for browser and SSR)
 export { parseArgs, camelCaseArgs } from "./scripts/parse-args.js";
 // defineAction — used by template actions, no Node.js deps
-export { defineAction, AgentActionStopError, isAgentActionStopError, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, } from "./action.js";
+export { defineAction, ActionContractError, isActionContractError, AgentActionStopError, isAgentActionStopError, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, } from "./action.js";
 export { normalizeUserProfileName, USER_PROFILE_SETTING_KEY, } from "./user-profile/index.js";
 export { ACTION_CHAT_UI_DATA_CHART_RENDERER, ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER, ACTION_CHAT_UI_DATA_TABLE_RENDERER, ACTION_CHAT_UI_DATA_WIDGET_RENDERER, ACTION_CHAT_UI_INLINE_EXTENSION_RENDERER, ACTION_CHAT_UI_WORKSPACE_FILE_RENDERER, } from "./action-ui.js";
 export { DATA_CHART_WIDGET, DATA_INSIGHTS_WIDGET, DATA_TABLE_WIDGET, createDataChartWidgetResult, createDataInsightsWidgetResult, createDataTableWidgetResult, dataChartWidgetResultSchema, dataChartWidgetSchema, dataInsightsWidgetResultSchema, dataTableWidgetResultSchema, dataTableWidgetSchema, dataWidgetResultSchema, isDataChartWidget, isDataTableWidget, isDataWidgetResult, normalizeDataWidgetKind, normalizeDataWidgetResult, } from "./data-widgets/index.js";

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./config.js";
 export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, DEFAULT_MODEL, TripWire, type Processor, type ProcessorState, type ProcessorAbort, } from "./agent/index.js";
-export { defineAction, AgentActionStopError, isAgentActionStopError, type ActionDefinition, type ActionHttpConfig, type AgentActionStopOptions, type PublicAgentActionConfig, type ActionDeepLink, type ActionLinkBuilder, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, type ActionMcpAppConfig, type ActionMcpAppCsp, type ActionMcpAppCspBuilder, type ActionMcpAppHtmlBuilder, type ActionMcpAppPermissions, type ActionMcpAppResourceConfig, type ActionMcpAppResourceMeta, } from "./action.js";
+export { defineAction, ActionContractError, isActionContractError, type ActionContractErrorOptions, AgentActionStopError, isAgentActionStopError, type ActionDefinition, type ActionHttpConfig, type AgentActionStopOptions, type PublicAgentActionConfig, type ActionDeepLink, type ActionLinkBuilder, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, type ActionMcpAppConfig, type ActionMcpAppCsp, type ActionMcpAppCspBuilder, type ActionMcpAppHtmlBuilder, type ActionMcpAppPermissions, type ActionMcpAppResourceConfig, type ActionMcpAppResourceMeta, } from "./action.js";
 export * from "./user-profile/index.js";
 export { embedApp, MCP_APP_REQUEST_ORIGIN_CSP_SOURCE, type EmbedAppOptions, } from "./mcp/embed-app.js";
 export { embedRoute, type EmbedRouteContext, type EmbedRouteOptions, type EmbedRoutePathBuilder, type EmbedRouteResult, } from "./mcp/embed-route.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export * from "./config.js";
 export { createProductionAgentHandler, DEFAULT_MODEL, 
 // In-loop processors (observers/guardrails for runAgentLoop)
 TripWire, } from "./agent/index.js";
-export { defineAction, AgentActionStopError, isAgentActionStopError, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, } from "./action.js";
+export { defineAction, ActionContractError, isActionContractError, AgentActionStopError, isAgentActionStopError, MCP_APP_EXTENSION_ID, MCP_APP_MIME_TYPE, MCP_APP_RESOURCE_URI_META_KEY, } from "./action.js";
 export * from "./user-profile/index.js";
 export { embedApp, MCP_APP_REQUEST_ORIGIN_CSP_SOURCE, } from "./mcp/embed-app.js";
 export { embedRoute, } from "./mcp/embed-route.js";

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

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

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    status?: undefined;
     ok?: undefined;
+    status?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
+    ok?: undefined;
     error: string;
     removed?: undefined;
-    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
+    ok?: undefined;
     error: string;
     note?: undefined;
-    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/action-routes.js

@@ -1,6 +1,6 @@
 import { createError, defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getQuery, getHeader, getRequestURL, } from "h3";
 import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
-import { isAgentActionStopError } from "../action.js";
+import { isActionContractError, isAgentActionStopError } from "../action.js";
 import { declaresFeatureFlagDelegation } from "../feature-flags/a2a-action-route.js";
 import { resolveOrgByDomain, resolveOrgIdForEmail } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
@@ -507,7 +507,15 @@ export function mountActionRoutes(nitroApp, actions, options) {
                         isAgentActionStopError(err) ||
                         (explicitStatus !== undefined && explicitStatus < 500);
                     if (isUserFacing) {
-                        return { error: msg };
+                        return isActionContractError(err)
+                            ? {
+                                error: msg,
+                                errorCode: err.errorCode,
+                                ...(err.details === undefined
+                                    ? {}
+                                    : { details: err.details }),
+                            }
+                            : { error: msg };
                     }
                     const requestId = getHttpRequestTelemetryId(event);
                     const captureId = captureError(err, {