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

package/dist/tools/approvals.service.d.ts

@@ -0,0 +1,172 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { KernelConfig } from "../config/schema.js";
+import type { EventLog } from "../conversations/event-log.js";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { type OrgRole } from "../orgs/roles.js";
+import type { ApprovalPolicySource } from "./pipeline.js";
+type Trx = Transaction<KernelDatabase>;
+export { APPROVAL_DENY_REASON_MAX_CHARS } from "../conversations/events.js";
+/** `list` 一次最多返回的审批数（收件箱据此判断这个来源是否取满）。 */
+export declare const APPROVALS_LIST_MAX = 100;
+export type ApprovalStatus = "pending" | "approved" | "denied" | "expired" | "cancelled";
+export type ApprovalScope = "once" | "session" | "always";
+/** 一条审批记录。 */
+export interface ApprovalRecord {
+    id: string;
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    callId: string;
+    /** 同一调用的第几次审批（从 1 起；工具定义变化后重新审批时递增）。 */
+    attempt: number;
+    toolKey: string;
+    specHash: string;
+    connectorId: string | null;
+    input: unknown;
+    requestedFor: string | null;
+    approverRole: OrgRole | null;
+    status: ApprovalStatus;
+    scope: ApprovalScope | null;
+    decidedBy: string | null;
+    decidedAt: string | null;
+    /** The reason given with a denial (null otherwise). */
+    denyReason: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+/** 审批详情（列表与详情接口返回）。 */
+export interface ApprovalView extends ApprovalRecord {
+    /** 来源内的工具原名（连接器工具为连接器里的名字；否则同 `toolKey`）。 */
+    toolName: string;
+    connector: {
+        id: string;
+        name: string;
+        slug: string;
+    } | null;
+    agent: {
+        id: string;
+        name: string;
+    };
+    /**
+     * 网页中该会话的路径（不含语言前缀）。A sub-agent's approval links to its parent conversation
+     * with the sub-agent open: `/chat/<parent>?subagent=<child>`.
+     */
+    conversationPath: string;
+    /** Set when the approval belongs to a sub-agent: the conversation it was dispatched from. */
+    parentConversationId?: string;
+    /** 发起本次运行的人。 */
+    initiatorAccountId: string;
+}
+/** 新建审批（Task 9 的 loop 在策略为 `ask` 时调用）。 */
+export interface ApprovalRequestInput {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    /** 工具调用所在的步（写进 `approval_requested`）。 */
+    step: number;
+    callId: string;
+    toolKey: string;
+    specHash: string;
+    connectorId: string | null;
+    input: unknown;
+    /** 指定处理人；与 `approverRole` 至少一个非空。 */
+    requestedFor: string | null;
+    approverRole: OrgRole | null;
+    /** 同一调用的第几次审批，缺省 1（等待期间工具定义变化、原批准不再适用时递增）。 */
+    attempt?: number;
+    /** Which rule asked (written to `approval_requested.policy`; display only). */
+    policy?: ApprovalPolicySource;
+}
+export interface DecisionInput {
+    decision: "approve" | "deny";
+    /** 只对批准有意义，缺省 `once`。按角色升级的审批只能 `once`。 */
+    scope?: ApprovalScope | undefined;
+    note?: string | undefined;
+    /** Only with `deny` (trimmed, 1–500 characters; checked by the route). */
+    reason?: string | undefined;
+}
+/** 「以后都允许」授权（本人可撤销）。 */
+export interface ToolGrantView {
+    agentId: string;
+    agentName: string;
+    toolKey: string;
+    specHash: string;
+    createdAt: string;
+}
+export interface ApprovalsServiceDeps {
+    db: KernelDb;
+    eventLog: EventLog;
+    config: () => KernelConfig;
+    log: Pick<Logger, "warn">;
+    /**
+     * 决定提交之后调用（恰好一次：只有赢得行锁、把 pending 改掉的那次决定会调用），内核接入续跑。
+     * 默认空操作；失败只记日志（决定已生效，超时任务到点时会再尝试续跑）。
+     */
+    onDecided?: (approval: ApprovalRecord) => Promise<void>;
+}
+/**
+ * 工具调用审批：新建（loop 调用）、列出 / 查看 / 处理（HTTP），以及「以后都允许」授权的查看与撤销。
+ * 状态全部在 PG：处理决定在事务里 `SELECT … FOR UPDATE` 审批行，多副本并发处理同一审批时恰好一个生效。
+ */
+export declare class ApprovalsService {
+    private readonly deps;
+    constructor(deps: ApprovalsServiceDeps);
+    /**
+     * 新建 pending 审批（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `approval_requested`，同一事务。
+     * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录（不覆盖），事件按 `approval_requested:<approvalId>` 幂等。
+     */
+    request(input: ApprovalRequestInput): Promise<ApprovalRecord>;
+    /** 当前用户能处理的审批（新的在前，最多 {@link APPROVALS_LIST_MAX} 条）；`status` 缺省为全部。 */
+    list(orgId: string, accountId: string, status?: ApprovalStatus): Promise<ApprovalView[]>;
+    /** 详情；当前用户不能处理的一律 `approval.not_found`（不泄露存在）。 */
+    get(orgId: string, id: string, accountId: string): Promise<ApprovalView>;
+    /**
+     * 处理审批：事务内 `SELECT … FOR UPDATE` 审批行并实时重读处理人角色（R5）；不能处理 → `approval.not_found`，
+     * 非 pending 或已过期 → `approval.already_decided`。同一事务写状态、授权（`session` → 会话授权，
+     * `always` → 发起人 × agent × 工具）、`approval_decided` 事件（幂等键 `approval_decided:<id>`）与审计；
+     * 提交后发布事件并调用 `onDecided`。
+     */
+    decide(orgId: string, id: string, accountId: string, body: DecisionInput, actorTokenId?: string): Promise<ApprovalRecord>;
+    /**
+     * 详情，不做处理人校验（内核内部用：渠道出站投递组装 IM 审批卡片）；不存在返回 null。
+     * 不得直接回给请求方——HTTP 接口用 {@link get}。
+     */
+    describe(id: string): Promise<ApprovalView | null>;
+    /** 某个工具调用最近一次的审批（attempt 最大者）；没有则返回 null。 */
+    forCall(runId: string, callId: string): Promise<ApprovalRecord | null>;
+    /**
+     * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `approval_decided{expired}`（处理人为 null）。
+     * 与人工决定都锁同一行，恰好一个生效。返回 `expired`（本次生效）/ `not_due`（尚未到期）/
+     * `settled`（已处理、已取消或不存在）。
+     */
+    expire(id: string): Promise<{
+        outcome: "expired" | "not_due" | "settled";
+        record?: ApprovalRecord;
+    }>;
+    /**
+     * 在事务 `t` 内取消运行的全部 pending 审批（运行在等待中被中止），各写 `approval_decided{cancelled}`
+     * （处理人为 null）。返回被取消的记录；调用方提交后发布事件。
+     */
+    cancelPendingIn(t: Trx, runId: string): Promise<ApprovalRecord[]>;
+    /**
+     * 在事务 `t` 内取消某组织里指定由 `accountId` 处理（`requested_for`）的全部 pending 审批（成员离职），
+     * 走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、写 `approval_decided{cancelled}`（处理人为 null）。
+     * 返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件（并可续跑对应运行）。
+     */
+    cancelPendingFor(t: Trx, orgId: string, accountId: string): Promise<{
+        records: ApprovalRecord[];
+        seqs: Map<string, number>;
+    }>;
+    /** 系统写的 `approval_decided`（超时 / 取消，处理人为 null），返回事件 seq。 */
+    private decidedEvent;
+    /** 本人在该组织的「以后都允许」授权。 */
+    listGrants(orgId: string, accountId: string): Promise<ToolGrantView[]>;
+    /** 撤销本人的一条授权；不存在时什么也不做（幂等）。 */
+    revokeGrant(orgId: string, accountId: string, agentId: string, toolKey: string, actorTokenId?: string): Promise<void>;
+    private roleOf;
+    /** agent id → 当前版本定义里的名字。 */
+    private agentNames;
+    /** 补齐详情字段（批量读会话、运行、agent 名与连接器）。 */
+    private views;
+}