@agent-native/core 0.108.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: 2306
-- template files: 6134
+- core files: 2309
+- template files: 6143

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @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
+
+- 6cd2c79: Add audience-bound direct invocation for explicitly exposed read-only actions so sibling apps can skip a second agent loop for bounded data operations.
+  Add shared Slack and Notion corpus recipes so cursor pagination runs inside one resumable data operation instead of one model turn per page.
+
+### Patch Changes
+
+- 6cd2c79: Prevent cross-turn chat stream splicing and link browser sessions and session replays to agent-chat threads and runs.
+- 6cd2c79: Resume existing A2A tasks after bounded waits so cross-app agents do not duplicate long-running work.
+- 6cd2c79: Make progress tracking tolerate blank optional status fields, make extension replacement guard errors retryable when the explicit intent flag is missing, expose extension readiness callbacks for host loading states, show the underlying repeated tool error in agent stop messages, and avoid MCP connection suggestions based on hidden tool payloads.
+- 6cd2c79: Show image attachments in queued agent chat messages.
+- 6cd2c79: Open shared chat-thread links in the matching full-page chat or agent sidebar.
+- 6cd2c79: Ignore stackless stale module-loader failures that are handled by route-chunk recovery instead of creating noisy error issues.
+- 6cd2c79: Keep long agent-chat tool histories compact by collapsing older calls behind a "Ran N tools" disclosure.
+- 6cd2c79: Show chat run durations in work summaries and animate their content when opening.
+
 ## 0.108.0
 
 ### Minor Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.108.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,11 @@
 import * as jose from "jose";
 
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
+import { sanitizeA2ACorrelationMetadata } from "./correlation.js";
 import type {
   A2AApprovedAction,
+  A2ACorrelationMetadata,
+  A2AReadOnlyActionResult,
   AgentCard,
   JsonRpcRequest,
   JsonRpcResponse,
@@ -188,9 +191,19 @@ export class A2AClient {
         );
 
         if (res.ok) {
+          const text = await res.text();
+          if (
+            i < this.apiKeyAttempts.length - 1 &&
+            isA2AAuthRejectionResponse(res.status, text)
+          ) {
+            lastError = new Error(
+              `A2A request failed (${res.status}): ${text}`,
+            );
+            continue;
+          }
           this.endpointCandidates = [url];
           this.markApiKeySucceeded(this.apiKeyAttempts[i]);
-          return res.json() as Promise<JsonRpcResponse>;
+          return JSON.parse(text) as JsonRpcResponse;
         }
 
         const text = await res.text();
@@ -228,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`
@@ -244,6 +258,7 @@ export class A2AClient {
       message,
       contextId: opts?.contextId,
       metadata: opts?.metadata,
+      ...(opts?.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
       ...(opts?.approvedActions?.length
         ? { approvedActions: opts.approvedActions }
         : {}),
@@ -272,6 +287,30 @@ export class A2AClient {
     return response.result as Task;
   }
 
+  /**
+   * Execute one receiver-approved read-only action without starting the
+   * receiver's agent loop. The receiver still owns validation, credentials,
+   * request scoping, and the explicit action exposure decision.
+   */
+  async invokeAction(
+    action: string,
+    input: Record<string, unknown> = {},
+    opts?: { metadata?: A2ACorrelationMetadata },
+  ): Promise<A2AReadOnlyActionResult> {
+    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}`,
+      );
+    }
+    return response.result as A2AReadOnlyActionResult;
+  }
+
   /**
    * Send a message in async mode and poll until the task reaches a terminal
    * state. This is the recommended path on serverless hosts with short
@@ -286,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;
@@ -298,12 +338,45 @@ export class A2AClient {
     const submitted = await this.send(message, {
       contextId: opts?.contextId,
       metadata: opts?.metadata,
+      idempotencyKey: opts?.idempotencyKey,
       ...(opts?.approvedActions?.length
         ? { approvedActions: opts.approvedActions }
         : {}),
       async: true,
     });
 
+    return this.pollTask(submitted, opts);
+  }
+
+  /**
+   * Continue waiting for an existing async task without submitting a second
+   * message. Use this after a bounded caller-side wait expires but the remote
+   * task is still working.
+   */
+  async waitForTask(
+    taskId: string,
+    opts?: {
+      /** Total time to wait for completion. Default 5 min. */
+      timeoutMs?: number;
+      /** Poll interval. Default 2s. */
+      pollIntervalMs?: number;
+      /** Called with each successfully polled task. */
+      onUpdate?: (task: Task) => void;
+    },
+  ): Promise<Task> {
+    const current = await this.getTask(taskId);
+    opts?.onUpdate?.(current);
+    return this.pollTask(current, opts);
+  }
+
+  private async pollTask(
+    submitted: Task,
+    opts?: {
+      timeoutMs?: number;
+      pollIntervalMs?: number;
+      onUpdate?: (task: Task) => void;
+    },
+  ): Promise<Task> {
     const terminalStates = new Set([
       "completed",
       "failed",
@@ -532,6 +605,7 @@ function uniqueAuthTokens(
 function isA2AAuthRejectionResponse(status: number, text: string): boolean {
   return (
     status === 401 ||
+    /verified, audience-bound user identity/i.test(text) ||
     /A2A error \(-32001\): (?:Invalid or expired A2A token|Invalid API key|Authentication required)|Invalid or expired A2A token|Invalid API key|Authentication required/i.test(
       text,
     )
@@ -558,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.
@@ -566,6 +644,11 @@ export async function callAgent(
     async?: boolean;
     /** Total time to wait for the polled task (default 5 min). */
     timeoutMs?: number;
+    /**
+     * Existing async task to keep polling. When set, no new message is sent.
+     * This prevents a caller-side timeout from duplicating downstream work.
+     */
+    taskId?: string;
     /** Poll interval for async calls. Primarily useful for tests/retries. */
     pollIntervalMs?: number;
     /**
@@ -590,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
@@ -615,20 +699,31 @@ export async function callAgent(
       });
       let task: Task;
       if (useAsync) {
-        task = await client.sendAndWait(message, {
-          contextId: opts?.contextId,
-          metadata,
-          ...(opts?.approvedActions?.length
-            ? { approvedActions: opts.approvedActions }
-            : {}),
-          timeoutMs: opts?.timeoutMs,
-          pollIntervalMs: opts?.pollIntervalMs,
-          onUpdate: opts?.onUpdate,
-        });
+        task = opts?.taskId
+          ? await client.waitForTask(opts.taskId, {
+              timeoutMs: opts.timeoutMs,
+              pollIntervalMs: opts.pollIntervalMs,
+              onUpdate: opts.onUpdate,
+            })
+          : await client.sendAndWait(message, {
+              contextId: opts?.contextId,
+              metadata,
+              idempotencyKey: opts?.idempotencyKey,
+              ...(opts?.approvedActions?.length
+                ? { approvedActions: opts.approvedActions }
+                : {}),
+              timeoutMs: opts?.timeoutMs,
+              pollIntervalMs: opts?.pollIntervalMs,
+              onUpdate: opts?.onUpdate,
+            });
       } else {
+        if (opts?.taskId) {
+          throw new Error("Polling an existing A2A task requires async mode");
+        }
         task = await client.send(message, {
           contextId: opts?.contextId,
           metadata,
+          idempotencyKey: opts?.idempotencyKey,
           ...(opts?.approvedActions?.length
             ? { approvedActions: opts.approvedActions }
             : {}),
@@ -665,12 +760,55 @@ export async function callAgent(
   return "";
 }
 
-async function buildA2AApiKeyAttempts(opts?: {
-  apiKey?: string;
-  userEmail?: string;
-  orgDomain?: string;
-  orgSecret?: string;
-}): Promise<Array<string | undefined>> {
+/**
+ * Invoke one receiver-approved read-only action with an audience-bound user
+ * token. Unlike conversational delegation, this never starts the receiver's
+ * model loop.
+ */
+export async function callAction(
+  url: string,
+  action: string,
+  input: Record<string, unknown> = {},
+  opts?: {
+    apiKey?: string;
+    userEmail?: string;
+    orgDomain?: string;
+    orgSecret?: string;
+    requestTimeoutMs?: number;
+    correlation?: A2ACorrelationMetadata;
+  },
+): Promise<A2AReadOnlyActionResult> {
+  const actionName = action.trim();
+  if (!actionName) throw new Error("A2A action name is required");
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("A2A action input must be an object");
+  }
+
+  const apiKeyAttempts = await buildA2AApiKeyAttempts(
+    opts,
+    normalizeA2AAudience(url),
+  );
+  const fallbackApiKeys = apiKeyAttempts
+    .slice(1)
+    .filter((token): token is string => token !== undefined);
+  const client = new A2AClient(url, apiKeyAttempts[0], {
+    fallbackApiKeys,
+    requestTimeoutMs: opts?.requestTimeoutMs,
+  });
+  return client.invokeAction(actionName, input, {
+    metadata: sanitizeA2ACorrelationMetadata(opts?.correlation),
+  });
+}
+
+async function buildA2AApiKeyAttempts(
+  opts?: {
+    apiKey?: string;
+    userEmail?: string;
+    orgDomain?: string;
+    orgSecret?: string;
+  },
+  audience?: string,
+): Promise<Array<string | undefined>> {
   const attempts: Array<string | undefined> = [];
   const add = (token: string | undefined) => {
     if (token === undefined || attempts.includes(token)) return;
@@ -685,6 +823,7 @@ async function buildA2AApiKeyAttempts(opts?: {
         add(
           await signA2AToken(opts.userEmail, opts.orgDomain, opts.orgSecret, {
             preferGlobalSecret: true,
+            audience,
           }),
         );
       } catch {
@@ -697,6 +836,7 @@ async function buildA2AApiKeyAttempts(opts?: {
         add(
           await signA2AToken(opts.userEmail, opts.orgDomain, opts.orgSecret, {
             preferGlobalSecret: false,
+            audience,
           }),
         );
       } catch {
@@ -709,6 +849,11 @@ async function buildA2AApiKeyAttempts(opts?: {
   return attempts;
 }
 
+function normalizeA2AAudience(url: string): string {
+  const explicit = splitExplicitA2AEndpoint(url.replace(/\/$/, ""));
+  return (explicit?.baseUrl ?? url).replace(/\/$/, "");
+}
+
 function isA2AAuthRejection(err: unknown): boolean {
   const message = err instanceof Error ? err.message : String(err ?? "");
   return /A2A request failed \(401\)|A2A error \(-32001\): (?:Invalid or expired A2A token|Invalid API key|Authentication required)|Invalid or expired A2A token|Invalid API key|Authentication required/i.test(

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 } : {}),
+  };
+}