@agent-native/core 0.171.0 → 0.171.1

package/corpus/templates/analytics/server/lib/workspace-feature-flags.ts

@@ -1,6 +1,10 @@
 import { randomUUID } from "node:crypto";
 
 import { signA2AToken } from "@agent-native/core/a2a";
+import {
+  ActionContractError,
+  AgentActionStopError,
+} from "@agent-native/core/action";
 import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
 import { fetchOrgApps, type OrgApp } from "@agent-native/core/mcp";
 import { getOrgDomain } from "@agent-native/core/org";
@@ -9,6 +13,7 @@ import { VERIFIED_FLEET_FLAG_MUTATIONS } from "../../shared/feature-flags.js";
 import type { AnalyticsAdminContext } from "./db-admin-connections.js";
 
 const TARGET_TIMEOUT_MS = 3_000;
+const VERIFICATION_ATTEMPTS = 2;
 const CONCURRENCY = 4;
 
 export type FleetFlagState =
@@ -197,6 +202,8 @@ export type WorkspaceFeatureFlagFailurePhase =
   | "unsupported-target"
   | "target-action"
   | "persistence"
+  | "verification-timeout"
+  | "verification-network"
   | "verification";
 
 const FAILURE_MESSAGES: Record<WorkspaceFeatureFlagFailurePhase, string> = {
@@ -211,16 +218,42 @@ const FAILURE_MESSAGES: Record<WorkspaceFeatureFlagFailurePhase, string> = {
   "target-action": "The target app could not complete the feature flag action.",
   persistence:
     "The target app did not persist the requested feature flag rules.",
+  "verification-timeout":
+    "The feature flag change persisted, but the target app timed out during verification.",
+  "verification-network":
+    "The feature flag change persisted, but Analytics could not reach the target app during verification.",
   verification: "Analytics could not verify the persisted feature flag change.",
 };
 
-export class WorkspaceFeatureFlagFailure extends Error {
+export class WorkspaceFeatureFlagFailure extends AgentActionStopError {
   constructor(readonly phase: WorkspaceFeatureFlagFailurePhase) {
-    super(`[${phase}] ${FAILURE_MESSAGES[phase]}`);
+    const message = `[${phase}] ${FAILURE_MESSAGES[phase]}`;
+    const errorCode = `workspace_feature_flag_${phase.replace("-", "_")}`;
+    super(message, {
+      errorCode,
+      details: { phase },
+      toolResult: JSON.stringify({ error: errorCode, phase, message }),
+    });
     this.name = "WorkspaceFeatureFlagFailure";
   }
 }
 
+class WorkspaceFeatureFlagSetupFailure extends ActionContractError {
+  readonly phase: "directory" | "token-generation";
+
+  constructor(phase: "directory" | "token-generation") {
+    const message = `[${phase}] ${FAILURE_MESSAGES[phase]}`;
+    const errorCode = `workspace_feature_flag_${phase.replace("-", "_")}`;
+    super(message, {
+      errorCode,
+      details: { phase },
+      statusCode: 503,
+    });
+    this.name = "WorkspaceFeatureFlagSetupFailure";
+    this.phase = phase;
+  }
+}
+
 type TargetFailureReason = "token-generation" | "timeout" | "network";
 
 class TargetCallFailure extends Error {
@@ -242,6 +275,16 @@ export function classifyWorkspaceFeatureFlagTargetFailure(
   return "network";
 }
 
+function isSyntaxError(error: unknown): boolean {
+  return (
+    error instanceof SyntaxError ||
+    (!!error &&
+      typeof error === "object" &&
+      "name" in error &&
+      error.name === "SyntaxError")
+  );
+}
+
 function targetFailure(error: unknown): WorkspaceFeatureFlagFailure {
   const reason = classifyWorkspaceFeatureFlagTargetFailure(error);
   return new WorkspaceFeatureFlagFailure(reason);
@@ -259,10 +302,10 @@ async function resolveTargetApp(
       serviceOrgId: admin.orgId,
     });
   } catch {
-    throw new WorkspaceFeatureFlagFailure("directory");
+    throw new WorkspaceFeatureFlagSetupFailure("directory");
   }
   const app = apps.find((candidate) => candidate.id === appId);
-  if (!app) throw new WorkspaceFeatureFlagFailure("directory");
+  if (!app) throw new WorkspaceFeatureFlagSetupFailure("directory");
   return app;
 }
 
@@ -302,12 +345,41 @@ async function callTarget(
   let parsed: unknown = null;
   try {
     parsed = await response.json();
-  } catch {
-    // A legacy/non-action endpoint is classified below without reflecting body.
+  } catch (error) {
+    const successfulResponse = response.status >= 200 && response.status < 300;
+    if (successfulResponse && !isSyntaxError(error))
+      throw new TargetCallFailure(
+        classifyWorkspaceFeatureFlagTargetFailure(error),
+      );
+    // Invalid legacy payloads and non-success statuses are classified below.
   }
   return { status: response.status, body: parsed };
 }
 
+async function readBackTarget(
+  app: OrgApp,
+  admin: AnalyticsAdminContext,
+  orgDomain: string,
+): Promise<{ status: number; body: unknown }> {
+  for (let attempt = 1; attempt <= VERIFICATION_ATTEMPTS; attempt += 1) {
+    try {
+      return await callTarget(app, admin, "list-feature-flags", {}, orgDomain);
+    } catch (error) {
+      const reason = classifyWorkspaceFeatureFlagTargetFailure(error);
+      const retryable = reason === "timeout" || reason === "network";
+      if (retryable && attempt < VERIFICATION_ATTEMPTS) continue;
+      throw new WorkspaceFeatureFlagFailure(
+        reason === "timeout"
+          ? "verification-timeout"
+          : reason === "network"
+            ? "verification-network"
+            : reason,
+      );
+    }
+  }
+  throw new WorkspaceFeatureFlagFailure("verification");
+}
+
 export function classifyWorkspaceFeatureFlagList(
   app: OrgApp,
   result: { status: number; body: unknown },
@@ -404,9 +476,10 @@ export async function setWorkspaceFeatureFlag(
   try {
     orgDomain = (await getOrgDomain(admin.orgId))?.trim().toLowerCase();
   } catch {
-    throw new WorkspaceFeatureFlagFailure("token-generation");
+    throw new WorkspaceFeatureFlagSetupFailure("token-generation");
   }
-  if (!orgDomain) throw new WorkspaceFeatureFlagFailure("token-generation");
+  if (!orgDomain)
+    throw new WorkspaceFeatureFlagSetupFailure("token-generation");
   let result: Awaited<ReturnType<typeof callTarget>>;
   try {
     result = await callTarget(
@@ -417,6 +490,8 @@ export async function setWorkspaceFeatureFlag(
       orgDomain,
     );
   } catch (error) {
+    if (classifyWorkspaceFeatureFlagTargetFailure(error) === "token-generation")
+      throw new WorkspaceFeatureFlagSetupFailure("token-generation");
     throw targetFailure(error);
   }
   if (result.status === 401 || result.status === 403)
@@ -465,18 +540,7 @@ export async function setWorkspaceFeatureFlag(
     return mutation;
   }
 
-  let readBack: Awaited<ReturnType<typeof callTarget>>;
-  try {
-    readBack = await callTarget(
-      app,
-      admin,
-      "list-feature-flags",
-      {},
-      orgDomain,
-    );
-  } catch (error) {
-    throw targetFailure(error);
-  }
+  const readBack = await readBackTarget(app, admin, orgDomain);
   if (readBack.status === 401 || readBack.status === 403)
     throw new WorkspaceFeatureFlagFailure("authorization");
   if (readBack.status === 404 || readBack.status === 405)

package/dist/action.d.ts

@@ -130,8 +130,10 @@ export interface ActionRunContext {
  */
 export type ActionAuthorize<TArgs> = (args: TArgs, ctx?: ActionRunContext) => void | boolean | Promise<void | boolean>;
 export interface AgentActionStopOptions {
-    /** Optional stable code surfaced in run metadata and tests. */
+    /** Optional stable code safe to surface in run metadata and action transports. */
     errorCode?: string;
+    /** Safe structured context for callers. Never include secrets or raw driver errors. */
+    details?: Record<string, unknown>;
     /** Optional short tool-result text. Defaults to the user-facing message. */
     toolResult?: string;
 }
@@ -164,6 +166,7 @@ export declare function isActionContractError(error: unknown): error is ActionCo
 export declare class AgentActionStopError extends Error {
     readonly agentNativeStop = true;
     readonly errorCode?: string;
+    readonly details?: Record<string, unknown>;
     readonly toolResult?: string;
     constructor(message: string, options?: AgentActionStopOptions);
 }

package/dist/action.js

@@ -34,11 +34,13 @@ export function isActionContractError(error) {
 export class AgentActionStopError extends Error {
     agentNativeStop = true;
     errorCode;
+    details;
     toolResult;
     constructor(message, options = {}) {
         super(message);
         this.name = "AgentActionStopError";
         this.errorCode = options.errorCode;
+        this.details = options.details;
         this.toolResult = options.toolResult;
     }
 }

package/dist/client/use-action.js

@@ -366,6 +366,14 @@ async function performActionFetch(name, method, params, options) {
         }
         const error = new Error(`Action ${name} failed: ${message}`);
         error.status = res.status;
+        if (typeof data?.errorCode === "string") {
+            error.errorCode = data.errorCode;
+        }
+        if (data?.details &&
+            typeof data.details === "object" &&
+            !Array.isArray(data.details)) {
+            error.details = data.details;
+        }
         throw error;
     }
     // 2xx but the body couldn't even be read (mid-stream abort, decode failure,

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<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/observability/routes.d.ts

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

package/dist/progress/routes.d.ts

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

package/dist/resources/handlers.d.ts

@@ -51,8 +51,8 @@ export declare function handleDeleteResource(event: any): Promise<{
     error: string;
     ok?: undefined;
 } | {
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>;
 /** POST /_agent-native/resources/upload — upload a file as a resource */
 export declare function handleUploadResource(event: any): Promise<import("./store.js").Resource | {
@@ -73,10 +73,10 @@ export declare function handleUploadResource(event: any): Promise<import("./stor
     runId: string | null;
     expiresAt: number | null;
     metadata: string | null;
+    error?: undefined;
     url: string;
     provider: string;
     storageSetupRequired?: undefined;
-    error?: undefined;
 } | {
     error: string;
     storageSetupRequired: boolean;

package/dist/server/action-routes.js

@@ -543,19 +543,23 @@ export function mountActionRoutes(nitroApp, actions, options) {
                     setResponseStatus(event, status);
                     // Only echo the raw message for known-safe cases:
                     //  - validation errors (deterministic, parameter-shape only)
+                    //  - action contract errors (explicitly safe on every transport)
                     //  - explicit user-facing errors (AgentActionStopError / fail())
                     //  - errors with an explicit statusCode < 500 (client errors)
                     // For uncategorized 500s, return a generic message and keep the
                     // real detail server-side only — it can contain DB/driver/
                     // upstream text we must not leak to HTTP callers.
                     const isUserFacing = isValidationError ||
+                        isActionContractError(err) ||
                         isAgentActionStopError(err) ||
                         (explicitStatus !== undefined && explicitStatus < 500);
                     if (isUserFacing) {
-                        return isActionContractError(err)
+                        return isActionContractError(err) || isAgentActionStopError(err)
                             ? {
                                 error: msg,
-                                errorCode: err.errorCode,
+                                ...(typeof err.errorCode === "string"
+                                    ? { errorCode: err.errorCode }
+                                    : {}),
                                 ...(err.details === undefined
                                     ? {}
                                     : { details: err.details }),

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

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

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.171.0",
+  "version": "0.171.1",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {