@agent-native/core 0.109.0 → 0.109.2

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 };

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;
 }