@every-app/sdk 0.3.0-rc.11 → 0.3.0-rc.13

package/dist/internal/remoteMcp.js

@@ -3,34 +3,53 @@
  * (`everyapp mcp add <url>`, Admin → Apps → Add app → "Add an MCP server",
  * `everyapp_mcp_add`), served to members' AI clients as an MCP app of the
  * Gateway's own, like a built-in provider app (./providerApps.ts) but with
- * its tools read from the server and each call forwarded to it with a
- * credential the Gateway holds (docs/design/2026-10-mcp-by-url.md).
+ * its tools read from the server and each call forwarded to it
+ * (docs/design/2026-10-mcp-by-url.md, docs/design/2026-11-mcp-apps-auth.md).
  *
  * The registration record is the app row's manifest: `id`, `name`,
  * `description` and a `remote` block ({@link RemoteMcpBlock}): the one URL
- * the Gateway ever fetches, how it authenticates ({@link RemoteMcpAuth},
- * the credential always the NAME of a Gateway setting, never a value), how
- * a tool's risk is decided when the server's annotations don't say, the
- * operator's per-tool overrides, and a revision the writers bump so the
- * Gateway re-lists the tools on first use after a change.
+ * the Gateway ever fetches, its credential ({@link RemoteMcpAuth}: none, or
+ * a provider of the registry, whose key or OAuth connection the Gateway
+ * holds and binds to the provider's hosts), how a tool's risk is decided
+ * when the server's annotations don't say, the operator's per-tool
+ * overrides, and a revision the writers bump so the Gateway re-lists the
+ * tools on first use after a change. An app with a provider also lists it
+ * under `capabilities` ({@link remoteMcpAppManifest}), so the settings
+ * model treats its key or client as any app's.
+ *
+ * A credential the registrar gives at `mcp add` becomes a provider row of
+ * the app's own, `<appId>-mcp` ({@link remoteMcpProviderId}; the specs are
+ * built in ./mcpOAuth.ts): an API-key row for a static value
+ * (`<APPID>_MCP_TOKEN`), a discovered `oauth2-user` row for OAuth
+ * (`<APPID>_MCP_CLIENT_ID`, `_SECRET`).
  *
  * Everything here is pure and shared by the CLI, the perimeter's registry
  * rules, the Gateway (which serves the row and validates again at every
  * fetch) and the settings model (./appSettings.ts), so the rules cannot
- * drift: what the URL may be, what the credential may be called, how a
- * server's tool names become the ToolBus's, and what risk a tool gets.
+ * drift: what the URL may be, what the credential may be, how a server's
+ * tool names become the ToolBus's, and what risk a tool gets.
  */
-import { CAPABILITIES } from "./capabilities.js";
-import { isRemoteMcpSecretName } from "./gatewaySettings.js";
+import { CAPABILITIES, apiKeyHosts, } from "./capabilities.js";
 import { isProviderAppId } from "./providerApps.js";
+import { PROVIDER_ID } from "./providerSpec.js";
 import { TOOL_NAME_PATTERN, isToolRisk } from "./tools.js";
-export const REMOTE_MCP_AUTH_KINDS = [
+/** The kinds a stored `remote.auth` block may have. */
+export const REMOTE_MCP_AUTH_KINDS = ["none", "provider"];
+/**
+ * What the registrar may ask for at `mcp add` (`--auth`): none, a static
+ * credential the add turns into a synthesized API-key provider row, or
+ * OAuth, a discovered `oauth2-user` row (./mcpOAuth.ts).
+ */
+export const REMOTE_MCP_CREDENTIAL_KINDS = [
     "none",
     "bearer",
     "header",
+    "query",
     "basic",
     "oauth",
 ];
+/** Why an old registration (`bearer`, `header`, `basic`, `oauth` with a `secret`) no longer parses. */
+export const REMOTE_MCP_AUTH_PREDATES = "this registration predates provider credentials; remove it and add it again";
 /**
  * How a tool's risk is decided for the app. `annotations`: from the
  * server's hints ({@link remoteToolRisk}); `read` or `write`: every tool,
@@ -45,18 +64,17 @@ const ID_PATTERN = /^[a-z]([a-z0-9-]*[a-z0-9])?$/;
 const ID_MAX_LENGTH = 32;
 /** App ids a remote server can't take: the Gateway's own tool prefix. */
 const RESERVED_IDS = ["everyapp"];
-const SECRET_MAX_LENGTH = 64;
-const HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,100}$/;
-const PREFIX_MAX_LENGTH = 32;
+const HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
 const URL_MAX_LENGTH = 2048;
 const NAME_MAX_LENGTH = 255;
 const DESCRIPTION_MAX_LENGTH = 1000;
 const OVERRIDES_MAX = 500;
 const UPSTREAM_NAME_MAX = 256;
 /**
- * Headers the `header` kind may not name: the ones the Gateway sets on the
- * request, the ones that route it, and the ones that would carry something
- * other than this app's credential.
+ * Headers a static `header` credential may not name: the ones the Gateway
+ * sets on the request, the ones that route it, and the ones that would
+ * carry something other than this app's credential (`Authorization` is
+ * the `bearer` kind's; `--prefix` gives it another scheme).
  */
 const FORBIDDEN_AUTH_HEADERS = new Set([
     "authorization",
@@ -71,10 +89,99 @@ const FORBIDDEN_AUTH_HEADERS = new Set([
     "mcp-protocol-version",
     "mcp-method",
     "mcp-name",
+    "last-event-id",
 ]);
-/** The default credential name for an app id: `treg` → `TREG_MCP_TOKEN`. */
-export function remoteMcpSecretName(id) {
-    return `${id.toUpperCase().replace(/-/g, "_")}_MCP_TOKEN`;
+/**
+ * Why `header` can't carry a remote MCP server's static credential, or
+ * null when it can: an HTTP header name the MCP transport and the Gateway
+ * don't set themselves.
+ */
+export function remoteMcpHeaderProblem(header) {
+    if (typeof header !== "string" || !HEADER_NAME_PATTERN.test(header)) {
+        return "the header must be an HTTP header name";
+    }
+    if (FORBIDDEN_AUTH_HEADERS.has(header.toLowerCase())) {
+        return `the header can't be ${header}; use --auth bearer for Authorization`;
+    }
+    return null;
+}
+/** The settings prefix of an app id's synthesized row: `my-server` → `MY_SERVER_MCP_`. */
+function settingsPrefix(appId) {
+    return `${appId.toUpperCase().replace(/-/g, "_")}_MCP_`;
+}
+/**
+ * The provider row `everyapp mcp add` writes for an app's own credential:
+ * `<appId>-mcp` (`treg` → `treg-mcp`), its settings `TREG_MCP_*`.
+ */
+export function remoteMcpProviderId(appId) {
+    return `${appId}-mcp`;
+}
+/** Whether `providerId` is `appId`'s synthesized row ({@link remoteMcpProviderId}). */
+export function isRemoteMcpProviderIdOf(providerId, appId) {
+    return providerId === remoteMcpProviderId(appId);
+}
+/** The static credential's setting on the synthesized row: `treg` → `TREG_MCP_TOKEN`. */
+export function remoteMcpTokenSetting(appId) {
+    return `${settingsPrefix(appId)}TOKEN`;
+}
+/** The OAuth client id's setting on the synthesized row: `treg` → `TREG_MCP_CLIENT_ID`. */
+export function remoteMcpClientIdSetting(appId) {
+    return `${settingsPrefix(appId)}CLIENT_ID`;
+}
+/** The OAuth client secret's setting on the synthesized row: `treg` → `TREG_MCP_CLIENT_SECRET`. */
+export function remoteMcpClientSecretSetting(appId) {
+    return `${settingsPrefix(appId)}CLIENT_SECRET`;
+}
+/**
+ * The redirect URI of an app's synthesized OAuth row, what a server's
+ * client is registered with: `<gateway origin>/connect/<appId>-mcp/callback`.
+ */
+export function remoteMcpRedirectUri(gatewayUrl, appId) {
+    let origin = gatewayUrl.trim().replace(/\/+$/, "");
+    try {
+        origin = new URL(gatewayUrl).origin;
+    }
+    catch {
+        // Not a URL: used as given, without a trailing slash.
+    }
+    return `${origin}/connect/${remoteMcpProviderId(appId)}/callback`;
+}
+/** Where the Gateway serves its OAuth client metadata documents (public, bypassed behind Access). */
+export const REMOTE_MCP_CLIENT_METADATA_PREFIX = "/oauth-clients/";
+/**
+ * The Gateway's client id at a server that takes OAuth client ID metadata
+ * documents (CIMD) instead of registration: the URL of the document that
+ * describes the client, `<gateway origin>/oauth-clients/<appId>-mcp`.
+ * Null for a Gateway that isn't on https (a local one): an authorization
+ * server fetches the document, and only from https.
+ */
+export function remoteMcpClientMetadataUrl(gatewayUrl, appId) {
+    let origin;
+    try {
+        const parsed = new URL(gatewayUrl);
+        if (parsed.protocol !== "https:")
+            return null;
+        origin = parsed.origin;
+    }
+    catch {
+        return null;
+    }
+    return `${origin}${REMOTE_MCP_CLIENT_METADATA_PREFIX}${remoteMcpProviderId(appId)}`;
+}
+/**
+ * The hosts a provider sends its credential to, the hosts an MCP URL
+ * using it must be on: an API-key provider's `hosts` (and its host
+ * setting's value, given `settings`), an OAuth provider's API hosts. Null
+ * for a provider a remote MCP app can't use: an AI provider, a service,
+ * or an OAuth client the Gateway runs no flow for.
+ */
+export function remoteMcpProviderHosts(capability, settings) {
+    if (capability.mode === "api_key")
+        return apiKeyHosts(capability, settings);
+    if (capability.mode === "oauth_client" && capability.flow) {
+        return [...capability.api];
+    }
+    return null;
 }
 /** Whether `id` can be a remote MCP app's id (kebab-case, at most 32, not reserved, not a built-in's). */
 export function remoteMcpIdProblem(id) {
@@ -157,11 +264,16 @@ export function reservedUpstreamHosts() {
  * `https:` (or `http:` and loopback hosts only while the Gateway itself
  * runs on `http://`, local dev), a host name rather than an address, no
  * credentials or fragment in it, not the Gateway's own origin or one of
- * its app hosts, and not a provider whose key the Gateway holds. The
- * Gateway checks the stored URL again before every fetch, so a row edited
- * by hand is refused the same way.
+ * its app hosts, and not a provider whose key the Gateway holds
+ * ({@link reservedUpstreamHosts}) unless the app names that provider:
+ * `providerHosts` are the hosts of the provider the app's credential is
+ * (never an app's own synthesized row), and a reserved host among them is
+ * allowed (`mcp add https://api.elevenlabs.io/v1/mcp --provider
+ * elevenlabs`). The Gateway's own origin, its app domains and IPs stay
+ * refused always. The Gateway checks the stored URL again before every
+ * fetch, so a row edited by hand is refused the same way.
  */
-export function remoteMcpUrlProblem(url, env) {
+export function remoteMcpUrlProblem(url, env, options = {}) {
     if (typeof url !== "string" || !url.trim())
         return "give the server's URL";
     if (url.length > URL_MAX_LENGTH)
@@ -230,74 +342,67 @@ export function remoteMcpUrlProblem(url, env) {
             return `the URL is on this Gateway's app domain (${normalized})`;
         }
     }
-    if (reservedUpstreamHosts().includes(host)) {
-        return `${host} is a provider this Gateway holds a key for; apps reach it through the Gateway's capabilities, not as an MCP app`;
+    const named = (options.providerHosts ?? []).map((each) => each.toLowerCase().replace(/\.$/, ""));
+    if (reservedUpstreamHosts().includes(host) && !named.includes(host)) {
+        return `${host} is a provider this Gateway holds a key for; add it with --provider <that provider> so the app uses its key, or reach it through the Gateway's capabilities`;
     }
     return null;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** The credential name's problem, or null: in the family, and bounded. */
-export function remoteMcpSecretProblem(name) {
-    if (typeof name !== "string" || !name)
-        return "give the credential's setting name";
-    if (name.length > SECRET_MAX_LENGTH)
-        return "the credential's name is too long";
-    if (!isRemoteMcpSecretName(name)) {
-        return `the credential's name must end in _MCP_TOKEN (letters, digits and underscores), like ${remoteMcpSecretName("treg")}`;
-    }
-    return null;
-}
-/** The auth block's problem, or the block as typed. */
+/**
+ * The auth block's problem, or the block as typed: `{ kind: "none" }`,
+ * or `{ kind: "provider", provider }` naming a provider id. A
+ * block of the kinds before provider credentials (`bearer`, `header`,
+ * `basic`, `oauth`) is refused with {@link REMOTE_MCP_AUTH_PREDATES}: such
+ * a row serves nothing and reads as needing setup.
+ */
 export function parseRemoteMcpAuth(raw) {
     if (!isRecord(raw) || typeof raw["kind"] !== "string") {
         return { ok: false, problem: "auth must name a kind" };
     }
     const kind = raw["kind"];
-    if (!REMOTE_MCP_AUTH_KINDS.includes(kind)) {
+    if (["bearer", "header", "basic", "oauth"].includes(kind)) {
+        return { ok: false, problem: REMOTE_MCP_AUTH_PREDATES };
+    }
+    if (kind === "none") {
+        for (const field of Object.keys(raw)) {
+            if (field !== "kind") {
+                return {
+                    ok: false,
+                    problem: `auth.${field} is not a field of kind none`,
+                };
+            }
+        }
+        return { ok: true, auth: { kind } };
+    }
+    if (kind !== "provider") {
         return {
             ok: false,
             problem: `auth.kind must be one of ${REMOTE_MCP_AUTH_KINDS.join(", ")}`,
         };
     }
-    if (kind === "none" || kind === "oauth") {
-        return { ok: true, auth: { kind } };
-    }
-    const secretProblem = remoteMcpSecretProblem(raw["secret"]);
-    if (secretProblem)
-        return { ok: false, problem: `auth.secret: ${secretProblem}` };
-    const secret = raw["secret"];
-    if (kind === "bearer" || kind === "basic") {
-        return { ok: true, auth: { kind, secret } };
-    }
-    const header = raw["header"];
-    if (typeof header !== "string" || !HEADER_NAME_PATTERN.test(header)) {
-        return { ok: false, problem: "auth.header must be an HTTP header name" };
+    for (const field of Object.keys(raw)) {
+        if (!["kind", "provider"].includes(field)) {
+            return {
+                ok: false,
+                problem: `auth.${field} is not a field of kind provider`,
+            };
+        }
     }
-    if (FORBIDDEN_AUTH_HEADERS.has(header.toLowerCase())) {
+    const provider = raw["provider"];
+    if (typeof provider !== "string" || !PROVIDER_ID.test(provider)) {
         return {
             ok: false,
-            problem: `auth.header can't be ${header}; use kind "bearer" or "basic" for Authorization`,
+            problem: "auth.provider must be a provider id: lowercase letters, digits and hyphens, a letter first",
         };
     }
-    const prefix = raw["prefix"];
-    if (prefix !== undefined) {
-        if (typeof prefix !== "string" ||
-            prefix.length > PREFIX_MAX_LENGTH ||
-            /[\r\n]/.test(prefix)) {
-            return { ok: false, problem: "auth.prefix must be a short string" };
-        }
-    }
-    return {
-        ok: true,
-        auth: {
-            kind: "header",
-            secret,
-            header,
-            ...(typeof prefix === "string" && prefix ? { prefix } : {}),
-        },
-    };
+    return { ok: true, auth: { kind: "provider", provider } };
+}
+/** The provider the block names, or null for `none`. */
+export function remoteMcpProviderOf(auth) {
+    return auth.kind === "provider" ? auth.provider : null;
 }
 /**
  * The `remote` block of a stored manifest, checked field by field (a row
@@ -348,7 +453,7 @@ export function parseRemoteMcpBlock(raw) {
             if (!isToolRisk(override["risk"])) {
                 return {
                     ok: false,
-                    problem: `remote.tools.${name}.risk must be read, write or destructive`,
+                    problem: `remote.tools.${name}.risk must be read or write`,
                 };
             }
             out.risk = override["risk"];
@@ -391,14 +496,21 @@ export function remoteMcpOf(manifest) {
     const parsed = parseRemoteMcpBlock(manifest["remote"]);
     return parsed.ok ? parsed.block : null;
 }
+/**
+ * Why a stored manifest's `remote` block can't be read, or null when it
+ * can or there is none: {@link REMOTE_MCP_AUTH_PREDATES} for a block from
+ * before provider credentials.
+ */
+export function remoteMcpBlockProblem(manifest) {
+    if (!isRecord(manifest) || manifest["remote"] === undefined)
+        return null;
+    const parsed = parseRemoteMcpBlock(manifest["remote"]);
+    return parsed.ok ? null : parsed.problem;
+}
 /** Whether a stored manifest declares a remote MCP server at all (well-formed or not). */
 export function hasRemoteMcpBlock(manifest) {
     return isRecord(manifest) && manifest["remote"] !== undefined;
 }
-/** The credential's setting name the block declares, if its kind takes one. */
-export function remoteMcpSecretOf(auth) {
-    return "secret" in auth ? auth.secret : null;
-}
 /**
  * A description for a row that gave none: the server's origin, read as a
  * sentence. The origin only: a path or query may carry something the
@@ -438,21 +550,52 @@ export function remoteToolOverride(block, upstreamName) {
 export function isHeaderSafeToolName(name) {
     return /^[\x21-\x7e]{1,256}$/.test(name);
 }
-/** The manifest a remote MCP app's row stores, from what the registrar gave. */
+/**
+ * The manifest a remote MCP app's row stores, from what the registrar
+ * gave. An app with a provider credential lists the provider under
+ * `capabilities` like a deployed app that uses it, so the settings model
+ * (./appSettings.ts) asks for its key or client, `secret list` names it
+ * and the connect flow asks for its scopes: nothing about a remote app's
+ * credential is special there. `providerCapability` is the provider as
+ * the registry resolves it (the synthesized row's, before it is written);
+ * for an OAuth provider the entry lists `scopes`, the server's own scope
+ * strings the connect asks for (discovery's, or none: the server decides).
+ */
 export function remoteMcpAppManifest(input) {
     const name = (input.name ?? "").trim().slice(0, NAME_MAX_LENGTH) || input.id;
     const description = (input.description ?? "").trim().slice(0, DESCRIPTION_MAX_LENGTH) ||
         remoteMcpDefaultDescription(name, input.remote.url);
-    return { id: input.id, name, description, remote: input.remote };
+    const manifest = {
+        id: input.id,
+        name,
+        description,
+        remote: input.remote,
+    };
+    const auth = input.remote.auth;
+    if (auth.kind !== "provider")
+        return manifest;
+    let where = "";
+    try {
+        where = new URL(input.remote.url).origin;
+    }
+    catch {
+        where = "the server";
+    }
+    const why = `${name}'s MCP server at ${where} takes this credential; the Gateway sends it there when a member calls the app's tools.`;
+    const shortWhy = why.length > 200 ? `${why.slice(0, 199)}…` : why;
+    manifest.capabilities = {
+        [auth.provider]: input.providerCapability?.mode === "oauth_client"
+            ? { scopes: [...(input.scopes ?? [])], why: shortWhy }
+            : { access: "read", why: shortWhy },
+    };
+    return manifest;
 }
 /**
  * A tool's risk for the Gateway. An override wins; then the app's `read`
- * or `write` default; then the server's hints, read conservatively: an
- * explicit `readOnlyHint: true` is `read`, an explicit `destructiveHint:
- * true` is `destructive` (hidden until approvals exist), and anything
- * else, a missing hint included, is `write`. The spec's missing-means-true
- * default for `destructiveHint` is not followed: it would hide every
- * unhinted tool.
+ * or `write` default; then the server's hints: an explicit `readOnlyHint:
+ * true` is `read`, and anything else, a missing hint included, is `write`.
+ * A write tool keeps the server's `destructiveHint`, so clients still ask
+ * before calling it.
  */
 export function remoteToolRisk(hints, block, upstreamName) {
     const override = remoteToolOverride(block, upstreamName)?.risk;
@@ -463,9 +606,8 @@ export function remoteToolRisk(hints, block, upstreamName) {
     }
     if (hints?.readOnlyHint === true)
         return { risk: "read", source: "hint" };
-    if (hints?.destructiveHint === true) {
-        return { risk: "destructive", source: "hint" };
-    }
+    if (hints?.destructiveHint === true)
+        return { risk: "write", source: "hint" };
     return { risk: "write", source: "default" };
 }
 /** Whether the operator left the tool on (the default). */
@@ -499,41 +641,36 @@ export function normalizeRemoteToolName(name) {
     return TOOL_NAME_PATTERN.test(out) ? out : null;
 }
 /**
- * The request headers that carry the credential for `auth`, from the
- * setting's value. The value never appears anywhere else.
+ * Plain words for how the app authenticates, for lists and dialogs. With
+ * the provider's capability as the registry resolves it: "bearer token",
+ * "header X-Api-Key", "query parameter key", "user and password" (an
+ * API-key provider; "<kind>, <provider>'s key" when the provider isn't
+ * the app's own synthesized row), or "OAuth, each member connects" (an
+ * OAuth provider). Without it, the provider's id.
  */
-export function remoteMcpAuthHeaders(auth, value) {
-    switch (auth.kind) {
-        case "none":
-        case "oauth":
-            return {};
-        case "bearer":
-            return { authorization: `Bearer ${value}` };
-        case "basic":
-            return { authorization: `Basic ${base64(value)}` };
-        case "header":
-            return { [auth.header]: `${auth.prefix ?? ""}${value}` };
-    }
-}
-function base64(text) {
-    const bytes = new TextEncoder().encode(text);
-    let binary = "";
-    for (const byte of bytes)
-        binary += String.fromCharCode(byte);
-    return btoa(binary);
-}
-/** Plain words for an auth kind, for lists and dialogs. */
-export function remoteMcpAuthLabel(auth) {
-    switch (auth.kind) {
-        case "none":
-            return "no credential";
-        case "bearer":
-            return "bearer token";
-        case "basic":
-            return "user and password";
-        case "header":
-            return `header ${auth.header}`;
-        case "oauth":
-            return "OAuth (not supported yet)";
-    }
+export function remoteMcpAuthLabel(auth, capability) {
+    if (auth.kind === "none")
+        return "no credential";
+    if (!capability)
+        return `provider ${auth.provider}`;
+    if (capability.mode === "oauth_client") {
+        return "OAuth, each member connects";
+    }
+    if (capability.mode !== "api_key")
+        return `provider ${auth.provider}`;
+    const placement = capability.auth;
+    const words = placement.kind === "bearer"
+        ? placement.scheme && placement.scheme.toLowerCase() !== "bearer"
+            ? `${placement.scheme} token`
+            : "bearer token"
+        : placement.kind === "header"
+            ? `header ${placement.header}`
+            : placement.kind === "query"
+                ? `query parameter ${placement.param}`
+                : placement.as === "pair"
+                    ? "user and password"
+                    : "basic auth";
+    return auth.provider.endsWith("-mcp")
+        ? words
+        : `${words}, ${capability.label}'s key`;
 }

package/dist/internal/tools.d.ts

@@ -4,8 +4,8 @@
  * gateway's service binding and never public:
  *
  *   POST /__everyapp/tools/list  x-everyapp-system JWT (purpose "tools.list")
- *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp" or
- *                                "agent" + tc claim
+ *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp"
+ *                                + tc claim
  *
  * MCP itself (protocol eras, headers, envelopes) stays in the gateway; apps
  * only ever speak this small versioned JSON shape. Both sides import the
@@ -15,19 +15,23 @@ export declare const TOOLS_PROTOCOL_VERSION = 1;
 export declare const TOOLS_PATH_PREFIX = "/__everyapp/tools";
 export declare const TOOLS_LIST_PATH = "/__everyapp/tools/list";
 export declare const TOOLS_CALL_PATH = "/__everyapp/tools/call";
-export declare const TOOL_RISKS: readonly ["read", "write", "destructive"];
+/**
+ * A tool reads or writes. A write tool that deletes or can't be undone also
+ * says `destructiveHint` in its annotations, so clients ask before calling.
+ */
+export declare const TOOL_RISKS: readonly ["read", "write"];
 export type ToolRisk = (typeof TOOL_RISKS)[number];
-/** Scopes the gateway mints on tool-call identities (`chan: "mcp"` or `"agent"`), one per risk. */
+/** Scopes the gateway mints on tool-call identities (`chan: "mcp"`), one per risk. */
 export declare const MCP_READ_SCOPE = "mcp:read";
 export declare const MCP_WRITE_SCOPE = "mcp:write";
-/** Never minted in v1: destructive tools are hidden until approvals exist. */
-export declare const MCP_DESTRUCTIVE_SCOPE = "mcp:destructive";
 /** Local tool names: lowercase snake_case, at most 48 characters. */
 export declare const TOOL_NAME_PATTERN: RegExp;
 export declare function isToolRisk(value: unknown): value is ToolRisk;
 /** The exact scope a tool-call identity must carry to call a tool. */
 export declare function requiredScopeForRisk(risk: ToolRisk): string;
 export interface ToolAnnotationsV1 {
+    /** A write tool deletes or can't be undone: clients ask before calling. */
+    destructiveHint?: boolean;
     idempotentHint?: boolean;
     openWorldHint?: boolean;
 }
@@ -56,7 +60,7 @@ export interface ToolsListResponseV1 {
     /** Tools the SDK left out because it can't describe them, and why. */
     warnings?: string[];
 }
-/** The `tc` identity claim: binds a tool-call token (`chan: "mcp"` or `"agent"`) to one call. */
+/** The `tc` identity claim: binds a tool-call token (`chan: "mcp"`) to one call. */
 export interface ToolCallClaim {
     id: string;
     name: string;

package/dist/internal/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/internal/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/internal/tools.ts"],"names":[],"mappings":"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"}

package/dist/internal/tools.js

@@ -4,8 +4,8 @@
  * gateway's service binding and never public:
  *
  *   POST /__everyapp/tools/list  x-everyapp-system JWT (purpose "tools.list")
- *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp" or
- *                                "agent" + tc claim
+ *   POST /__everyapp/tools/call  x-everyapp-identity JWT, chan "mcp"
+ *                                + tc claim
  *
  * MCP itself (protocol eras, headers, envelopes) stays in the gateway; apps
  * only ever speak this small versioned JSON shape. Both sides import the
@@ -15,12 +15,14 @@ export const TOOLS_PROTOCOL_VERSION = 1;
 export const TOOLS_PATH_PREFIX = "/__everyapp/tools";
 export const TOOLS_LIST_PATH = `${TOOLS_PATH_PREFIX}/list`;
 export const TOOLS_CALL_PATH = `${TOOLS_PATH_PREFIX}/call`;
-export const TOOL_RISKS = ["read", "write", "destructive"];
-/** Scopes the gateway mints on tool-call identities (`chan: "mcp"` or `"agent"`), one per risk. */
+/**
+ * A tool reads or writes. A write tool that deletes or can't be undone also
+ * says `destructiveHint` in its annotations, so clients ask before calling.
+ */
+export const TOOL_RISKS = ["read", "write"];
+/** Scopes the gateway mints on tool-call identities (`chan: "mcp"`), one per risk. */
 export const MCP_READ_SCOPE = "mcp:read";
 export const MCP_WRITE_SCOPE = "mcp:write";
-/** Never minted in v1: destructive tools are hidden until approvals exist. */
-export const MCP_DESTRUCTIVE_SCOPE = "mcp:destructive";
 /** Local tool names: lowercase snake_case, at most 48 characters. */
 export const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]{0,47}$/;
 export function isToolRisk(value) {
@@ -34,8 +36,6 @@ export function requiredScopeForRisk(risk) {
             return MCP_READ_SCOPE;
         case "write":
             return MCP_WRITE_SCOPE;
-        case "destructive":
-            return MCP_DESTRUCTIVE_SCOPE;
     }
 }
 /**