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

package/dist/tools/approvals.service.js

@@ -0,0 +1,568 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { ORG_ROLES, roleAtLeast } from "../orgs/roles.js";
+export { APPROVAL_DENY_REASON_MAX_CHARS } from "../conversations/events.js";
+/** `list` 一次最多返回的审批数（收件箱据此判断这个来源是否取满）。 */
+export const APPROVALS_LIST_MAX = 100;
+const notFound = () => new ApiError("approval.not_found", "Approval not found");
+const iso = (v) => new Date(v).toISOString();
+const isRole = (v) => v !== null && ORG_ROLES.includes(v);
+function toRecord(r) {
+    return {
+        id: r.id,
+        orgId: r.org_id,
+        conversationId: r.conversation_id,
+        runId: r.run_id,
+        callId: r.call_id,
+        attempt: r.attempt,
+        toolKey: r.tool_key,
+        specHash: r.spec_hash,
+        connectorId: r.connector_id,
+        input: r.input,
+        requestedFor: r.requested_for,
+        approverRole: isRole(r.approver_role) ? r.approver_role : null,
+        status: r.status,
+        scope: r.scope,
+        decidedBy: r.decided_by,
+        decidedAt: r.decided_at === null ? null : iso(r.decided_at),
+        denyReason: r.deny_reason,
+        expiresAt: iso(r.expires_at),
+        createdAt: iso(r.created_at),
+    };
+}
+/**
+ * 能处理该审批的人（spec 3.6 R2）：
+ * - 指定了 `requested_for` → 只有那个人；
+ * - 按角色升级（`approver_role`）→ 当前角色不低于它、且不是该运行发起人的成员（发起人不能批准按角色升级到别人的请求）。
+ * agent / 服务令牌不能处理任何审批（路由动作 `approvals.decide` 仅限用户主体）。
+ */
+function canHandle(a, initiator, accountId, role) {
+    if (a.requestedFor !== null)
+        return a.requestedFor === accountId;
+    return (a.approverRole !== null &&
+        role !== null &&
+        roleAtLeast(role, a.approverRole) &&
+        initiator !== accountId);
+}
+/**
+ * 工具调用审批：新建（loop 调用）、列出 / 查看 / 处理（HTTP），以及「以后都允许」授权的查看与撤销。
+ * 状态全部在 PG：处理决定在事务里 `SELECT … FOR UPDATE` 审批行，多副本并发处理同一审批时恰好一个生效。
+ */
+export class ApprovalsService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 新建 pending 审批（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `approval_requested`，同一事务。
+     * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录（不覆盖），事件按 `approval_requested:<approvalId>` 幂等。
+     */
+    async request(input) {
+        if (input.requestedFor === null && input.approverRole === null) {
+            throw new Error("approval requires requestedFor or approverRole");
+        }
+        const { db, eventLog, config } = this.deps;
+        const hours = config().tools.approvalTimeoutHours;
+        const { record, toSeq } = await db.transaction().execute(async (t) => {
+            // Lock the conversation row (the append's lock) before inserting the approval: the insert's
+            // foreign key check takes FOR KEY SHARE on that row, and two requests that each held it and
+            // then asked for the append's FOR UPDATE waited for each other (40P01)
+            await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", input.conversationId)
+                .forUpdate()
+                .execute();
+            await t
+                .insertInto("approvals")
+                .values({
+                id: randomUUID(),
+                org_id: input.orgId,
+                conversation_id: input.conversationId,
+                run_id: input.runId,
+                call_id: input.callId,
+                attempt: input.attempt ?? 1,
+                tool_key: input.toolKey,
+                spec_hash: input.specHash,
+                connector_id: input.connectorId,
+                input: JSON.stringify(input.input ?? {}),
+                requested_for: input.requestedFor,
+                approver_role: input.approverRole,
+                scope: null,
+                decided_by: null,
+                expires_at: sql `now() + ${hours}::integer * interval '1 hour'`,
+            })
+                .onConflict((oc) => oc.columns(["run_id", "call_id", "attempt"]).doNothing())
+                .execute();
+            const row = await t
+                .selectFrom("approvals")
+                .selectAll()
+                .where("run_id", "=", input.runId)
+                .where("call_id", "=", input.callId)
+                .where("attempt", "=", input.attempt ?? 1)
+                .executeTakeFirstOrThrow();
+            const rec = toRecord(row);
+            const written = await eventLog.append(rec.conversationId, [
+                {
+                    type: "approval_requested",
+                    runId: rec.runId,
+                    idemKey: `approval_requested:${rec.id}`,
+                    payload: {
+                        step: input.step,
+                        callId: rec.callId,
+                        approvalId: rec.id,
+                        toolKey: rec.toolKey,
+                        expiresAt: rec.expiresAt,
+                        ...(input.policy !== undefined && { policy: input.policy }),
+                    },
+                },
+            ], t);
+            return { record: rec, toSeq: Math.max(...written.map((e) => e.seq)) };
+        });
+        await eventLog.notify(record.conversationId, toSeq);
+        return record;
+    }
+    /** 当前用户能处理的审批（新的在前，最多 {@link APPROVALS_LIST_MAX} 条）；`status` 缺省为全部。 */
+    async list(orgId, accountId, status) {
+        const role = await this.roleOf(this.deps.db, orgId, accountId);
+        const roles = role === null ? [] : ORG_ROLES.filter((r) => roleAtLeast(role, r));
+        let q = this.deps.db
+            .selectFrom("approvals")
+            .innerJoin("runs", "runs.id", "approvals.run_id")
+            .selectAll("approvals")
+            .where("approvals.org_id", "=", orgId)
+            .where((eb) => eb.or([
+            eb("approvals.requested_for", "=", accountId),
+            eb.and([
+                eb("approvals.requested_for", "is", null),
+                roles.length === 0 ? eb.lit(false) : eb("approvals.approver_role", "in", [...roles]),
+                eb("runs.trigger_account_id", "!=", accountId),
+            ]),
+        ]));
+        if (status !== undefined)
+            q = q.where("approvals.status", "=", status);
+        // 已到期、超时任务尚未处理的审批不再列为待处理（处理它会得到 approval.already_decided）
+        if (status === "pending")
+            q = q.where("approvals.expires_at", ">", sql `now()`);
+        const rows = await q
+            .orderBy("approvals.created_at", "desc")
+            .limit(APPROVALS_LIST_MAX)
+            .execute();
+        return this.views(rows.map(toRecord));
+    }
+    /** 详情；当前用户不能处理的一律 `approval.not_found`（不泄露存在）。 */
+    async get(orgId, id, accountId) {
+        const row = await this.deps.db
+            .selectFrom("approvals")
+            .innerJoin("runs", "runs.id", "approvals.run_id")
+            .selectAll("approvals")
+            .select("runs.trigger_account_id")
+            .where("approvals.id", "=", id)
+            .where("approvals.org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        const role = await this.roleOf(this.deps.db, orgId, accountId);
+        const rec = toRecord(row);
+        if (!canHandle(rec, row.trigger_account_id, accountId, role))
+            throw notFound();
+        const [view] = await this.views([rec]);
+        if (!view)
+            throw notFound();
+        return view;
+    }
+    /**
+     * 处理审批：事务内 `SELECT … FOR UPDATE` 审批行并实时重读处理人角色（R5）；不能处理 → `approval.not_found`，
+     * 非 pending 或已过期 → `approval.already_decided`。同一事务写状态、授权（`session` → 会话授权，
+     * `always` → 发起人 × agent × 工具）、`approval_decided` 事件（幂等键 `approval_decided:<id>`）与审计；
+     * 提交后发布事件并调用 `onDecided`。
+     */
+    async decide(orgId, id, accountId, body, actorTokenId) {
+        const { db, eventLog } = this.deps;
+        const { record, toSeq } = await db.transaction().execute(async (t) => {
+            const locked = await t
+                .selectFrom("approvals")
+                .selectAll()
+                .select(sql `expires_at <= now()`.as("expired"))
+                .where("id", "=", id)
+                .where("org_id", "=", orgId)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!locked)
+                throw notFound();
+            const ctx = await t
+                .selectFrom("runs")
+                .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+                .select([
+                "runs.trigger_account_id",
+                "conversations.agent_id",
+                "conversations.parent_conversation_id",
+            ])
+                .where("runs.id", "=", locked.run_id)
+                .executeTakeFirstOrThrow();
+            const before = toRecord(locked);
+            const role = await this.roleOf(t, orgId, accountId);
+            if (!canHandle(before, ctx.trigger_account_id, accountId, role))
+                throw notFound();
+            if (before.status !== "pending") {
+                throw new ApiError("approval.already_decided", "Approval has already been decided");
+            }
+            if (locked.expired) {
+                throw new ApiError("approval.already_decided", "Approval has expired");
+            }
+            const approved = body.decision === "approve";
+            const reason = approved ? undefined : body.reason?.trim() || undefined;
+            const scope = approved ? (body.scope ?? "once") : null;
+            // 按角色升级的批准只对这一次有效：授权记在发起人名下会让其以后绕过角色要求
+            if (scope !== null && scope !== "once" && before.requestedFor === null) {
+                throw new ApiError("validation_failed", 'Only scope "once" is allowed for role-escalated approvals', [{ path: "scope", message: 'Only "once" is allowed for role-escalated approvals' }]);
+            }
+            const updated = await t
+                .updateTable("approvals")
+                .set({
+                status: approved ? "approved" : "denied",
+                scope,
+                decided_by: accountId,
+                decided_at: sql `now()`,
+                deny_reason: reason ?? null,
+            })
+                .where("id", "=", id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            // 授权绑定所批准的定义指纹与来源连接器（同 slug 重新安装的连接器 id 不同，不继承）
+            const hash = before.specHash;
+            const connectorId = before.connectorId;
+            if (scope === "session") {
+                // a sub-agent's grant is its parent conversation's (sub-agents spec §9): its siblings and
+                // the parent itself are not asked again for the same call
+                await t
+                    .insertInto("conversation_tool_grants")
+                    .values({
+                    conversation_id: ctx.parent_conversation_id ?? before.conversationId,
+                    tool_key: before.toolKey,
+                    spec_hash: hash,
+                    connector_id: connectorId,
+                })
+                    .onConflict((oc) => oc
+                    .columns(["conversation_id", "tool_key"])
+                    .doUpdateSet({ spec_hash: hash, connector_id: connectorId }))
+                    .execute();
+            }
+            else if (scope === "always" && before.requestedFor !== null) {
+                await t
+                    .insertInto("tool_grants")
+                    .values({
+                    org_id: orgId,
+                    account_id: before.requestedFor,
+                    agent_id: ctx.agent_id,
+                    tool_key: before.toolKey,
+                    spec_hash: hash,
+                    connector_id: connectorId,
+                })
+                    .onConflict((oc) => oc.columns(["org_id", "account_id", "agent_id", "tool_key"]).doUpdateSet({
+                    spec_hash: hash,
+                    connector_id: connectorId,
+                    created_at: sql `now()`,
+                }))
+                    .execute();
+            }
+            const written = await eventLog.append(before.conversationId, [
+                {
+                    type: "approval_decided",
+                    runId: before.runId,
+                    idemKey: `approval_decided:${id}`,
+                    payload: {
+                        approvalId: id,
+                        callId: before.callId,
+                        decision: approved ? "approved" : "denied",
+                        ...(scope !== null && { scope }),
+                        byAccountId: accountId,
+                        ...(reason !== undefined && { reason }),
+                    },
+                },
+            ], t);
+            await audit(t, {
+                actorAccountId: accountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "approval.decided",
+                target: id,
+                detail: {
+                    toolKey: before.toolKey,
+                    conversationId: before.conversationId,
+                    runId: before.runId,
+                    agentId: ctx.agent_id,
+                    initiatorAccountId: ctx.trigger_account_id,
+                    decision: approved ? "approved" : "denied",
+                    scope,
+                    ...(body.note !== undefined && { note: body.note }),
+                    ...(reason !== undefined && { reason }),
+                },
+            });
+            return { record: toRecord(updated), toSeq: Math.max(...written.map((e) => e.seq)) };
+        });
+        await eventLog.notify(record.conversationId, toSeq);
+        if (this.deps.onDecided) {
+            try {
+                await this.deps.onDecided(record);
+            }
+            catch (err) {
+                this.deps.log.warn("approval onDecided hook failed", { approvalId: record.id, err });
+            }
+        }
+        return record;
+    }
+    /**
+     * 详情，不做处理人校验（内核内部用：渠道出站投递组装 IM 审批卡片）；不存在返回 null。
+     * 不得直接回给请求方——HTTP 接口用 {@link get}。
+     */
+    async describe(id) {
+        const row = await this.deps.db
+            .selectFrom("approvals")
+            .selectAll()
+            .where("id", "=", id)
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        const [view] = await this.views([toRecord(row)]);
+        return view ?? null;
+    }
+    /** 某个工具调用最近一次的审批（attempt 最大者）；没有则返回 null。 */
+    async forCall(runId, callId) {
+        const row = await this.deps.db
+            .selectFrom("approvals")
+            .selectAll()
+            .where("run_id", "=", runId)
+            .where("call_id", "=", callId)
+            .orderBy("attempt", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return row ? toRecord(row) : null;
+    }
+    /**
+     * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `approval_decided{expired}`（处理人为 null）。
+     * 与人工决定都锁同一行，恰好一个生效。返回 `expired`（本次生效）/ `not_due`（尚未到期）/
+     * `settled`（已处理、已取消或不存在）。
+     */
+    async expire(id) {
+        const { db, eventLog } = this.deps;
+        const r = await db.transaction().execute(async (t) => {
+            const locked = await t
+                .selectFrom("approvals")
+                .selectAll()
+                .select(sql `expires_at <= now()`.as("expired"))
+                .where("id", "=", id)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!locked)
+                return { outcome: "settled" };
+            const before = toRecord(locked);
+            if (before.status !== "pending")
+                return { outcome: "settled", record: before };
+            if (!locked.expired)
+                return { outcome: "not_due", record: before };
+            const updated = await t
+                .updateTable("approvals")
+                .set({ status: "expired", decided_at: sql `now()` })
+                .where("id", "=", id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            const toSeq = await this.decidedEvent(t, before, "expired");
+            return { outcome: "expired", record: toRecord(updated), toSeq };
+        });
+        if ("toSeq" in r && r.toSeq !== undefined && r.record) {
+            await eventLog.notify(r.record.conversationId, r.toSeq);
+        }
+        return r.record ? { outcome: r.outcome, record: r.record } : { outcome: r.outcome };
+    }
+    /**
+     * 在事务 `t` 内取消运行的全部 pending 审批（运行在等待中被中止），各写 `approval_decided{cancelled}`
+     * （处理人为 null）。返回被取消的记录；调用方提交后发布事件。
+     */
+    async cancelPendingIn(t, runId) {
+        const rows = await t
+            .selectFrom("approvals")
+            .selectAll()
+            .where("run_id", "=", runId)
+            .where("status", "=", "pending")
+            .orderBy("created_at")
+            .forUpdate()
+            .execute();
+        const out = [];
+        for (const row of rows) {
+            const updated = await t
+                .updateTable("approvals")
+                .set({ status: "cancelled", decided_at: sql `now()` })
+                .where("id", "=", row.id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            await this.decidedEvent(t, toRecord(row), "cancelled");
+            out.push(toRecord(updated));
+        }
+        return out;
+    }
+    /**
+     * 在事务 `t` 内取消某组织里指定由 `accountId` 处理（`requested_for`）的全部 pending 审批（成员离职），
+     * 走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、写 `approval_decided{cancelled}`（处理人为 null）。
+     * 返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件（并可续跑对应运行）。
+     */
+    async cancelPendingFor(t, orgId, accountId) {
+        const rows = await t
+            .selectFrom("approvals")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("requested_for", "=", accountId)
+            .where("status", "=", "pending")
+            .orderBy("created_at")
+            .forUpdate()
+            .execute();
+        const records = [];
+        const seqs = new Map();
+        for (const row of rows) {
+            const updated = await t
+                .updateTable("approvals")
+                .set({ status: "cancelled", decided_at: sql `now()` })
+                .where("id", "=", row.id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            const seq = await this.decidedEvent(t, toRecord(row), "cancelled");
+            seqs.set(row.conversation_id, Math.max(seqs.get(row.conversation_id) ?? 0, seq));
+            records.push(toRecord(updated));
+        }
+        return { records, seqs };
+    }
+    /** 系统写的 `approval_decided`（超时 / 取消，处理人为 null），返回事件 seq。 */
+    async decidedEvent(t, a, decision) {
+        const written = await this.deps.eventLog.append(a.conversationId, [
+            {
+                type: "approval_decided",
+                runId: a.runId,
+                idemKey: `approval_decided:${a.id}`,
+                payload: { approvalId: a.id, callId: a.callId, decision, byAccountId: null },
+            },
+        ], t);
+        return Math.max(...written.map((e) => e.seq));
+    }
+    /** 本人在该组织的「以后都允许」授权。 */
+    async listGrants(orgId, accountId) {
+        const rows = await this.deps.db
+            .selectFrom("tool_grants")
+            .select(["agent_id", "tool_key", "spec_hash", "created_at"])
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .orderBy("created_at", "desc")
+            .execute();
+        const names = await this.agentNames([...new Set(rows.map((r) => r.agent_id))]);
+        return rows.map((r) => ({
+            agentId: r.agent_id,
+            agentName: names.get(r.agent_id) ?? "",
+            toolKey: r.tool_key,
+            specHash: r.spec_hash,
+            createdAt: iso(r.created_at),
+        }));
+    }
+    /** 撤销本人的一条授权；不存在时什么也不做（幂等）。 */
+    async revokeGrant(orgId, accountId, agentId, toolKey, actorTokenId) {
+        await this.deps.db.transaction().execute(async (t) => {
+            const res = await t
+                .deleteFrom("tool_grants")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .where("agent_id", "=", agentId)
+                .where("tool_key", "=", toolKey)
+                .executeTakeFirst();
+            if (Number(res.numDeletedRows) === 0)
+                return;
+            await audit(t, {
+                actorAccountId: accountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "tool_grant.revoked",
+                target: agentId,
+                detail: { toolKey },
+            });
+        });
+    }
+    async roleOf(db, orgId, accountId) {
+        const m = await db
+            .selectFrom("memberships")
+            .select("role")
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        return m?.role ?? null;
+    }
+    /** agent id → 当前版本定义里的名字。 */
+    async agentNames(ids) {
+        if (ids.length === 0)
+            return new Map();
+        const rows = await this.deps.db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select(["agents.id", "agent_versions.definition"])
+            .where("agents.id", "in", ids)
+            .execute();
+        return new Map(rows.map((r) => {
+            const name = r.definition?.name;
+            return [r.id, typeof name === "string" ? name : ""];
+        }));
+    }
+    /** 补齐详情字段（批量读会话、运行、agent 名与连接器）。 */
+    async views(recs) {
+        if (recs.length === 0)
+            return [];
+        const { db } = this.deps;
+        const ctxRows = await db
+            .selectFrom("runs")
+            .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+            .select([
+            "runs.id",
+            "runs.trigger_account_id",
+            "conversations.agent_id",
+            "conversations.parent_conversation_id",
+        ])
+            .where("runs.id", "in", [...new Set(recs.map((r) => r.runId))])
+            .execute();
+        const ctx = new Map(ctxRows.map((r) => [r.id, r]));
+        const names = await this.agentNames([...new Set(ctxRows.map((r) => r.agent_id))]);
+        const connectorIds = [
+            ...new Set(recs.flatMap((r) => (r.connectorId === null ? [] : [r.connectorId]))),
+        ];
+        const apps = connectorIds.length === 0
+            ? []
+            : await db
+                .selectFrom("connectors")
+                .select(["id", "name", "slug"])
+                .where("id", "in", connectorIds)
+                .execute();
+        const connectorById = new Map(apps.map((a) => [a.id, a]));
+        return recs.flatMap((r) => {
+            const c = ctx.get(r.runId);
+            if (!c)
+                return [];
+            const app = r.connectorId === null ? undefined : connectorById.get(r.connectorId);
+            const prefix = app ? `${app.slug}__` : undefined;
+            return [
+                {
+                    ...r,
+                    toolName: prefix !== undefined && r.toolKey.startsWith(prefix)
+                        ? r.toolKey.slice(prefix.length)
+                        : r.toolKey,
+                    connector: app ? { id: app.id, name: app.name, slug: app.slug } : null,
+                    agent: { id: c.agent_id, name: names.get(c.agent_id) ?? "" },
+                    ...(c.parent_conversation_id !== null
+                        ? {
+                            conversationPath: `/chat/${c.parent_conversation_id}?subagent=${r.conversationId}`,
+                            parentConversationId: c.parent_conversation_id,
+                        }
+                        : { conversationPath: `/chat/${r.conversationId}` }),
+                    initiatorAccountId: c.trigger_account_id,
+                },
+            ];
+        });
+    }
+}

package/dist/tools/breaker.d.ts

@@ -0,0 +1,28 @@
+import type { Redis } from "ioredis";
+import type { KernelConfig } from "../config/schema.js";
+/** 熔断器键：每个组织 × 连接器一个 hash（`f` = 连续失败次数，`o` = 打开到期的毫秒时间戳）。 */
+export declare const breakerKey: (orgId: string, connectorId: string) => string;
+export type BreakerState = {
+    open: false;
+} | {
+    open: true;
+    failures: number;
+    retryAfterSeconds: number;
+};
+/** 熔断打开时给模型的说明（英文）。 */
+export declare function breakerOpenMessage(connectorName: string, failures: number, retryAfterSeconds: number): string;
+/**
+ * 连接器级熔断器（spec 5.4；只用于连接器工具）：同一组织同一连接器连续失败 `tools.breakerFailures` 次后打开
+ * `tools.breakerOpenSeconds` 秒，期间直接拒绝；到期后半开放行，成功清零、失败立即重新打开。
+ * 状态只在 Redis（多副本共享），计数与打开状态都带 TTL。
+ */
+export declare class Breaker {
+    private readonly redis;
+    private readonly config;
+    constructor(redis: Redis, config: () => KernelConfig);
+    check(orgId: string, connectorId: string): Promise<BreakerState>;
+    /** 记一次失败，返回当前连续失败次数。 */
+    failure(orgId: string, connectorId: string): Promise<number>;
+    /** 调用成功：清零。 */
+    success(orgId: string, connectorId: string): Promise<void>;
+}

package/dist/tools/breaker.js

@@ -0,0 +1,72 @@
+/** 熔断器键：每个组织 × 连接器一个 hash（`f` = 连续失败次数，`o` = 打开到期的毫秒时间戳）。 */
+export const breakerKey = (orgId, connectorId) => `capk:breaker:${orgId}:${connectorId}`;
+/**
+ * 连续失败计数的保留时间：没有新的失败也没有成功时，计数在这之后过期（多副本纪律：Redis 写入带 TTL）。
+ * 打开后整个键的 TTL = 打开时长 + 该值，打开到期后进入半开（放行调用；再失败立即重新打开）。
+ */
+const COUNT_TTL_MS = 3_600_000;
+/** 时间统一取 Redis 服务端时间（多副本时钟不一致也不影响判定）。 */
+const NOW = `local t = redis.call('TIME'); local now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)`;
+/**
+ * 记一次失败：计数 +1；达到阈值、或处于半开（曾打开且已到期）时打开 / 重新打开；
+ * 仍在打开期内的失败（打开前已发出的调用）只计数，不延长打开时间。返回失败次数。
+ */
+const FAILURE = `
+${NOW}
+local n = redis.call('HINCRBY', KEYS[1], 'f', 1)
+local o = tonumber(redis.call('HGET', KEYS[1], 'o') or '0')
+local openMs = tonumber(ARGV[2])
+local countMs = tonumber(ARGV[3])
+if o > now then
+  return n
+end
+if n >= tonumber(ARGV[1]) or o > 0 then
+  redis.call('HSET', KEYS[1], 'o', now + openMs)
+  redis.call('PEXPIRE', KEYS[1], openMs + countMs)
+else
+  redis.call('PEXPIRE', KEYS[1], countMs)
+end
+return n
+`;
+/** 读状态：返回 {失败次数, 剩余打开毫秒}（未打开为 0）。 */
+const CHECK = `
+${NOW}
+local v = redis.call('HMGET', KEYS[1], 'f', 'o')
+local f = tonumber(v[1] or '0')
+local o = tonumber(v[2] or '0')
+local left = 0
+if o > now then left = o - now end
+return {f, left}
+`;
+/** 熔断打开时给模型的说明（英文）。 */
+export function breakerOpenMessage(connectorName, failures, retryAfterSeconds) {
+    return `Tool temporarily unavailable: ${connectorName} failed ${failures} times in a row; retry after ${retryAfterSeconds}s.`;
+}
+/**
+ * 连接器级熔断器（spec 5.4；只用于连接器工具）：同一组织同一连接器连续失败 `tools.breakerFailures` 次后打开
+ * `tools.breakerOpenSeconds` 秒，期间直接拒绝；到期后半开放行，成功清零、失败立即重新打开。
+ * 状态只在 Redis（多副本共享），计数与打开状态都带 TTL。
+ */
+export class Breaker {
+    redis;
+    config;
+    constructor(redis, config) {
+        this.redis = redis;
+        this.config = config;
+    }
+    async check(orgId, connectorId) {
+        const [failures, left] = (await this.redis.eval(CHECK, 1, breakerKey(orgId, connectorId)));
+        if (left <= 0)
+            return { open: false };
+        return { open: true, failures, retryAfterSeconds: Math.ceil(left / 1000) };
+    }
+    /** 记一次失败，返回当前连续失败次数。 */
+    async failure(orgId, connectorId) {
+        const { breakerFailures, breakerOpenSeconds } = this.config().tools;
+        return Number(await this.redis.eval(FAILURE, 1, breakerKey(orgId, connectorId), breakerFailures, breakerOpenSeconds * 1000, COUNT_TTL_MS));
+    }
+    /** 调用成功：清零。 */
+    async success(orgId, connectorId) {
+        await this.redis.del(breakerKey(orgId, connectorId));
+    }
+}