@agent-native/core 0.131.5 → 0.131.7

package/dist/a2a/client.js

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as jose from "jose";
 import { ssrfSafeFetch } from "../extensions/url-safety.js";
 /**
@@ -46,6 +47,10 @@ function workspacePrivateOrigins() {
 }
 import { sanitizeA2ACorrelationMetadata } from "./correlation.js";
 const DEFAULT_A2A_POLL_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_A2A_DISCOVERY_TIMEOUT_MS = 3_000;
+const MAX_A2A_RPC_ATTEMPTS = 3;
+const A2A_RPC_RETRY_BASE_MS = 100;
+export const MAX_A2A_CALLER_RESPONSE_CHARS = 32_768;
 export class A2ATaskTimeoutError extends Error {
     taskId;
     lastTask;
@@ -61,6 +66,40 @@ export class A2ATaskTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+/**
+ * Preserves a receiver's terminal protocol state across the text-oriented
+ * callAgent convenience boundary. Callers can distinguish a real answer from
+ * failure, cancellation, approval/input, and an invalid empty completion
+ * without parsing English prose.
+ */
+export class A2ATaskTerminalError extends Error {
+    taskId;
+    state;
+    responseText;
+    errorCode;
+    task;
+    constructor(task, state, responseText, errorCode = `a2a_task_${state.replace(/-/g, "_")}`) {
+        const detail = responseText.trim()
+            ? `: ${boundA2ACallerResponseText(responseText).trim()}`
+            : "";
+        super(`A2A task ${task.id} ended ${state}${detail}`);
+        this.name = "A2ATaskTerminalError";
+        this.taskId = task.id;
+        this.state = state;
+        this.responseText = boundA2ACallerResponseText(responseText);
+        this.errorCode = errorCode;
+        this.task = task;
+    }
+}
+/** Keep both the answer lead and artifact/source tail within caller context. */
+export function boundA2ACallerResponseText(value) {
+    if (value.length <= MAX_A2A_CALLER_RESPONSE_CHARS)
+        return value;
+    const marker = "\n\n...[A2A response compacted at the caller boundary; use the receiving app or returned artifact links for full details]...\n\n";
+    const tailChars = 8_192;
+    const headChars = MAX_A2A_CALLER_RESPONSE_CHARS - tailChars - marker.length;
+    return value.slice(0, headChars) + marker + value.slice(-tailChars);
+}
 /**
  * Sign a JWT for A2A cross-app identity verification.
  *
@@ -167,35 +206,72 @@ export class A2AClient {
             method,
             params,
         };
-        await this.ensureEndpointCandidates();
+        const discoveryTimeoutMs = resolveA2ADiscoveryTimeoutMs(options?.requestTimeoutMs ?? this.requestTimeoutMs, options?.deadlineMs);
+        await this.ensureEndpointCandidates(discoveryTimeoutMs);
         let lastError = null;
         for (const url of this.endpointCandidates) {
             for (let i = 0; i < this.apiKeyAttempts.length; i++) {
-                console.log(`[A2A Client] POST ${url} method=${method}`);
-                const startTime = Date.now();
-                const res = await this.postJson(url, body, this.apiKeyAttempts[i], options?.requestTimeoutMs);
-                console.log(`[A2A Client] Response: ${res.status} in ${Date.now() - startTime}ms`);
-                if (res.ok) {
+                const maxAttempts = isRetrySafeA2ARpc(method, params, this.apiKeyAttempts[i])
+                    ? MAX_A2A_RPC_ATTEMPTS
+                    : 1;
+                for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+                    const requestTimeoutMs = resolveA2ARequestTimeoutMs(options?.requestTimeoutMs ?? this.requestTimeoutMs, options?.deadlineMs);
+                    if (requestTimeoutMs !== undefined && requestTimeoutMs <= 0) {
+                        throw new Error("A2A request deadline exceeded");
+                    }
+                    console.log(`[A2A Client] POST ${url} method=${method} attempt=${attempt}/${maxAttempts}`);
+                    const startTime = Date.now();
+                    let res;
+                    try {
+                        res = await this.postJson(url, body, this.apiKeyAttempts[i], requestTimeoutMs);
+                    }
+                    catch (error) {
+                        lastError =
+                            error instanceof Error ? error : new Error(String(error));
+                        if (attempt < maxAttempts) {
+                            await waitForA2ARetry(attempt, null, remainingA2ADeadlineMs(options?.deadlineMs));
+                            continue;
+                        }
+                        break;
+                    }
+                    console.log(`[A2A Client] Response: ${res.status} in ${Date.now() - startTime}ms`);
+                    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}`);
+                            break;
+                        }
+                        try {
+                            const parsed = JSON.parse(text);
+                            this.endpointCandidates = [url];
+                            this.markApiKeySucceeded(this.apiKeyAttempts[i]);
+                            return parsed;
+                        }
+                        catch (error) {
+                            lastError = new Error(`A2A response was not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+                            if (attempt < maxAttempts) {
+                                await waitForA2ARetry(attempt, null, remainingA2ADeadlineMs(options?.deadlineMs));
+                                continue;
+                            }
+                            break;
+                        }
+                    }
                     const text = await res.text();
+                    lastError = new Error(`A2A request failed (${res.status}): ${text}`);
                     if (i < this.apiKeyAttempts.length - 1 &&
                         isA2AAuthRejectionResponse(res.status, text)) {
-                        lastError = new Error(`A2A request failed (${res.status}): ${text}`);
+                        break;
+                    }
+                    if (isRetryableA2AStatus(res.status) && attempt < maxAttempts) {
+                        await waitForA2ARetry(attempt, res.headers.get("retry-after"), remainingA2ADeadlineMs(options?.deadlineMs));
                         continue;
                     }
-                    this.endpointCandidates = [url];
-                    this.markApiKeySucceeded(this.apiKeyAttempts[i]);
-                    return JSON.parse(text);
-                }
-                const text = await res.text();
-                lastError = new Error(`A2A request failed (${res.status}): ${text}`);
-                if (i < this.apiKeyAttempts.length - 1 &&
-                    isA2AAuthRejectionResponse(res.status, text)) {
-                    continue;
-                }
-                if (!shouldTryNextEndpoint(res.status)) {
-                    throw lastError;
+                    if (!shouldTryNextEndpoint(res.status)) {
+                        throw lastError;
+                    }
+                    break;
                 }
-                break;
             }
         }
         throw lastError ?? new Error("No A2A endpoint candidates available");
@@ -219,11 +295,16 @@ export class A2AClient {
             message,
             contextId: opts?.contextId,
             metadata: opts?.metadata,
-            ...(opts?.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+            ...(opts?.idempotencyKey
+                ? { idempotencyKey: opts.idempotencyKey }
+                : {}),
             ...(opts?.approvedActions?.length
                 ? { approvedActions: opts.approvedActions }
                 : {}),
             ...(opts?.async ? { async: true } : {}),
+        }, {
+            requestTimeoutMs: opts?.requestTimeoutMs,
+            deadlineMs: opts?.deadlineMs,
         });
         if (response.error) {
             throw new Error(`A2A error (${response.error.code}): ${response.error.message}`);
@@ -234,7 +315,10 @@ export class A2AClient {
      * Poll for a task by id. Used in async mode after `send({ async: true })`.
      */
     async getTask(taskId, opts) {
-        const response = await this.rpc("tasks/get", { id: taskId }, { requestTimeoutMs: opts?.requestTimeoutMs });
+        const response = await this.rpc("tasks/get", { id: taskId }, {
+            requestTimeoutMs: opts?.requestTimeoutMs,
+            deadlineMs: opts?.deadlineMs,
+        });
         if (response.error) {
             throw new Error(`A2A error (${response.error.code}): ${response.error.message}`);
         }
@@ -267,6 +351,8 @@ export class A2AClient {
      * receiving side and is checked via `tasks/get`.
      */
     async sendAndWait(message, opts) {
+        const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
+        const deadlineMs = Date.now() + timeoutMs;
         const submitted = await this.send(message, {
             contextId: opts?.contextId,
             metadata: opts?.metadata,
@@ -275,8 +361,10 @@ export class A2AClient {
                 ? { approvedActions: opts.approvedActions }
                 : {}),
             async: true,
+            requestTimeoutMs: Math.min(this.requestTimeoutMs ?? DEFAULT_A2A_POLL_REQUEST_TIMEOUT_MS, Math.max(1, deadlineMs - Date.now())),
+            deadlineMs,
         });
-        return this.pollTask(submitted, opts);
+        return this.pollTask(submitted, { ...opts, timeoutMs, deadlineMs });
     }
     /**
      * Continue waiting for an existing async task without submitting a second
@@ -284,9 +372,14 @@ export class A2AClient {
      * task is still working.
      */
     async waitForTask(taskId, opts) {
-        const current = await this.getTask(taskId);
-        opts?.onUpdate?.(current);
-        return this.pollTask(current, opts);
+        const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
+        const deadlineMs = Date.now() + timeoutMs;
+        const current = await this.getTask(taskId, {
+            requestTimeoutMs: Math.min(this.requestTimeoutMs ?? DEFAULT_A2A_POLL_REQUEST_TIMEOUT_MS, Math.max(1, deadlineMs - Date.now())),
+            deadlineMs,
+        });
+        safelyNotifyA2AUpdate(opts?.onUpdate, current);
+        return this.pollTask(current, { ...opts, timeoutMs, deadlineMs });
     }
     async pollTask(submitted, opts) {
         const terminalStates = new Set([
@@ -299,7 +392,7 @@ export class A2AClient {
             return submitted;
         const timeoutMs = opts?.timeoutMs ?? 5 * 60_000;
         const pollMs = opts?.pollIntervalMs ?? 2_000;
-        const deadline = Date.now() + timeoutMs;
+        const deadline = opts?.deadlineMs ?? Date.now() + timeoutMs;
         let current = submitted;
         while (Date.now() < deadline) {
             const sleepMs = Math.min(pollMs, Math.max(0, deadline - Date.now()));
@@ -310,12 +403,17 @@ export class A2AClient {
             try {
                 current = await this.getTask(submitted.id, {
                     requestTimeoutMs: Math.min(this.requestTimeoutMs ?? DEFAULT_A2A_POLL_REQUEST_TIMEOUT_MS, remainingMs),
+                    deadlineMs: deadline,
                 });
-                opts?.onUpdate?.(current);
+                safelyNotifyA2AUpdate(opts?.onUpdate, current);
             }
-            catch {
-                // Transient fetch failure — keep polling until the deadline.
-                continue;
+            catch (error) {
+                // Retry only transport/gateway interruptions. Authentication,
+                // task-not-found, invalid params, and other protocol failures are
+                // permanent for this poll and must surface immediately.
+                if (isRetryableA2APollError(error))
+                    continue;
+                throw error;
             }
             if (terminalStates.has(current.status.state))
                 return current;
@@ -388,14 +486,14 @@ export class A2AClient {
             }
         }
     }
-    async ensureEndpointCandidates() {
+    async ensureEndpointCandidates(timeoutMs) {
         if (this.endpointResolved)
             return;
         this.endpointResolved = true;
         const candidates = [];
         addDefaultEndpointCandidates(candidates, this.baseUrl);
         try {
-            const card = await this.getAgentCard();
+            const card = await this.getAgentCard({ timeoutMs });
             const cardUrl = normalizeUrl(card.url, this.baseUrl);
             if (cardUrl) {
                 const explicitEndpoint = splitExplicitA2AEndpoint(cardUrl);
@@ -478,6 +576,92 @@ function normalizeUrl(value, baseUrl) {
 function shouldTryNextEndpoint(status) {
     return status === 404 || status === 405;
 }
+function isRetrySafeA2ARpc(method, params, apiKey) {
+    if (method === "message/send") {
+        return (params.async === true &&
+            typeof params.idempotencyKey === "string" &&
+            params.idempotencyKey.trim().length > 0 &&
+            hasJwtSubject(apiKey));
+    }
+    return method === "tasks/get" || method === "actions/invoke";
+}
+function isRetryableA2AStatus(status) {
+    return (status === 408 ||
+        status === 425 ||
+        status === 429 ||
+        status === 500 ||
+        status === 502 ||
+        status === 503 ||
+        status === 504);
+}
+async function waitForA2ARetry(attempt, retryAfter = null, maxWaitMs) {
+    const retryAfterSeconds = retryAfter ? Number(retryAfter) : NaN;
+    const retryAfterMs = Number.isFinite(retryAfterSeconds)
+        ? Math.max(0, Math.min(2_000, retryAfterSeconds * 1_000))
+        : 0;
+    const backoffMs = Math.max(retryAfterMs, Math.min(1_000, A2A_RPC_RETRY_BASE_MS * 2 ** (attempt - 1)));
+    const boundedWaitMs = maxWaitMs === undefined ? backoffMs : Math.min(backoffMs, maxWaitMs);
+    if (boundedWaitMs <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, boundedWaitMs));
+}
+function remainingA2ADeadlineMs(deadlineMs) {
+    return deadlineMs === undefined
+        ? undefined
+        : Math.max(0, deadlineMs - Date.now());
+}
+function resolveA2ARequestTimeoutMs(configuredMs, deadlineMs) {
+    const remainingMs = remainingA2ADeadlineMs(deadlineMs);
+    if (remainingMs === undefined)
+        return configuredMs;
+    return configuredMs === undefined
+        ? remainingMs
+        : Math.min(configuredMs, remainingMs);
+}
+/**
+ * Agent-card discovery is only a hint because first-party endpoints have
+ * conventional paths. Preserve most of a bounded call's deadline for the
+ * actual message instead of letting a cold or unavailable card consume it.
+ */
+function resolveA2ADiscoveryTimeoutMs(configuredMs, deadlineMs) {
+    const transportBudgetMs = resolveA2ARequestTimeoutMs(configuredMs, deadlineMs);
+    const remainingMs = remainingA2ADeadlineMs(deadlineMs);
+    const deadlineShareMs = remainingMs === undefined
+        ? DEFAULT_A2A_DISCOVERY_TIMEOUT_MS
+        : Math.max(1, Math.floor(remainingMs / 4));
+    return Math.min(DEFAULT_A2A_DISCOVERY_TIMEOUT_MS, transportBudgetMs ?? DEFAULT_A2A_DISCOVERY_TIMEOUT_MS, deadlineShareMs);
+}
+function hasJwtSubject(apiKey) {
+    if (!apiKey)
+        return false;
+    const segments = apiKey.split(".");
+    if (segments.length !== 3)
+        return false;
+    try {
+        const payload = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));
+        return typeof payload.sub === "string" && payload.sub.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function isRetryableA2APollError(error) {
+    const message = error instanceof Error ? error.message : String(error ?? "");
+    if (isA2AAuthRejection(error))
+        return false;
+    if (/A2A error \(-32\d+\)|A2A request failed \((?:400|403|404|405|409|422)\)/i.test(message)) {
+        return false;
+    }
+    return /(?:A2A request failed \((?:408|425|429|5\d\d)\)|fetch failed|network|socket|ECONN|ETIMEDOUT|timeout|deadline|aborted|invalid JSON)/i.test(message);
+}
+function safelyNotifyA2AUpdate(callback, task) {
+    try {
+        callback?.(task);
+    }
+    catch {
+        // Presentation/progress callbacks cannot alter task polling.
+    }
+}
 function unique(values) {
     return Array.from(new Set(values));
 }
@@ -521,6 +705,10 @@ export async function callAgent(url, text, opts) {
     // detached promises that get killed on Netlify/Vercel. Callers that
     // explicitly want a single-shot blocking POST can pass `async: false`.
     const useAsync = opts?.async ?? true;
+    // A stable per-call key makes retrying a submission safe even when this
+    // invocation has no durable parent turn id. If the receiver committed the
+    // task but the response was lost, the retry reuses the task.
+    const effectiveIdempotencyKey = opts?.idempotencyKey ?? (opts?.taskId ? undefined : `auto:${randomUUID()}`);
     const message = {
         role: "user",
         parts: [{ type: "text", text }],
@@ -546,7 +734,7 @@ export async function callAgent(url, text, opts) {
                     : await client.sendAndWait(message, {
                         contextId: opts?.contextId,
                         metadata,
-                        idempotencyKey: opts?.idempotencyKey,
+                        idempotencyKey: effectiveIdempotencyKey,
                         ...(opts?.approvedActions?.length
                             ? { approvedActions: opts.approvedActions }
                             : {}),
@@ -562,28 +750,47 @@ export async function callAgent(url, text, opts) {
                 task = await client.send(message, {
                     contextId: opts?.contextId,
                     metadata,
-                    idempotencyKey: opts?.idempotencyKey,
+                    idempotencyKey: effectiveIdempotencyKey,
                     ...(opts?.approvedActions?.length
                         ? { approvedActions: opts.approvedActions }
                         : {}),
                 });
             }
-            // Extract text from the response
+            // Preserve the receiver's typed terminal state. Failed, canceled, and
+            // input-required tasks are not successful text answers, even when the
+            // receiver attached a friendly explanatory message.
             const responseMessage = task.status.message;
-            if (responseMessage) {
-                const textParts = responseMessage.parts
-                    .filter((p) => p.type === "text")
-                    .map((p) => p.text);
-                return textParts.join("\n");
+            const responseText = responseMessage
+                ? extractMessageText(responseMessage)
+                : "";
+            const state = task.status.state;
+            if (state === "failed" ||
+                state === "canceled" ||
+                state === "input-required") {
+                throw new A2ATaskTerminalError(task, state, responseText);
+            }
+            if (state !== "completed") {
+                throw new A2ATaskTerminalError(task, "failed", responseText || `Unexpected terminal state: ${state}`, "a2a_invalid_terminal_state");
+            }
+            if (responseText.trim()) {
+                if (responseText.length > MAX_A2A_CALLER_RESPONSE_CHARS) {
+                    throw new A2ATaskTerminalError(task, "completed", responseText, "a2a_response_too_large");
+                }
+                return responseText;
             }
-            return "";
+            const artifactSummary = verifiedArtifactSummary(task);
+            if (artifactSummary)
+                return artifactSummary;
+            throw new A2ATaskTerminalError(task, "completed", "Agent completed without a response or verified artifact.", "empty_agent_response");
         }
         catch (err) {
             if (opts?.returnRecoverableArtifactsOnTimeout !== false &&
                 err instanceof A2ATaskTimeoutError) {
                 const recoverableText = extractRecoverableArtifactText(err.lastTask);
-                if (recoverableText)
+                if (recoverableText &&
+                    recoverableText.length <= MAX_A2A_CALLER_RESPONSE_CHARS) {
                     return recoverableText;
+                }
             }
             if (i < apiKeyAttempts.length - 1 && isA2AAuthRejection(err)) {
                 lastAuthError = err;
@@ -683,9 +890,67 @@ function extractRecoverableArtifactText(task) {
     return extractMessageText(task.status.message);
 }
 function extractMessageText(message) {
-    return message.parts
+    return (Array.isArray(message.parts) ? message.parts : [])
         .filter((p) => p.type === "text")
         .map((p) => p.text)
         .join("\n");
 }
+function verifiedArtifactSummary(task) {
+    const artifacts = Array.isArray(task.artifacts) ? task.artifacts : [];
+    if (artifacts.length === 0)
+        return "";
+    const summaries = artifacts
+        .map((artifact, artifactIndex) => {
+        const parts = Array.isArray(artifact?.parts) ? artifact.parts : [];
+        const usableParts = parts
+            .map((part) => summarizeVerifiedArtifactPart(part))
+            .filter((value) => !!value)
+            .slice(0, 5);
+        if (usableParts.length === 0)
+            return null;
+        const fallbackFileName = parts.find((part) => part.type === "file" && part.file.name?.trim());
+        const label = artifact?.name?.trim() ||
+            (fallbackFileName?.type === "file"
+                ? fallbackFileName.file.name?.trim()
+                : "") ||
+            `Artifact ${artifactIndex + 1}`;
+        return `- ${label}\n${usableParts.map((part) => `  - ${part}`).join("\n")}`;
+    })
+        .filter((value) => !!value)
+        .slice(0, 20);
+    if (summaries.length === 0)
+        return "";
+    return boundA2ACallerResponseText(`The agent completed with ${summaries.length} verified artifact(s):\n` +
+        summaries.join("\n"));
+}
+function summarizeVerifiedArtifactPart(part) {
+    if (!part || typeof part !== "object")
+        return null;
+    const candidate = part;
+    if (candidate.type === "text" && typeof candidate.text === "string") {
+        const text = candidate.text.trim();
+        return text ? boundA2ACallerResponseText(text).slice(0, 2_000) : null;
+    }
+    if (candidate.type === "file") {
+        const file = candidate.file;
+        if (!file)
+            return null;
+        const uri = typeof file.uri === "string" ? file.uri.trim() : "";
+        const name = typeof file.name === "string" ? file.name.trim() : "";
+        const bytes = typeof file.bytes === "string" ? file.bytes : "";
+        if (uri)
+            return name ? `${name}: ${uri}` : uri;
+        if (bytes)
+            return name ? `${name} (inline file)` : "Inline file artifact";
+        return null;
+    }
+    if (candidate.type === "data") {
+        const data = candidate.data;
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return null;
+        const serialized = JSON.stringify(data);
+        return serialized !== "{}" ? serialized.slice(0, 2_000) : null;
+    }
+    return null;
+}
 //# sourceMappingURL=client.js.map