@agent-native/core 0.205.0 → 0.206.0-nightly-20261009011246

package/dist/mcp/connect-route.js

@@ -1,6 +1,5 @@
 import { randomUUID } from "node:crypto";
 import { getMethod, getHeader } from "h3";
-import { signA2AToken } from "../a2a/client.js";
 import { getAppConfig } from "../app-config/index.js";
 import { mcpSettingsMessagesForLocale } from "../localization/mcp-settings-messages.js";
 import { resolveLocaleFromRequest } from "../localization/server.js";
@@ -13,8 +12,9 @@ import { publicFrameworkPath } from "../server/framework-route-prefix.js";
 import { readBody } from "../server/h3-helpers.js";
 import { FRAMEWORK_INTERNAL_ROUTE_PREFIX } from "../shared/framework-route-prefix.js";
 import { MCP_CONNECT_MCP_URL_TEMPLATE, getMcpConnectGuides, getMcpStaticTokenFallback, interpolateMcpConnectTemplate, resolveMcpConnectGuideId, } from "../shared/mcp-connect-content.js";
-import { ensureConnectTables, recordMintedToken, listTokens, revokeToken, normalizeServiceName, serviceIdentityEmail, createDeviceCode, getDeviceCode, getDeviceCodeByUserCode, approveDeviceCode, consumeDeviceCode, claimDeviceCodeForMint, finishDeviceCodeMint, expireDeviceCode, MCP_CONNECT_OAUTH_CLIENT_ID, MCP_CONNECT_SCOPE, DEFAULT_TOKEN_TTL_DAYS, MIN_TOKEN_TTL_DAYS, MAX_TOKEN_TTL_DAYS, MAX_SERVICE_TOKEN_TTL_DAYS, DEVICE_CODE_TTL_MS, } from "./connect-store.js";
+import { ensureConnectTables, recordMintedToken, listTokens, revokeToken, normalizeServiceName, serviceIdentityEmail, createDeviceCode, getDeviceCode, getDeviceCodeByUserCode, approveDeviceCode, consumeDeviceCode, claimDeviceCodeForMint, finishDeviceCodeMint, expireDeviceCode, MCP_CONNECT_OAUTH_CLIENT_ID, DEFAULT_TOKEN_TTL_DAYS, MIN_TOKEN_TTL_DAYS, MAX_TOKEN_TTL_DAYS, MAX_SERVICE_TOKEN_TTL_DAYS, DEVICE_CODE_TTL_MS, } from "./connect-store.js";
 import { McpCredentialIssuanceError, withMcpCredentialIssuance, } from "./credential-issuance.js";
+import { getMcpOAuthIssuer, resolveMcpOAuthIssuer } from "./oauth-route.js";
 import { MCP_OAUTH_DEFAULT_SCOPE, signMcpOAuthAccessToken, } from "./oauth-token.js";
 import { resolveMcpOrgChoices } from "./org-choice.js";
 import { MCP_PUBLIC_ROUTE_PREFIX } from "./route-paths.js";
@@ -157,7 +157,7 @@ async function mintConnectToken(params) {
             ownerEmail: params.email,
             orgId: params.orgId,
             orgDomain,
-            appUrl: params.appUrl,
+            issuer: params.issuer,
             expiresIn: `${params.ttlDays}d`,
             jti,
             ...(params.catalogScope === "full" ? { catalogScope: "full" } : {}),
@@ -171,34 +171,38 @@ async function mintConnectToken(params) {
         return { token, jti };
     });
 }
+/**
+ * Connect tokens are MCP OAuth access tokens bound to this app's MCP URL, so
+ * they share OAuth's verification path. Do not sign them as A2A JWTs again:
+ * that format let cross-app trust rules reinterpret a credential this app
+ * issued.
+ */
 async function signConnectToken(params) {
-    if (readDeployCredentialEnv("A2A_SECRET")?.trim()) {
-        return signA2AToken(params.ownerEmail, params.orgDomain, undefined, {
-            preferGlobalSecret: true,
-            expiresIn: params.expiresIn,
-            extraClaims: {
-                jti: params.jti,
-                scope: MCP_CONNECT_SCOPE,
-                ...(params.includeOrgIdClaim && params.orgId
-                    ? { org_id: params.orgId }
-                    : {}),
-                ...(params.catalogScope === "full" ? { catalog_scope: "full" } : {}),
-            },
-        });
-    }
     return signMcpOAuthAccessToken({
         ownerEmail: params.ownerEmail,
         orgId: params.orgId ?? null,
         orgDomain: params.orgDomain ?? null,
         clientId: MCP_CONNECT_OAUTH_CLIENT_ID,
         scope: MCP_OAUTH_DEFAULT_SCOPE,
-        resource: mcpResourceUrl(params.appUrl),
-        issuer: params.appUrl,
+        resource: mcpResourceUrl(params.issuer),
+        issuer: params.issuer,
         jti: params.jti,
         expiresIn: params.expiresIn,
         ...(params.catalogScope === "full" ? { catalogScope: "full" } : {}),
+        ...(params.service ? { service: true } : {}),
     });
 }
+/**
+ * Neither the request nor configuration names this app's public URL, so no
+ * audience `verifyAuth` would accept can be resolved. Guessing one would mint a
+ * token the app then refuses.
+ */
+export class OrgServiceTokenAppUrlError extends Error {
+    constructor() {
+        super("Could not determine the app URL needed to mint a token. Set APP_URL on the deployment.");
+        this.name = "OrgServiceTokenAppUrlError";
+    }
+}
 /**
  * Mint an ORG SERVICE token: a connect-scoped, revocable bearer whose subject
  * is the synthetic service identity `svc-<name>@service.<orgId>` instead of a
@@ -209,7 +213,7 @@ async function signConnectToken(params) {
  *
  * The token value is returned exactly once and never persisted — only the
  * random `jti` is stored, so the standard revocation path
- * (`isJtiRevoked` in `verifyAuth`) applies to service tokens identically.
+ * (`lookupConnectTokenOrg` in `verifyAuth`) applies to service tokens identically.
  *
  * The `create-org-service-token` action gates on org owner/admin before
  * calling this. Offboarding can remove that admin before the mint, so the
@@ -221,6 +225,9 @@ export async function mintOrgServiceToken(params) {
     const serviceEmail = serviceIdentityEmail(serviceName, params.orgId);
     const orgDomain = await resolveOrgDomain(params.orgId);
     const ttlDays = clampTtlDays(params.ttlDays ?? DEFAULT_TOKEN_TTL_DAYS, MAX_SERVICE_TOKEN_TTL_DAYS);
+    const issuer = resolveMcpOAuthIssuer(params.appUrl || undefined);
+    if (!issuer)
+        throw new OrgServiceTokenAppUrlError();
     await prepareConnectIssuance();
     return withMcpCredentialIssuance({
         email: params.createdBy,
@@ -233,10 +240,10 @@ export async function mintOrgServiceToken(params) {
             ownerEmail: serviceEmail,
             orgId: params.orgId,
             orgDomain,
-            appUrl: params.appUrl,
+            issuer,
             expiresIn: `${ttlDays}d`,
             jti,
-            includeOrgIdClaim: true,
+            service: true,
         });
         const id = await recordMintedToken({
             jti,
@@ -1205,6 +1212,9 @@ export async function handleMcpConnect(event, subpath, options = {}) {
     const origin = deriveOrigin(event);
     const basePath = configuredBasePath();
     const appUrl = `${origin}${basePath}`;
+    // Tokens bind to an audience verifyAuth accepts. Reached through an alias of
+    // a configured public URL, that differs from the appUrl this page displays.
+    const tokenIssuer = getMcpOAuthIssuer(event) ?? appUrl;
     let requestUrl = null;
     try {
         requestUrl = new URL(event.node?.req?.url ?? event.path ?? "/", "http://an.invalid");
@@ -1295,7 +1305,7 @@ export async function handleMcpConnect(event, subpath, options = {}) {
                 orgId: defaultOrganizationId,
                 label,
                 ttlDays,
-                appUrl,
+                issuer: tokenIssuer,
                 requestOrigin: origin,
                 ...(catalogScope ? { catalogScope } : {}),
             });
@@ -1451,7 +1461,7 @@ export async function handleMcpConnect(event, subpath, options = {}) {
                     ownerEmail: claimed.ownerEmail,
                     orgId: claimed.orgId,
                     orgDomain,
-                    appUrl,
+                    issuer: tokenIssuer,
                     expiresIn: `${DEFAULT_TOKEN_TTL_DAYS}d`,
                     jti,
                     ...(claimed.catalogScope

package/dist/mcp/connect-store.d.ts

@@ -57,33 +57,29 @@ export declare function recordMintedToken(params: {
     serviceName?: string | null;
     createdBy?: string | null;
 }, exec?: DbExec): Promise<string>;
-/**
- * Returns true when the given `jti` corresponds to a token that has been
- * revoked. Fails OPEN on a store/DB error: a transient Neon WS drop must not
- * lock every connected agent out. Signature verification is unaffected — this
- * is only the post-verify revoke check (see `verifyAuth` in build-server.ts).
- */
-/**
- * Throws when the revocation state can't be read. Answering "not revoked"
- * instead would let a transient read failure admit a revoked token.
- */
-export declare function isJtiRevoked(jti: string): Promise<boolean>;
 export type StoredConnectTokenIdentity = Pick<MintedTokenRow, "kind" | "ownerEmail" | "orgId">;
 export type ConnectTokenOrgLookup = ({
     status: "found";
 } & StoredConnectTokenIdentity) | {
+    status: "revoked";
+} | {
     status: "missing";
 } | {
     status: "unavailable";
 };
+/**
+ * A connect token's standing, read in one query. `unavailable` covers a read
+ * failure and a malformed row: answering `missing` or `found` instead would
+ * admit a revoked token, or refuse a live one, on a transient error.
+ */
 export declare function lookupConnectTokenOrg(jti: string): Promise<ConnectTokenOrgLookup>;
 export declare function listTokens(ownerEmail: string): Promise<MintedTokenRow[]>;
 export declare function listOrgServiceTokens(orgId: string): Promise<MintedTokenRow[]>;
 /**
  * Revoke an org service token by id, scoped to `orgId` AND `kind = 'service'`
  * so a caller can never revoke another org's token (or someone's personal
- * token) through this path. Uses the same `revoked_at` gate `isJtiRevoked`
- * checks, so revocation takes effect on the next request like personal
+ * token) through this path. Uses the same `revoked_at` gate
+ * `lookupConnectTokenOrg` checks, so revocation takes effect on the next request like personal
  * tokens. Idempotent; returns true when a row actually transitioned.
  */
 export declare function revokeOrgServiceToken(orgId: string, id: string): Promise<boolean>;

package/dist/mcp/connect-store.js

@@ -127,37 +127,23 @@ export async function recordMintedToken(params, exec) {
     return id;
 }
 /**
- * Returns true when the given `jti` corresponds to a token that has been
- * revoked. Fails OPEN on a store/DB error: a transient Neon WS drop must not
- * lock every connected agent out. Signature verification is unaffected — this
- * is only the post-verify revoke check (see `verifyAuth` in build-server.ts).
+ * A connect token's standing, read in one query. `unavailable` covers a read
+ * failure and a malformed row: answering `missing` or `found` instead would
+ * admit a revoked token, or refuse a live one, on a transient error.
  */
-/**
- * Throws when the revocation state can't be read. Answering "not revoked"
- * instead would let a transient read failure admit a revoked token.
- */
-export async function isJtiRevoked(jti) {
-    await ensureTable();
-    const client = getDbExec();
-    const { rows } = await client.execute({
-        sql: `SELECT revoked_at FROM mcp_connect_tokens WHERE jti = ?`,
-        args: [jti],
-    });
-    if (rows.length === 0)
-        return false;
-    const revokedAt = rows[0].revoked_at ?? rows[0].revokedAt;
-    return revokedAt != null;
-}
 export async function lookupConnectTokenOrg(jti) {
     try {
         await ensureTable();
         const client = getDbExec();
         const { rows } = await client.execute({
-            sql: `SELECT org_id, owner_email, kind FROM mcp_connect_tokens WHERE jti = ?`,
+            sql: `SELECT org_id, owner_email, kind, revoked_at FROM mcp_connect_tokens WHERE jti = ?`,
             args: [jti],
         });
         if (rows.length === 0)
             return { status: "missing" };
+        if ((rows[0].revoked_at ?? rows[0].revokedAt) != null) {
+            return { status: "revoked" };
+        }
         const rawOrgId = rows[0].org_id ?? rows[0].orgId;
         const ownerEmail = rows[0].owner_email ?? rows[0].ownerEmail;
         const kind = rows[0].kind;
@@ -176,7 +162,8 @@ export async function lookupConnectTokenOrg(jti) {
                 : null,
         };
     }
-    catch {
+    catch (error) {
+        console.error("[mcp] Connect-token lookup failed:", error);
         return { status: "unavailable" };
     }
 }
@@ -223,8 +210,8 @@ export async function listOrgServiceTokens(orgId) {
 /**
  * Revoke an org service token by id, scoped to `orgId` AND `kind = 'service'`
  * so a caller can never revoke another org's token (or someone's personal
- * token) through this path. Uses the same `revoked_at` gate `isJtiRevoked`
- * checks, so revocation takes effect on the next request like personal
+ * token) through this path. Uses the same `revoked_at` gate
+ * `lookupConnectTokenOrg` checks, so revocation takes effect on the next request like personal
  * tokens. Idempotent; returns true when a row actually transitioned.
  */
 export async function revokeOrgServiceToken(orgId, id) {

package/dist/mcp/credential-membership.js

@@ -23,15 +23,26 @@ export async function checkCredentialOrgMembership(input) {
     // A human OAuth subject can use a service-shaped address. Only the local
     // record of an authenticated connect token proves it is a service identity.
     const stored = input.storedConnectToken;
-    if (stored?.kind === "service" &&
-        stored.ownerEmail === email &&
-        stored.orgId === orgId &&
-        implicitServiceOrgRole({ email, orgId, requestOrgId: stored.orgId })) {
-        return "member";
-    }
     const lookup = () => isOrgMember(orgId, email, { requireOrganizationMetadata: true });
     const context = getRequestContext();
     try {
+        if (stored?.kind === "service" &&
+            stored.ownerEmail === email &&
+            stored.orgId === orgId &&
+            implicitServiceOrgRole({ email, orgId, requestOrgId: stored.orgId })) {
+            const organization = await getDbExec().execute({
+                sql: `SELECT identity_authority, identity_id
+              FROM organizations WHERE id = ? LIMIT 1`,
+                args: [orgId],
+            });
+            const metadata = organization.rows[0];
+            if (!metadata)
+                return "not-member";
+            return String(metadata.identity_authority ?? "").trim() ||
+                String(metadata.identity_id ?? "").trim()
+                ? "not-member"
+                : "member";
+        }
         const member = !input.requestOrigin || context?.requestOrigin
             ? await lookup()
             : await runWithRequestContext({ ...context, requestOrigin: input.requestOrigin }, lookup);

package/dist/mcp/oauth-route.d.ts

@@ -1,9 +1,18 @@
 import type { H3Event } from "h3";
+import { type BearerCredentialRefusal } from "../server/bearer-credential-refusal.js";
 export interface McpOAuthRouteOptions {
     appId?: string;
     appName?: string;
 }
 export declare function getMcpOAuthIssuer(event: H3Event): string | undefined;
+/**
+ * The issuer MCP credentials are bound to, given the caller's request origin.
+ * Verification accepts only this issuer's resources, so anything that mints a
+ * bearer for this app must resolve its audience here, not from request headers:
+ * a configured public URL wins over the host a page was reached through.
+ */
+export declare function resolveMcpOAuthIssuer(requestOrigin: string | undefined): string | undefined;
+export declare function getMcpConnectUrl(event: H3Event): string | undefined;
 export declare function getMcpOAuthResource(event: H3Event, routePath?: string): string | undefined;
 /**
  * All plausible MCP OAuth resource audiences for the given request, deduped.
@@ -16,7 +25,8 @@ export declare function getMcpOAuthResource(event: H3Event, routePath?: string):
  */
 export declare function getMcpOAuthAudiences(event: H3Event, routePath?: string): string[];
 export declare function getMcpOAuthProtectedResourceMetadataUrl(event: H3Event, routePath?: string): string | undefined;
-export declare function buildMcpOAuthChallenge(event: H3Event, routePath?: string): string;
+/** `refusal` is set only when the request presented a bearer token. */
+export declare function buildMcpOAuthChallenge(event: H3Event, routePath?: string, refusal?: BearerCredentialRefusal): string;
 export declare function handleMcpOAuthProtectedResourceMetadata(event: H3Event): Response;
 export declare function handleMcpOAuthAuthorizationServerMetadata(event: H3Event): Response;
 export declare function handleMcpOAuth(event: H3Event, subpath: string, options?: McpOAuthRouteOptions): Promise<Response>;

package/dist/mcp/oauth-route.js

@@ -2,6 +2,7 @@ import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { getHeader, getMethod, getQuery, setResponseStatus } from "h3";
 import { getOrgDomain } from "../org/context.js";
 import { getConfiguredLoginHtml, getSession } from "../server/auth.js";
+import { describeBearerCredentialRefusalWithRecovery, } from "../server/bearer-credential-refusal.js";
 import { getAuthSecret } from "../server/better-auth-instance.js";
 import { CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE } from "../server/credential-membership-unavailable.js";
 import { getOrigin } from "../server/google-oauth.js";
@@ -126,11 +127,24 @@ function deriveOrigin(event) {
     return host ? `${proto}://${host}` : "";
 }
 export function getMcpOAuthIssuer(event) {
-    const baseUrl = configuredPublicBaseUrl() || deriveOrigin(event);
+    return resolveMcpOAuthIssuer(deriveOrigin(event));
+}
+/**
+ * The issuer MCP credentials are bound to, given the caller's request origin.
+ * Verification accepts only this issuer's resources, so anything that mints a
+ * bearer for this app must resolve its audience here, not from request headers:
+ * a configured public URL wins over the host a page was reached through.
+ */
+export function resolveMcpOAuthIssuer(requestOrigin) {
+    const baseUrl = configuredPublicBaseUrl() || requestOrigin;
     if (!baseUrl)
         return undefined;
     return appendConfiguredBasePath(baseUrl);
 }
+export function getMcpConnectUrl(event) {
+    const issuer = getMcpOAuthIssuer(event);
+    return issuer ? `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}/connect` : undefined;
+}
 function normalizeMcpResourcePath(routePath) {
     if (routePath === MCP_LEGACY_ROUTE_PREFIX ||
         routePath === MCP_DIRECTORY_ROUTE_PREFIX) {
@@ -198,12 +212,20 @@ export function getMcpOAuthProtectedResourceMetadataUrl(event, routePath = MCP_P
     }
     return metadataUrl.toString();
 }
-export function buildMcpOAuthChallenge(event, routePath = MCP_PUBLIC_ROUTE_PREFIX) {
+/** `refusal` is set only when the request presented a bearer token. */
+export function buildMcpOAuthChallenge(event, routePath = MCP_PUBLIC_ROUTE_PREFIX, refusal) {
     const metadata = getMcpOAuthProtectedResourceMetadataUrl(event, routePath);
-    const scope = MCP_OAUTH_RESOURCE_SCOPE;
-    return metadata
-        ? `Bearer resource_metadata="${metadata}", scope="${scope}"`
-        : `Bearer scope="${scope}"`;
+    const params = [
+        ...(metadata ? [`resource_metadata="${metadata}"`] : []),
+        `scope="${MCP_OAUTH_RESOURCE_SCOPE}"`,
+        ...(refusal
+            ? [
+                `error="invalid_token"`,
+                `error_description="${describeBearerCredentialRefusalWithRecovery(refusal, getMcpConnectUrl(event))}"`,
+            ]
+            : []),
+    ];
+    return `Bearer ${params.join(", ")}`;
 }
 function protectedResourcePathFromRequest(event) {
     let pathname = event.url?.pathname ?? "";

package/dist/mcp/oauth-token.d.ts

@@ -2,7 +2,15 @@ import { MCP_OAUTH_ACCESS_TOKEN_TTL, MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS } from "
 export { MCP_OAUTH_ACCESS_TOKEN_TTL, MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS };
 export declare const MCP_OAUTH_SCOPES: readonly ["mcp:read", "mcp:write", "mcp:apps", "offline_access"];
 export declare const MCP_OAUTH_DEFAULT_SCOPE: string;
+export declare const MCP_OAUTH_TOKEN_TYPE = "agent-native-mcp-oauth";
 declare const MCP_OAUTH_CREDENTIAL_VERSION = 2;
+/**
+ * Service credentials carry a version that verifiers predating service
+ * identity assurance reject. Those verifiers admit any MCP OAuth token as a
+ * verified user, so a service token they accepted could approve gated actions.
+ * Never sign a service credential with `MCP_OAUTH_CREDENTIAL_VERSION`.
+ */
+declare const MCP_OAUTH_SERVICE_CREDENTIAL_VERSION = 3;
 export interface McpOAuthAccessTokenClaims {
     sub: string;
     org_id?: string | null;
@@ -11,8 +19,8 @@ export interface McpOAuthAccessTokenClaims {
     client_id: string;
     resource: string;
     jti?: string;
-    typ: "agent-native-mcp-oauth";
-    credential_version: typeof MCP_OAUTH_CREDENTIAL_VERSION;
+    typ: typeof MCP_OAUTH_TOKEN_TYPE;
+    credential_version: typeof MCP_OAUTH_CREDENTIAL_VERSION | typeof MCP_OAUTH_SERVICE_CREDENTIAL_VERSION;
 }
 export declare function normalizeOAuthScope(input: unknown): string | null;
 export declare function scopeList(scope: string | undefined): string[];
@@ -31,6 +39,8 @@ export declare function signMcpOAuthAccessToken(params: {
     jti?: string;
     expiresIn?: string | number;
     catalogScope?: "full";
+    /** An org service identity, not a person. */
+    service?: true;
 }): Promise<string>;
 export declare function verifyMcpOAuthAccessToken(token: string, resource: string | string[] | undefined): Promise<{
     userEmail: string;

package/dist/mcp/oauth-token.js

@@ -11,7 +11,15 @@ export const MCP_OAUTH_SCOPES = [
     "offline_access",
 ];
 export const MCP_OAUTH_DEFAULT_SCOPE = MCP_OAUTH_SCOPES.join(" ");
+export const MCP_OAUTH_TOKEN_TYPE = "agent-native-mcp-oauth";
 const MCP_OAUTH_CREDENTIAL_VERSION = 2;
+/**
+ * Service credentials carry a version that verifiers predating service
+ * identity assurance reject. Those verifiers admit any MCP OAuth token as a
+ * verified user, so a service token they accepted could approve gated actions.
+ * Never sign a service credential with `MCP_OAUTH_CREDENTIAL_VERSION`.
+ */
+const MCP_OAUTH_SERVICE_CREDENTIAL_VERSION = 3;
 function signingSecret() {
     return new TextEncoder().encode(process.env.A2A_SECRET?.trim() || getAuthSecret());
 }
@@ -60,8 +68,10 @@ export function parseMcpOAuthOrgIdClaim(payload) {
 }
 export async function signMcpOAuthAccessToken(params) {
     return new jose.SignJWT({
-        typ: "agent-native-mcp-oauth",
-        credential_version: MCP_OAUTH_CREDENTIAL_VERSION,
+        typ: MCP_OAUTH_TOKEN_TYPE,
+        credential_version: params.service
+            ? MCP_OAUTH_SERVICE_CREDENTIAL_VERSION
+            : MCP_OAUTH_CREDENTIAL_VERSION,
         sub: params.ownerEmail,
         ...(params.orgId !== undefined ? { org_id: params.orgId } : {}),
         ...(params.orgDomain ? { org_domain: params.orgDomain } : {}),
@@ -122,9 +132,10 @@ export async function verifyMcpOAuthAccessToken(token, resource) {
     if (!payload)
         return null;
     try {
-        if (payload.typ !== "agent-native-mcp-oauth")
+        if (payload.typ !== MCP_OAUTH_TOKEN_TYPE)
             return null;
-        if (payload.credential_version !== MCP_OAUTH_CREDENTIAL_VERSION)
+        if (payload.credential_version !== MCP_OAUTH_CREDENTIAL_VERSION &&
+            payload.credential_version !== MCP_OAUTH_SERVICE_CREDENTIAL_VERSION)
             return null;
         if (typeof payload.resource !== "string")
             return null;

package/dist/mcp/server.js

@@ -2,6 +2,7 @@ import { defineEventHandler, setResponseStatus, setResponseHeader, getMethod, ge
 import { getAppConfig } from "../app-config/store.js";
 import { getConfiguredAppBasePath } from "../server/app-base-path.js";
 import { isLoopbackRequest } from "../server/auth.js";
+import { describeBearerCredentialRefusal, } from "../server/bearer-credential-refusal.js";
 import { CREDENTIAL_MEMBERSHIP_UNAVAILABLE_MESSAGE } from "../server/credential-membership-unavailable.js";
 import { getH3App } from "../server/framework-request-handler.js";
 import { getOrigin } from "../server/google-oauth.js";
@@ -88,7 +89,7 @@ function buildWebRequest(event, method, routePath = MCP_PUBLIC_ROUTE_PREFIX) {
     const url = `${proto}://${host}${basePath}${routePath}`;
     return new Request(url, { method, headers });
 }
-function buildUnauthorizedBody(event, routePath = MCP_PUBLIC_ROUTE_PREFIX) {
+function buildUnauthorizedBody(event, routePath = MCP_PUBLIC_ROUTE_PREFIX, refusal) {
     const issuer = getMcpOAuthIssuer(event);
     const mcpUrl = getMcpOAuthResource(event, routePath);
     const resourceMetadataUrl = getMcpOAuthProtectedResourceMetadataUrl(event, routePath);
@@ -101,7 +102,7 @@ function buildUnauthorizedBody(event, routePath = MCP_PUBLIC_ROUTE_PREFIX) {
     const authorizeUrl = issuer
         ? `${issuer}${MCP_PUBLIC_ROUTE_PREFIX}/oauth/authorize`
         : undefined;
-    const message = command
+    const instructions = command
         ? `Authentication required. Run \`${command}\` to re-authenticate this ` +
             `MCP connector without reinstalling it (or, in a Claude Code host, ` +
             `run /mcp and choose Authenticate), then retry. For first-time ` +
@@ -110,7 +111,10 @@ function buildUnauthorizedBody(event, routePath = MCP_PUBLIC_ROUTE_PREFIX) {
             "then retry.";
     return {
         error: "Unauthorized",
-        message,
+        ...(refusal ? { reason: refusal } : {}),
+        message: refusal
+            ? `${describeBearerCredentialRefusal(refusal)} ${instructions}`
+            : instructions,
         authenticate: {
             ...(command ? { command } : {}),
             ...(firstTimeCommand ? { firstTimeCommand } : {}),
@@ -263,8 +267,8 @@ async function handleMcpRequestInternal(event, config, routePath = MCP_PUBLIC_RO
     }
     if (!authResult.authed) {
         setResponseStatus(event, 401);
-        setResponseHeader(event, "WWW-Authenticate", buildMcpOAuthChallenge(event, routePath));
-        return buildUnauthorizedBody(event, routePath);
+        setResponseHeader(event, "WWW-Authenticate", buildMcpOAuthChallenge(event, routePath, authResult.refusal));
+        return buildUnauthorizedBody(event, routePath, authResult.refusal);
     }
     const body = method === "POST" ? await readBody(event) : undefined;
     onMcpMethod?.(directoryLogMethod(body) ?? method);

package/dist/notifications/routes.d.ts

@@ -1,13 +1,13 @@
 export declare function createNotificationsHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<"" | import("./types.js").Notification[] | {
     count: number;
     updated?: undefined;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     count?: undefined;
     updated: number;
-    ok?: undefined;
     error?: undefined;
+    ok?: undefined;
 } | {
     count?: undefined;
     updated?: undefined;

package/dist/observability/posthog-ai.d.ts

@@ -5,6 +5,7 @@ export interface AiErrorDetail {
     terminal_code?: string;
     terminal_state?: string;
     retryable?: boolean;
+    cause?: string;
 }
 export declare function resolveAiError(isError: boolean, error: AiErrorDetail | undefined): AiErrorDetail | undefined;
 export declare function boundAiContent(value: unknown): {

package/dist/observability/posthog-ai.js

@@ -1,14 +1,16 @@
+import { runErrorTelemetryProperties } from "../agent/engine/error-telemetry.js";
+import { isToolDoneFailure } from "../agent/tool-done-error.js";
 import { sendPostHogEvent } from "../tracking/providers.js";
-import { boundedText } from "../tracking/redaction.js";
 export const MAX_AI_CONTENT_BYTES = 128 * 1024;
 export const MAX_AI_SPANS_PER_RUN = 100;
-const UNREPORTED_ERROR = {
-    message: "failed without a reported error message",
-};
 export function resolveAiError(isError, error) {
     if (!isError)
         return undefined;
-    return error ?? UNREPORTED_ERROR;
+    return failedRunErrorDetail(error?.message, {
+        state: error?.terminal_state,
+        code: error?.terminal_code,
+        retryable: error?.retryable,
+    });
 }
 function trackAiEvent(name, properties, userId, occurredAt) {
     for (const key of Object.keys(properties)) {
@@ -122,7 +124,12 @@ export function toPostHogMessages(value) {
                         ...(typeof part.toolName === "string"
                             ? { name: part.toolName }
                             : {}),
-                        content: part.content,
+                        content: isToolDoneFailure({
+                            isError: part.isError,
+                            result: part.content,
+                        })
+                            ? "[tool error message omitted from telemetry]"
+                            : part.content,
                     });
                     break;
                 case "tool-call":
@@ -245,12 +252,17 @@ export function emitAiFeedbackSurveyEvent(input) {
 export function toAiErrorDetail(errorMessage, terminalOutcome) {
     if (!errorMessage && !terminalOutcome?.code)
         return undefined;
+    return failedRunErrorDetail(errorMessage, terminalOutcome);
+}
+function failedRunErrorDetail(errorMessage, terminalOutcome) {
+    const { error_code, error_cause } = runErrorTelemetryProperties(terminalOutcome?.code, errorMessage);
     return {
-        message: boundedText(errorMessage ?? terminalOutcome?.code ?? "error", 1000),
+        message: `Agent run failed (${error_code})`,
+        cause: error_cause,
         ...(terminalOutcome?.state
             ? { terminal_state: terminalOutcome.state }
             : {}),
-        ...(terminalOutcome?.code ? { terminal_code: terminalOutcome.code } : {}),
+        terminal_code: error_code,
         ...(terminalOutcome?.retryable !== undefined
             ? { retryable: terminalOutcome.retryable }
             : {}),

package/dist/observability/routes.d.ts

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