@agent-native/core 0.128.4 → 0.129.1

package/src/mcp-client/oauth-client.ts

@@ -10,15 +10,17 @@
 import {
   auth,
   refreshAuthorization,
+  validateAuthorizationResponseIssuer,
+  type AuthorizationServerMetadata,
+  type OAuthClientInformationContext,
+  type OAuthClientMetadata,
   type OAuthClientProvider,
-} from "@modelcontextprotocol/sdk/client/auth.js";
-import type {
-  AuthorizationServerMetadata,
-  OAuthClientInformationMixed,
-  OAuthClientMetadata,
+  type OAuthDiscoveryState,
   OAuthProtectedResourceMetadata,
+  type StoredOAuthClientInformation,
+  type StoredOAuthTokens,
   OAuthTokens,
-} from "@modelcontextprotocol/sdk/shared/auth.js";
+} from "@modelcontextprotocol/client";
 
 import {
   deleteOAuthTokens,
@@ -131,18 +133,13 @@ function credentialOwner(options: { scope: "user" | "org"; scopeId: string }) {
   return `${options.scope}:${options.scopeId}`;
 }
 
-export interface McpOAuthDiscoveryState {
-  authorizationServerUrl: string;
-  authorizationServerMetadata?: AuthorizationServerMetadata;
-  resourceMetadata?: OAuthProtectedResourceMetadata;
-  resourceMetadataUrl?: string;
-}
+export type McpOAuthDiscoveryState = OAuthDiscoveryState;
 
 export interface McpOAuthCredentialBundle {
   serverUrl: string;
-  clientInformation: OAuthClientInformationMixed;
+  clientInformation: StoredOAuthClientInformation;
   discoveryState?: McpOAuthDiscoveryState;
-  tokens: OAuthTokens;
+  tokens: StoredOAuthTokens;
   tokenExpiresAt?: number;
 }
 
@@ -150,7 +147,7 @@ export interface McpOAuthStartResult {
   authorizationUrl: URL;
   codeVerifier: string;
   state: string;
-  clientInformation: OAuthClientInformationMixed;
+  clientInformation: StoredOAuthClientInformation;
   discoveryState?: McpOAuthDiscoveryState;
 }
 
@@ -162,11 +159,50 @@ export interface McpOAuthProviderOptions {
   serverUrl: string;
   redirectUrl: string;
   state: string;
-  clientInformation?: OAuthClientInformationMixed;
+  clientInformation?: StoredOAuthClientInformation;
   codeVerifier?: string;
   discoveryState?: McpOAuthDiscoveryState;
 }
 
+function issuerForDiscovery(
+  discovery: McpOAuthDiscoveryState | undefined,
+): string | undefined {
+  const issuer = discovery?.authorizationServerMetadata?.issuer;
+  return typeof issuer === "string" && issuer ? issuer : undefined;
+}
+
+function withIssuer<T extends { issuer?: string }>(
+  value: T,
+  context: OAuthClientInformationContext | undefined,
+): T {
+  if (value.issuer && context?.issuer && value.issuer !== context.issuer) {
+    throw new Error("MCP OAuth credential issuer does not match discovery");
+  }
+  const issuer = context?.issuer ?? value.issuer;
+  return issuer ? { ...value, issuer } : value;
+}
+
+function isBoundToIssuer(
+  value: { issuer?: string } | undefined,
+  context: OAuthClientInformationContext | undefined,
+): boolean {
+  return !context?.issuer || value?.issuer === context.issuer;
+}
+
+function applicationTypeForRedirect(redirectUrl: string): "native" | "web" {
+  const url = new URL(redirectUrl);
+  if (
+    url.protocol !== "https:" ||
+    url.hostname === "localhost" ||
+    url.hostname === "127.0.0.1" ||
+    url.hostname === "::1" ||
+    url.hostname === "[::1]"
+  ) {
+    return "native";
+  }
+  return "web";
+}
+
 /**
  * A small adapter around the MCP SDK's OAuth provider interface. The route
  * stores the adapter's state in an encrypted, short-lived browser cookie; the
@@ -176,8 +212,8 @@ export class McpOAuthClientProvider implements OAuthClientProvider {
   private readonly redirectUrlValue: string;
   private readonly stateValue: string;
   private readonly metadata: OAuthClientMetadata;
-  private clientInfo?: OAuthClientInformationMixed;
-  private savedTokens?: OAuthTokens;
+  private clientInfo?: StoredOAuthClientInformation;
+  private savedTokens?: StoredOAuthTokens;
   private savedCodeVerifier?: string;
   private savedDiscovery?: McpOAuthDiscoveryState;
   private authorizationUrl?: URL;
@@ -188,11 +224,24 @@ export class McpOAuthClientProvider implements OAuthClientProvider {
     this.clientInfo = options.clientInformation;
     this.savedCodeVerifier = options.codeVerifier;
     this.savedDiscovery = options.discoveryState;
+    const recordedIssuer = issuerForDiscovery(this.savedDiscovery);
+    if (
+      this.clientInfo &&
+      !this.clientInfo.issuer &&
+      recordedIssuer &&
+      this.savedCodeVerifier
+    ) {
+      // A callback flow persists registration, discovery, PKCE, and state in
+      // one encrypted cookie. Binding that pre-v2 in-flight registration to
+      // its recorded issuer is safe; durable credentials are never inferred.
+      this.clientInfo = { ...this.clientInfo, issuer: recordedIssuer };
+    }
     this.metadata = {
       redirect_uris: [options.redirectUrl],
       token_endpoint_auth_method: "none",
-      grant_types: ["authorization_code"],
+      grant_types: ["authorization_code", "refresh_token"],
       response_types: ["code"],
+      application_type: applicationTypeForRedirect(options.redirectUrl),
       client_name: "Agent Native MCP connector",
     };
   }
@@ -209,20 +258,34 @@ export class McpOAuthClientProvider implements OAuthClientProvider {
     return this.stateValue;
   }
 
-  clientInformation(): OAuthClientInformationMixed | undefined {
-    return this.clientInfo;
+  clientInformation(
+    context?: OAuthClientInformationContext,
+  ): StoredOAuthClientInformation | undefined {
+    return isBoundToIssuer(this.clientInfo, context)
+      ? this.clientInfo
+      : undefined;
   }
 
-  saveClientInformation(info: OAuthClientInformationMixed): void {
-    this.clientInfo = info;
+  saveClientInformation(
+    info: StoredOAuthClientInformation,
+    context?: OAuthClientInformationContext,
+  ): void {
+    this.clientInfo = withIssuer(info, context);
   }
 
-  tokens(): OAuthTokens | undefined {
-    return this.savedTokens;
+  tokens(
+    context?: OAuthClientInformationContext,
+  ): StoredOAuthTokens | undefined {
+    return isBoundToIssuer(this.savedTokens, context)
+      ? this.savedTokens
+      : undefined;
   }
 
-  saveTokens(tokens: OAuthTokens): void {
-    this.savedTokens = tokens;
+  saveTokens(
+    tokens: StoredOAuthTokens,
+    context?: OAuthClientInformationContext,
+  ): void {
+    this.savedTokens = withIssuer(tokens, context);
   }
 
   redirectToAuthorization(authorizationUrl: URL): void {
@@ -269,7 +332,7 @@ export class McpOAuthClientProvider implements OAuthClientProvider {
     return this.savedTokens;
   }
 
-  get savedClientInformation(): OAuthClientInformationMixed | undefined {
+  get savedClientInformation(): StoredOAuthClientInformation | undefined {
     return this.clientInfo;
   }
 }
@@ -301,13 +364,17 @@ export async function startMcpOAuthAuthorization(
 }
 
 export async function finishMcpOAuthAuthorization(
-  options: McpOAuthProviderOptions & { authorizationCode: string },
+  options: McpOAuthProviderOptions & {
+    authorizationCode: string;
+    iss?: string;
+  },
 ): Promise<McpOAuthCallbackResult> {
   checkedRemoteUrl(options.serverUrl, "server");
   const provider = new McpOAuthClientProvider(options);
   const result = await auth(provider, {
     serverUrl: options.serverUrl,
     authorizationCode: options.authorizationCode,
+    iss: options.iss,
     fetchFn: guardedOAuthFetch(),
   });
   if (result !== "AUTHORIZED" || !provider.savedTokensValue) {
@@ -325,6 +392,19 @@ export async function finishMcpOAuthAuthorization(
   };
 }
 
+export function validateMcpOAuthCallbackIssuer(
+  discoveryState: McpOAuthDiscoveryState | undefined,
+  iss: string | undefined,
+): void {
+  validateAuthorizationResponseIssuer({
+    iss,
+    expectedIssuer: issuerForDiscovery(discoveryState),
+    issParameterSupported:
+      discoveryState?.authorizationServerMetadata
+        ?.authorization_response_iss_parameter_supported === true,
+  });
+}
+
 export function tokenExpiresAt(tokens: OAuthTokens): number | undefined {
   const expiresIn = Number(tokens.expires_in);
   if (!Number.isFinite(expiresIn) || expiresIn <= 0) return undefined;
@@ -406,20 +486,30 @@ export async function getMcpOAuthAccessToken(options: {
   if (!credentials || credentials.serverUrl !== options.serverUrl) return null;
 
   const accessToken = credentials.tokens.access_token;
+  const now = Date.now();
   if (
     typeof credentials.tokenExpiresAt !== "number" ||
-    credentials.tokenExpiresAt - Date.now() > TOKEN_EXPIRY_SKEW_MS
+    credentials.tokenExpiresAt - now > TOKEN_EXPIRY_SKEW_MS
   ) {
     return accessToken;
   }
+  const tokenIsExpired = credentials.tokenExpiresAt <= now;
 
   const refreshToken = credentials.tokens.refresh_token;
   const discovery = credentials.discoveryState;
   if (!refreshToken || !discovery?.authorizationServerUrl) {
-    return accessToken;
+    return tokenIsExpired ? null : accessToken;
   }
 
   try {
+    const expectedIssuer = issuerForDiscovery(discovery);
+    if (
+      !expectedIssuer ||
+      credentials.clientInformation.issuer !== expectedIssuer ||
+      credentials.tokens.issuer !== expectedIssuer
+    ) {
+      return null;
+    }
     const resource = discovery.resourceMetadata?.resource
       ? checkedRemoteUrl(discovery.resourceMetadata.resource, "resource")
       : undefined;
@@ -434,9 +524,10 @@ export async function getMcpOAuthAccessToken(options: {
       resource,
       fetchFn: guardedOAuthFetch(),
     });
-    const nextTokens: OAuthTokens = {
+    const nextTokens: StoredOAuthTokens = {
       ...credentials.tokens,
       ...refreshed,
+      issuer: expectedIssuer,
       ...(refreshed.refresh_token
         ? { refresh_token: refreshed.refresh_token }
         : credentials.tokens.refresh_token
@@ -454,9 +545,9 @@ export async function getMcpOAuthAccessToken(options: {
     });
     return nextTokens.access_token;
   } catch {
-    // Keep the old token so the MCP request can return the provider's normal
-    // auth error. A single expired connector must not remove every server from
-    // the process-wide manager during a config refresh.
-    return accessToken;
+    // A still-valid token can survive a transient refresh failure. Once it has
+    // expired, omit it so callers surface reauthorization instead of retrying
+    // a credential that can never authenticate.
+    return tokenIsExpired ? null : accessToken;
   }
 }

package/src/mcp-client/oauth-routes.ts

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 
-import type { OAuthClientInformationMixed } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { StoredOAuthClientInformation } from "@modelcontextprotocol/client";
 import {
   deleteCookie,
   defineEventHandler,
@@ -23,6 +23,7 @@ import {
   finishMcpOAuthAuthorization,
   startMcpOAuthAuthorization,
   type McpOAuthDiscoveryState,
+  validateMcpOAuthCallbackIssuer,
 } from "./oauth-client.js";
 import {
   addOAuthRemoteServer,
@@ -48,7 +49,7 @@ export interface McpOAuthFlow {
   redirectUri: string;
   state: string;
   codeVerifier: string;
-  clientInformation: OAuthClientInformationMixed;
+  clientInformation: StoredOAuthClientInformation;
   discoveryState?: McpOAuthDiscoveryState;
   returnUrl?: string;
   expiresAt: number;
@@ -214,22 +215,30 @@ async function handleMcpOAuthCallback(
   const query = getQuery(event);
   const code = text(query.code);
   const state = text(query.state);
+  const iss = text(query.iss);
   const providerError = text(query.error);
   const flow = readMcpOAuthFlowCookie(event);
   clearMcpOAuthFlowCookies(event);
-  if (providerError || !code || !state) {
-    setResponseStatus(event, 400);
-    return { error: "MCP OAuth authorization was not completed." };
-  }
   const org =
     flow?.scope === "org" ? await getOrgContext(event).catch(() => null) : null;
   if (
+    !state ||
     !flow ||
     !isValidMcpOAuthFlow(flow, session.email, org?.orgId ?? undefined, state)
   ) {
     setResponseStatus(event, 400);
     return { error: "MCP OAuth state is invalid or expired." };
   }
+  try {
+    validateMcpOAuthCallbackIssuer(flow.discoveryState, iss);
+  } catch {
+    setResponseStatus(event, 400);
+    return { error: "MCP OAuth authorization response issuer is invalid." };
+  }
+  if (providerError || !code) {
+    setResponseStatus(event, 400);
+    return { error: "MCP OAuth authorization was not completed." };
+  }
   if (flow.scope === "org" && !isOrgAdmin(org?.role)) {
     setResponseStatus(event, 403);
     return {
@@ -250,6 +259,7 @@ async function handleMcpOAuthCallback(
           codeVerifier: flow.codeVerifier,
           discoveryState: flow.discoveryState,
           authorizationCode: code,
+          iss,
         }),
     );
     const result = await addOAuthRemoteServer(flow.scope, flow.scopeId, {

package/src/mcp-client/routes.ts

@@ -1055,10 +1055,8 @@ async function tryConnect(
   | { ok: false; error: string }
 > {
   try {
-    const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
-      import("@modelcontextprotocol/sdk/client/index.js"),
-      import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
-    ]);
+    const { Client, StreamableHTTPClientTransport } =
+      await import("@modelcontextprotocol/client");
     const requestInit: Record<string, unknown> = {};
     if (headers && Object.keys(headers).length > 0) {
       requestInit.headers = headers;
@@ -1068,7 +1066,10 @@ async function tryConnect(
     });
     const client = new Client(
       { name: "agent-native-mcp-client-test", version: "1.0.0" },
-      { capabilities: {} },
+      {
+        capabilities: {},
+        versionNegotiation: { mode: "auto" },
+      },
     );
     try {
       await client.connect(transport);

package/src/server/agent-capabilities.ts

@@ -1,6 +1,7 @@
 import { A2AClient } from "../a2a/client.js";
 import type { AgentCard, AgentSkill } from "../a2a/types.js";
 import { type DiscoveredAgent } from "./agent-discovery.js";
+import { getRequestUserEmail } from "./request-context.js";
 
 /** Matches the `<available-apps>` prompt block so both surfaces agree. */
 export const MAX_APPS = 30;
@@ -33,8 +34,27 @@ export async function loadCapabilities(
   agent: DiscoveredAgent,
 ): Promise<PeerCapabilities> {
   try {
+    // Discover as ourselves. An anonymous card lists only publicly-safe
+    // actions, which never overlap the set `actions/invoke` accepts, so an
+    // unauthenticated probe reports every sibling as having no callable
+    // actions and pushes the caller into open-ended delegation.
+    let token: string | undefined;
+    try {
+      const { signA2AToken } = await import("../a2a/client.js");
+      const email = getRequestUserEmail();
+      if (email) {
+        token = await signA2AToken(email, undefined, undefined, {
+          preferGlobalSecret: true,
+          audience: new URL(agent.url).origin,
+        });
+      }
+    } catch {
+      // No signable identity (no secret, no session) — fall back to the
+      // anonymous card rather than failing discovery outright.
+    }
     const card = await new A2AClient(agent.url).getAgentCard({
       timeoutMs: CARD_TIMEOUT_MS,
+      ...(token ? { token } : {}),
     });
     return {
       agent,

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

@@ -119,6 +119,33 @@ export function buildPublicAgentA2ASkills(
   );
 }
 
+/**
+ * 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.
+ */
+export function buildAuthenticatedAgentA2ASkills(
+  actions: Record<string, ActionEntry>,
+  options: Pick<AgentChatPluginOptions, "connectorCatalog" | "externalAgents">,
+): Array<{
+  id: string;
+  name: string;
+  description: string;
+  publicAgent: ActionEntry["publicAgent"];
+}> {
+  return Object.entries(filterDirectA2AActions(actions, options)).map(
+    ([name, entry]) => ({
+      id: name,
+      name,
+      description: entry.tool.description,
+      publicAgent: entry.publicAgent,
+    }),
+  );
+}
+
 export function resolveArtifactBaseUrl(
   event: any | undefined,
 ): string | undefined {

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

@@ -102,6 +102,7 @@ import type {
   MentionProvider,
 } from "../agent/types.js";
 import { readAppStateForCurrentTab } from "../application-state/script-helpers.js";
+import { runChatThreadDataMigrations } from "../chat-threads/migrations.js";
 import {
   createThread,
   forkThread,
@@ -280,6 +281,7 @@ import {
   runMCPAgentLoop,
   assembleA2AFinalResponse,
   buildPublicAgentA2ASkills,
+  buildAuthenticatedAgentA2ASkills,
   resolveArtifactBaseUrl,
 } from "./agent-chat/action-filters-a2a.js";
 import {
@@ -1318,6 +1320,10 @@ export function createAgentChatPlugin(
           : "Agent",
         description: `Agent-native ${options?.appId ?? "app"} agent`,
         skills: buildPublicAgentA2ASkills(allScripts),
+        authenticatedSkills: buildAuthenticatedAgentA2ASkills(
+          mcpFullActions ?? allScripts,
+          options ?? {},
+        ),
         publicSkillsOnly: true,
         streaming: true,
         durableBackgroundRuns: options?.durableBackgroundRuns,
@@ -5952,6 +5958,18 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
         }, 20_000); // Start 20s after init (after the agent-teams sweep)
       })();
 
+      // ─── Legacy chat-thread message_count repair ──────────────────────
+      // Long-lived processes apply this name-tracked data migration once.
+      // Serverless isolates skip it: launching a full thread_data scan from
+      // every cold start would recreate the connection stampede this repair
+      // was extracted from table bootstrap to prevent.
+      void runChatThreadDataMigrations(nitroApp).catch((err: unknown) => {
+        console.error(
+          "[chat-threads] legacy message_count repair failed — retrying on the next long-lived boot:",
+          err,
+        );
+      });
+
       // ─── Trigger Dispatcher (event-based automations) ─────────────────
       if (disableRecurringJobsRuntime) {
         if (process.env.DEBUG) {

package/src/server/transcribe-voice.ts

@@ -49,10 +49,10 @@ const GROQ_URL = "https://api.groq.com/openai/v1/audio/transcriptions";
 const GROQ_CHAT_URL = "https://api.groq.com/openai/v1/chat/completions";
 const GROQ_MODEL = "whisper-large-v3-turbo";
 const GROQ_CLEANUP_MODEL = "llama-3.3-70b-versatile";
-const OPENAI_MODEL = "whisper-1";
+const OPENAI_MODEL = "gpt-transcribe";
 const OPENAI_CHAT_URL = "https://api.openai.com/v1/chat/completions";
 const OPENAI_CLEANUP_MODEL = "gpt-5.6-luna";
-const MAX_AUDIO_BYTES = 25 * 1024 * 1024; // Whisper hard limit.
+const MAX_AUDIO_BYTES = 25 * 1024 * 1024; // OpenAI audio upload hard limit.
 // Hard cap for the dictation-cleanup text path (`sanitizeTranscriptText`
 // below). This endpoint has no `task` field — it's always the Hold-Fn
 // dictation cleanup pass — but a long session (many minutes across
@@ -497,8 +497,8 @@ export function createTranscribeVoiceHandler() {
 }
 
 /**
- * Posts the audio to a Whisper-compatible OpenAI-style endpoint (Groq or
- * OpenAI itself) and returns `{ text }` / `{ error }` shaped like the
+ * Posts the audio to an OpenAI-style transcription endpoint (Groq or OpenAI)
+ * and returns `{ text }` / `{ error }` shaped like the
  * other branches in `createTranscribeVoiceHandler`. Hoisted so the
  * strict-Groq preference path and the auto fallback chain share one
  * implementation.
@@ -538,7 +538,16 @@ async function callWhisperCompat({
   );
   form.append("model", provider.model);
   form.append("response_format", "json");
-  if (language) form.append("language", language);
+  if (language) {
+    if (provider.name === "openai") {
+      form.append(
+        "languages[]",
+        language.split("-")[0]?.toLowerCase() ?? language,
+      );
+    } else {
+      form.append("language", language);
+    }
+  }
   if (instructions) form.append("prompt", instructions);
 
   const controller = new AbortController();

package/src/templates/chat/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/src/templates/chat/README.md

@@ -30,5 +30,3 @@ pnpm dev
 ```
 
 Full docs: [agent-native.com/docs/template-chat](https://agent-native.com/docs/template-chat).
-
-<!-- vendor-branch mirror end-to-end test — safe to remove -->

package/src/templates/default/.agents/skills/security/SKILL.md

@@ -163,7 +163,9 @@ private UI after the shell loads. See the `authentication` skill and
 proves *someone* is signed in. To restrict an operation to some teammates, set
 `authorize` on the `defineAction`. It wraps `run`, so it applies at every
 dispatch site (agent tool, HTTP, frontend, MCP, A2A, CLI) — unlike
-`needsApproval`, which is honoured only in the agent loop.
+`needsApproval`, which is honored by the agent loop and MCP 2026 hosts that
+support elicitation, but is not an authorization boundary for every dispatch
+site.
 
 ```ts
 import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
@@ -203,7 +205,16 @@ export default defineAction({
 });
 ```
 
-When the gate is truthy and the call is not yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's stable `approvalKey`; only then does the action run. A predicate gates conditionally (e.g. only external recipients) and **fails closed** — a throw is treated as "approval required".
+When the gate is truthy and the call is not yet approved, the agent loop emits
+an `approval_required` event and **stops the turn — `run()` never executes**.
+The human approves via the chat UI's Approve affordance, which re-issues the
+turn with the call's stable `approvalKey`; only then does the action run. MCP
+2026 hosts receive an `input_required` approval request bound to the exact
+caller, action, and arguments. The signed response state is backed by a durable,
+single-use grant, so denial, expiry, replay, missing host support, or invalid
+state fails closed before `run()`. A predicate gates conditionally (e.g. only
+external recipients) and **fails closed** — a throw is treated as "approval
+required".
 
 Rules:
 

package/src/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -39,8 +39,11 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 Every app's `/mcp` endpoint is also a standard protected MCP
 resource. OAuth-capable hosts connect with the remote MCP URL only, receive a
 `WWW-Authenticate` challenge, discover `/.well-known/oauth-protected-resource`
-and `/.well-known/oauth-authorization-server`, dynamically register a public
-client, and complete authorization-code + PKCE at
+and `/.well-known/oauth-authorization-server`, then use a validated Client ID
+Metadata Document when the client id is an HTTPS URL or dynamically register a
+public client otherwise. URL-like client ids never fall back to dynamic
+registration when their metadata is missing or invalid. Clients complete
+authorization-code + PKCE at
 `/mcp/oauth/authorize` / `/mcp/oauth/token`.
 Access tokens are audience-bound to the exact MCP URL and carry user/org
 identity plus `mcp:read`, `mcp:write`, `mcp:apps`, and/or `offline_access`;

package/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -44,6 +44,24 @@ can still use `npx @agent-native/core connect <url>`, which mints a per-user,
 scoped, revocable token from a logged-in browser session; no shared secret is
 copied.
 
+The framework serves MCP `2026-07-28` natively over stateless, per-request HTTP
+and keeps the established stateless path for 2025-era clients. New MCP client
+code uses the split `@modelcontextprotocol/client` package with
+`versionNegotiation: { mode: "auto" }`; do not pin a protocol header or
+hand-send `initialize`. OAuth callback handlers preserve `state` and pass the
+RFC 9207 `iss` parameter to the v2 SDK for validation before exchanging a
+code. The authorization server accepts HTTPS Client ID Metadata Documents after
+strict URL, SSRF, size, redirect, schema, and exact callback validation; URL-like
+client ids never fall back to dynamic registration. Traditional non-URL clients
+continue to use public-client dynamic registration.
+
+Actions marked `needsApproval` use MCP 2026 `input_required` elicitation. The
+approval is bound to the authenticated caller, exact action, exact arguments,
+and expiry, and its durable grant is consumed atomically before the action runs.
+If the host cannot complete the approval exchange, the predicate throws, the
+state is invalid or replayed, or durable storage is unavailable, the action
+fails closed.
+
 Claude and ChatGPT can cache custom connector tool/resource metadata. After
 changing MCP App metadata or the shared `embedApp()` shell, validate with a
 fresh tool call; if the host still behaves like the old descriptor, reconnect