@agent-native/core 0.107.2 → 0.109.0

package/corpus/core/src/scripts/call-agent.ts

@@ -6,6 +6,7 @@ import {
   shouldPreferGlobalA2ASecret,
   signA2AToken,
 } from "../a2a/client.js";
+import { invokeAgentAction } from "../a2a/invoke.js";
 import type { A2AApprovedAction, Task } from "../a2a/types.js";
 import {
   formatLlmCredentialErrorMessage,
@@ -94,12 +95,13 @@ function formatDownstreamLlmCredentialFailure(
 
 export const tool: ActionTool = {
   description:
-    "Call a DIFFERENT, separately-deployed agent app to ask a question or delegate a task. This is strictly for cross-app A2A communication — for example, asking the mail agent to send an email while you are the calendar agent. NEVER use this to call your own app or perform actions you can do with your own tools. Using call-agent on yourself will fail and waste time. " +
+    "Call a DIFFERENT, separately-deployed app over A2A. When you know the exact exposed read-only action, pass action + input and omit message; this invokes it directly without starting the other app's model and is the fastest path for bounded data reads. Use message only for natural-language investigation, synthesis, mutations, or multi-step work that needs the other agent. NEVER use this to call your own app or perform actions you can do with your own tools. Using call-agent on yourself will fail and waste time. " +
     'For brand-consistent generated media, the first-party Assets agent is available as agent="assets"; use it when another app needs generated heroes, diagrams, product shots, thumbnails, videos, or design imagery, unless the current app has its own generation action that already delegates there. ' +
     "IMPORTANT — handling the response: " +
     "(a) If it contains a URL or ID, copy it VERBATIM into your reply. Do not 'correct' or pluralize the path (e.g. /deck/ → /decks/), normalize casing, or change the slug — any edit breaks the link. " +
     '(b) If it does NOT contain a URL/ID and the user asked for one, say so explicitly (e.g. "the agent created the deck/image but didn\'t return a link — open the app directly to view it"). NEVER invent a URL, slug, or path — guessing produces broken links that look real. ' +
-    "(c) If the downstream response reports missing credentials, never repeat raw env var names, Vault key names, token names, secret names, or other credential identifiers. Tell the user the target app needs its LLM/provider connection configured.",
+    "(c) If the downstream response reports missing credentials, never repeat raw env var names, Vault key names, token names, secret names, or other credential identifiers. Tell the user the target app needs its LLM/provider connection configured. " +
+    "(d) A bounded wait can expire while the remote task is still healthy. The result will include its taskId and exact retry instructions. Continue polling that SAME task with taskId; NEVER send a new check-in/follow-up message, because that starts duplicate downstream work.",
   parameters: {
     type: "object",
     properties: {
@@ -110,7 +112,24 @@ export const tool: ActionTool = {
       },
       message: {
         type: "string",
-        description: "The message/question to send to the other agent",
+        description:
+          "The message/question to send when starting a new task. Omit when taskId is provided.",
+      },
+      taskId: {
+        type: "string",
+        description:
+          "Existing A2A task ID returned by a timed-out call. Polls that exact task without sending a new message. Never create a fresh check-in message for work that already has a taskId.",
+      },
+      action: {
+        type: "string",
+        description:
+          "Exact read-only action exposed by the target app. Use with input and omit message/taskId to skip the downstream agent loop.",
+      },
+      input: {
+        type: "object",
+        description:
+          "Complete input object for action. The target app validates it and refuses actions that are not explicitly exposed read-only operations.",
+        additionalProperties: true,
       },
       approvedActions: {
         type: "array",
@@ -126,7 +145,7 @@ export const tool: ActionTool = {
         },
       },
     },
-    required: ["agent", "message"],
+    required: ["agent"],
   },
 };
 
@@ -137,12 +156,23 @@ export async function run(
 ): Promise<string> {
   const agentIdOrName = String(args.agent ?? "");
   const message = String(args.message ?? "");
+  const taskId = String(args.taskId ?? "").trim();
+  const action = String(args.action ?? "").trim();
+  const input = args.input ?? {};
   const approvedActions = Array.isArray(args.approvedActions)
     ? (args.approvedActions as A2AApprovedAction[])
     : undefined;
 
   if (!agentIdOrName) return "Error: --agent is required";
-  if (!message) return "Error: --message is required";
+  if (!message && !taskId && !action) {
+    return "Error: --message, --taskId, or --action is required";
+  }
+  if (action && (message || taskId)) {
+    return "Error: --action direct-invoke mode cannot be combined with --message or --taskId";
+  }
+  if (action && (!input || typeof input !== "object" || Array.isArray(input))) {
+    return "Error: --input must be an object when --action is provided";
+  }
 
   // Prevent self-calls — the agent must use its own registered tools instead
   if (selfAppId && agentIdOrName.toLowerCase() === selfAppId.toLowerCase()) {
@@ -157,16 +187,36 @@ export async function run(
     return `Error: Agent "${agentIdOrName}" not found. Available agents: ${available || "(none)"}`;
   }
 
+  if (action) {
+    if (context?.send) {
+      context.send({ type: "agent_call", agent: agent.name, status: "start" });
+    }
+    try {
+      const output = await invokeReadOnlyAppAction(
+        agent,
+        action,
+        input as Record<string, unknown>,
+      );
+      return output;
+    } finally {
+      if (context?.send) {
+        context.send({ type: "agent_call", agent: agent.name, status: "done" });
+      }
+    }
+  }
+
   // Append a small cross-app hint to the outgoing message so the receiving
   // agent (which may be on an older deploy without the receiver-side hint
   // in handlers.ts) still emits fully-qualified URLs. This is belt-and-
   // suspenders with the receiver hint — but it works against any current
   // deployment, no redeploy required.
-  const messageWithHint =
-    `${message}${integrationSourceContextHint()}\n\n` +
-    `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
-    `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
-    `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts.]`;
+  const messageWithHint = taskId
+    ? ""
+    : `${message}${integrationSourceContextHint()}\n\n` +
+      `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
+      `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
+      `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts. ` +
+      `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.]`;
 
   try {
     // If we have a send context, use streaming so the UI shows progressive text
@@ -228,8 +278,9 @@ export async function run(
 
       let responseText = "";
       let lastSentLength = 0;
-      const existingContinuationText =
-        await formatExistingIntegrationContinuationIfRetry(agent, message);
+      const existingContinuationText = taskId
+        ? null
+        : await formatExistingIntegrationContinuationIfRetry(agent, message);
       if (existingContinuationText) return existingContinuationText;
 
       context.send({
@@ -338,13 +389,12 @@ export async function run(
           orgDomain: callerOrgDomain,
           orgSecret: callerOrgSecret,
           approvedActions,
+          ...(taskId ? { taskId } : {}),
           onUpdate: onRemotePollUpdate,
+          returnRecoverableArtifactsOnTimeout: false,
           ...(callTimeoutMs
             ? {
                 timeoutMs: callTimeoutMs,
-                // Integration callers must keep the timeout task id so the
-                // catch below can enqueue durable continuation polling.
-                returnRecoverableArtifactsOnTimeout: false,
               }
             : {}),
         });
@@ -387,8 +437,11 @@ export async function run(
                 agent.url,
               );
             } else {
-              const reason = pollErr?.message ?? "unknown error";
-              responseText = `The ${agent.name} agent is taking longer than expected and didn't reply in time. (${reason})`;
+              responseText = formatExistingTaskWaitInstruction(
+                agent.name,
+                timeoutTaskId,
+                agentIdOrName,
+              );
             }
           }
         } else {
@@ -427,6 +480,8 @@ export async function run(
       orgDomain: domain,
       orgSecret,
       approvedActions,
+      ...(taskId ? { taskId } : {}),
+      returnRecoverableArtifactsOnTimeout: false,
     });
     const sanitized =
       formatDownstreamLlmCredentialFailure(agent.name, response) ?? response;
@@ -438,6 +493,14 @@ export async function run(
       err,
     );
     if (credentialMessage) return credentialMessage;
+    const timeoutTaskId = getA2ATaskTimeoutTaskId(err);
+    if (timeoutTaskId) {
+      return formatExistingTaskWaitInstruction(
+        agent.name,
+        timeoutTaskId,
+        agentIdOrName,
+      );
+    }
     // Friendlier message for the common timeout case so the calling agent can
     // decide whether to give up or retry.
     if (/timeout|did not complete|Inactivity|504/i.test(msg)) {
@@ -447,6 +510,63 @@ export async function run(
   }
 }
 
+async function invokeReadOnlyAppAction(
+  agent: { name: string; url: string },
+  action: string,
+  input: Record<string, unknown>,
+): Promise<string> {
+  const callerEmail = getRequestUserEmail();
+  if (!callerEmail) {
+    return `Error calling ${agent.name} action ${action}: a signed-in user identity is required`;
+  }
+
+  let callerOrgDomain: string | undefined;
+  let callerOrgSecret: string | undefined;
+  const orgId = getRequestOrgId();
+  if (orgId) {
+    try {
+      callerOrgDomain = (await getOrgDomain(orgId)) ?? undefined;
+    } catch {}
+    try {
+      callerOrgSecret = (await getOrgA2ASecret(orgId)) ?? undefined;
+    } catch {}
+  }
+
+  if (!callerOrgSecret && !process.env.A2A_SECRET) {
+    return `Error calling ${agent.name} action ${action}: direct cross-app reads require A2A identity verification`;
+  }
+
+  try {
+    const invocation = await invokeAgentAction({
+      target: agent.url,
+      action,
+      input,
+      userEmail: callerEmail,
+      orgDomain: callerOrgDomain,
+      orgSecret: callerOrgSecret,
+    });
+    return invocation.result.status === "completed"
+      ? invocation.result.output
+      : `Error calling ${agent.name} action ${action}: ${invocation.result.output}`;
+  } catch (error) {
+    return `Error calling ${agent.name} action ${action}: ${
+      error instanceof Error ? error.message : String(error)
+    }`;
+  }
+}
+
+function formatExistingTaskWaitInstruction(
+  agentName: string,
+  taskId: string,
+  agentIdOrName: string,
+): string {
+  return (
+    `The ${agentName} task is still running under taskId "${taskId}". ` +
+    `Do not send ${agentName} a new check-in or follow-up message; that would start duplicate work. ` +
+    `Call call-agent again with agent="${agentIdOrName}" and taskId="${taskId}" (omit message) to continue waiting for this same task.`
+  );
+}
+
 async function enqueueIntegrationContinuationIfPossible(
   taskId: string,
   agent: { name: string; url: string },

package/corpus/core/src/server/action-discovery.ts

@@ -595,6 +595,18 @@ export async function mergeCoreSharingActions(
       () => import("../sharing/actions/create-agent-resource-link.js"),
     ],
     ["upload-image", () => import("../file-upload/actions/upload-image.js")],
+    [
+      "get-feature-flags",
+      () => import("../feature-flags/actions/get-feature-flags.js"),
+    ],
+    [
+      "list-feature-flags",
+      () => import("../feature-flags/actions/list-feature-flags.js"),
+    ],
+    [
+      "set-feature-flag",
+      () => import("../feature-flags/actions/set-feature-flag.js"),
+    ],
     // Agent Jobs page — UI-only scoped reads and mutations for resource-backed
     // recurring jobs and personal automations. The agent-facing native tools
     // remain the canonical conversational surface.

package/corpus/core/src/server/action-routes.ts

@@ -9,8 +9,10 @@ import {
   getRequestURL,
 } from "h3";
 
+import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
 import { isAgentActionStopError } from "../action.js";
 import type { ActionEntry } from "../agent/production-agent.js";
+import { declaresFeatureFlagDelegation } from "../feature-flags/a2a-action-route.js";
 import { resolveOrgIdForEmail } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
@@ -39,6 +41,30 @@ import { runWithRequestContext } from "./request-context.js";
 
 const ROUTE_PREFIX = "/_agent-native/actions";
 
+async function resolveFeatureFlagA2ACaller(event: any, actionName: string) {
+  const required =
+    actionName === "list-feature-flags"
+      ? "flags:read"
+      : actionName === "set-feature-flag"
+        ? "flags:write"
+        : null;
+  if (!required) return null;
+  const authorization = getHeader(event, "authorization");
+  if (!authorization?.startsWith("Bearer ")) return null;
+  const token = authorization.slice(7);
+  if (!declaresFeatureFlagDelegation(token)) return null;
+  const claims = await verifyA2ATokenWithClaims(token, event);
+  if (!claims || !claims.scope.includes(required))
+    throw new Error("Invalid feature flag delegation");
+  return {
+    owner: claims.email,
+    orgId: claims.orgId,
+    anonymous: false,
+    delegationJti: claims.jti,
+    delegationIssuer: claims.issuer,
+  } as ActionRouteResolvedCaller;
+}
+
 export function parseActionSearchParams(
   searchParams: URLSearchParams,
 ): Record<string, any> {
@@ -189,6 +215,9 @@ export type ActionRouteResolvedCaller = AgentRunOwnerContext & {
    * must not leak into the token caller's request context.
    */
   orgId?: string;
+  /** Verified A2A correlation and issuer metadata for the audit row. */
+  delegationJti?: string;
+  delegationIssuer?: string;
 };
 
 export interface ActionRouteAuthAdapter {
@@ -336,10 +365,14 @@ export function mountActionRoutes(
         // through, so a live same-origin session cookie can't silently execute
         // the request as the logged-in user.
         let resolvedCaller: ActionRouteResolvedCaller | null = null;
-        if (options?.actionRouteAuth?.resolveCaller) {
+        {
           let caller: ActionRouteResolvedCaller | null;
           try {
-            caller = await options.actionRouteAuth.resolveCaller(event);
+            caller = options?.actionRouteAuth?.resolveCaller
+              ? await options.actionRouteAuth.resolveCaller(event)
+              : null;
+            if (!caller)
+              caller = await resolveFeatureFlagA2ACaller(event, name);
           } catch {
             throw createError({
               statusCode: 401,
@@ -463,14 +496,23 @@ export function mountActionRoutes(
             // userEmail / orgId mirror the request context resolved above (do
             // NOT inject a dev identity — leave undefined when unauthenticated).
             try {
-              const caller = isFrontendActionRequest(event)
-                ? "frontend"
-                : "http";
+              const caller = resolvedCaller
+                ? "a2a"
+                : isFrontendActionRequest(event)
+                  ? "frontend"
+                  : "http";
               const result = await entry.run(params, {
                 userEmail,
                 orgId: orgId ?? null,
                 caller,
                 actionName: name,
+                ...(resolvedCaller?.delegationJti
+                  ? {
+                      networkProtocol: "a2a",
+                      networkId: resolvedCaller.delegationJti,
+                      networkPeer: resolvedCaller.delegationIssuer,
+                    }
+                  : {}),
               });
 
               // Auto-refresh the UI after a successful mutating action. GET

package/corpus/core/src/server/agent-chat/action-filters-a2a.ts

@@ -15,6 +15,10 @@ import {
 } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
 import type { AgentChatEvent } from "../../agent/types.js";
+import {
+  isAuthenticatedReadAction,
+  isAutoReadExcludedActionName,
+} from "../../mcp/build-server.js";
 import { withConfiguredAppBasePath } from "../app-base-path.js";
 import type { AgentChatPluginOptions } from "./plugin-options.js";
 
@@ -61,6 +65,42 @@ export function filterPublicAgentActions(
   );
 }
 
+/**
+ * Direct A2A action calls share the authenticated external-agent policy with
+ * MCP, but remain stricter: only explicitly exposed, authenticated read-only
+ * actions can skip the receiver's model loop.
+ */
+export function filterDirectA2AActions(
+  actions: Record<string, ActionEntry>,
+  options: Pick<AgentChatPluginOptions, "connectorCatalog" | "externalAgents">,
+): Record<string, ActionEntry> {
+  const catalog = new Set(options.connectorCatalog ?? []);
+  const denied = new Set(options.externalAgents?.denyActions ?? []);
+  const autoReads = options.externalAgents?.authenticatedReads === "auto";
+
+  return Object.fromEntries(
+    Object.entries(actions).filter(([name, entry]) => {
+      const exposure = entry.publicAgent;
+      const selected =
+        catalog.has(name) ||
+        (autoReads &&
+          isAuthenticatedReadAction(entry) &&
+          !isAutoReadExcludedActionName(name));
+      return (
+        selected &&
+        !denied.has(name) &&
+        entry.agentTool !== false &&
+        entry.readOnly === true &&
+        exposure?.expose === true &&
+        exposure.readOnly === true &&
+        exposure.requiresAuth === true &&
+        (entry.needsApproval === undefined || entry.needsApproval === false) &&
+        exposure.isConsequential !== true
+      );
+    }),
+  );
+}
+
 export function buildPublicAgentA2ASkills(
   actions: Record<string, ActionEntry>,
 ): Array<{

package/corpus/core/src/server/agent-chat-plugin.ts

@@ -210,6 +210,7 @@ import {
   createA2AEngineToolSurface,
   filterAgentTools,
   filterPublicAgentActions,
+  filterDirectA2AActions,
   filterReadOnlyActions,
   resolveInitialToolNames,
   runA2AAgentLoop,
@@ -1216,6 +1217,36 @@ export function createAgentChatPlugin(
         publicSkillsOnly: true,
         streaming: true,
         durableBackgroundRuns: options?.durableBackgroundRuns,
+        executeReadOnlyAction: async ({ action, input }) => {
+          const actions = filterDirectA2AActions(
+            mcpFullActions ?? allScripts,
+            options ?? {},
+          );
+          const entry = actions[action];
+          if (!entry) {
+            return {
+              status: "failed" as const,
+              output: "Unknown or unavailable read-only action",
+            };
+          }
+
+          const result = await executeAgentToolCall({
+            actions: { [action]: entry },
+            name: action,
+            input,
+            callId: `a2a-action-${crypto.randomUUID()}`,
+            ownerEmail: getRequestUserEmail(),
+            orgId: getRequestOrgId() ?? null,
+            caller: "a2a",
+          });
+          if (result.status === "approval_required") {
+            return {
+              status: "failed" as const,
+              output: "Read-only action unexpectedly requires approval",
+            };
+          }
+          return { status: result.status, output: result.output };
+        },
         executeApproval: async (approval) => {
           const result = await executeAgentToolCall({
             actions: mcpFullActions ?? allScripts,

package/corpus/core/src/server/index.ts

@@ -180,6 +180,7 @@ export { createSentryPlugin, defaultSentryPlugin } from "./sentry-plugin.js";
 // (which references "defaultOrgPlugin" from @agent-native/core/server) can
 // resolve it during the deploy build worker-entry generation.
 export { createOrgPlugin, defaultOrgPlugin } from "../org/plugin.js";
+export { createFeatureFlagsPlugin } from "../feature-flags/plugin.js";
 export {
   createContextXrayPlugin,
   defaultContextXrayPlugin,

package/corpus/core/src/settings/org-settings.ts

@@ -10,6 +10,7 @@
 
 import {
   getSetting,
+  mutateSetting,
   putSetting,
   deleteSetting,
   getAllSettings,
@@ -40,6 +41,18 @@ export async function putOrgSetting(
   return putSetting(orgKey(orgId, key), value, options);
 }
 
+/** Atomically derive and persist an org-scoped setting. */
+export async function mutateOrgSetting(
+  orgId: string,
+  key: string,
+  updater: (
+    current: Record<string, unknown> | null,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  options?: StoreWriteOptions,
+): Promise<Record<string, unknown>> {
+  return mutateSetting(orgKey(orgId, key), updater, options);
+}
+
 /** Delete an org-scoped setting. */
 export async function deleteOrgSetting(
   orgId: string,

package/corpus/core/src/settings/store.ts

@@ -128,6 +128,63 @@ export interface StoreWriteOptions {
   requestSource?: string;
 }
 
+const SETTINGS_MUTATION_ATTEMPTS = 25;
+
+/**
+ * Atomically derive and persist one setting with an optimistic raw-value CAS.
+ * This works across SQLite/libSQL and Postgres and remains safe across
+ * horizontally scaled processes where an in-memory mutex would not.
+ * The updater may run more than once after contention and must not perform
+ * external side effects.
+ */
+export async function mutateSetting(
+  key: string,
+  updater: (
+    current: Record<string, unknown> | null,
+  ) => Record<string, unknown> | Promise<Record<string, unknown>>,
+  options?: StoreWriteOptions,
+): Promise<Record<string, unknown>> {
+  await ensureTable();
+  const client = getDbExec();
+  const table = settingsTable();
+  for (let attempt = 0; attempt < SETTINGS_MUTATION_ATTEMPTS; attempt += 1) {
+    // Deliberately bypass the request cache: a failed CAS means another
+    // request committed a newer value and the next attempt must reread it.
+    const snapshot = await client.execute({
+      sql: `SELECT value FROM ${table} WHERE key = ?`,
+      args: [key],
+    });
+    const raw =
+      snapshot.rows.length === 0 ? null : (snapshot.rows[0]?.value as string);
+    const current = raw == null ? null : JSON.parse(raw);
+    const next = await updater(current);
+    const nextRaw = JSON.stringify(next);
+    const timestamp = Date.now();
+    const result =
+      raw == null
+        ? await client.execute({
+            sql: isPostgres()
+              ? `INSERT INTO ${table} (key, value, updated_at) VALUES (?, ?, ?) ON CONFLICT (key) DO NOTHING`
+              : `INSERT OR IGNORE INTO ${table} (key, value, updated_at) VALUES (?, ?, ?)`,
+            args: [key, nextRaw, timestamp],
+          })
+        : await client.execute({
+            sql: `UPDATE ${table} SET value = ?, updated_at = ? WHERE key = ? AND value = ?`,
+            args: [nextRaw, timestamp, key, raw],
+          });
+    if (result.rowsAffected === 0) continue;
+    requestSettingsCache()?.set(key, nextRaw);
+    _emitter.emit("settings", {
+      source: "settings",
+      type: "change",
+      key,
+      ...(options?.requestSource && { requestSource: options.requestSource }),
+    });
+    return JSON.parse(nextRaw);
+  }
+  throw new Error(`Setting ${key} changed too many times; retry the mutation.`);
+}
+
 export async function putSetting(
   key: string,
   value: Record<string, unknown>,

package/corpus/core/src/styles/agent-conversation.css

@@ -502,6 +502,13 @@
     opacity 150ms ease-out;
 }
 
+@starting-style {
+  .agent-chat-collapse[data-state="open"] {
+    grid-template-rows: 0fr;
+    opacity: 0;
+  }
+}
+
 .agent-chat-collapse[data-state="closed"] {
   grid-template-rows: 0fr;
   opacity: 0;