@agent-native/core 0.109.0 → 0.109.1

package/corpus/README.md

@@ -27,5 +27,5 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 2308
-- template files: 6135
+- core files: 2309
+- template files: 6143

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @agent-native/core
 
+## 0.109.1
+
+### Patch Changes
+
+- d74a5a4: Return retryable responses for transient agent-chat database failures and back off active-run polling while the database recovers.
+- d74a5a4: Add bounded per-tool generation telemetry, delegated trace linkage, direct-read telemetry, and idempotent A2A submissions.
+
 ## 0.109.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.109.0",
+  "version": "0.109.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": {

package/corpus/core/src/a2a/client.ts

@@ -1,8 +1,10 @@
 import * as jose from "jose";
 
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
+import { sanitizeA2ACorrelationMetadata } from "./correlation.js";
 import type {
   A2AApprovedAction,
+  A2ACorrelationMetadata,
   A2AReadOnlyActionResult,
   AgentCard,
   JsonRpcRequest,
@@ -239,6 +241,7 @@ export class A2AClient {
     opts?: {
       contextId?: string;
       metadata?: Record<string, unknown>;
+      idempotencyKey?: string;
       approvedActions?: A2AApprovedAction[];
       /**
        * If true, ask the server to return the task immediately in `working`
@@ -255,6 +258,7 @@ export class A2AClient {
       message,
       contextId: opts?.contextId,
       metadata: opts?.metadata,
+      ...(opts?.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
       ...(opts?.approvedActions?.length
         ? { approvedActions: opts.approvedActions }
         : {}),
@@ -291,8 +295,14 @@ export class A2AClient {
   async invokeAction(
     action: string,
     input: Record<string, unknown> = {},
+    opts?: { metadata?: A2ACorrelationMetadata },
   ): Promise<A2AReadOnlyActionResult> {
-    const response = await this.rpc("actions/invoke", { action, input });
+    const metadata = sanitizeA2ACorrelationMetadata(opts?.metadata);
+    const response = await this.rpc("actions/invoke", {
+      action,
+      input,
+      ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+    });
     if (response.error) {
       throw new Error(
         `A2A error (${response.error.code}): ${response.error.message}`,
@@ -315,6 +325,7 @@ export class A2AClient {
     opts?: {
       contextId?: string;
       metadata?: Record<string, unknown>;
+      idempotencyKey?: string;
       approvedActions?: A2AApprovedAction[];
       /** Total time to wait for completion. Default 5 min. */
       timeoutMs?: number;
@@ -327,6 +338,7 @@ export class A2AClient {
     const submitted = await this.send(message, {
       contextId: opts?.contextId,
       metadata: opts?.metadata,
+      idempotencyKey: opts?.idempotencyKey,
       ...(opts?.approvedActions?.length
         ? { approvedActions: opts.approvedActions }
         : {}),
@@ -620,6 +632,10 @@ export async function callAgent(
     requestOrigin?: string;
     /** Exact downstream actions explicitly authorized in the caller's chat. */
     approvedActions?: A2AApprovedAction[];
+    /** Bounded telemetry-only lineage forwarded to the receiving app. */
+    correlation?: A2ACorrelationMetadata;
+    /** Stable caller-generated key for one message submission. */
+    idempotencyKey?: string;
     /**
      * Use async/poll instead of a single blocking POST. Recommended for
      * cross-app calls that may exceed a synchronous serverless request budget.
@@ -657,6 +673,7 @@ export async function callAgent(
   if (opts?.userEmail) metadata.userEmail = opts.userEmail;
   if (opts?.orgDomain) metadata.orgDomain = opts.orgDomain;
   if (opts?.requestOrigin) metadata.requestOrigin = opts.requestOrigin;
+  Object.assign(metadata, sanitizeA2ACorrelationMetadata(opts?.correlation));
 
   // Default to async + poll. The receiving A2A server's `_process-task` route
   // runs the handler in a fresh function execution (cross-platform queue
@@ -691,6 +708,7 @@ export async function callAgent(
           : await client.sendAndWait(message, {
               contextId: opts?.contextId,
               metadata,
+              idempotencyKey: opts?.idempotencyKey,
               ...(opts?.approvedActions?.length
                 ? { approvedActions: opts.approvedActions }
                 : {}),
@@ -705,6 +723,7 @@ export async function callAgent(
         task = await client.send(message, {
           contextId: opts?.contextId,
           metadata,
+          idempotencyKey: opts?.idempotencyKey,
           ...(opts?.approvedActions?.length
             ? { approvedActions: opts.approvedActions }
             : {}),
@@ -756,6 +775,7 @@ export async function callAction(
     orgDomain?: string;
     orgSecret?: string;
     requestTimeoutMs?: number;
+    correlation?: A2ACorrelationMetadata;
   },
 ): Promise<A2AReadOnlyActionResult> {
   const actionName = action.trim();
@@ -775,7 +795,9 @@ export async function callAction(
     fallbackApiKeys,
     requestTimeoutMs: opts?.requestTimeoutMs,
   });
-  return client.invokeAction(actionName, input);
+  return client.invokeAction(actionName, input, {
+    metadata: sanitizeA2ACorrelationMetadata(opts?.correlation),
+  });
 }
 
 async function buildA2AApiKeyAttempts(

package/corpus/core/src/a2a/correlation.ts

@@ -0,0 +1,50 @@
+import type { A2ACorrelationMetadata } from "./types.js";
+
+export const MAX_A2A_CORRELATION_VALUE_CHARS = 200;
+
+const APP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const CORRELATION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+function boundedIdentifier(
+  value: unknown,
+  pattern: RegExp,
+): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (
+    !trimmed ||
+    trimmed.length > MAX_A2A_CORRELATION_VALUE_CHARS ||
+    !pattern.test(trimmed)
+  ) {
+    return undefined;
+  }
+  return trimmed;
+}
+
+export function sanitizeA2ACorrelationId(value: unknown): string | undefined {
+  return boundedIdentifier(value, CORRELATION_ID_PATTERN);
+}
+
+/**
+ * Keep only bounded, opaque ASCII correlation identifiers. These values
+ * remain telemetry hints; authentication continues to come exclusively from
+ * the verified A2A token/request context.
+ */
+export function sanitizeA2ACorrelationMetadata(
+  value: unknown,
+): A2ACorrelationMetadata {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const metadata = value as Record<string, unknown>;
+  const callerApp = boundedIdentifier(metadata.callerApp, APP_ID_PATTERN);
+  const callerThreadId = sanitizeA2ACorrelationId(metadata.callerThreadId);
+  const parentRunId = sanitizeA2ACorrelationId(metadata.parentRunId);
+  const parentTurnId = sanitizeA2ACorrelationId(metadata.parentTurnId);
+  const invocationId = sanitizeA2ACorrelationId(metadata.invocationId);
+  return {
+    ...(callerApp ? { callerApp } : {}),
+    ...(callerThreadId ? { callerThreadId } : {}),
+    ...(parentRunId ? { parentRunId } : {}),
+    ...(parentTurnId ? { parentTurnId } : {}),
+    ...(invocationId ? { invocationId } : {}),
+  };
+}

package/corpus/core/src/a2a/handlers.ts

@@ -1,3 +1,5 @@
+import crypto from "node:crypto";
+
 import { setResponseHeader, setResponseStatus } from "h3";
 
 import {
@@ -7,18 +9,22 @@ import {
   isAgentChatDurableBackgroundEnabled,
   resolveAgentChatProcessRunDispatchPath,
 } from "../agent/durable-background.js";
+import { trackingIdentityProperties } from "../observability/tracking-identity.js";
 import { withConfiguredAppBasePath } from "../server/app-base-path.js";
 import { getOrigin, isConfiguredAppOrigin } from "../server/google-oauth.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { agentChat } from "../shared/agent-chat.js";
+import { track } from "../tracking/registry.js";
 import {
   hasConfiguredA2ASecret,
   isA2AProductionRuntime,
 } from "./auth-policy.js";
+import { sanitizeA2ACorrelationMetadata } from "./correlation.js";
 import {
   createTask,
+  createOrReuseTask,
   getTask,
-  getTaskOwner,
+  getTaskOwnership,
   updateTask,
   claimA2ATaskForProcessing,
   getA2ATaskDispatchState,
@@ -28,6 +34,8 @@ import {
   touchQueuedA2ATaskDispatch,
   touchProcessingA2ATask,
   pauseProcessingA2ATask,
+  MAX_A2A_IDEMPOTENCY_KEY_CHARS,
+  A2A_PERSONAL_OWNER_SCOPE,
 } from "./task-store.js";
 import type {
   A2AApprovedAction,
@@ -51,6 +59,7 @@ const A2A_PROCESSING_HEARTBEAT_MS = 30_000;
 const MAX_A2A_APPROVED_ACTIONS = 10;
 const MAX_A2A_DIRECT_ACTION_NAME_CHARS = 200;
 const MAX_A2A_DIRECT_ACTION_INPUT_BYTES = 64 * 1024;
+const A2A_READ_INVOKE_EVENT = "$a2a_read_invoke";
 
 function trustedApprovedActions(
   value: unknown,
@@ -580,6 +589,22 @@ async function runHandlerAndPersist(
   }
 }
 
+function verifiedTaskOwner(event?: any): {
+  ownerEmail: string | null;
+  ownerScope: string | null;
+} {
+  const ownerEmail =
+    (event?.context?.__a2aVerifiedEmail as string | undefined) ?? null;
+  return {
+    ownerEmail,
+    ownerScope: ownerEmail
+      ? ((event?.context?.__a2aOrgDomain as string | undefined)
+          ?.trim()
+          .toLowerCase() ?? A2A_PERSONAL_OWNER_SCOPE)
+      : null,
+  };
+}
+
 async function handleSend(
   params: Record<string, unknown>,
   config: A2AConfig,
@@ -606,8 +631,31 @@ async function handleSend(
   // on every subsequent tasks/get and tasks/cancel call. Caller-supplied
   // metadata.userEmail is NEVER used for ownership; that would re-introduce
   // the IDOR class fixed here.
-  const ownerEmailForTask =
-    (event?.context?.__a2aVerifiedEmail as string | undefined) ?? null;
+  const { ownerEmail: ownerEmailForTask, ownerScope: ownerScopeForTask } =
+    verifiedTaskOwner(event);
+  let idempotencyKey: string | undefined;
+  if (ownerEmailForTask && params.idempotencyKey !== undefined) {
+    if (typeof params.idempotencyKey !== "string") {
+      return {
+        ...jsonRpcError(
+          0,
+          -32602,
+          "Invalid params: idempotencyKey must be a string",
+        ),
+        _id: 0,
+      };
+    }
+    idempotencyKey = params.idempotencyKey.trim();
+    if (
+      !idempotencyKey ||
+      idempotencyKey.length > MAX_A2A_IDEMPOTENCY_KEY_CHARS
+    ) {
+      return {
+        ...jsonRpcError(0, -32602, "Invalid params: idempotencyKey is invalid"),
+        _id: 0,
+      };
+    }
+  }
 
   // Async mode: return the task immediately in `working` state, run the
   // handler in the background, and let the caller poll `tasks/get`. This is
@@ -620,6 +668,7 @@ async function handleSend(
   // production — see the additional gate below.
   const asyncMode =
     params.async === true || (event && event.context?.__a2aForceAsync === true);
+  if (!asyncMode) idempotencyKey = undefined;
 
   if (asyncMode) {
     // Refuse async mode entirely when no auth is configured in production.
@@ -667,12 +716,20 @@ async function handleSend(
         approvedActions: approvedActions ?? null,
       },
     };
-    const task = await createTask(
+    const { task, reused } = await createOrReuseTask(
       message,
       contextId,
       taskMetadata,
       ownerEmailForTask,
+      ownerScopeForTask,
+      idempotencyKey,
     );
+    if (reused) {
+      return {
+        ...jsonRpcResult(0, sanitizeTaskForResponse(task)),
+        _id: 0,
+      };
+    }
     const working = await updateTask(task.id, { state: "working" });
 
     // Awaited, not fire-and-forget: this handler is about to return, and a
@@ -695,12 +752,20 @@ async function handleSend(
   }
 
   return withA2ARequestContext(metadata, event, async () => {
-    const task = await createTask(
+    const { task, reused } = await createOrReuseTask(
       message,
       contextId,
       undefined,
       ownerEmailForTask,
+      ownerScopeForTask,
+      idempotencyKey,
     );
+    if (reused) {
+      return {
+        ...jsonRpcResult(0, sanitizeTaskForResponse(task)),
+        _id: 0,
+      };
+    }
     await updateTask(task.id, { state: "working" });
 
     const ctx = makeHandlerContext(
@@ -790,8 +855,8 @@ async function handleStream(
   const contextId = params.contextId as string | undefined;
   const metadata = params.metadata as Record<string, unknown> | undefined;
   const approvedActions = trustedApprovedActions(params.approvedActions, event);
-  const ownerEmailForTask =
-    (event?.context?.__a2aVerifiedEmail as string | undefined) ?? null;
+  const { ownerEmail: ownerEmailForTask, ownerScope: ownerScopeForTask } =
+    verifiedTaskOwner(event);
 
   await withA2ARequestContext(metadata, event, async () => {
     const task = await createTask(
@@ -799,6 +864,7 @@ async function handleStream(
       contextId,
       undefined,
       ownerEmailForTask,
+      ownerScopeForTask,
     );
 
     await updateTask(task.id, { state: "working" });
@@ -879,16 +945,23 @@ const SENSITIVE_METADATA_KEYS = new Set([
 
 function sanitizeTaskForResponse(task: any): any {
   if (!task || typeof task !== "object") return task;
-  if (!task.metadata || typeof task.metadata !== "object") return task;
+  const {
+    ownerEmail: _ownerEmail,
+    ownerScope: _ownerScope,
+    ...publicTask
+  } = task;
+  if (!publicTask.metadata || typeof publicTask.metadata !== "object") {
+    return publicTask;
+  }
 
-  const meta = task.metadata as Record<string, unknown>;
+  const meta = publicTask.metadata as Record<string, unknown>;
   const publicMeta: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(meta)) {
     if (k === "__a2a_processor") continue;
     if (SENSITIVE_METADATA_KEYS.has(k)) continue;
     publicMeta[k] = v;
   }
-  return { ...task, metadata: publicMeta };
+  return { ...publicTask, metadata: publicMeta };
 }
 
 /**
@@ -907,6 +980,7 @@ function sanitizeTaskForResponse(task: any): any {
  */
 function authorizeTaskAccess(
   taskOwnerEmail: string | null,
+  taskOwnerScope: string | null,
   event: any,
   config: A2AConfig,
 ): JsonRpcResponse | null {
@@ -928,6 +1002,15 @@ function authorizeTaskAccess(
     if (verifiedEmail.toLowerCase() !== taskOwnerEmail.toLowerCase()) {
       return jsonRpcError(0, -32001, "Task not found");
     }
+    if (taskOwnerScope) {
+      const verifiedScope =
+        (event?.context?.__a2aOrgDomain as string | undefined)
+          ?.trim()
+          .toLowerCase() ?? A2A_PERSONAL_OWNER_SCOPE;
+      if (verifiedScope !== taskOwnerScope.toLowerCase()) {
+        return jsonRpcError(0, -32001, "Task not found");
+      }
+    }
   }
   // Legacy row (no owner_email recorded). The route-level auth gate is the
   // only thing protecting it — fall through and serve.
@@ -943,8 +1026,13 @@ async function handleGet(
   if (!id) {
     return jsonRpcError(0, -32602, "Invalid params: id required");
   }
-  const ownerEmail = await getTaskOwner(id);
-  const denied = authorizeTaskAccess(ownerEmail, event, config);
+  const ownership = await getTaskOwnership(id);
+  const denied = authorizeTaskAccess(
+    ownership.ownerEmail,
+    ownership.ownerScope,
+    event,
+    config,
+  );
   if (denied) return denied;
 
   const task = await getTask(id);
@@ -1038,8 +1126,13 @@ async function handleCancel(
   if (!id) {
     return jsonRpcError(0, -32602, "Invalid params: id required");
   }
-  const ownerEmail = await getTaskOwner(id);
-  const denied = authorizeTaskAccess(ownerEmail, event, config);
+  const ownership = await getTaskOwnership(id);
+  const denied = authorizeTaskAccess(
+    ownership.ownerEmail,
+    ownership.ownerScope,
+    event,
+    config,
+  );
   if (denied) return denied;
 
   const task = await updateTask(id, { state: "canceled" });
@@ -1089,15 +1182,48 @@ async function handleInvokeReadOnlyAction(
     return jsonRpcError(0, -32601, "Direct action invocation not supported");
   }
 
+  const startedAt = Date.now();
+  const correlation = sanitizeA2ACorrelationMetadata(params.metadata);
+  const invocationId = crypto.randomUUID();
+  const verifiedEmail = event.context.__a2aVerifiedEmail as string;
+  const emitTracking = (status: "completed" | "failed") => {
+    const identity = trackingIdentityProperties();
+    track(
+      A2A_READ_INVOKE_EVENT,
+      {
+        ...identity,
+        action,
+        receiver_app: config.appId ?? identity.app ?? config.name,
+        caller_app: correlation.callerApp ?? "unknown",
+        duration_ms: Math.max(0, Date.now() - startedAt),
+        status,
+        invocation_id: invocationId,
+        ...(correlation.parentRunId
+          ? { parent_run_id: correlation.parentRunId }
+          : {}),
+        ...(correlation.parentTurnId
+          ? { parent_turn_id: correlation.parentTurnId }
+          : {}),
+        ...(correlation.invocationId
+          ? { caller_invocation_id: correlation.invocationId }
+          : {}),
+      },
+      { userId: verifiedEmail },
+    );
+  };
+
   try {
     const result = await withA2ARequestContext(undefined, event, () =>
       config.executeReadOnlyAction!({
         action,
         input: input as Record<string, unknown>,
+        invocationId,
       }),
     );
+    emitTracking(result.status);
     return jsonRpcResult(0, { action, ...result });
   } catch (error) {
+    emitTracking("failed");
     console.error(`[a2a] Direct action ${action} failed:`, error);
     return jsonRpcError(0, -32000, "Direct action invocation failed");
   }

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

@@ -34,6 +34,7 @@ export type {
   Artifact,
   JsonRpcRequest,
   JsonRpcResponse,
+  A2ACorrelationMetadata,
   A2AReadOnlyActionInvocation,
   A2AReadOnlyActionResult,
 } from "./types.js";

package/corpus/core/src/a2a/invoke.ts

@@ -7,7 +7,10 @@ import {
   callAction as defaultCallAction,
   callAgent as defaultCallAgent,
 } from "./client.js";
-import type { A2AReadOnlyActionResult } from "./types.js";
+import type {
+  A2ACorrelationMetadata,
+  A2AReadOnlyActionResult,
+} from "./types.js";
 
 export type AgentInvocationErrorCode =
   | "missing-target"
@@ -82,6 +85,8 @@ export interface InvokeAgentOptions extends ResolveAgentInvocationTargetOptions
   timeoutMs?: number;
   pollIntervalMs?: number;
   includeInvocationHint?: boolean;
+  correlation?: A2ACorrelationMetadata;
+  idempotencyKey?: string;
   runtime?: Partial<AgentInvocationRuntime>;
 }
 
@@ -94,6 +99,7 @@ export interface InvokeAgentActionOptions extends ResolveAgentInvocationTargetOp
   orgDomain?: string;
   orgSecret?: string;
   requestTimeoutMs?: number;
+  correlation?: A2ACorrelationMetadata;
   runtime?: Partial<AgentInvocationRuntime>;
 }
 
@@ -197,6 +203,8 @@ export async function invokeAgent(
     async: options.async,
     timeoutMs: options.timeoutMs,
     pollIntervalMs: options.pollIntervalMs,
+    correlation: options.correlation,
+    idempotencyKey: options.idempotencyKey,
   });
 
   return {
@@ -243,6 +251,7 @@ export async function invokeAgentAction(
     orgDomain: options.orgDomain,
     orgSecret: options.orgSecret,
     requestTimeoutMs: options.requestTimeoutMs,
+    correlation: options.correlation,
   });
 
   return { target, action, result };