@agent-native/core 0.109.0 → 0.109.1

package/corpus/core/src/a2a/task-store.ts

@@ -1,10 +1,17 @@
 import crypto from "crypto";
 
 import { getDbExec, intType, isPostgres } from "../db/client.js";
-import { ensureTableExists, ensureColumnExists } from "../db/ddl-guard.js";
+import {
+  ensureTableExists,
+  ensureColumnExists,
+  ensureIndexExists,
+} from "../db/ddl-guard.js";
 import type { Task, Message, TaskState, Artifact } from "./types.js";
 
 let _initPromise: Promise<void> | undefined;
+export const MAX_A2A_IDEMPOTENCY_KEY_CHARS = 128;
+const A2A_IDEMPOTENCY_INDEX = "idx_a2a_tasks_owner_scope_idempotency";
+export const A2A_PERSONAL_OWNER_SCOPE = "__personal__";
 
 async function ensureTable(): Promise<void> {
   if (!_initPromise) {
@@ -20,10 +27,16 @@ async function ensureTable(): Promise<void> {
           history TEXT NOT NULL DEFAULT '[]',
           artifacts TEXT NOT NULL DEFAULT '[]',
           metadata TEXT,
+          owner_email TEXT,
+          owner_scope TEXT NOT NULL DEFAULT '',
+          idempotency_key TEXT,
           created_at ${intType()} NOT NULL,
           updated_at ${intType()} NOT NULL
         )
       `;
+      const createIdempotencyIndexSql =
+        `CREATE UNIQUE INDEX IF NOT EXISTS ${A2A_IDEMPOTENCY_INDEX} ` +
+        `ON a2a_tasks(owner_email, owner_scope, idempotency_key)`;
       const createApprovalsSql = `
         CREATE TABLE IF NOT EXISTS a2a_approvals (
           id TEXT PRIMARY KEY,
@@ -57,6 +70,20 @@ async function ensureTable(): Promise<void> {
           "owner_email",
           `ALTER TABLE a2a_tasks ADD COLUMN IF NOT EXISTS owner_email TEXT`,
         );
+        await ensureColumnExists(
+          "a2a_tasks",
+          "owner_scope",
+          `ALTER TABLE a2a_tasks ADD COLUMN IF NOT EXISTS owner_scope TEXT NOT NULL DEFAULT ''`,
+        );
+        await ensureColumnExists(
+          "a2a_tasks",
+          "idempotency_key",
+          `ALTER TABLE a2a_tasks ADD COLUMN IF NOT EXISTS idempotency_key TEXT`,
+        );
+        await ensureIndexExists(
+          A2A_IDEMPOTENCY_INDEX,
+          createIdempotencyIndexSql,
+        );
         await ensureTableExists("a2a_approvals", createApprovalsSql);
         return;
       }
@@ -69,6 +96,13 @@ async function ensureTable(): Promise<void> {
       // have NULL owner_email and remain accessible to legacy callers via
       // the legacy-token apiKeyEnv path; new rows are scoped from this point
       // forward.
+      try {
+        await client.execute(
+          `ALTER TABLE a2a_tasks ADD COLUMN owner_scope TEXT NOT NULL DEFAULT ''`,
+        );
+      } catch {
+        // Column already exists — expected on every restart after first run.
+      }
       try {
         await client.execute(
           `ALTER TABLE a2a_tasks ADD COLUMN owner_email TEXT`,
@@ -76,6 +110,14 @@ async function ensureTable(): Promise<void> {
       } catch {
         // Column already exists — expected on every restart after first run.
       }
+      try {
+        await client.execute(
+          `ALTER TABLE a2a_tasks ADD COLUMN idempotency_key TEXT`,
+        );
+      } catch {
+        // Column already exists — expected on every restart after first run.
+      }
+      await client.execute(createIdempotencyIndexSql);
       await client.execute(createApprovalsSql);
     })().catch((err) => {
       // Retry init on the next call after a failed startup.
@@ -320,7 +362,10 @@ export async function pauseProcessingA2ATask(
   return task;
 }
 
-function taskFromRow(row: any): Task & { ownerEmail?: string | null } {
+function taskFromRow(row: any): Task & {
+  ownerEmail?: string | null;
+  ownerScope?: string | null;
+} {
   return {
     id: row.id as string,
     contextId: (row.context_id as string) || undefined,
@@ -335,6 +380,7 @@ function taskFromRow(row: any): Task & { ownerEmail?: string | null } {
     artifacts: JSON.parse(row.artifacts as string),
     metadata: row.metadata ? JSON.parse(row.metadata as string) : undefined,
     ownerEmail: (row.owner_email as string | null) ?? null,
+    ownerScope: (row.owner_scope as string | null) ?? null,
   };
 }
 
@@ -356,6 +402,7 @@ export async function createTask(
   contextId?: string,
   metadata?: Record<string, unknown>,
   ownerEmail?: string | null,
+  ownerScope?: string | null,
 ): Promise<Task> {
   await ensureTable();
   const client = getDbExec();
@@ -373,7 +420,7 @@ export async function createTask(
   };
 
   await client.execute({
-    sql: `INSERT INTO a2a_tasks (id, context_id, status_state, status_timestamp, history, artifacts, metadata, owner_email, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    sql: `INSERT INTO a2a_tasks (id, context_id, status_state, status_timestamp, history, artifacts, metadata, owner_email, owner_scope, idempotency_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     args: [
       id,
       contextId ?? null,
@@ -383,6 +430,8 @@ export async function createTask(
       "[]",
       metadata ? JSON.stringify(metadata) : null,
       ownerEmail ?? null,
+      ownerScope ?? "",
+      null,
       now,
       now,
     ],
@@ -391,6 +440,87 @@ export async function createTask(
   return task;
 }
 
+export async function createOrReuseTask(
+  message: Message,
+  contextId: string | undefined,
+  metadata: Record<string, unknown> | undefined,
+  ownerEmail: string | null,
+  ownerScope: string | null,
+  idempotencyKey: string | undefined,
+): Promise<{ task: Task; reused: boolean }> {
+  if (!ownerEmail || !idempotencyKey) {
+    return {
+      task: await createTask(
+        message,
+        contextId,
+        metadata,
+        ownerEmail,
+        ownerScope,
+      ),
+      reused: false,
+    };
+  }
+  if (idempotencyKey.length > MAX_A2A_IDEMPOTENCY_KEY_CHARS) {
+    throw new Error("A2A idempotency key is too long");
+  }
+
+  await ensureTable();
+  const client = getDbExec();
+  const normalizedOwner = ownerEmail.trim().toLowerCase();
+  const normalizedScope =
+    ownerScope?.trim().toLowerCase() || A2A_PERSONAL_OWNER_SCOPE;
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const id = crypto.randomUUID();
+    const now = Date.now();
+    const timestamp = new Date().toISOString();
+    await client.execute({
+      sql: `INSERT INTO a2a_tasks (id, context_id, status_state, status_timestamp, history, artifacts, metadata, owner_email, owner_scope, idempotency_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(owner_email, owner_scope, idempotency_key) DO NOTHING`,
+      args: [
+        id,
+        contextId ?? null,
+        "submitted",
+        timestamp,
+        JSON.stringify([message]),
+        "[]",
+        metadata ? JSON.stringify(metadata) : null,
+        normalizedOwner,
+        normalizedScope,
+        idempotencyKey,
+        now,
+        now,
+      ],
+    });
+
+    const { rows } = await client.execute({
+      sql: `SELECT * FROM a2a_tasks WHERE owner_email = ? AND owner_scope = ? AND idempotency_key = ?`,
+      args: [normalizedOwner, normalizedScope, idempotencyKey],
+    });
+    if (rows.length === 0) {
+      throw new Error("A2A idempotent task insert could not be verified");
+    }
+    const task = taskFromRow(rows[0]);
+    const reused = task.id !== id;
+    if (
+      reused &&
+      (task.status.state === "failed" || task.status.state === "canceled")
+    ) {
+      await client.execute({
+        sql: `UPDATE a2a_tasks SET idempotency_key = NULL, updated_at = ? WHERE id = ? AND idempotency_key = ? AND status_state IN ('failed', 'canceled')`,
+        args: [Date.now(), task.id, idempotencyKey],
+      });
+      continue;
+    }
+    return { task, reused };
+  }
+  throw new Error("A2A terminal task idempotency key could not be released");
+}
+
+export interface A2ATaskOwnership {
+  ownerEmail: string | null;
+  ownerScope: string | null;
+}
+
 /**
  * Fetch the verified owner email recorded against a task at creation time.
  * Returns null when the task has no owner (legacy rows or unauthenticated
@@ -400,15 +530,25 @@ export async function createTask(
  * verified caller's email must match `owner_email` to read or cancel.
  */
 export async function getTaskOwner(id: string): Promise<string | null> {
+  return (await getTaskOwnership(id)).ownerEmail;
+}
+
+export async function getTaskOwnership(id: string): Promise<A2ATaskOwnership> {
   await ensureTable();
   const client = getDbExec();
   const { rows } = await client.execute({
-    sql: `SELECT owner_email FROM a2a_tasks WHERE id = ?`,
+    sql: `SELECT owner_email, owner_scope FROM a2a_tasks WHERE id = ?`,
     args: [id],
   });
-  if (rows.length === 0) return null;
+  if (rows.length === 0) return { ownerEmail: null, ownerScope: null };
   const ownerEmail = (rows[0] as any).owner_email;
-  return typeof ownerEmail === "string" && ownerEmail ? ownerEmail : null;
+  const ownerScope = (rows[0] as any).owner_scope;
+  return {
+    ownerEmail:
+      typeof ownerEmail === "string" && ownerEmail ? ownerEmail : null,
+    ownerScope:
+      typeof ownerScope === "string" && ownerScope ? ownerScope : null,
+  };
 }
 
 /**

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

@@ -132,6 +132,19 @@ export interface A2AApprovedAction {
   input: unknown;
 }
 
+/**
+ * Telemetry-only cross-app correlation. Receivers must never use these
+ * caller-supplied values for identity, ownership, org scoping, access, or
+ * approval decisions.
+ */
+export interface A2ACorrelationMetadata {
+  callerApp?: string;
+  callerThreadId?: string;
+  parentRunId?: string;
+  parentTurnId?: string;
+  invocationId?: string;
+}
+
 // --- Framework config ---
 
 export interface A2AHandlerContext {
@@ -168,6 +181,7 @@ export interface A2AApprovalExecution {
 export interface A2AReadOnlyActionInvocation {
   action: string;
   input: Record<string, unknown>;
+  invocationId: string;
 }
 
 export interface A2AReadOnlyActionResult {
@@ -183,6 +197,8 @@ export type A2AHandler = (
 
 export interface A2AConfig {
   name: string;
+  /** Canonical receiver app id used only for telemetry attribution. */
+  appId?: string;
   description: string;
   version?: string;
   skills: AgentSkill[];

package/corpus/core/src/action.ts

@@ -97,6 +97,8 @@ export interface ActionRunContext {
    * every human/programmatic surface.
    */
   threadId?: string;
+  /** Concrete execution id for this agent-loop attempt. */
+  runId?: string;
   turnId?: string;
 }
 

package/corpus/core/src/agent/production-agent.ts

@@ -2481,6 +2481,9 @@ export interface ExecuteAgentToolCallOptions {
   orgId?: string | null;
   /** Audit/action attribution for this externally selected call. */
   caller?: ActionCaller;
+  networkProtocol?: "a2a" | "mcp" | "provider-api";
+  networkId?: string;
+  networkPeer?: string;
   threadId?: string;
   turnId?: string;
   approvedToolCalls?: string[];
@@ -2576,6 +2579,9 @@ export async function executeAgentToolCall(
       ownerEmail: options.ownerEmail,
       orgId: options.orgId,
       actionCaller: options.caller,
+      networkProtocol: options.networkProtocol,
+      networkId: options.networkId,
+      networkPeer: options.networkPeer,
       executionMode: "act",
       maxIterations: 2,
       threadId: options.threadId,
@@ -3157,6 +3163,12 @@ export async function runAgentLoop(opts: {
   orgId?: string | null;
   /** Action invocation attribution. Defaults to the normal agent tool loop. */
   actionCaller?: ActionCaller;
+  /** Concrete execution id used for cross-app trace correlation. */
+  runId?: string;
+  /** Verified/telemetry-only delegated lineage supplied by the transport. */
+  networkProtocol?: "a2a" | "mcp" | "provider-api";
+  networkId?: string;
+  networkPeer?: string;
   /**
    * Attachments submitted with this turn (pasted text, files, images), passed
    * through to each tool's `ActionRunContext.attachments` so actions can
@@ -4215,6 +4227,9 @@ export async function runAgentLoop(opts: {
                     userEmail: getRequestUserEmail(),
                     orgId: getRequestOrgId() ?? null,
                     caller: opts.actionCaller ?? "tool",
+                    networkProtocol: opts.networkProtocol,
+                    networkId: opts.networkId,
+                    networkPeer: opts.networkPeer,
                   }),
                 )
               : actionEntry.needsApproval === true;
@@ -4249,6 +4264,9 @@ export async function runAgentLoop(opts: {
               ctx: {
                 actionName: toolCall.name,
                 caller: opts.actionCaller ?? "tool",
+                networkProtocol: opts.networkProtocol,
+                networkId: opts.networkId,
+                networkPeer: opts.networkPeer,
                 userEmail: getRequestUserEmail(),
                 orgId: getRequestOrgId() ?? null,
                 ...(opts.threadId ? { threadId: opts.threadId } : {}),
@@ -4645,12 +4663,16 @@ export async function runAgentLoop(opts: {
           userEmail: actionUserEmail ?? undefined,
           orgId: actionOrgId,
           caller: opts.actionCaller ?? "tool",
+          networkProtocol: opts.networkProtocol,
+          networkId: opts.networkId,
+          networkPeer: opts.networkPeer,
           attachments: opts.attachments,
           signal,
           // Audit attribution: the action name + the agent thread/turn that
           // triggered this call, so a mutation can be traced to its run.
           actionName: toolCall.name,
           ...(opts.threadId ? { threadId: opts.threadId } : {}),
+          ...(opts.runId ? { runId: opts.runId } : {}),
           ...(opts.turnId ? { turnId: opts.turnId } : {}),
         };
         const requestContext = getRequestContext();
@@ -8004,6 +8026,7 @@ export function createProductionAgentHandler(
         const agentLoopOpts = {
           engine,
           model: effectiveModel,
+          runId,
           systemPrompt: requestSystemPrompt,
           tools: requestTools,
           availableTools: availableRequestTools,

package/corpus/core/src/client/use-run-stuck-detection.ts

@@ -80,6 +80,7 @@ export const DEFAULT_BACKGROUND_STUCK_THRESHOLD_MS = 180_000;
 export const DEFAULT_LIVE_BACKGROUND_STUCK_THRESHOLD_MS = 13 * 60_000;
 const DEFAULT_POLL_INTERVAL_MS = 5_000;
 const IDLE_BACKOFF_INTERVAL_MS = 15_000;
+const MAX_POLL_ERROR_BACKOFF_MS = 30_000;
 const FRESH_BACKGROUND_HEARTBEAT_MS = 30_000;
 
 interface ActiveRunResponse {
@@ -129,6 +130,22 @@ export function useRunStuckDetection({
     let timer: ReturnType<typeof setTimeout> | null = null;
     let snapshotTransitionTimer: ReturnType<typeof setTimeout> | null = null;
     let snapshotVersion = 0;
+    let consecutivePollFailures = 0;
+
+    const pollFailureDelay = () => {
+      consecutivePollFailures += 1;
+      return Math.min(
+        Math.max(pollIntervalMs, 1) * 2 ** consecutivePollFailures,
+        MAX_POLL_ERROR_BACKOFF_MS,
+      );
+    };
+
+    const clearObservedRun = () => {
+      snapshotVersion += 1;
+      if (snapshotTransitionTimer) clearTimeout(snapshotTransitionTimer);
+      snapshotTransitionTimer = null;
+      setState(EMPTY_STATE);
+    };
 
     type RunHealthSnapshot = {
       active: boolean;
@@ -269,6 +286,7 @@ export function useRunStuckDetection({
         );
         if (cancelled) return;
         if (res.ok) {
+          consecutivePollFailures = 0;
           const data = (await res.json()) as ActiveRunResponse;
           const lastProgressAt = data.lastProgressAt ?? null;
           // Measure elapsed against the SERVER clock (serverNow) rather than the
@@ -336,9 +354,17 @@ export function useRunStuckDetection({
           if (!data.active || data.status !== "running") {
             nextDelay = IDLE_BACKOFF_INTERVAL_MS;
           }
+        } else if (res.status === 429 || res.status >= 500) {
+          nextDelay = pollFailureDelay();
+        } else {
+          consecutivePollFailures = 0;
+          clearObservedRun();
+          nextDelay = MAX_POLL_ERROR_BACKOFF_MS;
         }
       } catch {
-        // Network blip — leave previous state. Next tick will retry.
+        // Network/503 blip — leave previous state and ease polling pressure
+        // while the server or database recovers.
+        nextDelay = pollFailureDelay();
       }
       if (!cancelled) {
         timer = setTimeout(poll, nextDelay);

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

@@ -669,6 +669,61 @@ export function isConnectionError(err: any): boolean {
   );
 }
 
+/**
+ * Classify database failures that should temporarily shed request load.
+ * Statement timeouts are not included in isConnectionError() because retrying
+ * every timed-out mutation would not be safe, but request handlers can still
+ * return a retryable service-unavailable response for them.
+ */
+export function isTransientDatabaseError(err: unknown): boolean {
+  const error = err as {
+    code?: unknown;
+    name?: unknown;
+    message?: unknown;
+    stack?: unknown;
+    cause?: {
+      code?: unknown;
+      name?: unknown;
+      message?: unknown;
+      stack?: unknown;
+    };
+  };
+  const code = String(error?.code ?? error?.cause?.code ?? "");
+  if (
+    code === "ECHECKOUTTIMEOUT" ||
+    code === "53300" ||
+    code === "57014" ||
+    /^08/.test(code) ||
+    /^57P0[123]$/.test(code)
+  ) {
+    return true;
+  }
+
+  const message = [error?.message, error?.cause?.message]
+    .filter((value): value is string => typeof value === "string")
+    .join(" ");
+  if (
+    /\bstatement timeout\b|\bdb (?:query|connect) timed out\b/i.test(message)
+  ) {
+    return true;
+  }
+
+  const databaseSurface = [
+    error?.name,
+    error?.cause?.name,
+    error?.stack,
+    error?.cause?.stack,
+  ]
+    .filter((value): value is string => typeof value === "string")
+    .join(" ");
+  return (
+    isConnectionError(error) &&
+    /@neondatabase|@libsql|\bpostgres(?:ql)?\b|\bpg-pool\b|drizzle-orm|\/db\/client\.[cm]?[jt]s/i.test(
+      databaseSurface,
+    )
+  );
+}
+
 export async function retryOnConnectionError<T>(
   fn: () => Promise<T>,
   maxAttempts = 3,