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

package/dist/sandbox/unreachable.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a provider call failed to reach the provider: `connect` when no connection was made (the
+ * request never reached the provider, so it did nothing), `dropped` when an open connection broke
+ * (the provider may have acted before it broke).
+ */
+export type ProviderConnectionFailure = "connect" | "dropped";
+/**
+ * Whether `e` is a network-level failure to reach the provider, and which kind. Providers may
+ * wrap the socket error (`fetch failed` with a `cause`, an `AggregateError` of one error per
+ * address, an SDK error with a `cause`), so the cause chain and `errors` are searched. The
+ * provider's own verdicts (`SandboxGoneError`, `FileSystemGoneError`) are never connection
+ * failures.
+ */
+export declare function providerConnectionFailure(e: unknown, depth?: number): ProviderConnectionFailure | undefined;
+/**
+ * A sandbox provider call that could not reach the provider (the socket proxy, the Docker daemon,
+ * the E2B API is down or misaddressed). An ordinary error to the sandbox lifecycle (never "gone":
+ * a network blip must not rebuild the instance); the tools turn it into an actionable tool error.
+ * `cause` is the provider's error, unchanged.
+ */
+export declare class SandboxProviderUnreachableError extends Error {
+    readonly failure: ProviderConnectionFailure;
+    constructor(failure: ProviderConnectionFailure, cause: unknown);
+}
+/**
+ * `impl` with every method's network-level failure rethrown as
+ * {@link SandboxProviderUnreachableError} (other errors and results unchanged): the one place a
+ * provider's connection failure is told apart from the kernel's own (database, Redis) failures.
+ */
+export declare function guardProviderConnection<P extends object>(impl: P): P;

package/dist/sandbox/unreachable.js

@@ -0,0 +1,108 @@
+import { isFileSystemGoneError, isSandboxGoneError } from "@capybara-hq/plugin-sdk";
+/** Codes of a connection that was never made (node `net` / `dns`, undici). */
+const CONNECT_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "EHOSTDOWN",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+/** Codes of a connection that broke after it was made. */
+const DROPPED_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EPIPE",
+    "ECONNABORTED",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CLOSED",
+]);
+/** System calls that open a connection: any error code they fail with means no connection. */
+const CONNECT_SYSCALLS = new Set(["connect", "getaddrinfo"]);
+const MAX_DEPTH = 5;
+/**
+ * Whether `e` is a network-level failure to reach the provider, and which kind. Providers may
+ * wrap the socket error (`fetch failed` with a `cause`, an `AggregateError` of one error per
+ * address, an SDK error with a `cause`), so the cause chain and `errors` are searched. The
+ * provider's own verdicts (`SandboxGoneError`, `FileSystemGoneError`) are never connection
+ * failures.
+ */
+export function providerConnectionFailure(e, depth = 0) {
+    if (depth > MAX_DEPTH || typeof e !== "object" || e === null)
+        return undefined;
+    if (isSandboxGoneError(e) || isFileSystemGoneError(e))
+        return undefined;
+    const { code, syscall, message, cause, errors } = e;
+    if (typeof code === "string") {
+        if (CONNECT_CODES.has(code))
+            return "connect";
+        if (typeof syscall === "string" && CONNECT_SYSCALLS.has(syscall))
+            return "connect";
+        if (DROPPED_CODES.has(code))
+            return "dropped";
+    }
+    if (typeof message === "string" && /socket hang up/i.test(message))
+        return "dropped";
+    let found;
+    if (Array.isArray(errors)) {
+        for (const inner of errors) {
+            const f = providerConnectionFailure(inner, depth + 1);
+            if (f === "dropped")
+                return f;
+            found ??= f;
+        }
+    }
+    return found ?? providerConnectionFailure(cause, depth + 1);
+}
+/**
+ * A sandbox provider call that could not reach the provider (the socket proxy, the Docker daemon,
+ * the E2B API is down or misaddressed). An ordinary error to the sandbox lifecycle (never "gone":
+ * a network blip must not rebuild the instance); the tools turn it into an actionable tool error.
+ * `cause` is the provider's error, unchanged.
+ */
+export class SandboxProviderUnreachableError extends Error {
+    failure;
+    constructor(failure, cause) {
+        const why = cause instanceof Error ? cause.message : String(cause);
+        super(`sandbox provider ${failure === "connect" ? "unreachable" : "connection dropped"}: ${why}`, { cause });
+        this.failure = failure;
+        this.name = "SandboxProviderUnreachableError";
+    }
+}
+function converted(e) {
+    if (e instanceof SandboxProviderUnreachableError)
+        return e;
+    const failure = providerConnectionFailure(e);
+    return failure === undefined ? e : new SandboxProviderUnreachableError(failure, e);
+}
+/**
+ * `impl` with every method's network-level failure rethrown as
+ * {@link SandboxProviderUnreachableError} (other errors and results unchanged): the one place a
+ * provider's connection failure is told apart from the kernel's own (database, Redis) failures.
+ */
+export function guardProviderConnection(impl) {
+    return new Proxy(impl, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            return (...args) => {
+                let r;
+                try {
+                    r = value.apply(target, args);
+                }
+                catch (e) {
+                    throw converted(e);
+                }
+                if (r instanceof Promise) {
+                    return r.catch((e) => {
+                        throw converted(e);
+                    });
+                }
+                return r;
+            };
+        },
+    });
+}

package/dist/setup/kernel-checks.d.ts

@@ -0,0 +1,91 @@
+import { type SetupCheckResult, type SetupCheckText } from "@capybara-hq/plugin-sdk";
+import { type OnModuleInit } from "@nestjs/common";
+import type { Redis } from "ioredis";
+import { webhookBase } from "../channels/webhook-url.js";
+import type { KernelConfig } from "../config/schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { Credentials } from "../tools/credentials.js";
+import { SetupCheckRegistry } from "./setup-check-registry.js";
+/** The fixed texts of the kernel checks (only `last_error` and a time are ever interpolated). */
+export declare const KERNEL_CHECK_TEXTS: {
+    readonly publicUrlSet: SetupCheckText;
+    readonly publicUrlMissing: SetupCheckText;
+    readonly publicUrlFix: SetupCheckText;
+    readonly webhookPublic: SetupCheckText;
+    readonly webhookBaseMissing: SetupCheckText;
+    readonly webhookBaseFix: SetupCheckText;
+    readonly webhookNone: SetupCheckText;
+    readonly connectionGone: SetupCheckText;
+    readonly connectionDisabled: SetupCheckText;
+    readonly connectionEnableFix: SetupCheckText;
+    readonly connectionFailed: SetupCheckText;
+    readonly connectionFix: SetupCheckText;
+    readonly connectionPending: SetupCheckText;
+    readonly connectionActive: SetupCheckText;
+    readonly connectorGone: SetupCheckText;
+    readonly notOAuthCode: SetupCheckText;
+    readonly dcr: SetupCheckText;
+    readonly clientStored: SetupCheckText;
+    readonly clientMissing: SetupCheckText;
+    readonly clientFix: SetupCheckText;
+    readonly noClient: SetupCheckText;
+    readonly toolsRead: SetupCheckText;
+    readonly toolsPending: SetupCheckText;
+    readonly connected: SetupCheckText;
+    readonly notConnected: SetupCheckText;
+    readonly connectFix: SetupCheckText;
+    readonly publicUrlFirst: SetupCheckText;
+};
+/** `capybara:public-url`: `http.publicUrl` is set. */
+export declare function publicUrlCheck(config: Pick<KernelConfig, "http">): SetupCheckResult;
+/**
+ * `capybara:webhook-public`: webhook callback URLs have a usable https base. The kernel builds
+ * them from `channels.webhookBaseUrl` only (`webhook-url.ts`), never from `http.publicUrl`, so
+ * that is what is checked; a loopback http base (tests only) is not public.
+ */
+export declare function webhookPublicCheck(config: Parameters<typeof webhookBase>[0]): SetupCheckResult;
+/** `capybara:webhook-received`: the marker the gateway sets on an accepted webhook, or none. */
+export declare function webhookReceivedResult(seenAt: string | null): SetupCheckResult;
+/**
+ * `capybara:connection-active`: active with a bot identity and no recorded error is ok. A recorded
+ * `last_error` (status `error`, or a failure an active connection keeps retrying) is failing with
+ * that text, redacted by every secret the result is redacted by and kept only when the result
+ * with it passes the result validation (control, bidi and lone surrogate rules, length);
+ * otherwise the reason leaves it out. The kernel pipeline validates and redacts the result again.
+ */
+export declare function connectionActiveResult(row: {
+    status: string;
+    botUserId: string | null;
+    lastError: string | null;
+} | undefined, secrets: readonly string[]): SetupCheckResult;
+/**
+ * Registers the kernel checks on module init (static code, the same on every replica). Each reads
+ * only the target the service resolved (ids of the caller's org, after authorization) and never
+ * writes; `capybara:oauth-token-endpoint` is the only one that leaves the kernel (§10.6).
+ */
+export declare class KernelChecks implements OnModuleInit {
+    private readonly registry;
+    private readonly config;
+    private readonly db;
+    private readonly redis;
+    private readonly credentials;
+    constructor(registry: SetupCheckRegistry, config: Pick<KernelConfigService, "get">, db: KernelDb, redis: Pick<Redis, "get">, credentials: Pick<Credentials, "oauthClient" | "status">);
+    onModuleInit(): void;
+    private webhookReceived;
+    private connectionActive;
+    /** The connector's auth settings (a live connector of the caller's org), or undefined. */
+    private connectorAuth;
+    private oauthClient;
+    private connectorTools;
+    /** The caller's own credential (cached per account, as every kernel check). */
+    private connectorConnected;
+    /**
+     * The token endpoint probe for a manual OAuth client (`oauth-token-probe.ts`): the stored
+     * client record is the connect flow's (its `tokenEndpoint` came from discovery or the
+     * template's `tokenUrl` at install, its auth method from `tokenAuthMethod`), the redirect URI
+     * is the connect flow's callback URL. Runs per admin (kernel checks are cached per account);
+     * each run is one token request, inside the per-account rate limit and the org's cap.
+     */
+    private tokenEndpoint;
+}

package/dist/setup/kernel-checks.js

@@ -0,0 +1,295 @@
+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); }
+};
+// The kernel's own setup checks, `capybara:*` (spec 2026-11-09-setup-guides-v2-design.md §10.6):
+// answered from the kernel's state with no plugin code, usable by any guide of their place. They go
+// through the same `SetupChecksService` pipeline as plugin checks (authorization, the rendered
+// guide, cache, single flight, the org's concurrency cap, the time limit, validate / redact /
+// validate), and are cached per account like every kernel check.
+import { validateSetupCheckResult, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { webhookSeenKey } from "../channels/webhook.js";
+import { webhookBase } from "../channels/webhook-url.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { REDIS } from "../infra/tokens.js";
+import { Credentials } from "../tools/credentials.js";
+import { callbackUrl } from "../tools/oauth/flow-paths.js";
+import { probeNetPolicy, probeTokenEndpoint } from "./oauth-token-probe.js";
+import { checkRedactor } from "./redact-check.js";
+import { SetupCheckRegistry } from "./setup-check-registry.js";
+const text = (en, zh) => ({ en, zh });
+/** The fixed texts of the kernel checks (only `last_error` and a time are ever interpolated). */
+export const KERNEL_CHECK_TEXTS = {
+    publicUrlSet: text("The public URL (http.publicUrl) is set.", "公开地址（http.publicUrl）已设置。"),
+    publicUrlMissing: text("The public URL (http.publicUrl) is not set.", "公开地址（http.publicUrl）没有设置。"),
+    publicUrlFix: text("Ask your super admin to set http.publicUrl.", "请超级管理员设置 http.publicUrl。"),
+    webhookPublic: text("Webhook callbacks have a public https address (channels.webhookBaseUrl).", "Webhook 回调有公开的 https 地址（channels.webhookBaseUrl）。"),
+    webhookBaseMissing: text("No public https address is set for webhook callbacks (channels.webhookBaseUrl).", "没有为 Webhook 回调设置公开的 https 地址（channels.webhookBaseUrl）。"),
+    webhookBaseFix: text("Ask your super admin to set channels.webhookBaseUrl to an https address that reaches the gateway.", "请超级管理员把 channels.webhookBaseUrl 设置为能到达网关的 https 地址。"),
+    webhookNone: text("No verified webhook request has arrived in the last 7 days.", "最近 7 天没有收到通过校验的 Webhook 请求。"),
+    connectionGone: text("The connection was not found.", "找不到这个连接。"),
+    connectionDisabled: text("The connection is disabled.", "这个连接已停用。"),
+    connectionEnableFix: text("Enable the connection.", "启用这个连接。"),
+    connectionFailed: text("The connection reported an error.", "这个连接报告了错误。"),
+    connectionFix: text("Check the credentials on this page and save them again.", "检查本页的凭据并重新保存。"),
+    connectionPending: text("The connection has not reported its bot identity yet; retry in a moment.", "这个连接还没有报告机器人身份，请稍后重试。"),
+    connectionActive: text("The connection is active.", "这个连接正常运行。"),
+    connectorGone: text("The connector was not found.", "找不到这个连接器。"),
+    notOAuthCode: text("This connector does not use an OAuth client.", "这个连接器不使用 OAuth 客户端。"),
+    dcr: text("Registered automatically; nothing to check.", "客户端是自动注册的，无需检查。"),
+    clientStored: text("The OAuth client id and secret are stored.", "OAuth 客户端 ID 和密钥已保存。"),
+    clientMissing: text("The OAuth client id or secret is not stored.", "OAuth 客户端 ID 或密钥没有保存。"),
+    clientFix: text("Enter the Client ID and Client Secret on the connector's page.", "在连接器页面填写 Client ID 和 Client Secret。"),
+    noClient: text("No OAuth client is stored yet.", "还没有保存 OAuth 客户端。"),
+    toolsRead: text("The connector's tool list has been read.", "已读取这个连接器的工具清单。"),
+    toolsPending: text("The tool list is read when the first member connects.", "第一位成员连接后会读取工具清单。"),
+    connected: text("You are connected.", "你已连接。"),
+    notConnected: text("You have not connected your account yet.", "你还没有连接自己的账号。"),
+    connectFix: text("Select Connect and sign in.", "选择「连接」并登录。"),
+    publicUrlFirst: text("The callback URL needs http.publicUrl; ask your super admin to set it.", "回调地址需要 http.publicUrl，请超级管理员设置。"),
+};
+/** `capybara:public-url`: `http.publicUrl` is set. */
+export function publicUrlCheck(config) {
+    return config.http.publicUrl
+        ? { status: "ok", reason: KERNEL_CHECK_TEXTS.publicUrlSet }
+        : {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.publicUrlMissing,
+            fix: KERNEL_CHECK_TEXTS.publicUrlFix,
+        };
+}
+/**
+ * `capybara:webhook-public`: webhook callback URLs have a usable https base. The kernel builds
+ * them from `channels.webhookBaseUrl` only (`webhook-url.ts`), never from `http.publicUrl`, so
+ * that is what is checked; a loopback http base (tests only) is not public.
+ */
+export function webhookPublicCheck(config) {
+    const base = webhookBase(config);
+    return base?.startsWith("https://")
+        ? { status: "ok", reason: KERNEL_CHECK_TEXTS.webhookPublic }
+        : {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.webhookBaseMissing,
+            fix: KERNEL_CHECK_TEXTS.webhookBaseFix,
+        };
+}
+/** `capybara:webhook-received`: the marker the gateway sets on an accepted webhook, or none. */
+export function webhookReceivedResult(seenAt) {
+    const at = seenAt === null ? Number.NaN : Date.parse(seenAt);
+    if (Number.isNaN(at))
+        return { status: "unknown", reason: KERNEL_CHECK_TEXTS.webhookNone };
+    const iso = new Date(at).toISOString();
+    return {
+        status: "ok",
+        reason: text(`A verified webhook request arrived at ${iso}.`, `${iso} 收到过通过校验的 Webhook 请求。`),
+    };
+}
+/** The most of `last_error` a reason carries (after redaction). */
+const LAST_ERROR_CHARS = 200;
+/**
+ * `last_error` fit for a reason: redacted over the whole text first by every secret the result is
+ * redacted by (the connection's and the plugin's config secrets: a cut never leaves part of a
+ * secret behind), then cut to {@link LAST_ERROR_CHARS} code points.
+ */
+function lastErrorText(lastError, secrets) {
+    const redacted = checkRedactor(secrets)(lastError);
+    const points = [...redacted];
+    return points.length > LAST_ERROR_CHARS
+        ? `${points.slice(0, LAST_ERROR_CHARS).join("")}…`
+        : redacted;
+}
+/**
+ * `capybara:connection-active`: active with a bot identity and no recorded error is ok. A recorded
+ * `last_error` (status `error`, or a failure an active connection keeps retrying) is failing with
+ * that text, redacted by every secret the result is redacted by and kept only when the result
+ * with it passes the result validation (control, bidi and lone surrogate rules, length);
+ * otherwise the reason leaves it out. The kernel pipeline validates and redacts the result again.
+ */
+export function connectionActiveResult(row, secrets) {
+    if (!row)
+        return { status: "unknown", reason: KERNEL_CHECK_TEXTS.connectionGone };
+    if (row.status === "disabled") {
+        return {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.connectionDisabled,
+            fix: KERNEL_CHECK_TEXTS.connectionEnableFix,
+        };
+    }
+    if (row.status === "error" || (row.lastError !== null && row.lastError !== "")) {
+        const generic = {
+            status: "failing",
+            reason: KERNEL_CHECK_TEXTS.connectionFailed,
+            fix: KERNEL_CHECK_TEXTS.connectionFix,
+        };
+        if (row.lastError === null || row.lastError === "")
+            return generic;
+        const detail = lastErrorText(row.lastError, secrets);
+        const withError = validateSetupCheckResult({
+            ...generic,
+            reason: text(`The connection reported an error: ${detail}`, `这个连接报告了错误：${detail}`),
+        });
+        return "problem" in withError ? generic : withError;
+    }
+    if (row.botUserId === null || row.botUserId === "") {
+        return { status: "unknown", reason: KERNEL_CHECK_TEXTS.connectionPending };
+    }
+    return { status: "ok", reason: KERNEL_CHECK_TEXTS.connectionActive };
+}
+/**
+ * Registers the kernel checks on module init (static code, the same on every replica). Each reads
+ * only the target the service resolved (ids of the caller's org, after authorization) and never
+ * writes; `capybara:oauth-token-endpoint` is the only one that leaves the kernel (§10.6).
+ */
+let KernelChecks = class KernelChecks {
+    registry;
+    config;
+    db;
+    redis;
+    credentials;
+    constructor(registry, config, db, redis, credentials) {
+        this.registry = registry;
+        this.config = config;
+        this.db = db;
+        this.redis = redis;
+        this.credentials = credentials;
+    }
+    onModuleInit() {
+        const r = this.registry;
+        r.registerKernel("capybara:public-url", "any", async () => publicUrlCheck(this.config.get()));
+        r.registerKernel("capybara:webhook-public", "channel-connection", async () => webhookPublicCheck(this.config.get()));
+        r.registerKernel("capybara:webhook-received", "channel-connection", (a) => this.webhookReceived(a));
+        r.registerKernel("capybara:connection-active", "channel-connection", (a) => this.connectionActive(a));
+        r.registerKernel("capybara:oauth-client", "connector-template", (a) => this.oauthClient(a));
+        r.registerKernel("capybara:connector-tools", "connector-template", (a) => this.connectorTools(a));
+        r.registerKernel("capybara:connector-connected", "connector-template", (a) => this.connectorConnected(a));
+        r.registerKernel("capybara:oauth-token-endpoint", "connector-template", (a) => this.tokenEndpoint(a));
+    }
+    async webhookReceived(a) {
+        if (a.target.kind !== "channel-connection")
+            return notApplicable();
+        return webhookReceivedResult(await this.redis.get(webhookSeenKey(a.target.connectionId)));
+    }
+    async connectionActive(a) {
+        if (a.target.kind !== "channel-connection")
+            return notApplicable();
+        const row = await this.db
+            .selectFrom("channel_connections")
+            .select(["status", "bot_user_id", "last_error"])
+            .where("id", "=", a.target.connectionId)
+            .where("org_id", "=", a.orgId)
+            .where("plugin", "=", a.target.plugin)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return connectionActiveResult(row && { status: row.status, botUserId: row.bot_user_id, lastError: row.last_error }, a.secrets);
+    }
+    /** The connector's auth settings (a live connector of the caller's org), or undefined. */
+    async connectorAuth(a) {
+        if (a.target.kind !== "connector")
+            return undefined;
+        const row = await this.db
+            .selectFrom("connectors")
+            .select("auth")
+            .where("id", "=", a.target.connectorId)
+            .where("org_id", "=", a.orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return row ? row.auth : undefined;
+    }
+    async oauthClient(a) {
+        const auth = await this.connectorAuth(a);
+        if (!auth || a.target.kind !== "connector")
+            return connectorGone();
+        if (auth.type !== "oauth_code")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.notOAuthCode };
+        if (auth.client === "dcr")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.dcr };
+        const client = await this.credentials.oauthClient(a.orgId, a.target.connectorId);
+        return client && client.clientId !== "" && client.clientSecret
+            ? { status: "ok", reason: KERNEL_CHECK_TEXTS.clientStored }
+            : {
+                status: "failing",
+                reason: KERNEL_CHECK_TEXTS.clientMissing,
+                fix: KERNEL_CHECK_TEXTS.clientFix,
+            };
+    }
+    async connectorTools(a) {
+        if (a.target.kind !== "connector" || !(await this.connectorAuth(a)))
+            return connectorGone();
+        const tool = await this.db
+            .selectFrom("connector_tools")
+            .select("name")
+            .where("connector_id", "=", a.target.connectorId)
+            .limit(1)
+            .executeTakeFirst();
+        return tool
+            ? { status: "ok", reason: KERNEL_CHECK_TEXTS.toolsRead }
+            : { status: "unknown", reason: KERNEL_CHECK_TEXTS.toolsPending };
+    }
+    /** The caller's own credential (cached per account, as every kernel check). */
+    async connectorConnected(a) {
+        const auth = await this.connectorAuth(a);
+        if (!auth || a.target.kind !== "connector")
+            return connectorGone();
+        const s = await this.credentials.status(a.orgId, a.target.connectorId, auth, a.accountId);
+        return s === "connected"
+            ? { status: "ok", reason: KERNEL_CHECK_TEXTS.connected }
+            : {
+                status: "failing",
+                reason: KERNEL_CHECK_TEXTS.notConnected,
+                fix: KERNEL_CHECK_TEXTS.connectFix,
+            };
+    }
+    /**
+     * The token endpoint probe for a manual OAuth client (`oauth-token-probe.ts`): the stored
+     * client record is the connect flow's (its `tokenEndpoint` came from discovery or the
+     * template's `tokenUrl` at install, its auth method from `tokenAuthMethod`), the redirect URI
+     * is the connect flow's callback URL. Runs per admin (kernel checks are cached per account);
+     * each run is one token request, inside the per-account rate limit and the org's cap.
+     */
+    async tokenEndpoint(a) {
+        const auth = await this.connectorAuth(a);
+        if (!auth || a.target.kind !== "connector")
+            return connectorGone();
+        if (auth.type !== "oauth_code")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.notOAuthCode };
+        if (auth.client === "dcr")
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.dcr };
+        const config = this.config.get();
+        const publicUrl = config.http.publicUrl;
+        if (!publicUrl)
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.publicUrlFirst };
+        const client = await this.credentials.oauthClient(a.orgId, a.target.connectorId);
+        if (!client)
+            return { status: "unknown", reason: KERNEL_CHECK_TEXTS.noClient };
+        return probeTokenEndpoint({
+            client,
+            redirectUri: callbackUrl(publicUrl),
+            net: probeNetPolicy(config),
+            signal: a.signal,
+        });
+    }
+};
+KernelChecks = __decorate([
+    Injectable(),
+    __param(0, Inject(SetupCheckRegistry)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(KernelDb)),
+    __param(3, Inject(REDIS)),
+    __param(4, Inject(Credentials))
+], KernelChecks);
+export { KernelChecks };
+const notApplicable = () => ({
+    status: "unknown",
+    reason: text("This check does not apply on this page.", "这项检查不适用于本页面。"),
+});
+const connectorGone = () => ({
+    status: "unknown",
+    reason: KERNEL_CHECK_TEXTS.connectorGone,
+});

package/dist/setup/oauth-token-probe.d.ts

@@ -0,0 +1,47 @@
+import type { SetupCheckResult, SetupCheckText } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../config/schema.js";
+import type { NetPolicy } from "../net/public-address.js";
+import { safeFetch } from "../net/safe-fetch.js";
+import { type OAuthClientRecord } from "../tools/oauth/tokens.js";
+/** The authorization code the probe sends: never a code any server issued. */
+export declare const PROBE_CODE = "capybara-setup-probe";
+/** The probe's fixed texts: nothing a token endpoint sends ever reaches a result. */
+export declare const PROBE_TEXTS: {
+    readonly accepted: SetupCheckText;
+    readonly clientRefused: SetupCheckText;
+    readonly clientFix: SetupCheckText;
+    readonly redirectRefused: SetupCheckText;
+    readonly unknown: SetupCheckText;
+    readonly netDenied: SetupCheckText;
+};
+/**
+ * The fix of a redirect refusal: the kernel-built callback URL (never anything the endpoint
+ * said): `http.publicUrl` + the fixed callback path. (A public URL so long that the fix passes
+ * its limit makes the result invalid, which the kernel answers as unknown.)
+ */
+export declare const redirectFix: (callbackUrl: string) => SetupCheckText;
+/**
+ * The network rules of the probe: the deployment's egress proxy (`net.httpsProxy` /
+ * `net.noProxy`), its private host exemptions (`marketplaces.allowPrivateHosts`, the one list of
+ * internal hosts the kernel may reach) and loopback http only under
+ * `tools.oauthAllowInsecureLoopback` (tests), as for every other OAuth URL.
+ */
+export declare function probeNetPolicy(config: KernelConfig): NetPolicy;
+export interface TokenProbeInput {
+    /** The stored client: its `tokenEndpoint` is the one the connect flow posts codes to. */
+    client: OAuthClientRecord;
+    /** The connect flow's redirect URI (`http.publicUrl` + the callback path). */
+    redirectUri: string;
+    net: NetPolicy;
+    /** The run's signal (the kernel's time limit). */
+    signal: AbortSignal;
+    /** Tests only: the network calls (defaults to {@link safeFetch}). */
+    fetch?: typeof safeFetch;
+}
+/**
+ * Probes the token endpoint (spec §10.6 table): `invalid_grant` / Slack `invalid_code` → ok; a
+ * refused client (or any other 401) → failing with the copy-again fix; a refused redirect URI →
+ * failing with the callback URL; anything else (429, 5xx, a network error, a redirect, a 2xx) →
+ * unknown. Never throws, never logs; the answer is read only for its refusal code and dropped.
+ */
+export declare function probeTokenEndpoint(input: TokenProbeInput): Promise<SetupCheckResult>;