@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,31 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+import type { KernelConfig } from "../../config/schema.js";
+import { type Principal } from "../../identity/principal.js";
+import { type OrgContext } from "../../orgs/org.guard.js";
+import { type OAuthFlow } from "./flow.js";
+declare const ConnectBody: z.ZodObject<{
+    returnTo: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 发起 OAuth 连接（`POST /orgs/:orgId/connectors/:connectorId/connect`，`connectors.use`，仅用户主体）：返回授权 URL，并写浏览器绑定
+ * Cookie `cap_oauth`（HttpOnly、SameSite=Lax——授权服务器回跳是跨站顶级 GET 导航、Lax 会带上；Path 只到回调）。
+ */
+export declare class OAuthConnectController {
+    private readonly flow;
+    private readonly config;
+    constructor(flow: OAuthFlow, config: () => KernelConfig);
+    connect(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof ConnectBody>, req: FastifyRequest, reply: FastifyReply): Promise<{
+        authorizationUrl: string;
+    }>;
+}
+/**
+ * 授权服务器的回跳（`GET /api/v1/oauth/callback`，公开路由：浏览器从授权服务器跳回来，会话 Cookie 可能已过期；
+ * 身份由 state 与浏览器绑定 Cookie 确定）。总是 302 回网页，结果放在 `connected` / `oauth_error` 参数里。
+ */
+export declare class OAuthCallbackController {
+    private readonly flow;
+    constructor(flow: OAuthFlow);
+    callback(q: Record<string, unknown>, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+}
+export {};

package/dist/tools/oauth/oauth.controller.js

@@ -0,0 +1,95 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Body, Controller, Get, HttpCode, Inject, Param, Post, Query, Req, Res, } from "@nestjs/common";
+import { z } from "zod";
+import { KERNEL_CONFIG, OAUTH_FLOW } from "../../http/tokens.js";
+import { ZodPipe } from "../../http/zod.pipe.js";
+import { CurrentPrincipal, Public, requireUser } from "../../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../../orgs/org.guard.js";
+import { browserBinding, isSafeReturnPath, OAUTH_BINDING_COOKIE, OAUTH_CALLBACK_PATH, OAUTH_STATE_TTL_SECONDS, } from "./flow.js";
+const ConnectBody = z
+    .object({
+    returnTo: z
+        .string()
+        .max(500)
+        .refine(isSafeReturnPath, { message: "returnTo must be a relative path on this site" })
+        .optional(),
+})
+    .strict();
+/** 查询参数只取单值字符串（重复参数 / 数组按缺失处理）。 */
+const one = (v) => typeof v === "string" && v.length <= 4096 ? v : undefined;
+/**
+ * 发起 OAuth 连接（`POST /orgs/:orgId/connectors/:connectorId/connect`，`connectors.use`，仅用户主体）：返回授权 URL，并写浏览器绑定
+ * Cookie `cap_oauth`（HttpOnly、SameSite=Lax——授权服务器回跳是跨站顶级 GET 导航、Lax 会带上；Path 只到回调）。
+ */
+let OAuthConnectController = class OAuthConnectController {
+    flow;
+    config;
+    constructor(flow, config) {
+        this.flow = flow;
+        this.config = config;
+    }
+    async connect(principal, org, connectorId, body, req, reply) {
+        const p = requireUser(principal);
+        const binding = browserBinding(req.cookies[OAUTH_BINDING_COOKIE]);
+        const out = await this.flow.start(org.orgId, connectorId, p.account.id, body.returnTo, binding);
+        reply.setCookie(OAUTH_BINDING_COOKIE, binding, {
+            path: OAUTH_CALLBACK_PATH,
+            httpOnly: true,
+            sameSite: "lax",
+            secure: this.config().auth.cookieSecure,
+            maxAge: OAUTH_STATE_TTL_SECONDS,
+        });
+        return out;
+    }
+};
+__decorate([
+    Post(":connectorId/connect"),
+    HttpCode(200),
+    OrgAction("connectors.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("connectorId")),
+    __param(3, Body(new ZodPipe(ConnectBody))),
+    __param(4, Req()),
+    __param(5, Res({ passthrough: true }))
+], OAuthConnectController.prototype, "connect", null);
+OAuthConnectController = __decorate([
+    Controller("api/v1/orgs/:orgId/connectors"),
+    __param(0, Inject(OAUTH_FLOW)),
+    __param(1, Inject(KERNEL_CONFIG))
+], OAuthConnectController);
+export { OAuthConnectController };
+/**
+ * 授权服务器的回跳（`GET /api/v1/oauth/callback`，公开路由：浏览器从授权服务器跳回来，会话 Cookie 可能已过期；
+ * 身份由 state 与浏览器绑定 Cookie 确定）。总是 302 回网页，结果放在 `connected` / `oauth_error` 参数里。
+ */
+let OAuthCallbackController = class OAuthCallbackController {
+    flow;
+    constructor(flow) {
+        this.flow = flow;
+    }
+    async callback(q, req, reply) {
+        const location = await this.flow.callback({ code: one(q.code), state: one(q.state), error: one(q.error), iss: one(q.iss) }, req.cookies[OAUTH_BINDING_COOKIE]);
+        await reply.header("cache-control", "no-store").redirect(location, 302);
+    }
+};
+__decorate([
+    Get("callback"),
+    Public(),
+    __param(0, Query()),
+    __param(1, Req()),
+    __param(2, Res())
+], OAuthCallbackController.prototype, "callback", null);
+OAuthCallbackController = __decorate([
+    Controller("api/v1/oauth"),
+    __param(0, Inject(OAUTH_FLOW))
+], OAuthCallbackController);
+export { OAuthCallbackController };

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

@@ -0,0 +1,111 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { type OAuthHttpOptions } from "./discovery.js";
+export type TokenAuthMethod = "client_secret_basic" | "client_secret_post" | "none";
+/**
+ * 一个连接器的 OAuth 客户端（组织级凭据，键 `credentials:app:<connectorId>:client`）：DCR 注册所得或管理员手填，
+ * 连同发现得到的端点与资源标识。
+ */
+export interface OAuthClientRecord {
+    clientId: string;
+    clientSecret?: string;
+    authMethod: TokenAuthMethod;
+    /** 授权码流才有。 */
+    authorizationEndpoint?: string;
+    tokenEndpoint: string;
+    /** RFC 8707 `resource` 参数（MCP 发现所得）。 */
+    resource?: string;
+    scopes?: string[];
+    /** 授权服务器标识（MCP 发现所得）：回调带 RFC 9207 `iss` 时与它核对。 */
+    issuer?: string;
+    /** DCR 返回的注册信息（`registration_access_token` 为密钥）。 */
+    registration?: {
+        accessToken?: string;
+        clientUri?: string;
+        issuedAt?: number;
+    };
+}
+/** 令牌（个人凭据：授权码流；组织凭据：客户端凭据流的缓存）。`expires_at` 为毫秒时间戳，null = 未告知。 */
+export interface OAuthTokenRecord {
+    access_token: string;
+    refresh_token?: string;
+    expires_at: number | null;
+    token_type: string;
+    scope?: string;
+}
+export type OAuthOwner = {
+    kind: "org";
+} | {
+    kind: "user";
+    accountId: string;
+};
+/** 令牌端点以 400 / 401 + RFC 6749 错误码明确拒绝（如 `invalid_grant`）。 */
+export declare class OAuthGrantError extends Error {
+    readonly error: string;
+    constructor(error: string);
+}
+/** 这些错误码说明凭据本身已失效（refresh token / 客户端），只有它们才作废令牌。 */
+export declare const INVALIDATING_ERRORS: ReadonlySet<string>;
+/** 授权服务器暂时不可用（网络、超时、5xx、畸形响应）：模型可见的英文说明，计入「服务不可用」。 */
+export declare class OAuthUnavailable extends ToolError {
+    constructor(message?: string);
+}
+/** 刷新失败且已把凭据删除：需要（重新）连接。Credentials 把它换成 CredentialMissing。 */
+export declare class OAuthReconnectRequired extends Error {
+    readonly owner: OAuthOwner;
+    constructor(owner: OAuthOwner);
+}
+/** access token 过期前多久就刷新。 */
+export declare const REFRESH_MARGIN_MS = 60000;
+/**
+ * 调令牌端点（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 拦截不能当成凭据失效。
+ */
+export declare function tokenRequest(client: OAuthClientRecord, params: Record<string, string | undefined>, http: OAuthHttpOptions): Promise<OAuthTokenRecord>;
+/** 令牌与客户端的存取（由 Credentials 实现：信封加密存入 capybara.secrets）。 */
+export interface OAuthStore {
+    readClient(orgId: string, connectorId: string): Promise<OAuthClientRecord | null>;
+    readTokens(orgId: string, connectorId: string, owner: OAuthOwner): Promise<OAuthTokenRecord | null>;
+    writeTokens(orgId: string, connectorId: string, owner: OAuthOwner, rec: OAuthTokenRecord): Promise<void>;
+    deleteTokens(orgId: string, connectorId: string, owner: OAuthOwner): Promise<void>;
+}
+/** 取 token 所需的认证方式字段（与 credentials.ts 的 OAuthAuth 对应）。 */
+export type TokenAuth = {
+    type: "oauth_code";
+} | {
+    type: "oauth_client";
+    scopes?: string[] | undefined;
+};
+/**
+ * access token 的获取与刷新。
+ *
+ * - 调用前：未过期（距过期 > 60 秒或未告知过期时间）直接用；否则刷新（授权码流用 refresh token，客户端凭据流重新取）。
+ * - 收到 401：`forceRefresh(stale)`——只要库里的 token 仍是收到 401 的那个就刷新。
+ * - 刷新一律在 Redis 锁 `capk:oauth-refresh:<orgId>:<connectorId>:<owner>` 内进行（SET NX PX，值为本次随机 id，
+ *   只删除自己持有的锁）；拿不到锁的轮询等锁消失后重读凭据，库里已是别的 token 就直接用（不并发刷新——授权服务器
+ *   轮换 refresh token 时，并发刷新的第二个必然失败）。
+ * - 令牌端点明确拒绝 → 删除该凭据并抛 OAuthReconnectRequired（需要重新连接）；暂时不可用 → OAuthUnavailable，凭据保留。
+ */
+export declare class OAuthTokens {
+    private readonly store;
+    private readonly redis;
+    private readonly http;
+    private readonly log;
+    constructor(store: OAuthStore, redis: Redis, http: () => OAuthHttpOptions, log: Logger);
+    accessToken(orgId: string, connectorId: string, auth: TokenAuth, owner: OAuthOwner): Promise<string>;
+    /** 收到 401 后调用：`stale` 为收到 401 的那个 access token。 */
+    forceRefresh(orgId: string, connectorId: string, auth: TokenAuth, owner: OAuthOwner, stale: string | undefined): Promise<void>;
+    private lockKey;
+    /**
+     * 换掉 `stale`（null = 库里还没有 token）：锁内先重读，已被别人换掉就直接用；否则向令牌端点要新的。
+     * 锁的 TTL = 往返限时 + 5 秒，持有者崩溃后锁自然过期；等锁最多一个 TTL。
+     */
+    private renew;
+    /**
+     * 锁内：向令牌端点要新 token 并写回。作废前做围栏检查：锁仍归自己、库里的 token 仍是这次用掉的那组——
+     * 锁过期后另一个刷新者若已写入新 token，就直接用它而不是删掉它。
+     */
+    private obtain;
+}

package/dist/tools/oauth/tokens.js

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { OAuthSetupError, oauthFetch } from "./discovery.js";
+/** 令牌端点以 400 / 401 + RFC 6749 错误码明确拒绝（如 `invalid_grant`）。 */
+export class OAuthGrantError extends Error {
+    error;
+    constructor(error) {
+        super(`The authorization server rejected the token request (${error})`);
+        this.error = error;
+        this.name = "OAuthGrantError";
+    }
+}
+/** 这些错误码说明凭据本身已失效（refresh token / 客户端），只有它们才作废令牌。 */
+export const INVALIDATING_ERRORS = new Set([
+    "invalid_grant",
+    "invalid_client",
+    "unauthorized_client",
+]);
+/** 授权服务器暂时不可用（网络、超时、5xx、畸形响应）：模型可见的英文说明，计入「服务不可用」。 */
+export class OAuthUnavailable extends ToolError {
+    constructor(message = "Could not obtain an access token: the app's authorization server is unavailable. Try again later.") {
+        super(message, { kind: "unavailable" });
+        this.name = "OAuthUnavailable";
+    }
+}
+/** 刷新失败且已把凭据删除：需要（重新）连接。Credentials 把它换成 CredentialMissing。 */
+export class OAuthReconnectRequired extends Error {
+    owner;
+    constructor(owner) {
+        super("The OAuth credential is invalid and must be connected again");
+        this.owner = owner;
+        this.name = "OAuthReconnectRequired";
+    }
+}
+/** access token 过期前多久就刷新。 */
+export const REFRESH_MARGIN_MS = 60_000;
+/** 等锁时的轮询间隔（本进程自己的等待）。 */
+const LOCK_POLL_MS = 50;
+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 拦截不能当成凭据失效。
+ */
+export async function tokenRequest(client, params, http) {
+    const form = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined && v !== "")
+            form.set(k, v);
+    const headers = {
+        "content-type": "application/x-www-form-urlencoded",
+        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")}`;
+    }
+    else {
+        form.set("client_id", client.clientId);
+        if (client.authMethod === "client_secret_post" && client.clientSecret !== undefined) {
+            form.set("client_secret", client.clientSecret);
+        }
+    }
+    let res;
+    try {
+        res = await oauthFetch(client.tokenEndpoint, { method: "POST", headers, body: form }, http);
+    }
+    catch (e) {
+        if (e instanceof OAuthSetupError)
+            throw e;
+        throw new OAuthUnavailable();
+    }
+    let body;
+    try {
+        body = JSON.parse(res.text);
+    }
+    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);
+    }
+    if (res.status !== 200 || !isObj(body))
+        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")
+        throw new OAuthGrantError("unsupported_token_type");
+    return {
+        access_token,
+        ...(typeof refresh_token === "string" && refresh_token !== "" && { refresh_token }),
+        expires_at: typeof expires_in === "number" && Number.isFinite(expires_in) && expires_in > 0
+            ? Date.now() + expires_in * 1000
+            : null,
+        token_type: "Bearer",
+        ...(typeof scope === "string" && { scope }),
+    };
+}
+const RELEASE = `
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+  return redis.call('DEL', KEYS[1])
+end
+return 0
+`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * access token 的获取与刷新。
+ *
+ * - 调用前：未过期（距过期 > 60 秒或未告知过期时间）直接用；否则刷新（授权码流用 refresh token，客户端凭据流重新取）。
+ * - 收到 401：`forceRefresh(stale)`——只要库里的 token 仍是收到 401 的那个就刷新。
+ * - 刷新一律在 Redis 锁 `capk:oauth-refresh:<orgId>:<connectorId>:<owner>` 内进行（SET NX PX，值为本次随机 id，
+ *   只删除自己持有的锁）；拿不到锁的轮询等锁消失后重读凭据，库里已是别的 token 就直接用（不并发刷新——授权服务器
+ *   轮换 refresh token 时，并发刷新的第二个必然失败）。
+ * - 令牌端点明确拒绝 → 删除该凭据并抛 OAuthReconnectRequired（需要重新连接）；暂时不可用 → OAuthUnavailable，凭据保留。
+ */
+export class OAuthTokens {
+    store;
+    redis;
+    http;
+    log;
+    constructor(store, redis, http, log) {
+        this.store = store;
+        this.redis = redis;
+        this.http = http;
+        this.log = log;
+    }
+    async accessToken(orgId, connectorId, auth, owner) {
+        const rec = await this.store.readTokens(orgId, connectorId, owner);
+        if (rec) {
+            const fresh = rec.expires_at === null || rec.expires_at - Date.now() > REFRESH_MARGIN_MS;
+            // 没有 refresh token 的授权码凭据无法提前刷新：照用，过期由服务端 401 → forceRefresh 处理
+            if (fresh || (auth.type === "oauth_code" && rec.refresh_token === undefined)) {
+                return rec.access_token;
+            }
+        }
+        else if (auth.type === "oauth_code") {
+            throw new OAuthReconnectRequired(owner);
+        }
+        return this.renew(orgId, connectorId, auth, owner, rec?.access_token ?? null);
+    }
+    /** 收到 401 后调用：`stale` 为收到 401 的那个 access token。 */
+    async forceRefresh(orgId, connectorId, auth, owner, stale) {
+        const current = stale ?? (await this.store.readTokens(orgId, connectorId, owner))?.access_token;
+        if (current === undefined && auth.type === "oauth_code")
+            throw new OAuthReconnectRequired(owner);
+        await this.renew(orgId, connectorId, auth, owner, current ?? null);
+    }
+    lockKey(orgId, connectorId, owner) {
+        return `capk:oauth-refresh:${orgId}:${connectorId}:${owner.kind === "org" ? "org" : owner.accountId}`;
+    }
+    /**
+     * 换掉 `stale`（null = 库里还没有 token）：锁内先重读，已被别人换掉就直接用；否则向令牌端点要新的。
+     * 锁的 TTL = 往返限时 + 5 秒，持有者崩溃后锁自然过期；等锁最多一个 TTL。
+     */
+    async renew(orgId, connectorId, auth, owner, stale) {
+        const key = this.lockKey(orgId, connectorId, owner);
+        const ttlMs = this.http().timeoutMs + 5_000;
+        const deadline = Date.now() + ttlMs * 2;
+        const replaced = (rec) => rec !== null && rec.access_token !== stale ? rec.access_token : undefined;
+        for (;;) {
+            const id = randomUUID();
+            if ((await this.redis.set(key, id, "PX", ttlMs, "NX")) === "OK") {
+                try {
+                    const rec = await this.store.readTokens(orgId, connectorId, owner);
+                    const done = replaced(rec);
+                    if (done !== undefined)
+                        return done;
+                    if (rec === null && auth.type === "oauth_code")
+                        throw new OAuthReconnectRequired(owner);
+                    return await this.obtain(orgId, connectorId, auth, owner, rec, key, id);
+                }
+                finally {
+                    await this.redis.eval(RELEASE, 1, key, id).catch((err) => {
+                        this.log.warn("oauth refresh lock release failed", { connectorId, err });
+                    });
+                }
+            }
+            // 别的副本 / 请求正在刷新：等锁消失后重读
+            while ((await this.redis.exists(key)) === 1 && Date.now() < deadline)
+                await sleep(LOCK_POLL_MS);
+            const rec = await this.store.readTokens(orgId, connectorId, owner);
+            const done = replaced(rec);
+            if (done !== undefined)
+                return done;
+            if (rec === null && auth.type === "oauth_code")
+                throw new OAuthReconnectRequired(owner);
+            if (Date.now() >= deadline)
+                throw new OAuthUnavailable();
+        }
+    }
+    /**
+     * 锁内：向令牌端点要新 token 并写回。作废前做围栏检查：锁仍归自己、库里的 token 仍是这次用掉的那组——
+     * 锁过期后另一个刷新者若已写入新 token，就直接用它而不是删掉它。
+     */
+    async obtain(orgId, connectorId, auth, owner, rec, lockKey, lockId) {
+        const client = await this.store.readClient(orgId, connectorId);
+        if (!client)
+            throw new OAuthReconnectRequired({ kind: "org" });
+        const invalidate = async (reason) => {
+            const current = await this.store.readTokens(orgId, connectorId, owner);
+            const unchanged = current !== null &&
+                rec !== null &&
+                current.access_token === rec.access_token &&
+                current.refresh_token === rec.refresh_token;
+            if (current !== null && !unchanged)
+                return current.access_token;
+            if (current !== null && (await this.redis.get(lockKey)) !== lockId) {
+                // 锁已不归自己（过期）：不删，交给持锁者；这次按暂时不可用处理
+                throw new OAuthUnavailable();
+            }
+            if (current !== null)
+                await this.store.deleteTokens(orgId, connectorId, owner);
+            this.log.warn("oauth credential invalidated", { connectorId, owner: owner.kind, reason });
+            throw new OAuthReconnectRequired(owner);
+        };
+        let next;
+        try {
+            if (auth.type === "oauth_code") {
+                if (rec?.refresh_token === undefined)
+                    return await invalidate("no_refresh_token");
+                next = await tokenRequest(client, {
+                    grant_type: "refresh_token",
+                    refresh_token: rec.refresh_token,
+                    resource: client.resource,
+                }, this.http());
+                // 授权服务器不轮换时沿用旧 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());
+            }
+        }
+        catch (e) {
+            if (e instanceof OAuthGrantError) {
+                if (INVALIDATING_ERRORS.has(e.error))
+                    return invalidate(e.error);
+                // invalid_scope / invalid_request 等：配置问题，凭据保留
+                this.log.warn("oauth token request rejected", { connectorId, error: e.error });
+                throw new OAuthUnavailable(`Could not obtain an access token: the authorization server rejected the request (${e.error}). Ask an administrator to check the app.`);
+            }
+            if (e instanceof OAuthUnavailable)
+                throw e;
+            // URL 校验失败等（配置问题）：按不可用处理，不删凭据
+            this.log.warn("oauth token request failed", { connectorId, err: e });
+            throw new OAuthUnavailable();
+        }
+        await this.store.writeTokens(orgId, connectorId, owner, next);
+        return next.access_token;
+    }
+}

package/dist/tools/outputs.d.ts

@@ -0,0 +1,61 @@
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+/** 文本行数（按 `\n` 切分；空串算 1 行，与按行分页读取一致）。 */
+export declare function countLines(s: string): number;
+export interface SavedOutput {
+    id: string;
+    sizeChars: number;
+    lineCount: number;
+}
+/** 读存档的范围：只能读产生它的那个会话（且组织一致）的存档。 */
+export interface OutputScope {
+    orgId: string;
+    conversationId: string;
+}
+/**
+ * 输出存档（spec 5.4）：超大工具结果的全文存进 `capybara.tool_outputs`，保留 `tools.outputRetentionDays` 天。
+ * 只能在产生它的会话里读取（同组织别的会话也不行：会话之间可见范围不同），过期即视为不存在（清理由维护任务负责）。
+ */
+export declare class ToolOutputs {
+    private readonly db;
+    private readonly config;
+    constructor(db: KernelDb, config: () => KernelConfig);
+    save(a: {
+        orgId: string;
+        conversationId: string;
+        callId: string;
+        content: string;
+    }): Promise<SavedOutput>;
+    /** 读本会话未过期的存档全文；不存在 / 过期 / 属于别的会话或组织 → null。 */
+    load(scope: OutputScope, id: string): Promise<string | null>;
+}
+/** 存档不存在 / 过期 / 不属于本会话（模型可见，英文；不区分几种情况，不泄露别处的存档是否存在）。 */
+export declare const outputNotFoundText: (id: string) => string;
+/**
+ * 管线第 1 阶段：把参数中任意位置的 `{"$output": "<id>"}`（对象恰好只有这一个键）替换为该存档全文。
+ * 不存在 / 过期 / 不属于本会话 → `ToolError`（给模型看的英文）。不修改传入的对象。
+ */
+export declare function resolveOutputRefs(input: unknown, load: (id: string) => Promise<string | null>): Promise<unknown>;
+export interface RenderedResult {
+    /** 模型看到的文本（尚未转存）。 */
+    text: string;
+    /** 结果里出现的内容类型（按首次出现的顺序）。 */
+    contentTypes: string[];
+    isError: boolean;
+}
+/**
+ * 管线第 5 阶段（渲染）：文本块按行拼接；图片 → `[image <mimeType>, <n> bytes]`（M3 不把图片回传模型）；
+ * `resource_link` → `[resource <uri>]`；未知块 → `[unsupported content <type>]`。
+ * 畸形结果（不是对象、content 不是数组）给出说明并标为错误，不抛错（Review Focus 5）。
+ */
+export declare function renderResult(result: unknown): RenderedResult;
+/**
+ * 管线第 5 阶段（转存）：超过 `spillChars` 的文本存为输出存档，模型只见前 `previewChars` 个字符与截断说明。
+ */
+export declare function spillIfLarge(text: string, opts: {
+    spillChars: number;
+    previewChars: number;
+}, save: (content: string) => Promise<SavedOutput>): Promise<{
+    content: string;
+    outputId?: string;
+}>;