@agent-native/core 0.154.0 → 0.154.2

package/dist/a2a/types.d.ts

@@ -189,10 +189,10 @@ export interface A2AConfig {
     version?: string;
     skills: AgentSkill[];
     /**
-     * Skills advertised only to a caller with a verified A2A identity — the set
-     * `actions/invoke` will actually run. Anonymous card fetches never see these.
-     * Without it the card advertises the public set, which is disjoint from the
-     * invocable set, so siblings are told nothing is directly callable.
+     * Skills advertised only to a caller with a verified A2A identity. Read-only
+     * skills may also be available through `actions/invoke`; mutating skills are
+     * message-only capabilities for delegation. Anonymous card fetches never see
+     * either set.
      */
     authenticatedSkills?: AgentSkill[];
     /** If true, public agent-card discovery includes only explicit public-safe skills. */

package/dist/a2a-claims.d.ts

@@ -1,6 +1,7 @@
 export interface VerifiedA2AClaims {
     email: string;
     orgId: string;
+    orgDomain: string;
     jti: string;
     issuer?: string;
     scope: string[];

package/dist/a2a-claims.js

@@ -24,10 +24,12 @@ export async function verifyA2ATokenWithClaims(token, event) {
             ? raw.scope.split(/\s+/).filter(Boolean)
             : [];
         const issuer = typeof raw.iss === "string" ? raw.iss.trim() : "";
-        return orgId && jti
+        const orgDomain = identity.orgDomain?.trim().toLowerCase() ?? "";
+        return orgId && orgDomain && jti
             ? {
                 email: identity.email,
                 orgId,
+                orgDomain,
                 jti,
                 ...(issuer ? { issuer } : {}),
                 scope: scopes,

package/dist/client/feature-flags/FeatureFlagsPanel.js

@@ -117,9 +117,9 @@ function FeatureFlagRow({ flag, onMutate, isPending, error, }) {
     const actor = formatActor(flag.rules.updatedBy);
     const when = formatWhen(flag.rules.updatedAt);
     const metadata = [actor, when].filter(Boolean).join(" · ");
-    return (_jsxs("article", { id: `feature-flag-${flag.key}`, className: "grid gap-4 scroll-mt-24 border-b border-border py-5 last:border-b-0 md:grid-cols-[minmax(0,1fr)_auto] md:items-center", children: [_jsxs("div", { className: "min-w-0", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsx("h3", { className: "truncate text-sm font-medium text-foreground", children: flag.displayName ?? flag.key }), flag.displayName && flag.displayName !== flag.key ? (_jsx("code", { className: "truncate text-xs text-muted-foreground", children: flag.key })) : null, _jsx(Badge, { variant: flag.rules.mode === "on" ? "secondary" : "outline", className: "ms-auto shrink-0", children: modeLabel(flag.rules, t) })] }), flag.description ? (_jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: flag.description })) : null, _jsxs("div", { className: "mt-3 flex flex-wrap gap-x-3 gap-y-1 text-xs text-muted-foreground", children: [_jsxs("span", { children: [t("featureFlags.enabledFor"), ": ", audienceLabel(flag.rules, t)] }), metadata ? (_jsx("span", { children: t("featureFlags.lastChanged", { metadata }) })) : null] }), _jsx("div", { className: "mt-2 flex items-center gap-1.5 text-xs font-medium text-foreground", children: flag.enabledForCurrentUser === true ? (_jsxs(_Fragment, { children: [_jsx(IconCheck, { className: "size-4 text-emerald-500" }), t("featureFlags.youHaveAccess")] })) : flag.enabledForCurrentUser === false ? (_jsx(_Fragment, { children: t("featureFlags.youDoNotHaveAccess") })) : (_jsx(_Fragment, { children: t("featureFlags.currentUserUnknown") })) }), error ? (_jsx("p", { className: "mt-3 text-sm text-destructive", children: t("featureFlags.mutationUnverified", {
+    return (_jsxs("article", { id: `feature-flag-${flag.key}`, className: "grid gap-4 scroll-mt-24 border-b border-border py-5 last:border-b-0 lg:grid-cols-[minmax(0,1fr)_auto] lg:items-center", children: [_jsxs("div", { className: "min-w-0", children: [_jsxs("div", { className: "flex min-w-0 items-center gap-2", children: [_jsx("h3", { className: "truncate text-sm font-medium text-foreground", children: flag.displayName ?? flag.key }), flag.displayName && flag.displayName !== flag.key ? (_jsx("code", { className: "truncate text-xs text-muted-foreground", children: flag.key })) : null, _jsx(Badge, { variant: flag.rules.mode === "on" ? "secondary" : "outline", className: "ms-auto shrink-0", children: modeLabel(flag.rules, t) })] }), flag.description ? (_jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: flag.description })) : null, _jsxs("div", { className: "mt-3 flex flex-wrap gap-x-3 gap-y-1 text-xs text-muted-foreground", children: [_jsxs("span", { children: [t("featureFlags.enabledFor"), ": ", audienceLabel(flag.rules, t)] }), metadata ? (_jsx("span", { children: t("featureFlags.lastChanged", { metadata }) })) : null] }), _jsx("div", { className: "mt-2 flex items-center gap-1.5 text-xs font-medium text-foreground", children: flag.enabledForCurrentUser === true ? (_jsxs(_Fragment, { children: [_jsx(IconCheck, { className: "size-4 text-emerald-500" }), t("featureFlags.youHaveAccess")] })) : flag.enabledForCurrentUser === false ? (_jsx(_Fragment, { children: t("featureFlags.youDoNotHaveAccess") })) : (_jsx(_Fragment, { children: t("featureFlags.currentUserUnknown") })) }), error ? (_jsx("p", { className: "mt-3 text-sm text-destructive", children: t("featureFlags.mutationUnverified", {
                             name: flag.displayName ?? flag.key,
-                        }) })) : null] }), _jsxs("div", { className: "flex flex-wrap items-center gap-2 md:justify-end", children: [_jsxs(Button, { type: "button", variant: "outline", size: "sm", className: "text-xs", disabled: isPending || flag.enabledForCurrentUser === true, onClick: () => onMutate({
+                        }) })) : null] }), _jsxs("div", { className: "flex flex-wrap items-center gap-2 lg:justify-end", children: [_jsxs(Button, { type: "button", variant: "outline", size: "sm", className: "text-xs", disabled: isPending || flag.enabledForCurrentUser === true, onClick: () => onMutate({
                             key: flag.key,
                             operation: "enable-for-current-user",
                         }), children: [flag.enabledForCurrentUser === true ? (_jsx(IconCheck, {})) : (_jsx(IconUserCheck, {})), flag.enabledForCurrentUser === true

package/dist/collab/awareness.d.ts

@@ -62,11 +62,11 @@ export declare const postAwareness: import("h3").EventHandlerWithFetch<import("h
     error: string;
     states?: undefined;
 } | {
+    error?: undefined;
     states: {
         clientId: number;
         state: string;
     }[];
-    error?: undefined;
 }>>;
 /**
  * GET /_agent-native/collab/:docId/users
@@ -77,9 +77,9 @@ export declare const getActiveUsers: import("h3").EventHandlerWithFetch<import("
     error: string;
     users?: undefined;
 } | {
+    error?: undefined;
     users: {
         clientId: number;
         lastSeen: number;
     }[];
-    error?: undefined;
 }>>;

package/dist/collab/routes.d.ts

@@ -26,8 +26,8 @@ export declare const getCollabState: import("h3").EventHandlerWithFetch<import("
  * Body: { update: string (base64), requestSource?: string }
  */
 export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    error: string;
     ok?: undefined;
+    error: string;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/feature-flags/a2a-action-route.js

@@ -1,6 +1,8 @@
 import { getHeader } from "h3";
 import * as jose from "jose";
 import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
+import { resolveOrgByDomain } from "../org/context.js";
+import { consumeOneTimeJti } from "../server/identity-sso-store.js";
 const FLAG_ACTION_SCOPES = {
     "list-feature-flags": "flags:read",
     "set-feature-flag": "flags:write",
@@ -37,9 +39,16 @@ export function createFeatureFlagA2AActionRouteAuth(actionName) {
             if (!claims || !claims.scope.includes(FLAG_ACTION_SCOPES[actionName])) {
                 throw new Error("Invalid feature flag delegation");
             }
+            const localOrg = await resolveOrgByDomain(claims.orgDomain);
+            if (!localOrg)
+                throw new Error("Invalid feature flag delegation");
+            if (actionName === "set-feature-flag" &&
+                (await consumeOneTimeJti(claims.jti))) {
+                throw new Error("Invalid feature flag delegation");
+            }
             return {
                 owner: claims.email,
-                orgId: claims.orgId,
+                orgId: localOrg.orgId,
                 anonymous: false,
                 delegationJti: claims.jti,
                 delegationIssuer: claims.issuer,

package/dist/feature-flags/actions/set-feature-flag.d.ts

@@ -14,12 +14,13 @@ declare const _default: import("../../action.js").ActionDefinition<{
         percentage?: number;
     };
 }, {
-    contractVersion: 1;
+    contractVersion: 2;
     status: "ready";
     key: string;
     rules: import("../store.js").FeatureFlagRules;
     scope: {
         orgId: string;
+        orgDomain: string;
     };
 }>;
 export default _default;

package/dist/feature-flags/actions/set-feature-flag.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { defineAction } from "../../action.js";
+import { getOrgDomain } from "../../org/context.js";
 import { requireFeatureFlagManager } from "../permissions.js";
 import { getFeatureFlagDefinition } from "../registry.js";
 import { defaultFeatureFlagRules, mutateFeatureFlagRules, normalizeFeatureFlagRules, } from "../store.js";
@@ -47,6 +48,12 @@ export default defineAction({
         if (!getFeatureFlagDefinition(args.key)) {
             throw new Error(`Unknown feature flag: ${args.key}`);
         }
+        const orgDomain = manager.orgId
+            ? (await getOrgDomain(manager.orgId))?.trim().toLowerCase() || null
+            : null;
+        if (ctx?.caller === "a2a" && manager.orgId && !orgDomain) {
+            throw new Error("Feature flag organization domain is unavailable.");
+        }
         const persistedRules = await mutateFeatureFlagRules(args.key, manager, (current) => {
             let rules;
             if (args.operation === "off") {
@@ -67,11 +74,11 @@ export default defineAction({
             return { ...rules, updatedAt: Date.now(), updatedBy: manager.email };
         });
         return {
-            contractVersion: 1,
+            contractVersion: 2,
             status: "ready",
             key: args.key,
             rules: persistedRules,
-            scope: { orgId: manager.orgId },
+            scope: { orgId: manager.orgId, orgDomain },
         };
     },
 });

package/dist/mcp/org-directory.d.ts

@@ -71,11 +71,14 @@ export declare function resolveOrgDirectoryOrigin(env?: NodeJS.ProcessEnv): stri
  *
  * @param opts.selfId      Current app id (so it's stripped from the result).
  * @param opts.selfOrigin  Current app origin (so it's stripped by origin too).
+ * @param opts.includeDirectoryApp Request the directory authority itself. The
+ *   server keeps legacy self-filtering unless this explicit signal is present.
  * @param opts.env         Injectable env (tests). Defaults to `process.env`.
  */
 export declare function fetchOrgApps(opts?: {
     selfId?: string;
     selfOrigin?: string;
+    includeDirectoryApp?: boolean;
     serviceOrgId?: string;
     env?: NodeJS.ProcessEnv;
 }): Promise<OrgApp[]>;

package/dist/mcp/org-directory.js

@@ -109,18 +109,23 @@ function sameOrigin(a, b) {
         return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
     }
 }
-function scopedCacheKey(origin, auth) {
+function scopedCacheKey(origin, auth, includeDirectoryApp = false) {
     return [
         origin,
         `user:${auth.userEmail ?? ""}`,
         `org:${auth.orgId ?? auth.orgDomain ?? ""}`,
+        `include-directory:${includeDirectoryApp ? "1" : "0"}`,
     ].join("|");
 }
 function authTokenAttempts(auth) {
     return [auth.apiKey, ...(auth.apiKeyFallbacks ?? [])].filter((token) => typeof token === "string" && token.length > 0);
 }
-function serviceScopedCacheKey(origin, orgId) {
-    return [origin, `service-org:${orgId}`].join("|");
+function serviceScopedCacheKey(origin, orgId, includeDirectoryApp = false) {
+    return [
+        origin,
+        `service-org:${orgId}`,
+        `include-directory:${includeDirectoryApp ? "1" : "0"}`,
+    ].join("|");
 }
 /**
  * Fetch the org's first-party sibling apps from the org directory.
@@ -133,6 +138,8 @@ function serviceScopedCacheKey(origin, orgId) {
  *
  * @param opts.selfId      Current app id (so it's stripped from the result).
  * @param opts.selfOrigin  Current app origin (so it's stripped by origin too).
+ * @param opts.includeDirectoryApp Request the directory authority itself. The
+ *   server keeps legacy self-filtering unless this explicit signal is present.
  * @param opts.env         Injectable env (tests). Defaults to `process.env`.
  */
 export async function fetchOrgApps(opts) {
@@ -155,7 +162,7 @@ export async function fetchOrgApps(opts) {
     let ttl = EMPTY_TTL_MS;
     const serviceOrgId = opts?.serviceOrgId?.trim();
     if (serviceOrgId) {
-        const serviceCacheKey = serviceScopedCacheKey(origin, serviceOrgId);
+        const serviceCacheKey = serviceScopedCacheKey(origin, serviceOrgId, opts?.includeDirectoryApp);
         const cached = cache.get(serviceCacheKey);
         if (cached && cached.expiresAt > Date.now()) {
             return stripSelf(cached.apps);
@@ -174,7 +181,7 @@ export async function fetchOrgApps(opts) {
         }
         if (!cacheKey) {
             const now = Date.now();
-            cacheKey = scopedCacheKey(origin, auth);
+            cacheKey = scopedCacheKey(origin, auth, opts?.includeDirectoryApp);
             const cached = cache.get(cacheKey);
             if (cached && cached.expiresAt > now) {
                 return stripSelf(cached.apps);
@@ -186,6 +193,9 @@ export async function fetchOrgApps(opts) {
                 headers: {
                     Authorization: `Bearer ${attempts[i]}`,
                     Accept: "application/json",
+                    ...(opts?.includeDirectoryApp
+                        ? { "X-Agent-Native-Include-Directory-App": "1" }
+                        : {}),
                 },
                 signal: AbortSignal.timeout(4000),
             });

package/dist/notifications/routes.d.ts

@@ -28,6 +28,6 @@ export declare function createNotificationsHandler(): import("h3").EventHandlerW
 } | {
     count?: undefined;
     updated?: undefined;
-    ok: boolean;
     error?: undefined;
+    ok: boolean;
 }>>;

package/dist/observability/routes.d.ts

@@ -41,27 +41,27 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    ok?: undefined;
-    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
-} | {
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id: string;
-} | {
+    error?: undefined;
     ok?: undefined;
+} | {
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     error: any;
+    ok?: undefined;
 } | {
-    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id?: undefined;
     ok: boolean;
+    error?: undefined;
 }>>;

package/dist/provider-api/actions/custom-provider-registration.d.ts

@@ -75,8 +75,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
         user: "user";
     }>>;
 }, z.core.$strip>>, {
-    id?: undefined;
     deleted?: undefined;
+    id?: undefined;
     provider?: undefined;
     providers: {
         id: string;
@@ -93,8 +93,8 @@ export declare function createCustomProviderRegistrationAction<TSchema extends Z
     label?: undefined;
     message?: undefined;
 } | {
-    id?: undefined;
     deleted?: undefined;
+    id?: undefined;
     providers?: undefined;
     count?: undefined;
     found: boolean;

package/dist/resources/handlers.d.ts

@@ -48,8 +48,8 @@ export declare function handleUpdateResource(event: any): Promise<import("./stor
 }>;
 /** DELETE /_agent-native/resources/:id — delete a resource */
 export declare function handleDeleteResource(event: any): Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/secrets/routes.d.ts

@@ -34,16 +34,16 @@ export declare function createListSecretsHandler(): import("h3").EventHandlerWit
 /** POST /_agent-native/secrets/:key — write a secret. */
 export declare function createWriteSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: string;
-    ok?: undefined;
     status?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     status: string;
     error?: undefined;
 } | {
-    ok?: undefined;
     error: string;
     removed?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     removed: boolean;
@@ -54,9 +54,9 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
  * or the current stored value without changing anything.
  */
 export declare function createTestSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
     note?: undefined;
+    ok?: undefined;
 } | {
     ok: boolean;
     note?: undefined;

package/dist/server/action-routes.js

@@ -2,7 +2,7 @@ import { createError, defineEventHandler, setResponseStatus, setResponseHeader,
 import { verifyA2ATokenWithClaims } from "../a2a-claims.js";
 import { isAgentActionStopError } from "../action.js";
 import { declaresFeatureFlagDelegation } from "../feature-flags/a2a-action-route.js";
-import { resolveOrgIdForEmail } from "../org/context.js";
+import { resolveOrgByDomain, resolveOrgIdForEmail } from "../org/context.js";
 import { readBody } from "../server/h3-helpers.js";
 import { EMBED_TARGET_HEADER } from "../shared/embed-auth.js";
 import { isMcpEmbedCorsOrigin, MCP_EMBED_CORS_ALLOW_HEADERS, shouldAllowMcpEmbedCredentials, } from "../shared/mcp-embed-headers.js";
@@ -12,6 +12,7 @@ import { captureError } from "./capture-error.js";
 import { getAllowedCorsOrigin as resolveAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { resolveEmbedSessionFromRequest, resolvedEmbedCapabilityScope, } from "./embed-session.js";
 import { getHttpRequestTelemetryId } from "./http-response-telemetry.js";
+import { consumeOneTimeJti } from "./identity-sso-store.js";
 function requiredClientCompatibilityVersion() {
     const configured = typeof __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__ === "string"
         ? __AGENT_NATIVE_CLIENT_COMPATIBILITY_VERSION__
@@ -52,9 +53,16 @@ async function resolveFeatureFlagA2ACaller(event, actionName) {
     const claims = await verifyA2ATokenWithClaims(token, event);
     if (!claims || !claims.scope.includes(required))
         throw new Error("Invalid feature flag delegation");
+    const localOrg = await resolveOrgByDomain(claims.orgDomain);
+    if (!localOrg)
+        throw new Error("Invalid feature flag delegation");
+    if (actionName === "set-feature-flag" &&
+        (await consumeOneTimeJti(claims.jti))) {
+        throw new Error("Invalid feature flag delegation");
+    }
     return {
         owner: claims.email,
-        orgId: claims.orgId,
+        orgId: localOrg.orgId,
         anonymous: false,
         delegationJti: claims.jti,
         delegationIssuer: claims.issuer,

package/dist/server/agent-chat/action-filters-a2a.d.ts

@@ -1,4 +1,5 @@
 import { type A2AArtifactResponseOptions, type A2AToolResultSummary } from "../../a2a/artifact-response.js";
+import type { AgentSkill } from "../../a2a/types.js";
 import type { EngineTool } from "../../agent/engine/types.js";
 import { type ActionEntry, type AgentLoopOutcome } from "../../agent/production-agent.js";
 import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
@@ -44,6 +45,13 @@ export interface A2AExternalAgentSurface {
  * query the caller wrote.
  */
 export declare function filterDirectA2AActions(actions: Record<string, ActionEntry>, options: A2AExternalAgentSurface): Record<string, ActionEntry>;
+/**
+ * Authenticated write capabilities that a sibling may delegate to this app's
+ * agent, but never invoke directly. `publicAgent` is the action-owned opt-in;
+ * keeping this projection independent of `connectorCatalog` avoids making apps
+ * maintain a second capability registry. The deny list remains a final veto.
+ */
+export declare function filterDelegatedA2ACapabilityActions(actions: Record<string, ActionEntry>, options: A2AExternalAgentSurface): Record<string, ActionEntry>;
 export declare function buildPublicAgentA2ASkills(actions: Record<string, ActionEntry>): Array<{
     id: string;
     name: string;
@@ -52,20 +60,13 @@ export declare function buildPublicAgentA2ASkills(actions: Record<string, Action
     inputSchema?: Record<string, unknown>;
 }>;
 /**
- * Skills for a caller with a verified A2A identity: exactly what
- * `filterDirectA2AActions` will execute. Kept separate from
- * `buildPublicAgentA2ASkills` because the public card may only name actions
- * with `requiresAuth !== true` while direct invocation requires
- * `requiresAuth === true` — advertising the public set alone tells siblings
- * an app has nothing callable when it does.
+ * Skills for a caller with a verified A2A identity. Exact bounded reads carry
+ * schemas and may be invoked directly; explicitly exposed writes carry no
+ * schema and are discoverable only as natural-language delegation targets.
+ * Kept separate from `buildPublicAgentA2ASkills` because neither authenticated
+ * surface may be disclosed by the anonymous card.
  */
-export declare function buildAuthenticatedAgentA2ASkills(actions: Record<string, ActionEntry>, options: A2AExternalAgentSurface): Array<{
-    id: string;
-    name: string;
-    description: string;
-    publicAgent: ActionEntry["publicAgent"];
-    inputSchema?: Record<string, unknown>;
-}>;
+export declare function buildAuthenticatedAgentA2ASkills(actions: Record<string, ActionEntry>, options: A2AExternalAgentSurface): AgentSkill[];
 export declare function resolveArtifactBaseUrl(event: any | undefined): string | undefined;
 export declare function assembleA2AFinalResponse(events: readonly AgentChatEvent[], toolResults: readonly A2AToolResultSummary[], options?: A2AArtifactResponseOptions & {
     event?: any;

package/dist/server/agent-chat/action-filters-a2a.js

@@ -96,6 +96,24 @@ export function filterDirectA2AActions(actions, options) {
             exposure.isConsequential !== true);
     }));
 }
+/**
+ * Authenticated write capabilities that a sibling may delegate to this app's
+ * agent, but never invoke directly. `publicAgent` is the action-owned opt-in;
+ * keeping this projection independent of `connectorCatalog` avoids making apps
+ * maintain a second capability registry. The deny list remains a final veto.
+ */
+export function filterDelegatedA2ACapabilityActions(actions, options) {
+    const denied = new Set(options.externalAgents?.denyActions ?? []);
+    return Object.fromEntries(Object.entries(actions).filter(([name, entry]) => {
+        const exposure = entry.publicAgent;
+        return (!denied.has(name) &&
+            entry.agentTool !== false &&
+            entry.readOnly !== true &&
+            exposure?.expose === true &&
+            exposure.readOnly === false &&
+            exposure.requiresAuth === true);
+    }));
+}
 export function buildPublicAgentA2ASkills(actions) {
     return Object.entries(filterPublicAgentActions(actions)).map(([name, entry]) => ({
         id: name,
@@ -110,31 +128,49 @@ export function buildPublicAgentA2ASkills(actions) {
     }));
 }
 /**
- * Skills for a caller with a verified A2A identity: exactly what
- * `filterDirectA2AActions` will execute. Kept separate from
- * `buildPublicAgentA2ASkills` because the public card may only name actions
- * with `requiresAuth !== true` while direct invocation requires
- * `requiresAuth === true` — advertising the public set alone tells siblings
- * an app has nothing callable when it does.
+ * Skills for a caller with a verified A2A identity. Exact bounded reads carry
+ * schemas and may be invoked directly; explicitly exposed writes carry no
+ * schema and are discoverable only as natural-language delegation targets.
+ * Kept separate from `buildPublicAgentA2ASkills` because neither authenticated
+ * surface may be disclosed by the anonymous card.
  */
 export function buildAuthenticatedAgentA2ASkills(actions, options) {
-    return Object.entries(filterDirectA2AActions(actions, options)).map(([name, entry]) => ({
-        id: name,
-        name,
-        description: entry.tool.description,
-        publicAgent: entry.publicAgent,
-        // Every action in this set is read-only by construction. Omitting the
-        // flag made discovery label all of them "(mutating)", which pushes a
-        // caller away from invoking them and back into open-ended delegation.
-        readOnly: true,
-        // Naming an action without its parameters is what makes a caller invoke
-        // it with `{}` and fail on a required field.
-        ...(entry.tool.parameters
-            ? {
-                inputSchema: entry.tool.parameters,
-            }
-            : {}),
-    }));
+    const directActions = filterDirectA2AActions(actions, options);
+    const delegatedActions = filterDelegatedA2ACapabilityActions(actions, options);
+    return Object.entries(actions).flatMap(([name, entry]) => {
+        const directEntry = directActions[name];
+        const delegatedEntry = delegatedActions[name];
+        if (!directEntry && !delegatedEntry)
+            return [];
+        if (directEntry) {
+            return {
+                id: name,
+                name,
+                description: entry.tool.description,
+                publicAgent: entry.publicAgent,
+                // Every action in this set is read-only by construction. Omitting the
+                // flag made discovery label all of them "(mutating)", which pushes a
+                // caller away from invoking them and back into open-ended delegation.
+                readOnly: true,
+                // Naming a directly callable action without its parameters is what
+                // makes a caller invoke it with `{}` and fail on a required field.
+                ...(entry.tool.parameters
+                    ? {
+                        inputSchema: entry.tool.parameters,
+                    }
+                    : {}),
+            };
+        }
+        return {
+            id: name,
+            name,
+            description: entry.tool.description,
+            publicAgent: entry.publicAgent,
+            // No input schema: the sibling sends an objective to the receiving app,
+            // whose agent chooses and validates its own local actions.
+            readOnly: false,
+        };
+    });
 }
 export function resolveArtifactBaseUrl(event) {
     const fromEnv = process.env.APP_URL ||

package/dist/server/agent-discovery.d.ts

@@ -70,12 +70,16 @@ export declare function shouldIncludeRemoteAgentManifest(manifest: {
 /**
  * Get built-in agents (static, no DB). Used as fallback and for seeding.
  */
-export declare function getBuiltinAgents(selfAppId?: string): DiscoveredAgent[];
+export declare function getBuiltinAgents(selfAppId?: string, options?: {
+    preferLocalUrls?: boolean;
+}): DiscoveredAgent[];
 /**
  * Discover all agents: built-in + custom agents stored as resources.
  * Custom agents override built-in agents with the same ID.
  */
-export declare function discoverAgents(selfAppId?: string): Promise<DiscoveredAgent[]>;
+export declare function discoverAgents(selfAppId?: string, options?: {
+    preferLocalUrls?: boolean;
+}): Promise<DiscoveredAgent[]>;
 /**
  * Look up a single agent by ID or name (case-insensitive).
  */

package/dist/server/agent-discovery.js

@@ -191,13 +191,13 @@ export function shouldIncludeRemoteAgentManifest(manifest, selfAppId) {
 /**
  * Get built-in agents (static, no DB). Used as fallback and for seeding.
  */
-export function getBuiltinAgents(selfAppId) {
+export function getBuiltinAgents(selfAppId, options) {
     const normalizedSelfAppId = selfAppId ? normalizeAgentId(selfAppId) : "";
     return BUILTIN_AGENTS.filter((app) => app.id !== normalizedSelfAppId && app.url).map((app) => ({
         id: app.id,
         name: app.name,
         description: app.description,
-        url: resolveAgentUrl(app),
+        url: resolveAgentUrl(app, options?.preferLocalUrls),
         color: app.color,
     }));
 }
@@ -205,8 +205,8 @@ export function getBuiltinAgents(selfAppId) {
  * Discover all agents: built-in + custom agents stored as resources.
  * Custom agents override built-in agents with the same ID.
  */
-export async function discoverAgents(selfAppId) {
-    const builtins = getBuiltinAgents(selfAppId);
+export async function discoverAgents(selfAppId, options) {
+    const builtins = getBuiltinAgents(selfAppId, options);
     const agentsById = new Map();
     // Start with built-ins
     for (const agent of builtins) {
@@ -249,6 +249,11 @@ export async function discoverAgents(selfAppId) {
                         url = builtin.url;
                 }
                 const builtin = agentsById.get(manifestId);
+                if (options?.preferLocalUrls && builtin) {
+                    const isBuiltinAgent = BUILTIN_AGENTS.some((candidate) => candidate.id === manifestId);
+                    if (isBuiltinAgent)
+                        url = builtin.url;
+                }
                 const isLegacyAssetsManifest = manifest.id.trim().toLowerCase() !== manifestId;
                 if (isLegacyAssetsManifest && builtin?.url) {
                     try {
@@ -280,7 +285,7 @@ export async function discoverAgents(selfAppId) {
     }
     // Overlay sibling workspace apps last so same-origin workspaces prefer the
     // app mounted in this workspace over the public template with the same id.
-    for (const agent of await discoverWorkspaceAgents(selfAppId)) {
+    for (const agent of await discoverWorkspaceAgents(selfAppId, options)) {
         agentsById.set(agent.id, agent);
     }
     return Array.from(agentsById.values());
@@ -347,8 +352,8 @@ function isHostedRuntime() {
 function shouldUseLocalAgentUrls() {
     return !isHostedRuntime();
 }
-function resolveAgentUrl(app) {
-    if (shouldUseLocalAgentUrls()) {
+function resolveAgentUrl(app, preferLocalUrls = false) {
+    if (preferLocalUrls || shouldUseLocalAgentUrls()) {
         return app.devUrl || `http://localhost:${app.devPort}`;
     }
     return app.url;
@@ -527,7 +532,7 @@ function workspaceAppUrl(app, hostedLoopbackFallbackUrl) {
         return null;
     }
 }
-async function discoverWorkspaceAgents(selfAppId) {
+async function discoverWorkspaceAgents(selfAppId, options) {
     const workspaceApps = loadWorkspaceAppsManifest();
     if (!workspaceApps)
         return [];
@@ -537,7 +542,9 @@ async function discoverWorkspaceAgents(selfAppId) {
         .map((app) => {
         const withOverride = applyWorkspaceAppMetadataOverride(app, metadataSettings);
         const builtin = BUILTIN_AGENTS.find((agent) => agent.id === withOverride.id);
-        const url = workspaceAppUrl(withOverride, builtin?.url);
+        const url = options?.preferLocalUrls && builtin
+            ? resolveAgentUrl(builtin, true)
+            : workspaceAppUrl(withOverride, builtin?.url);
         if (!url)
             return null;
         return {