@agent-native/core 0.108.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 {
@@ -164,6 +177,19 @@ export interface A2AApprovalExecution {
   callId: string;
 }
 
+/** One explicitly exposed read-only app action invoked without an agent loop. */
+export interface A2AReadOnlyActionInvocation {
+  action: string;
+  input: Record<string, unknown>;
+  invocationId: string;
+}
+
+export interface A2AReadOnlyActionResult {
+  action: string;
+  status: "completed" | "failed";
+  output: string;
+}
+
 export type A2AHandler = (
   message: Message,
   context: A2AHandlerContext,
@@ -171,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[];
@@ -186,4 +214,8 @@ export interface A2AConfig {
     status: "completed" | "failed";
     output: string;
   }>;
+  /** Execute an explicitly exposed read-only action without starting a model. */
+  executeReadOnlyAction?: (
+    invocation: A2AReadOnlyActionInvocation,
+  ) => Promise<Pick<A2AReadOnlyActionResult, "status" | "output">>;
 }

package/corpus/core/src/action.ts

@@ -24,8 +24,9 @@ import type { ActionAuditConfig } from "./audit/types.js";
  *   `callAction` (tagged with the `X-Request-Source` header).
  * - `"cli"` — `pnpm action <name>` (the CLI runner).
  * - `"mcp"` — an external agent over the MCP `tools/call` endpoint.
- * - `"a2a"` — a direct, scoped A2A action dispatch. Ordinary A2A agent work
- *   still runs through the agent loop and is tagged `"tool"`.
+ * - `"a2a"` — a direct, explicitly exposed read-only A2A action dispatch.
+ *   Natural-language A2A delegation still runs through the agent loop and its
+ *   selected actions are attributed as `"tool"`.
  */
 export type ActionCaller = "tool" | "http" | "frontend" | "cli" | "mcp" | "a2a";
 
@@ -96,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

@@ -8,7 +8,7 @@ import {
 } from "h3";
 import type { EventHandler as H3EventHandler } from "h3";
 
-import { isAgentActionStopError } from "../action.js";
+import { isAgentActionStopError, type ActionCaller } from "../action.js";
 import { readAppState } from "../application-state/script-helpers.js";
 import { isReadOnlyShellCommand } from "../coding-tools/index.js";
 import { extensionIdFromPathname } from "../extensions/path.js";
@@ -2479,6 +2479,11 @@ export interface ExecuteAgentToolCallOptions {
   signal?: AbortSignal;
   ownerEmail?: string | null;
   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[];
@@ -2573,6 +2578,10 @@ export async function executeAgentToolCall(
       signal,
       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,
@@ -3152,6 +3161,14 @@ export async function runAgentLoop(opts: {
   signal: AbortSignal;
   ownerEmail?: string | null;
   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
@@ -4102,6 +4119,7 @@ export async function runAgentLoop(opts: {
         requestedActionStop ??= {
           message:
             `Stopped because ${toolCall.name} failed ${count} times with the same arguments and error. ` +
+            `Last error: ${sanitizedResult} ` +
             "Fix the underlying issue or change the arguments before retrying.",
           errorCode: "repeated_identical_tool_error",
         };
@@ -4208,7 +4226,10 @@ export async function runAgentLoop(opts: {
                   await actionEntry.needsApproval(toolCall.input, {
                     userEmail: getRequestUserEmail(),
                     orgId: getRequestOrgId() ?? null,
-                    caller: "tool",
+                    caller: opts.actionCaller ?? "tool",
+                    networkProtocol: opts.networkProtocol,
+                    networkId: opts.networkId,
+                    networkPeer: opts.networkPeer,
                   }),
                 )
               : actionEntry.needsApproval === true;
@@ -4242,7 +4263,10 @@ export async function runAgentLoop(opts: {
               args: toolCall.input,
               ctx: {
                 actionName: toolCall.name,
-                caller: "tool",
+                caller: opts.actionCaller ?? "tool",
+                networkProtocol: opts.networkProtocol,
+                networkId: opts.networkId,
+                networkPeer: opts.networkPeer,
                 userEmail: getRequestUserEmail(),
                 orgId: getRequestOrgId() ?? null,
                 ...(opts.threadId ? { threadId: opts.threadId } : {}),
@@ -4638,13 +4662,17 @@ export async function runAgentLoop(opts: {
           send,
           userEmail: actionUserEmail ?? undefined,
           orgId: actionOrgId,
-          caller: "tool" as const,
+          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();
@@ -7998,6 +8026,7 @@ export function createProductionAgentHandler(
         const agentLoopOpts = {
           engine,
           model: effectiveModel,
+          runId,
           systemPrompt: requestSystemPrompt,
           tools: requestTools,
           availableTools: availableRequestTools,