@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/tools/legacy-keys.js

@@ -0,0 +1,114 @@
+import { BUILTIN } from "./builtin-names.js";
+export const LEGACY_BUILTINS = Object.freeze({
+    sandbox_bash: {
+        name: BUILTIN.Bash,
+        params: { timeoutSeconds: "timeout" },
+        msParams: ["timeout"],
+    },
+    sandbox_read: { name: BUILTIN.Read, params: { path: "file_path" } },
+    sandbox_write: { name: BUILTIN.Write, params: { path: "file_path" } },
+    sandbox_edit: {
+        name: BUILTIN.Edit,
+        params: {
+            path: "file_path",
+            oldText: "old_string",
+            newText: "new_string",
+            replaceAll: "replace_all",
+        },
+    },
+    sandbox_glob: { name: BUILTIN.Glob, params: {} },
+    sandbox_grep: { name: BUILTIN.Grep, params: { ignoreCase: "-i" } },
+    sandbox_deliver: { name: BUILTIN.Deliver, params: { path: "file_path" } },
+    skill_load: { name: BUILTIN.Skill, params: { name: "skill" } },
+    ask_user: { name: BUILTIN.AskUserQuestion, params: {} },
+    read_tool_output: { name: BUILTIN.ReadToolOutput, params: {} },
+    tool_search: { name: BUILTIN.ToolSearch, params: { limit: "max_results" } },
+    agent: { name: BUILTIN.Agent, params: {} },
+});
+/** Is `key` a release-candidate builtin name? */
+export const isLegacyBuiltinKey = (key) => Object.hasOwn(LEGACY_BUILTINS, key);
+/** A key in the current format for connector and extension tools (`mcp__…`, `plugin__…`). */
+const CURRENT_PREFIXED_RE = /^(mcp|plugin)__/;
+/** An rc connector or extension key `<x>__<tool>` (the SQL of migration 0063 uses the same test). */
+const LEGACY_PREFIXED_RE = /^[a-z0-9][a-z0-9_-]*__./;
+/**
+ * Is `key` an rc `<x>__<tool>` key, which only a {@link LegacyScope} can map? Keys in the current
+ * format (`mcp__…`, `plugin__…`) never are.
+ */
+export const isLegacyPrefixedKey = (key) => LEGACY_PREFIXED_RE.test(key) && !CURRENT_PREFIXED_RE.test(key);
+/**
+ * The current key of a release-candidate key: a builtin by the frozen map; `<x>__<tool>` becomes
+ * `mcp__x__tool` when `x` is only a connector slug in `scope`, `plugin__x__tool` when only an
+ * extension name, else null (ambiguous, unknown, or not an old key; a key in the current format
+ * is never mapped again).
+ */
+export function legacyToolKey(key, scope) {
+    if (isLegacyBuiltinKey(key))
+        return LEGACY_BUILTINS[key].name;
+    if (scope === undefined || !isLegacyPrefixedKey(key))
+        return null;
+    const i = key.indexOf("__");
+    if (i <= 0 || i + 2 >= key.length)
+        return null;
+    const head = key.slice(0, i);
+    const tool = key.slice(i + 2);
+    const connector = scope.connectorSlugs.has(head);
+    const extension = scope.extensionNames.has(head);
+    if (connector === extension)
+        return null;
+    return connector ? `mcp__${head}__${tool}` : `plugin__${head}__${tool}`;
+}
+/** The input of an old builtin call in the current parameter names (seconds -> milliseconds). */
+export function legacyToolInput(oldKey, input) {
+    if (!isLegacyBuiltinKey(oldKey))
+        return input;
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return input;
+    const { params, msParams } = LEGACY_BUILTINS[oldKey];
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        const next = Object.hasOwn(params, k) ? params[k] : k;
+        out[next] = msParams?.includes(next) === true && typeof v === "number" ? v * 1000 : v;
+    }
+    return out;
+}
+/** The new parameters of the builtins whose parameters were renamed (model-visible hint text). */
+const HINT_PARAMS = {
+    Bash: "command, description, timeout in milliseconds",
+    Read: "file_path, offset, limit",
+    Write: "file_path, content",
+    Edit: "file_path, old_string, new_string, replace_all",
+    Grep: "pattern, path, glob, -i, output_mode, -n, -A, -B, -C, head_limit, offset",
+    Deliver: "file_path, name",
+    Skill: "skill, args",
+    ToolSearch: "query, max_results",
+};
+/** The model-visible hint for a call to an old builtin key; null for any other key. */
+export function legacyHint(key) {
+    if (!isLegacyBuiltinKey(key))
+        return null;
+    const { name } = LEGACY_BUILTINS[key];
+    const params = HINT_PARAMS[name];
+    return `Tool "${key}" no longer exists; it is now "${name}"${params === undefined ? "" : ` (parameters: ${params})`}.`;
+}
+/**
+ * The current key(s) an rc key stands for, to name in a refusal when a definition is saved with
+ * it: a builtin's new name; for `<x>__<tool>`, the candidates among `known` (the agent's tool
+ * keys), else both `mcp__<x>__<tool>` and `plugin__<x>__<tool>`. Empty when `key` is no rc key.
+ */
+export function legacyKeyCandidates(key, known) {
+    if (isLegacyBuiltinKey(key))
+        return [LEGACY_BUILTINS[key].name];
+    if (!isLegacyPrefixedKey(key))
+        return [];
+    const all = [`mcp__${key}`, `plugin__${key}`];
+    const hit = all.filter((k) => known?.has(k) === true);
+    return hit.length > 0 ? hit : all;
+}
+/** The refusal text for saving rc key `key` (null when it is none): names the new key(s). */
+export function legacyKeySaveText(key, known) {
+    const c = legacyKeyCandidates(key, known);
+    if (c.length === 0)
+        return null;
+    return `"${key}" is a release-candidate tool key; use ${c.map((x) => `"${x}"`).join(" or ")}`;
+}

package/dist/tools/naming.d.ts

@@ -1,14 +1,12 @@
 /**
  * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
- * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 插件工具为 `plugin__<plugin>__<tool>`，连接器工具为 `mcp__<connectorSlug>__<tool>`（拼与拆见 SDK 的 tool-key.ts），内置工具就是其名字本身。
  * 超长或含非法字符的 key 一律报出来，不截断、不猜。
  */
 export declare const TOOL_KEY_RE: RegExp;
 export declare const TOOL_KEY_MAX = 64;
 /** 连接器 slug：小写字母开头，小写字母 / 数字 / 下划线，最长 24。 */
 export declare const APP_SLUG_RE: RegExp;
-/** 前缀与工具名之间的分隔符。 */
-export declare const KEY_SEPARATOR = "__";
 /**
  * slug 是否合法：除正则外，不得含连续下划线、不得以下划线结尾——否则 `a__b` + `c` 与 `a` + `b__c`
  * 会拼出同一个 key。
@@ -21,7 +19,5 @@ export declare const SLUG_RULE = "Slug must start with a lowercase letter, conta
  * 截到 24 位（再去掉尾部下划线）。推导不出合法 slug（如名称全是中文）时返回 null，由调用方要求显式给出。
  */
 export declare function deriveSlug(name: string): string | null;
-/** 拼 `<prefix>__<name>`。 */
-export declare function toolKey(prefix: string, name: string): string;
 /** key 不合法时返回英文原因，合法时返回 null。 */
 export declare function toolKeyIssue(key: string): string | null;

package/dist/tools/naming.js

@@ -1,14 +1,12 @@
 /**
  * 工具命名（Global Constraints）：模型可见的工具 key 必须匹配 `^[a-zA-Z0-9_-]{1,64}$`；
- * 插件工具为 `<plugin>__<tool>`，连接器工具为 `<connectorSlug>__<tool>`，内置工具就是其名字本身。
+ * 插件工具为 `plugin__<plugin>__<tool>`，连接器工具为 `mcp__<connectorSlug>__<tool>`（拼与拆见 SDK 的 tool-key.ts），内置工具就是其名字本身。
  * 超长或含非法字符的 key 一律报出来，不截断、不猜。
  */
 export const TOOL_KEY_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 export const TOOL_KEY_MAX = 64;
 /** 连接器 slug：小写字母开头，小写字母 / 数字 / 下划线，最长 24。 */
 export const APP_SLUG_RE = /^[a-z][a-z0-9_]{0,23}$/;
-/** 前缀与工具名之间的分隔符。 */
-export const KEY_SEPARATOR = "__";
 /**
  * slug 是否合法：除正则外，不得含连续下划线、不得以下划线结尾——否则 `a__b` + `c` 与 `a` + `b__c`
  * 会拼出同一个 key。
@@ -31,10 +29,6 @@ export function deriveSlug(name) {
         .replace(/_+$/, "");
     return isValidSlug(s) ? s : null;
 }
-/** 拼 `<prefix>__<name>`。 */
-export function toolKey(prefix, name) {
-    return `${prefix}${KEY_SEPARATOR}${name}`;
-}
 /** key 不合法时返回英文原因，合法时返回 null。 */
 export function toolKeyIssue(key) {
     if (key.length > TOOL_KEY_MAX) {

package/dist/tools/oauth/flow-paths.d.ts

@@ -6,7 +6,7 @@ export declare const OAUTH_STATE_TTL_SECONDS = 600;
 /** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
 export declare const OAUTH_BINDING_COOKIE = "cap_oauth";
 /** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
-export declare const DEFAULT_RETURN_PATH = "/settings/connections";
+export declare const DEFAULT_RETURN_PATH = "/account/connections";
 /** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
 export declare const publicUrlRequired: () => ApiError;
 export declare function callbackUrl(publicUrl: string): string;

package/dist/tools/oauth/flow-paths.js

@@ -8,7 +8,7 @@ export const OAUTH_STATE_TTL_SECONDS = 600;
 /** 浏览器绑定 Cookie：回调必须来自发起连接的同一个浏览器。 */
 export const OAUTH_BINDING_COOKIE = "cap_oauth";
 /** 回调失败、或连接时没给回跳页面时回到的网页（next-intl 会补语言前缀）。 */
-export const DEFAULT_RETURN_PATH = "/settings/connections";
+export const DEFAULT_RETURN_PATH = "/account/connections";
 /** OAuth 连接器需要 `http.publicUrl`（回调地址）；未配置 → 这条校验错误。 */
 export const publicUrlRequired = () => new ApiError("validation_failed", "Request validation failed", [
     {

package/dist/tools/oauth/flow.js

@@ -178,7 +178,7 @@ let OAuthFlow = class OAuthFlow {
                 redirect_uri: rec.redirectUri,
                 code_verifier: rec.verifier,
                 resource: client.resource,
-            }, oauthHttpOptions(this.config.get()));
+            }, oauthHttpOptions(this.config.get()), { tokenTypes: app.auth.tokenTypes });
         }
         catch (e) {
             this.log.warn("oauth code exchange failed", { orgId, connectorId, err: e });

package/dist/tools/oauth/tokens.d.ts

@@ -41,13 +41,24 @@ export type OAuthOwner = {
     kind: "user";
     accountId: string;
 };
-/** 令牌端点以 400 / 401 + RFC 6749 错误码明确拒绝（如 `invalid_grant`）。 */
+/**
+ * The token endpoint refused with an RFC 6749-shaped error code (`invalid_grant`, ...): a 400 / 401
+ * with `error`, or a 200 whose body carries `ok: false` (Slack) or an `error` and no token.
+ */
 export declare class OAuthGrantError extends Error {
     readonly error: string;
     constructor(error: string);
 }
-/** 这些错误码说明凭据本身已失效（refresh token / 客户端），只有它们才作废令牌。 */
+/**
+ * These codes say the credential itself is dead (refresh token / client); only they invalidate the
+ * tokens. Besides RFC 6749's, Slack's `invalid_refresh_token`, `token_revoked` and `token_expired`.
+ */
 export declare const INVALIDATING_ERRORS: ReadonlySet<string>;
+/**
+ * `token_type` values (lower case) stored and sent as `Authorization: Bearer`: RFC 6750 `Bearer`
+ * and Slack's `user` (`oauth.v2.user.access`). A template may allow more with `auth.tokenTypes`.
+ */
+export declare const BEARER_TOKEN_TYPES: ReadonlySet<string>;
 /** 授权服务器暂时不可用（网络、超时、5xx、畸形响应）：模型可见的英文说明，计入「服务不可用」。 */
 export declare class OAuthUnavailable extends ToolError {
     constructor(message?: string);
@@ -59,12 +70,46 @@ export declare class OAuthReconnectRequired extends Error {
 }
 /** access token 过期前多久就刷新。 */
 export declare const REFRESH_MARGIN_MS = 60000;
+/** What the connector's auth settings add to a token request. */
+export interface TokenRequestOptions {
+    /** More `token_type` values to accept as bearer tokens (`auth.tokenTypes`, case-insensitive). */
+    tokenTypes?: readonly string[] | undefined;
+}
+/**
+ * The headers and form of a token request (RFC 6749 §3.2): client_id / secret per the client's
+ * auth method (Basic form-encodes them first, §2.3.1; otherwise `client_id`, plus
+ * `client_secret` for `client_secret_post`). Empty parameters are left out.
+ */
+export declare function tokenRequestInit(client: OAuthClientRecord, params: Record<string, string | undefined>): {
+    headers: Record<string, string>;
+    body: URLSearchParams;
+};
+/** The form encoding of a Basic client credential part (RFC 6749 §2.3.1). */
+export declare const formEncode: (s: string) => string;
+/** The `Authorization` value of `client_secret_basic` (both parts form-encoded first). */
+export declare const basicClientAuth: (clientId: string, clientSecret: string) => string;
+/**
+ * The refusal code of a token endpoint answer, or null when it is not a refusal (the one parser of
+ * token refusals): a 400 / 401 whose JSON body has an RFC 6749-shaped `error`, or a 200 whose body
+ * carries `ok: false` (Slack) or an `error` and no `access_token`, with a code that is not
+ * transient. Only codes matching the RFC 6749 shape are returned, never other text of the body.
+ */
+export declare function parseTokenRefusal(status: number, body: unknown): string | null;
 /**
- * 调令牌端点（RFC 6749 §3.2）：按客户端认证方式带 client_id / secret（Basic 按 §2.3.1 先表单编码）。
- * 400 / 401 且正文带可解析的 RFC 6749 `error` 码 → OAuthGrantError；其余（网络错误、超时、429、408、
- * 403 等其他 4xx、没有错误码的 4xx、5xx、3xx、畸形响应）→ OAuthUnavailable——网关限流或 WAF 拦截不能当成凭据失效。
+ * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
+ * (Basic form-encodes them first, §2.3.1).
+ * - 400 / 401 with a parsable RFC 6749 `error` code -> OAuthGrantError.
+ * - 200 with `ok: false` (Slack reports every error this way), or with an `error` code and no
+ *   `access_token` -> OAuthGrantError with that code (`ok: false` wins over an `access_token`); a
+ *   transient code (`temporarily_unavailable`, `server_error`, Slack's `ratelimited`, ...) or no
+ *   parsable code -> OAuthUnavailable.
+ * - Everything else (network error, timeout, 429, 408, 403 and other 4xx, a 4xx without a code,
+ *   5xx, 3xx, a malformed body) -> OAuthUnavailable: a gateway's rate limit or a WAF block is not a
+ *   dead credential.
+ * - A `token_type` other than Bearer / `user` / `opts.tokenTypes` -> OAuthGrantError
+ *   `unsupported_token_type`; an accepted one is stored as `Bearer`.
  */
-export declare function tokenRequest(client: OAuthClientRecord, params: Record<string, string | undefined>, http: OAuthHttpOptions): Promise<OAuthTokenRecord>;
+export declare function tokenRequest(client: OAuthClientRecord, params: Record<string, string | undefined>, http: OAuthHttpOptions, opts?: TokenRequestOptions): Promise<OAuthTokenRecord>;
 /** 令牌与客户端的存取（由 Credentials 实现：信封加密存入 capybara.secrets）。 */
 export interface OAuthStore {
     readClient(orgId: string, connectorId: string): Promise<OAuthClientRecord | null>;
@@ -73,11 +118,13 @@ export interface OAuthStore {
     deleteTokens(orgId: string, connectorId: string, owner: OAuthOwner): Promise<void>;
 }
 /** 取 token 所需的认证方式字段（与 credentials.ts 的 OAuthAuth 对应）。 */
-export type TokenAuth = {
+export type TokenAuth = ({
     type: "oauth_code";
 } | {
     type: "oauth_client";
     scopes?: string[] | undefined;
+}) & {
+    tokenTypes?: string[] | undefined;
 };
 /**
  * access token 的获取与刷新。

package/dist/tools/oauth/tokens.js

@@ -1,7 +1,10 @@
 import { randomUUID } from "node:crypto";
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { OAuthSetupError, oauthFetch } from "./discovery.js";
-/** 令牌端点以 400 / 401 + RFC 6749 错误码明确拒绝（如 `invalid_grant`）。 */
+/**
+ * The token endpoint refused with an RFC 6749-shaped error code (`invalid_grant`, ...): a 400 / 401
+ * with `error`, or a 200 whose body carries `ok: false` (Slack) or an `error` and no token.
+ */
 export class OAuthGrantError extends Error {
     error;
     constructor(error) {
@@ -10,12 +13,37 @@ export class OAuthGrantError extends Error {
         this.name = "OAuthGrantError";
     }
 }
-/** 这些错误码说明凭据本身已失效（refresh token / 客户端），只有它们才作废令牌。 */
+/**
+ * These codes say the credential itself is dead (refresh token / client); only they invalidate the
+ * tokens. Besides RFC 6749's, Slack's `invalid_refresh_token`, `token_revoked` and `token_expired`.
+ */
 export const INVALIDATING_ERRORS = new Set([
     "invalid_grant",
     "invalid_client",
     "unauthorized_client",
+    "invalid_refresh_token",
+    "token_revoked",
+    "token_expired",
+]);
+/**
+ * Error codes of a 200 error body that mean "try again later", not a refusal: they count as
+ * unavailable like a 429 / 5xx. RFC 6749's `temporarily_unavailable` / `server_error` and Slack's
+ * Web API codes.
+ */
+const TRANSIENT_ERRORS = new Set([
+    "temporarily_unavailable",
+    "server_error",
+    "ratelimited",
+    "service_unavailable",
+    "internal_error",
+    "fatal_error",
+    "request_timeout",
 ]);
+/**
+ * `token_type` values (lower case) stored and sent as `Authorization: Bearer`: RFC 6750 `Bearer`
+ * and Slack's `user` (`oauth.v2.user.access`). A template may allow more with `auth.tokenTypes`.
+ */
+export const BEARER_TOKEN_TYPES = new Set(["bearer", "user"]);
 /** 授权服务器暂时不可用（网络、超时、5xx、畸形响应）：模型可见的英文说明，计入「服务不可用」。 */
 export class OAuthUnavailable extends ToolError {
     constructor(message = "Could not obtain an access token: the app's authorization server is unavailable. Try again later.") {
@@ -40,11 +68,11 @@ const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** RFC 6749 §5.2 形式的错误码（只有这种串才写进日志 / 错误，不回显对方任意文本）。 */
 const OAUTH_ERROR_RE = /^[a-z][a-z0-9_]{0,63}$/;
 /**
- * 调令牌端点（RFC 6749 §3.2）：按客户端认证方式带 client_id / secret（Basic 按 §2.3.1 先表单编码）。
- * 400 / 401 且正文带可解析的 RFC 6749 `error` 码 → OAuthGrantError；其余（网络错误、超时、429、408、
- * 403 等其他 4xx、没有错误码的 4xx、5xx、3xx、畸形响应）→ OAuthUnavailable——网关限流或 WAF 拦截不能当成凭据失效。
+ * The headers and form of a token request (RFC 6749 §3.2): client_id / secret per the client's
+ * auth method (Basic form-encodes them first, §2.3.1; otherwise `client_id`, plus
+ * `client_secret` for `client_secret_post`). Empty parameters are left out.
  */
-export async function tokenRequest(client, params, http) {
+export function tokenRequestInit(client, params) {
     const form = new URLSearchParams();
     for (const [k, v] of Object.entries(params))
         if (v !== undefined && v !== "")
@@ -54,8 +82,7 @@ export async function tokenRequest(client, params, http) {
         accept: "application/json",
     };
     if (client.authMethod === "client_secret_basic" && client.clientSecret !== undefined) {
-        const enc = (s) => encodeURIComponent(s).replace(/%20/g, "+");
-        headers.authorization = `Basic ${Buffer.from(`${enc(client.clientId)}:${enc(client.clientSecret)}`).toString("base64")}`;
+        headers.authorization = basicClientAuth(client.clientId, client.clientSecret);
     }
     else {
         form.set("client_id", client.clientId);
@@ -63,6 +90,46 @@ export async function tokenRequest(client, params, http) {
             form.set("client_secret", client.clientSecret);
         }
     }
+    return { headers, body: form };
+}
+/** The form encoding of a Basic client credential part (RFC 6749 §2.3.1). */
+export const formEncode = (s) => encodeURIComponent(s).replace(/%20/g, "+");
+/** The `Authorization` value of `client_secret_basic` (both parts form-encoded first). */
+export const basicClientAuth = (clientId, clientSecret) => `Basic ${Buffer.from(`${formEncode(clientId)}:${formEncode(clientSecret)}`).toString("base64")}`;
+/**
+ * The refusal code of a token endpoint answer, or null when it is not a refusal (the one parser of
+ * token refusals): a 400 / 401 whose JSON body has an RFC 6749-shaped `error`, or a 200 whose body
+ * carries `ok: false` (Slack) or an `error` and no `access_token`, with a code that is not
+ * transient. Only codes matching the RFC 6749 shape are returned, never other text of the body.
+ */
+export function parseTokenRefusal(status, body) {
+    const code = isObj(body) ? body.error : undefined;
+    const shaped = typeof code === "string" && OAUTH_ERROR_RE.test(code) ? code : null;
+    if (status === 400 || status === 401)
+        return shaped;
+    if (status !== 200 || !isObj(body))
+        return null;
+    if (body.ok === false || (body.access_token === undefined && body.error !== undefined)) {
+        return shaped !== null && !TRANSIENT_ERRORS.has(shaped) ? shaped : null;
+    }
+    return null;
+}
+/**
+ * Calls the token endpoint (RFC 6749 §3.2), sending client_id / secret per the client's auth method
+ * (Basic form-encodes them first, §2.3.1).
+ * - 400 / 401 with a parsable RFC 6749 `error` code -> OAuthGrantError.
+ * - 200 with `ok: false` (Slack reports every error this way), or with an `error` code and no
+ *   `access_token` -> OAuthGrantError with that code (`ok: false` wins over an `access_token`); a
+ *   transient code (`temporarily_unavailable`, `server_error`, Slack's `ratelimited`, ...) or no
+ *   parsable code -> OAuthUnavailable.
+ * - Everything else (network error, timeout, 429, 408, 403 and other 4xx, a 4xx without a code,
+ *   5xx, 3xx, a malformed body) -> OAuthUnavailable: a gateway's rate limit or a WAF block is not a
+ *   dead credential.
+ * - A `token_type` other than Bearer / `user` / `opts.tokenTypes` -> OAuthGrantError
+ *   `unsupported_token_type`; an accepted one is stored as `Bearer`.
+ */
+export async function tokenRequest(client, params, http, opts = {}) {
+    const { headers, body: form } = tokenRequestInit(client, params);
     let res;
     try {
         res = await oauthFetch(client.tokenEndpoint, { method: "POST", headers, body: form }, http);
@@ -79,18 +146,21 @@ export async function tokenRequest(client, params, http) {
     catch {
         body = undefined;
     }
-    if (res.status === 400 || res.status === 401) {
-        const code = isObj(body) ? body.error : undefined;
-        if (typeof code === "string" && OAUTH_ERROR_RE.test(code))
-            throw new OAuthGrantError(code);
-    }
+    const refusal = parseTokenRefusal(res.status, body);
+    if (refusal !== null)
+        throw new OAuthGrantError(refusal);
     if (res.status !== 200 || !isObj(body))
         throw new OAuthUnavailable();
+    // an error body without a usable code (or a transient one): unavailable, not a refusal
+    if (body.ok === false || (body.access_token === undefined && body.error !== undefined)) {
+        throw new OAuthUnavailable();
+    }
     const { access_token, refresh_token, expires_in, token_type, scope } = body;
     if (typeof access_token !== "string" || access_token === "")
         throw new OAuthUnavailable();
-    const type = typeof token_type === "string" ? token_type : "Bearer";
-    if (type.toLowerCase() !== "bearer")
+    const type = (typeof token_type === "string" ? token_type : "Bearer").toLowerCase();
+    const accepted = BEARER_TOKEN_TYPES.has(type) || opts.tokenTypes?.some((t) => t.toLowerCase() === type);
+    if (!accepted)
         throw new OAuthGrantError("unsupported_token_type");
     return {
         access_token,
@@ -229,14 +299,14 @@ export class OAuthTokens {
                     grant_type: "refresh_token",
                     refresh_token: rec.refresh_token,
                     resource: client.resource,
-                }, this.http());
+                }, this.http(), { tokenTypes: auth.tokenTypes });
                 // 授权服务器不轮换时沿用旧 refresh token
                 if (next.refresh_token === undefined)
                     next = { ...next, refresh_token: rec.refresh_token };
             }
             else {
                 const scopes = auth.scopes ?? client.scopes;
-                next = await tokenRequest(client, { grant_type: "client_credentials", scope: scopes?.join(" "), resource: client.resource }, this.http());
+                next = await tokenRequest(client, { grant_type: "client_credentials", scope: scopes?.join(" "), resource: client.resource }, this.http(), { tokenTypes: auth.tokenTypes });
             }
         }
         catch (e) {

package/dist/tools/org-tool-switches.d.ts

@@ -0,0 +1,89 @@
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+/** One tool of an extension with its switch in the org. */
+export interface OrgToolSwitch {
+    tool: string;
+    enabled: boolean;
+}
+/** An org agent whose current version selects the tool being switched off. */
+export interface AffectedAgent {
+    id: string;
+    name: string;
+}
+/**
+ * The result of {@link OrgToolSwitches.set}: the PCM §5 rule 8 preview of a switch-off (the org's
+ * agents that selected the tool and the hash to confirm it with), or the switch applied.
+ */
+export type OrgToolSwitchResult = {
+    applied: false;
+    affectedAgents: AffectedAgent[];
+    confirm: string;
+} | {
+    applied: true;
+};
+/** Model-visible (English): why a turned-off extension tool is not offered. */
+export declare const toolTurnedOffReason: (key: string) => string;
+/**
+ * Per-org switches of single extension tools (layering spec A §7, table `org_tool_switches`): an
+ * org admin turns off one tool an extension registers (`ctx.tools.register`); it is then not
+ * offered to any agent of the org (`ToolRegistry.forAgent`) and refused if called
+ * (`ToolPipeline`). No row means on. A row of a tool the extension stops registering is kept and
+ * applies again if the tool comes back. Builtin and connector tools are out of scope. Read from PG
+ * on every use, no in-process state.
+ */
+export declare class OrgToolSwitches {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly host;
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    private readonly orgLock;
+    constructor(kdb: KernelDb, txHost: TransactionHost, host: Pick<ExtensionHost, "tools" | "current">, 
+    /** The org row lock: re-checks `org.extensions.manage` under the lock. */
+    orgLock: Pick<OrgLock, "lockAndAuthorize">);
+    private get db();
+    /** The tool names `plugin` registers on this replica, in registration order. */
+    private registered;
+    /**
+     * The tools of an extension the org sees: running here and visible under plugin scope, else 404
+     * `extension.not_found` (an invisible one is answered like an unknown one). An extension that
+     * runs but registers no tools (a channel, a model provider) answers an empty list, not 404.
+     */
+    private toolsFor;
+    /** The stored switches of the org (all extensions, or one), `false` ones only matter. */
+    private offRows;
+    /** Every tool the extension registers on this replica with its switch (default on). */
+    list(orgId: string, plugin: string): Promise<OrgToolSwitch[]>;
+    /**
+     * What turning one tool off would affect (nothing written): the agents selecting it and the
+     * confirm hash {@link set} takes, or null when it is off already. Unknown tool -> 404
+     * `extension.tool_not_found`.
+     */
+    previewOff(orgId: string, plugin: string, tool: string): Promise<{
+        affectedAgents: AffectedAgent[];
+        confirm: string;
+    } | null>;
+    /** The model-visible keys (`plugin__<extension>__<tool>`) of the tools turned off in the org. */
+    offKeys(orgId: string): Promise<Set<string>>;
+    /** Whether the org turned off this tool. */
+    isToolOff(orgId: string, plugin: string, tool: string): Promise<boolean>;
+    /**
+     * Switches one tool in the org. On applies at once. Off, while the tool is on: without
+     * `confirm` the preview (the org's agents whose current version does not turn it off) and its hash,
+     * with the current hash the switch is written (a changed preview -> 409 `plugin.switch_stale`).
+     * A tool the extension does not register -> 404 `extension.tool_not_found`. A change writes the
+     * audit row `extension.tool_switched`.
+     */
+    set(orgId: string, plugin: string, tool: string, enabled: boolean, actor: {
+        accountId: string;
+        tokenId?: string | undefined;
+        /** Merged into the audit detail (a write made through the Platform tool). */
+        auditDetail?: Record<string, unknown>;
+    }, confirm?: string): Promise<OrgToolSwitchResult>;
+    /**
+     * The org's live agents whose current version has extension tool `tool` of `plugin` on: tools
+     * are on by default (tools default-on spec §4), so every agent that does not turn it off.
+     */
+    private agentsSelecting;
+}