@agent-native/core 0.107.1 → 0.108.0

package/corpus/core/src/feature-flags/store.ts

@@ -0,0 +1,176 @@
+import { getOrgSetting, mutateOrgSetting } from "../settings/org-settings.js";
+import { getSetting, mutateSetting } from "../settings/store.js";
+import {
+  getFeatureFlagDefinition,
+  type FeatureFlagDefinition,
+} from "./registry.js";
+
+export type FeatureFlagMode = "off" | "on" | "rules";
+
+export interface FeatureFlagRules {
+  version: 1;
+  mode: FeatureFlagMode;
+  emails: string[];
+  orgIds: string[];
+  percentage: number;
+  updatedAt: number | null;
+  updatedBy: string | null;
+}
+
+export interface FeatureFlagScope {
+  userEmail?: string;
+  /** Canonical authenticated identity. V1 callers use normalized email. */
+  userKey?: string;
+  orgId?: string | null;
+}
+
+export const FEATURE_FLAG_SETTINGS_PREFIX = "feature-flag:";
+
+function settingKey(key: string): string {
+  return `${FEATURE_FLAG_SETTINGS_PREFIX}${key}`;
+}
+
+export function defaultFeatureFlagRules(): FeatureFlagRules {
+  return {
+    version: 1,
+    mode: "off",
+    emails: [],
+    orgIds: [],
+    percentage: 0,
+    updatedAt: null,
+    updatedBy: null,
+  };
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [
+    ...new Set(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+export function normalizeFeatureFlagRules(value: unknown): FeatureFlagRules {
+  if (!value || typeof value !== "object") return defaultFeatureFlagRules();
+  const raw = value as Record<string, unknown>;
+  const mode: FeatureFlagMode =
+    raw.mode === "on" || raw.mode === "rules" || raw.mode === "off"
+      ? raw.mode
+      : "off";
+  const percentage =
+    typeof raw.percentage === "number" && Number.isFinite(raw.percentage)
+      ? Math.max(0, Math.min(100, Math.floor(raw.percentage)))
+      : 0;
+  return {
+    version: 1,
+    mode,
+    emails: stringList(raw.emails).map((email) => email.toLowerCase()),
+    orgIds: stringList(raw.orgIds),
+    percentage,
+    updatedAt:
+      typeof raw.updatedAt === "number" && Number.isSafeInteger(raw.updatedAt)
+        ? raw.updatedAt
+        : null,
+    updatedBy:
+      typeof raw.updatedBy === "string" && raw.updatedBy.trim()
+        ? raw.updatedBy.trim().toLowerCase()
+        : null,
+  };
+}
+
+export async function getFeatureFlagRules(
+  key: string,
+  scope: Pick<FeatureFlagScope, "orgId">,
+): Promise<FeatureFlagRules> {
+  if (!getFeatureFlagDefinition(key)) return defaultFeatureFlagRules();
+  // An organization-specific rule overrides the global rule. The fallback is
+  // what makes global exact-org targeting meaningful for callers in an org.
+  const stored = scope.orgId?.trim()
+    ? ((await getOrgSetting(scope.orgId, settingKey(key))) ??
+      (await getSetting(settingKey(key))))
+    : await getSetting(settingKey(key));
+  return normalizeFeatureFlagRules(stored);
+}
+
+/**
+ * Atomically derive one flag's scoped rules. An org's first override starts
+ * from the global fallback, then becomes independently CAS-protected.
+ */
+export async function mutateFeatureFlagRules(
+  key: string,
+  scope: Pick<FeatureFlagScope, "orgId">,
+  updater: (
+    current: FeatureFlagRules,
+  ) => FeatureFlagRules | Promise<FeatureFlagRules>,
+): Promise<FeatureFlagRules> {
+  if (!getFeatureFlagDefinition(key)) {
+    throw new Error(`Unknown feature flag: ${key}`);
+  }
+  const mutate = async (stored: Record<string, unknown> | null) => {
+    const fallback =
+      stored == null && scope.orgId?.trim()
+        ? await getSetting(settingKey(key))
+        : null;
+    return {
+      ...(await updater(normalizeFeatureFlagRules(stored ?? fallback))),
+    };
+  };
+  const persisted = scope.orgId?.trim()
+    ? await mutateOrgSetting(scope.orgId, settingKey(key), mutate)
+    : await mutateSetting(settingKey(key), mutate);
+  return normalizeFeatureFlagRules(persisted);
+}
+
+function rolloutBucket(input: string): number {
+  // FNV-1a is deliberately tiny, deterministic, and independent of runtime.
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % 100;
+}
+
+export function evaluateFeatureFlagRules(
+  key: string,
+  rules: FeatureFlagRules,
+  scope: FeatureFlagScope,
+): boolean {
+  if (rules.mode === "off") return false;
+  if (rules.mode === "on") return true;
+  const email = scope.userEmail?.trim().toLowerCase();
+  if (email && rules.emails.includes(email)) return true;
+  if (scope.orgId && rules.orgIds.includes(scope.orgId)) return true;
+  const userKey = scope.userKey?.trim() || email;
+  if (!userKey || rules.percentage <= 0) return false;
+  return rolloutBucket(`${key}:${userKey}`) < rules.percentage;
+}
+
+export async function evaluateFeatureFlag(
+  key: string,
+  scope: FeatureFlagScope = {},
+): Promise<boolean> {
+  if (!getFeatureFlagDefinition(key)) return false;
+  try {
+    return evaluateFeatureFlagRules(
+      key,
+      await getFeatureFlagRules(key, scope),
+      scope,
+    );
+  } catch {
+    // A feature flag must never become an availability dependency.
+    return false;
+  }
+}
+
+/** Ergonomic app-action guard. Accepts either a registered definition or its key. */
+export async function isFeatureFlagEnabled(
+  flag: string | FeatureFlagDefinition,
+  scope: FeatureFlagScope = {},
+): Promise<boolean> {
+  return evaluateFeatureFlag(typeof flag === "string" ? flag : flag.key, scope);
+}

package/corpus/core/src/index.ts

@@ -142,6 +142,21 @@ export {
   type AutomationWorkflowDefinition,
   type JsonSchema,
 } from "./automation/index.js";
+export {
+  createFeatureFlagsPlugin,
+  defineFeatureFlag,
+  defineFeatureFlags,
+  evaluateFeatureFlag,
+  getFeatureFlagDefinition,
+  getFeatureFlagRules,
+  isFeatureFlagEnabled,
+  listFeatureFlags,
+  registerFeatureFlags,
+  type FeatureFlagDefinition,
+  type FeatureFlagMode,
+  type FeatureFlagRules,
+  type FeatureFlagScope,
+} from "./feature-flags/index.js";
 
 // Server
 export {

package/corpus/core/src/integrations/a2a-continuation-processor.ts

@@ -171,11 +171,22 @@ async function processClaimedContinuation(
     ...(auth.apiKeyFallbacks ? { fallbackApiKeys: auth.apiKeyFallbacks } : {}),
   });
   const deadline = Date.now() + PROCESSOR_WAIT_MS;
+  const recoverableArtifactSecrets =
+    await resolveContinuationArtifactSecrets(continuation);
   let task: Task | null = null;
+  let latestRecoverableArtifactText: string | null = null;
 
   try {
     while (Date.now() < deadline) {
       task = await client.getTask(continuation.a2aTaskId);
+      const recoverableArtifactText = extractVerifiedRecoverableArtifactText(
+        task,
+        continuation.agentUrl,
+        recoverableArtifactSecrets,
+      );
+      if (recoverableArtifactText) {
+        latestRecoverableArtifactText = recoverableArtifactText;
+      }
       if (TERMINAL_STATES.has(task.status.state)) break;
       await reportA2AContinuationProgress(continuation, progress, task);
       await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
@@ -183,6 +194,17 @@ async function processClaimedContinuation(
   } catch (err) {
     if (isTransientA2APollError(err)) {
       if (shouldStopPollingRemoteTask(continuation)) {
+        if (latestRecoverableArtifactText) {
+          await deliverAndCompleteA2AContinuation(
+            continuation,
+            adapter,
+            formatRecoverableArtifactFallbackText(
+              latestRecoverableArtifactText,
+            ),
+            progress,
+          );
+          return;
+        }
         await notifyAndFailA2AContinuation(
           continuation,
           adapter,
@@ -209,6 +231,15 @@ async function processClaimedContinuation(
 
   if (!task || !TERMINAL_STATES.has(task.status.state)) {
     if (shouldStopPollingRemoteTask(continuation)) {
+      if (latestRecoverableArtifactText) {
+        await deliverAndCompleteA2AContinuation(
+          continuation,
+          adapter,
+          formatRecoverableArtifactFallbackText(latestRecoverableArtifactText),
+          progress,
+        );
+        return;
+      }
       await notifyAndFailA2AContinuation(
         continuation,
         adapter,
@@ -222,6 +253,15 @@ async function processClaimedContinuation(
   }
 
   if (task.status.state !== "completed") {
+    if (latestRecoverableArtifactText) {
+      await deliverAndCompleteA2AContinuation(
+        continuation,
+        adapter,
+        formatRecoverableArtifactFallbackText(latestRecoverableArtifactText),
+        progress,
+      );
+      return;
+    }
     const reason =
       extractTaskText(task) ||
       `Remote A2A task ${continuation.a2aTaskId} ended with state ${task.status.state}`;
@@ -234,6 +274,15 @@ async function processClaimedContinuation(
     continuation.agentUrl,
   );
   if (!text.trim()) {
+    if (latestRecoverableArtifactText) {
+      await deliverAndCompleteA2AContinuation(
+        continuation,
+        adapter,
+        formatRecoverableArtifactFallbackText(latestRecoverableArtifactText),
+        progress,
+      );
+      return;
+    }
     await notifyAndFailA2AContinuation(
       continuation,
       adapter,
@@ -382,6 +431,8 @@ async function deliverAndCompleteA2AContinuation(
       `${deliveryContinuation.platform} response delivery timed out`,
     );
     let persistenceError: unknown;
+    const artifactSecrets =
+      await resolveContinuationArtifactSecrets(deliveryContinuation);
     for (let attempt = 0; attempt < 3; attempt += 1) {
       try {
         await persistA2AContinuationDelivery(
@@ -389,6 +440,7 @@ async function deliverAndCompleteA2AContinuation(
           outgoing,
           deliveryReceipt,
           text,
+          artifactSecrets,
         );
         persistenceError = undefined;
         break;
@@ -463,6 +515,7 @@ async function persistA2AContinuationDelivery(
   outgoing: OutgoingMessage,
   receipt: PlatformDeliveryReceipt,
   artifactText: string,
+  artifactSecrets: readonly string[],
 ): Promise<void> {
   const mapping = await getThreadMapping(
     continuation.platform,
@@ -480,9 +533,12 @@ async function persistA2AContinuationDelivery(
   }
   if (!Array.isArray(repo.messages)) repo.messages = [];
 
-  const artifacts = extractA2AArtifactIdentities([
-    { tool: "call-agent", result: artifactText },
-  ]);
+  const artifacts = extractA2AArtifactIdentities(
+    [{ tool: "call-agent", result: artifactText }],
+    {
+      persistedArtifactSecrets: artifactSecrets,
+    },
+  );
   const metadata: Record<string, unknown> = {
     integrationDeliveryAttempted: true,
     integrationDelivery: {
@@ -726,6 +782,24 @@ async function signFreshContinuationTokens(
   return tokens;
 }
 
+async function resolveContinuationArtifactSecrets(
+  continuation: A2AContinuation,
+): Promise<string[]> {
+  const secrets: string[] = [];
+  const add = (secret: string | null | undefined) => {
+    const value = secret?.trim();
+    if (value && !secrets.includes(value)) secrets.push(value);
+  };
+  add(process.env.A2A_SECRET);
+  if (continuation.orgId) {
+    try {
+      const { getOrgA2ASecret } = await import("../org/context.js");
+      add(await getOrgA2ASecret(continuation.orgId));
+    } catch {}
+  }
+  return secrets;
+}
+
 function isLikelyJwt(token: string): boolean {
   return token.split(".").length === 3;
 }
@@ -740,6 +814,36 @@ function extractTaskText(task: Task): string {
     .join("\n");
 }
 
+function extractVerifiedRecoverableArtifactText(
+  task: Task,
+  agentUrl: string,
+  artifactSecrets: readonly string[],
+): string | null {
+  if (task.status.message?.metadata?.agentNativeRecoverableArtifacts !== true) {
+    return null;
+  }
+
+  const text = formatContinuationArtifactText(extractTaskText(task), agentUrl);
+  if (!text.trim()) return null;
+
+  // Require the signed identity ledger so arbitrary peer progress prose cannot
+  // prematurely complete the continuation.
+  const artifacts = extractA2AArtifactIdentities(
+    [{ tool: "call-agent", result: text }],
+    {
+      persistedArtifactSecrets: artifactSecrets,
+    },
+  );
+  return artifacts.length > 0 ? text : null;
+}
+
+function formatRecoverableArtifactFallbackText(text: string): string {
+  return text.replace(
+    "The agent is still working on the full response, but these verified artifacts already exist:",
+    "The downstream agent did not finish its full response, but these verified artifacts already exist:",
+  );
+}
+
 function formatContinuationArtifactText(
   text: string,
   agentUrl: string,

package/corpus/core/src/integrations/pending-tasks-store.ts

@@ -272,6 +272,19 @@ export async function claimPendingTask(
                AND active.status = 'processing'
                AND active.id <> integration_pending_tasks.id
            )
+           AND NOT EXISTS (
+             SELECT 1 FROM integration_pending_tasks earlier
+             WHERE earlier.platform = integration_pending_tasks.platform
+               AND earlier.external_thread_id = integration_pending_tasks.external_thread_id
+               AND earlier.status = 'pending'
+               AND (
+                 earlier.created_at < integration_pending_tasks.created_at
+                 OR (
+                   earlier.created_at = integration_pending_tasks.created_at
+                   AND earlier.id < integration_pending_tasks.id
+                 )
+               )
+           )
          RETURNING id, platform, external_thread_id, payload, owner_email, org_id, status, attempts, error_message, created_at, updated_at, completed_at`
       : `UPDATE integration_pending_tasks
          SET status = ?, attempts = attempts + 1, updated_at = ?
@@ -282,6 +295,19 @@ export async function claimPendingTask(
                AND active.external_thread_id = integration_pending_tasks.external_thread_id
                AND active.status = 'processing'
                AND active.id <> integration_pending_tasks.id
+           )
+           AND NOT EXISTS (
+             SELECT 1 FROM integration_pending_tasks earlier
+             WHERE earlier.platform = integration_pending_tasks.platform
+               AND earlier.external_thread_id = integration_pending_tasks.external_thread_id
+               AND earlier.status = 'pending'
+               AND (
+                 earlier.created_at < integration_pending_tasks.created_at
+                 OR (
+                   earlier.created_at = integration_pending_tasks.created_at
+                   AND earlier.id < integration_pending_tasks.id
+                 )
+               )
            )`,
     args: ["processing", now, id],
   });
@@ -312,7 +338,7 @@ export async function getNextPendingTaskIdForThread(
   const { rows } = await getDbExec().execute({
     sql: `SELECT id FROM integration_pending_tasks
       WHERE platform = ? AND external_thread_id = ? AND status = 'pending'
-      ORDER BY created_at ASC LIMIT 1`,
+      ORDER BY created_at ASC, id ASC LIMIT 1`,
     args: [platform, externalThreadId],
   });
   return rows[0]?.id ? String(rows[0].id) : null;
@@ -354,6 +380,77 @@ export async function markTaskRetryable(
   });
 }
 
+export async function stageTaskDeliveryPayload(
+  id: string,
+  payload: string,
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  const now = Date.now();
+  const result = await client.execute({
+    sql: `UPDATE integration_pending_tasks
+          SET payload = ?, updated_at = ?
+          WHERE id = ? AND status = 'processing'`,
+    args: [payload, now, id],
+  });
+  const affected = Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+  if (affected === 0) {
+    throw new Error("Integration task is no longer claimable for delivery");
+  }
+}
+
+export async function markTaskDeliveryRetryable(
+  id: string,
+  payload: string,
+  errorMessage: string,
+): Promise<void> {
+  await ensureTable();
+  const client = getDbExec();
+  const result = await client.execute({
+    sql: `UPDATE integration_pending_tasks
+          SET status = ?, payload = ?, updated_at = ?, error_message = ?
+          WHERE id = ? AND status = 'processing'`,
+    args: ["pending", payload, Date.now(), errorMessage.slice(0, 2000), id],
+  });
+  const affected = Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+  if (affected === 0) {
+    throw new Error(
+      "Integration task is no longer claimable for delivery retry",
+    );
+  }
+}
+
+export async function failTaskDeliveryTransition(
+  id: string,
+  errorMessage: string,
+): Promise<void> {
+  await ensureTable();
+  const result = await getDbExec().execute({
+    sql: `UPDATE integration_pending_tasks
+          SET status = ?, updated_at = ?, error_message = ?, payload = ?
+          WHERE id = ? AND status = 'processing'`,
+    args: ["failed", Date.now(), errorMessage.slice(0, 2000), "{}", id],
+  });
+  const affected = Number(
+    (result as { rowsAffected?: number }).rowsAffected ??
+      (result as { rowCount?: number }).rowCount ??
+      0,
+  );
+  if (affected === 0) {
+    throw new Error(
+      "Integration task delivery failure transition lost its race",
+    );
+  }
+}
+
 /** Mark a task as failed and stash an error message. */
 export async function markTaskFailed(
   id: string,