@agent-native/core 0.107.1 → 0.108.0

package/corpus/core/src/server/action-routes.ts

@@ -9,8 +9,10 @@ import {
   getRequestURL,
 } from "h3";
 
+import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
 import { isAgentActionStopError } from "../action.js";
 import type { ActionEntry } from "../agent/production-agent.js";
+import { declaresFeatureFlagDelegation } from "../feature-flags/a2a-action-route.js";
 import { resolveOrgIdForEmail } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
@@ -39,6 +41,30 @@ import { runWithRequestContext } from "./request-context.js";
 
 const ROUTE_PREFIX = "/_agent-native/actions";
 
+async function resolveFeatureFlagA2ACaller(event: any, actionName: string) {
+  const required =
+    actionName === "list-feature-flags"
+      ? "flags:read"
+      : actionName === "set-feature-flag"
+        ? "flags:write"
+        : null;
+  if (!required) return null;
+  const authorization = getHeader(event, "authorization");
+  if (!authorization?.startsWith("Bearer ")) return null;
+  const token = authorization.slice(7);
+  if (!declaresFeatureFlagDelegation(token)) return null;
+  const claims = await verifyA2ATokenWithClaims(token, event);
+  if (!claims || !claims.scope.includes(required))
+    throw new Error("Invalid feature flag delegation");
+  return {
+    owner: claims.email,
+    orgId: claims.orgId,
+    anonymous: false,
+    delegationJti: claims.jti,
+    delegationIssuer: claims.issuer,
+  } as ActionRouteResolvedCaller;
+}
+
 export function parseActionSearchParams(
   searchParams: URLSearchParams,
 ): Record<string, any> {
@@ -189,6 +215,9 @@ export type ActionRouteResolvedCaller = AgentRunOwnerContext & {
    * must not leak into the token caller's request context.
    */
   orgId?: string;
+  /** Verified A2A correlation and issuer metadata for the audit row. */
+  delegationJti?: string;
+  delegationIssuer?: string;
 };
 
 export interface ActionRouteAuthAdapter {
@@ -336,10 +365,14 @@ export function mountActionRoutes(
         // through, so a live same-origin session cookie can't silently execute
         // the request as the logged-in user.
         let resolvedCaller: ActionRouteResolvedCaller | null = null;
-        if (options?.actionRouteAuth?.resolveCaller) {
+        {
           let caller: ActionRouteResolvedCaller | null;
           try {
-            caller = await options.actionRouteAuth.resolveCaller(event);
+            caller = options?.actionRouteAuth?.resolveCaller
+              ? await options.actionRouteAuth.resolveCaller(event)
+              : null;
+            if (!caller)
+              caller = await resolveFeatureFlagA2ACaller(event, name);
           } catch {
             throw createError({
               statusCode: 401,
@@ -463,14 +496,23 @@ export function mountActionRoutes(
             // userEmail / orgId mirror the request context resolved above (do
             // NOT inject a dev identity — leave undefined when unauthenticated).
             try {
-              const caller = isFrontendActionRequest(event)
-                ? "frontend"
-                : "http";
+              const caller = resolvedCaller
+                ? "a2a"
+                : isFrontendActionRequest(event)
+                  ? "frontend"
+                  : "http";
               const result = await entry.run(params, {
                 userEmail,
                 orgId: orgId ?? null,
                 caller,
                 actionName: name,
+                ...(resolvedCaller?.delegationJti
+                  ? {
+                      networkProtocol: "a2a",
+                      networkId: resolvedCaller.delegationJti,
+                      networkPeer: resolvedCaller.delegationIssuer,
+                    }
+                  : {}),
               });
 
               // Auto-refresh the UI after a successful mutating action. GET

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -14,6 +14,7 @@ import {
 } from "h3";
 
 import {
+  appendA2AArtifactLinks,
   buildA2ARecoverableArtifactMessage,
   type A2AToolResultSummary,
 } from "../a2a/artifact-response.js";
@@ -27,6 +28,7 @@ import {
   createA2AApproval,
   updateTaskStatusMessage,
 } from "../a2a/task-store.js";
+import type { Message as A2AMessage } from "../a2a/types.js";
 import type { ActionHttpConfig } from "../action.js";
 import {
   canUpdateAgentAppModelDefaultSettings,
@@ -275,6 +277,74 @@ export { loadRunCodeToolEntries };
 export { shouldDisableRecurringJobsRuntime };
 export { finalizeClaimedAgentChatProcessRunFailure };
 
+export function createSerializedA2ATaskStatusWriter(
+  taskId: string,
+  writeStatus: (
+    taskId: string,
+    message: A2AMessage,
+  ) => Promise<void> = updateTaskStatusMessage,
+  onError: (error: unknown) => void = (error) => {
+    console.error(
+      `[A2A] Failed to persist recoverable artifact message for task ${taskId}:`,
+      error,
+    );
+  },
+): {
+  enqueue: (message: A2AMessage) => void;
+  flush: () => Promise<void>;
+} {
+  const maxAttempts = 3;
+  let latestWrite: Promise<void> = Promise.resolve();
+
+  const persistWithRetry = async (message: A2AMessage): Promise<void> => {
+    let lastError: unknown;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      try {
+        await writeStatus(taskId, message);
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    try {
+      onError(lastError);
+    } catch {
+      // The durable-write error below remains the authoritative failure.
+    }
+    throw lastError;
+  };
+
+  return {
+    enqueue(message) {
+      // A newer checkpoint supersedes an earlier failed checkpoint, so keep
+      // the queue moving. flush() still rejects when the latest write itself
+      // cannot be made durable after bounded retries.
+      latestWrite = latestWrite
+        .catch(() => undefined)
+        .then(() => {
+          return persistWithRetry(message);
+        });
+    },
+    flush() {
+      return latestWrite;
+    },
+  };
+}
+
+export async function resolveA2ARecoverableArtifactSecret(
+  orgId: string | null | undefined = getRequestOrgId(),
+): Promise<string | undefined> {
+  const globalSecret = process.env.A2A_SECRET?.trim();
+  if (globalSecret) return globalSecret;
+  if (!orgId) return undefined;
+  try {
+    const { getOrgA2ASecret } = await import("../org/context.js");
+    return (await getOrgA2ASecret(orgId))?.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function buildLeanRunPolicyPrompt(
   codeEditingSurfaceRestriction: string,
   prodCodeExecPromptNote: string,
@@ -1468,6 +1538,10 @@ export function createAgentChatPlugin(
           const a2aEvents: AgentChatEvent[] = [];
           const a2aToolResults: A2AToolResultSummary[] = [];
           let lastRecoverableArtifactText = "";
+          const recoverableArtifactSecret =
+            await resolveA2ARecoverableArtifactSecret();
+          const recoverableArtifactStatusWriter =
+            createSerializedA2ATaskStatusWriter(context.taskId);
           const controller = new AbortController();
 
           console.log(
@@ -1504,16 +1578,28 @@ export function createAgentChatPlugin(
                     isError: event.isError,
                     completedSideEffect: event.completedSideEffect,
                   });
-                  const recoverableArtifactText =
+                  const artifactBaseUrl = resolveArtifactBaseUrl(context.event);
+                  const recoverableArtifactMessage =
                     buildA2ARecoverableArtifactMessage(a2aToolResults, {
-                      baseUrl: resolveArtifactBaseUrl(context.event),
+                      baseUrl: artifactBaseUrl,
                     });
+                  const recoverableArtifactText = recoverableArtifactMessage
+                    ? appendA2AArtifactLinks(
+                        recoverableArtifactMessage,
+                        a2aToolResults,
+                        {
+                          baseUrl: artifactBaseUrl,
+                          includePersistedArtifactMarker: true,
+                          persistedArtifactSecret: recoverableArtifactSecret,
+                        },
+                      )
+                    : null;
                   if (
                     recoverableArtifactText &&
                     recoverableArtifactText !== lastRecoverableArtifactText
                   ) {
                     lastRecoverableArtifactText = recoverableArtifactText;
-                    updateTaskStatusMessage(context.taskId, {
+                    recoverableArtifactStatusWriter.enqueue({
                       role: "agent",
                       metadata: { agentNativeRecoverableArtifacts: true },
                       parts: [
@@ -1522,11 +1608,6 @@ export function createAgentChatPlugin(
                           text: recoverableArtifactText,
                         },
                       ],
-                    }).catch((err) => {
-                      console.error(
-                        `[A2A] Failed to persist recoverable artifact message for task ${context.taskId}:`,
-                        err,
-                      );
                     });
                   }
                 } else if (event.type === "error") {
@@ -1548,6 +1629,10 @@ export function createAgentChatPlugin(
             },
           );
 
+          // The continuation can observe terminal output immediately, so make
+          // its latest mutation checkpoint durable first.
+          await recoverableArtifactStatusWriter.flush();
+
           const approval = [...a2aEvents]
             .reverse()
             .find(

package/corpus/core/src/server/index.ts

@@ -180,6 +180,7 @@ export { createSentryPlugin, defaultSentryPlugin } from "./sentry-plugin.js";
 // (which references "defaultOrgPlugin" from @agent-native/core/server) can
 // resolve it during the deploy build worker-entry generation.
 export { createOrgPlugin, defaultOrgPlugin } from "../org/plugin.js";
+export { createFeatureFlagsPlugin } from "../feature-flags/plugin.js";
 export {
   createContextXrayPlugin,
   defaultContextXrayPlugin,

package/corpus/core/src/settings/org-settings.ts

@@ -10,6 +10,7 @@
 
 import {
   getSetting,
+  mutateSetting,
   putSetting,
   deleteSetting,
   getAllSettings,
@@ -40,6 +41,18 @@ export async function putOrgSetting(
   return putSetting(orgKey(orgId, key), value, options);
 }
 
+/** Atomically derive and persist an org-scoped setting. */
+export async function mutateOrgSetting(
+  orgId: string,
+  key: string,
+  updater: (
+    current: Record<string, unknown> | null,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  options?: StoreWriteOptions,
+): Promise<Record<string, unknown>> {
+  return mutateSetting(orgKey(orgId, key), updater, options);
+}
+
 /** Delete an org-scoped setting. */
 export async function deleteOrgSetting(
   orgId: string,

package/corpus/core/src/settings/store.ts

@@ -128,6 +128,63 @@ export interface StoreWriteOptions {
   requestSource?: string;
 }
 
+const SETTINGS_MUTATION_ATTEMPTS = 25;
+
+/**
+ * Atomically derive and persist one setting with an optimistic raw-value CAS.
+ * This works across SQLite/libSQL and Postgres and remains safe across
+ * horizontally scaled processes where an in-memory mutex would not.
+ * The updater may run more than once after contention and must not perform
+ * external side effects.
+ */
+export async function mutateSetting(
+  key: string,
+  updater: (
+    current: Record<string, unknown> | null,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  options?: StoreWriteOptions,
+): Promise<Record<string, unknown>> {
+  await ensureTable();
+  const client = getDbExec();
+  const table = settingsTable();
+  for (let attempt = 0; attempt < SETTINGS_MUTATION_ATTEMPTS; attempt += 1) {
+    // Deliberately bypass the request cache: a failed CAS means another
+    // request committed a newer value and the next attempt must reread it.
+    const snapshot = await client.execute({
+      sql: `SELECT value FROM ${table} WHERE key = ?`,
+      args: [key],
+    });
+    const raw =
+      snapshot.rows.length === 0 ? null : (snapshot.rows[0]?.value as string);
+    const current = raw == null ? null : JSON.parse(raw);
+    const next = await updater(current);
+    const nextRaw = JSON.stringify(next);
+    const timestamp = Date.now();
+    const result =
+      raw == null
+        ? await client.execute({
+            sql: isPostgres()
+              ? `INSERT INTO ${table} (key, value, updated_at) VALUES (?, ?, ?) ON CONFLICT (key) DO NOTHING`
+              : `INSERT OR IGNORE INTO ${table} (key, value, updated_at) VALUES (?, ?, ?)`,
+            args: [key, nextRaw, timestamp],
+          })
+        : await client.execute({
+            sql: `UPDATE ${table} SET value = ?, updated_at = ? WHERE key = ? AND value = ?`,
+            args: [nextRaw, timestamp, key, raw],
+          });
+    if (result.rowsAffected === 0) continue;
+    requestSettingsCache()?.set(key, nextRaw);
+    _emitter.emit("settings", {
+      source: "settings",
+      type: "change",
+      key,
+      ...(options?.requestSource && { requestSource: options.requestSource }),
+    });
+    return JSON.parse(nextRaw);
+  }
+  throw new Error(`Setting ${key} changed too many times; retry the mutation.`);
+}
+
 export async function putSetting(
   key: string,
   value: Record<string, unknown>,

package/corpus/core/src/templates/default/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

package/corpus/core/src/templates/default/AGENTS.md

@@ -158,6 +158,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | ---------------------- | --------------------------------------------------------------------------------- |
 | `agent-native-docs`    | Before using advanced Agent Native framework APIs or generated-app features       |
 | `adding-a-feature`     | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `feature-flags`        | Before shipping a staged production rollout or replacing a compile-time switch    |
 | `real-time-sync`       | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
 | `storing-data`         | Before storing or reading any app state                                           |
 | `internationalization` | Before adding or editing visible UI copy, prompts, toasts, labels, or formatting  |