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

package/dist/tools/policy.d.ts

@@ -0,0 +1,60 @@
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { DecidePolicy } from "./pipeline.js";
+import type { ResolvedTool, ToolPolicy } from "./registry.js";
+/**
+ * spec 3.6 R3「有权 ≠ 已确认」固定清单上的工具 key：策略至少为 `ask`，记住的授权也不放行。
+ *
+ * R3 清单：发布到公共市场、安装连接器、提插件申请、改角色与成员、删除、改共享技能、改自己的指令。
+ * M3 的内置工具（`ask_user`、`read_tool_output`、`tool_search`）与连接器工具都不在清单上；M5 T15 加入
+ * `skill_write`（改共享技能）。后续实现上述动作的内置工具时把 key 登记在这里。连接器 / 插件工具由
+ * `annotations.requiresUserInteraction` 表达同一约束。
+ */
+export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
+/**
+ * R3 清单里只对共享 agent 生效的 key（窄口子）：R3 的条目是「改共享技能」，私有 agent（`visibility = private`，
+ * 只有负责人本人能用）的技能不是共享的，`skill_write` 直接生效、不询问（R4）。其余 R3 条目不论可见性一律固定 ask。
+ */
+export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
+/** 取更严的策略（`allow < ask < deny`）。 */
+export declare function stricter(a: ToolPolicy, b: ToolPolicy | undefined): ToolPolicy;
+export interface PolicyInput {
+    /** 组织默认：`connector_tools.default_policy`，插件 / 内置工具为其声明（或注解推导）的默认。 */
+    connectorDefault: ToolPolicy;
+    /** agent 负责人的收紧（`definition.toolPolicies[key]`）。 */
+    agentOverride?: "ask" | "deny";
+    /** R3 清单或 `requiresUserInteraction`。 */
+    fixedAsk: boolean;
+    /** 已记住且 specHash 与当前一致的授权。 */
+    grant: "session" | "always" | null;
+}
+/**
+ * 策略判定（纯函数）：取组织默认、agent 收紧、R3 固定询问三者中最严者；
+ * 记住的授权只能把 `ask` 放行为 `allow`，不能越过 `deny`，对 R3 / `requiresUserInteraction` 的工具无效。
+ */
+export declare function decide(input: PolicyInput): ToolPolicy;
+/**
+ * 是否属于 R3 固定询问（清单或工具声明需要用户交互）。`visibility` 为 agent 当前的可见性：
+ * {@link R3_SHARED_AGENT_ONLY_TOOL_KEYS} 里的内置工具在私有 agent 上不算固定询问，
+ * 除非 agent 当前版本的 `skills.writePolicy` 为 `ask`（`skillWritePolicy`）；不知道可见性时按共享处理（更严）。
+ */
+export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" | "org" | "members" | undefined, skillWritePolicy?: "allow" | "ask" | undefined): boolean;
+/**
+ * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
+ * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
+ * - 连接器工具的 `connector_tools.default_policy` / 状态 / 指纹（连接器或工具已不存在、停用、删除、待审核 →
+ *   `{ unavailable: 原因 }`，管线写「工具不可用」的事实说明，而非策略拒绝）；
+ * - agent 当前版本的 `toolPolicies`，与运行所用版本取更严者（负责人运行中收紧立即生效；放宽不影响已在跑的运行）；
+ * - a sub-agent (template or general-purpose): `agentDef` is its frozen effective definition (the
+ *   parent's policies with the template's on top) and `ctx.agentId` is the parent's agent, so the
+ *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
+ *   grants are the parent conversation's; an org agent sub-agent (§5.5): `ctx.agentId` is the
+ *   dispatched agent (its current version, its "always" grants) and the parent agent's current
+ *   policies apply on top ({@link parentAgentOverride});
+ * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），
+ *   `connector_id` 与工具的来源连接器不一致也无效（删除后用同一 slug 重新安装的连接器不继承旧授权）；
+ * - 工具声明了 `requiredRole`（R1）时，发起人在组织中的当前角色：不是成员 → 拒绝；角色不足 → 按角色升级的审批
+ *   （`approverRole` = 所需角色、`requestedFor` = null），此时记住的授权不放行。
+ *
+ * 结果为 `ask` 时返回审批请求，默认指向发起人本人；记住的授权把 `ask` 放行时返回 `{ grant }`（按 allow 执行）。
+ */
+export declare function createDecidePolicy(db: KernelDb): DecidePolicy;

package/dist/tools/policy.js

@@ -0,0 +1,236 @@
+import { sql } from "kysely";
+import { roleAtLeast } from "../orgs/roles.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { SANDBOX_ASK_TOOL_NAMES } from "./builtins/sandbox/names.js";
+/**
+ * spec 3.6 R3「有权 ≠ 已确认」固定清单上的工具 key：策略至少为 `ask`，记住的授权也不放行。
+ *
+ * R3 清单：发布到公共市场、安装连接器、提插件申请、改角色与成员、删除、改共享技能、改自己的指令。
+ * M3 的内置工具（`ask_user`、`read_tool_output`、`tool_search`）与连接器工具都不在清单上；M5 T15 加入
+ * `skill_write`（改共享技能）。后续实现上述动作的内置工具时把 key 登记在这里。连接器 / 插件工具由
+ * `annotations.requiresUserInteraction` 表达同一约束。
+ */
+export const R3_FIXED_ASK_TOOL_KEYS = new Set(["skill_write"]);
+/**
+ * R3 清单里只对共享 agent 生效的 key（窄口子）：R3 的条目是「改共享技能」，私有 agent（`visibility = private`，
+ * 只有负责人本人能用）的技能不是共享的，`skill_write` 直接生效、不询问（R4）。其余 R3 条目不论可见性一律固定 ask。
+ */
+export const R3_SHARED_AGENT_ONLY_TOOL_KEYS = new Set(["skill_write"]);
+const RANK = { allow: 0, ask: 1, deny: 2 };
+/** 取更严的策略（`allow < ask < deny`）。 */
+export function stricter(a, b) {
+    return b !== undefined && RANK[b] > RANK[a] ? b : a;
+}
+/**
+ * 策略判定（纯函数）：取组织默认、agent 收紧、R3 固定询问三者中最严者；
+ * 记住的授权只能把 `ask` 放行为 `allow`，不能越过 `deny`，对 R3 / `requiresUserInteraction` 的工具无效。
+ */
+export function decide(input) {
+    let p = stricter(input.connectorDefault, input.agentOverride);
+    if (input.fixedAsk)
+        p = stricter(p, "ask");
+    if (p === "ask" && input.grant !== null && !input.fixedAsk)
+        return "allow";
+    return p;
+}
+/**
+ * 是否属于 R3 固定询问（清单或工具声明需要用户交互）。`visibility` 为 agent 当前的可见性：
+ * {@link R3_SHARED_AGENT_ONLY_TOOL_KEYS} 里的内置工具在私有 agent 上不算固定询问，
+ * 除非 agent 当前版本的 `skills.writePolicy` 为 `ask`（`skillWritePolicy`）；不知道可见性时按共享处理（更严）。
+ */
+export function isFixedAsk(tool, visibility, skillWritePolicy) {
+    if (tool.spec.annotations?.requiresUserInteraction === true)
+        return true;
+    if (!R3_FIXED_ASK_TOOL_KEYS.has(tool.key))
+        return false;
+    const builtinOnly = tool.source.kind === "builtin" && R3_SHARED_AGENT_ONLY_TOOL_KEYS.has(tool.key);
+    // 私有 agent：缺省 / allow 不问（R4），负责人设为 ask（D10）时与共享 agent 一样固定询问
+    return !(builtinOnly && visibility === "private" && skillWritePolicy !== "ask");
+}
+const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
+/**
+ * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
+ * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
+ * - 连接器工具的 `connector_tools.default_policy` / 状态 / 指纹（连接器或工具已不存在、停用、删除、待审核 →
+ *   `{ unavailable: 原因 }`，管线写「工具不可用」的事实说明，而非策略拒绝）；
+ * - agent 当前版本的 `toolPolicies`，与运行所用版本取更严者（负责人运行中收紧立即生效；放宽不影响已在跑的运行）；
+ * - a sub-agent (template or general-purpose): `agentDef` is its frozen effective definition (the
+ *   parent's policies with the template's on top) and `ctx.agentId` is the parent's agent, so the
+ *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
+ *   grants are the parent conversation's; an org agent sub-agent (§5.5): `ctx.agentId` is the
+ *   dispatched agent (its current version, its "always" grants) and the parent agent's current
+ *   policies apply on top ({@link parentAgentOverride});
+ * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），
+ *   `connector_id` 与工具的来源连接器不一致也无效（删除后用同一 slug 重新安装的连接器不继承旧授权）；
+ * - 工具声明了 `requiredRole`（R1）时，发起人在组织中的当前角色：不是成员 → 拒绝；角色不足 → 按角色升级的审批
+ *   （`approverRole` = 所需角色、`requestedFor` = null），此时记住的授权不放行。
+ *
+ * 结果为 `ask` 时返回审批请求，默认指向发起人本人；记住的授权把 `ask` 放行时返回 `{ grant }`（按 allow 执行）。
+ */
+export function createDecidePolicy(db) {
+    return async (tool, agentDef, ctx) => {
+        let connectorDefault = tool.defaultPolicy;
+        let connectorId = null;
+        let hashCurrent = true;
+        if (tool.source.kind === "connector") {
+            connectorId = tool.source.connectorId;
+            const app = await db
+                .selectFrom("connectors")
+                .select(["slug", "status", "deleted_at"])
+                .where("id", "=", tool.source.connectorId)
+                .where("org_id", "=", ctx.orgId)
+                .executeTakeFirst();
+            // 调用那一刻连接器 / 工具已不可用：给事实原因（与注册表的不可用说明一致），不说成「策略拒绝」
+            if (!app)
+                return { unavailable: "App does not exist" };
+            if (app.deleted_at !== null)
+                return { unavailable: `App ${app.slug} was deleted` };
+            if (app.status !== "active")
+                return { unavailable: `App ${app.slug} is disabled` };
+            const row = await db
+                .selectFrom("connector_tools")
+                .select(["default_policy", "spec_hash", "status", "missing_since"])
+                .where("connector_id", "=", tool.source.connectorId)
+                .where("name", "=", tool.source.name)
+                .executeTakeFirst();
+            if (!row || row.missing_since !== null) {
+                return { unavailable: `Tool no longer exists in app ${app.slug}` };
+            }
+            if (row.status === "disabled")
+                return { unavailable: "Tool is disabled" };
+            if (row.status !== "enabled")
+                return { unavailable: "Tool is pending review" };
+            connectorDefault = row.default_policy;
+            hashCurrent = row.spec_hash === tool.specHash;
+        }
+        // 沙箱工具的组织默认（M5 T8）：组织设置 sandboxToolPolicy 为 ask 时，有副作用的沙箱工具至少 ask
+        // `orgAsk`: the org setting, not the tool's own default, is what makes it ask
+        let orgAsk = false;
+        if (tool.source.kind === "builtin" && SANDBOX_ASK_TOOL_NAMES.has(tool.source.name)) {
+            if ((await readOrgSettings(db, ctx.orgId)).sandboxToolPolicy === "ask") {
+                orgAsk = connectorDefault === "allow";
+                connectorDefault = stricter(connectorDefault, "ask");
+            }
+        }
+        // 运行所用版本可能是加 toolPolicies 字段之前保存的：缺省为空
+        const runOverride = asOverride(agentDef.toolPolicies?.[tool.key]);
+        const current = await db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select(["agent_versions.definition", "agents.visibility"])
+            .where("agents.id", "=", ctx.agentId)
+            .executeTakeFirst();
+        const currentPolicies = current?.definition?.toolPolicies;
+        const currentOverride = asOverride(currentPolicies?.[tool.key]);
+        let strictest = stricter(runOverride ?? "allow", currentOverride);
+        if (ctx.parentConversationId !== undefined && ctx.parentAgentDiffers !== false) {
+            strictest = stricter(strictest, await parentAgentOverride(db, tool.key, ctx));
+        }
+        const agentOverride = strictest === "allow" ? undefined : strictest;
+        let escalateTo = null;
+        if (tool.requiredRole !== undefined) {
+            const m = await db
+                .selectFrom("memberships")
+                .select("role")
+                .where("org_id", "=", ctx.orgId)
+                .where("account_id", "=", ctx.accountId)
+                .executeTakeFirst();
+            if (!m)
+                return "deny";
+            if (!roleAtLeast(m.role, tool.requiredRole))
+                escalateTo = tool.requiredRole;
+        }
+        // 可见性实时读（R5）：共享 agent 的 skill_write 固定 ask，私有 agent 不问（见 R3_SHARED_AGENT_ONLY_TOOL_KEYS）
+        // 当前版本的 skills.writePolicy 同样实时读（R5）：运行中改为 ask，下一次调用即生效；固定 ask 时授权不放行
+        const writePolicy = current?.definition?.skills?.writePolicy;
+        const fixedAsk = isFixedAsk(tool, current?.visibility, writePolicy);
+        const input = {
+            connectorDefault,
+            ...(agentOverride !== undefined && { agentOverride }),
+            fixedAsk,
+            grant: null,
+        };
+        const pre = decide(input);
+        if (pre === "deny")
+            return "deny";
+        if (pre === "ask" && !fixedAsk && escalateTo === null && hashCurrent) {
+            input.grant = await findGrant(db, tool, connectorId, ctx);
+        }
+        const result = decide(input);
+        if (result === "allow" && escalateTo === null) {
+            // 记住的授权把 ask 放行：返回授权种类（审计链记录凭什么放行）
+            return pre === "ask" && input.grant !== null ? { grant: input.grant } : "allow";
+        }
+        const ask = {
+            toolKey: tool.key,
+            specHash: tool.specHash,
+            connectorId,
+            requestedFor: escalateTo === null ? ctx.accountId : null,
+            approverRole: escalateTo,
+            // the most specific rule that asked: role escalation, the agent's tightening, the connector,
+            // a fixed ask (R3, requiresUserInteraction), the org's sandboxToolPolicy, else the tool's own
+            // default
+            policy: escalateTo !== null
+                ? "role"
+                : agentOverride === "ask"
+                    ? "agent"
+                    : tool.source.kind === "connector" && connectorDefault === "ask"
+                        ? "connector"
+                        : fixedAsk
+                            ? "fixed"
+                            : orgAsk
+                                ? "org"
+                                : "default",
+        };
+        return { ask };
+    };
+}
+/**
+ * An org agent sub-agent (sub-agents spec §5.5, §9): its conversation's agent is the dispatched
+ * agent, so `ctx.agentId`'s current version above is that agent's; the parent agent's current
+ * policy for the same key applies on top, so the parent's owner can tighten a running child too.
+ * For a template or general-purpose child the parent conversation has the same agent, already read.
+ */
+async function parentAgentOverride(db, toolKey, ctx) {
+    const row = await db
+        .selectFrom("conversations as c")
+        .innerJoin("agents as a", "a.id", "c.agent_id")
+        .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
+        .select(["a.id", "v.definition"])
+        .where("c.id", "=", ctx.parentConversationId ?? "")
+        .executeTakeFirst();
+    if (!row || row.id === ctx.agentId)
+        return undefined;
+    const policies = row.definition.toolPolicies;
+    return asOverride(policies?.[toolKey]);
+}
+/**
+ * A grant matching the current definition hash and source connector: this conversation's first,
+ * then "always". `connectorId` is the tool's source connector (null for plugin and builtin tools,
+ * which match only grants without a connector). A sub-agent's "this conversation" grants live on
+ * its parent conversation (sub-agents spec §9), so parallel children are approved once.
+ */
+async function findGrant(db, tool, connectorId, ctx) {
+    const sameConnector = sql `connector_id IS NOT DISTINCT FROM ${connectorId}`;
+    const session = await db
+        .selectFrom("conversation_tool_grants")
+        .select("spec_hash")
+        .where("conversation_id", "=", ctx.parentConversationId ?? ctx.conversationId)
+        .where("tool_key", "=", tool.key)
+        .where(sameConnector)
+        .executeTakeFirst();
+    if (session?.spec_hash === tool.specHash)
+        return "session";
+    const always = await db
+        .selectFrom("tool_grants")
+        .select("spec_hash")
+        .where("org_id", "=", ctx.orgId)
+        .where("account_id", "=", ctx.accountId)
+        .where("agent_id", "=", ctx.agentId)
+        .where("tool_key", "=", tool.key)
+        .where(sameConnector)
+        .executeTakeFirst();
+    return always?.spec_hash === tool.specHash ? "always" : null;
+}

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

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { QuestionsService, QuestionView } from "./questions.service.js";
+/** 回答体：`answer` 的形状由服务按表单校验（`validateAnswer`，不符 → `validation_failed`）。 */
+declare const AnswerBody: z.ZodObject<{
+    answer: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+/**
+ * 输入请求（`ask_user`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
+ * 动作用 `approvals.decide`（访客起、仅限用户主体）：回答必须由人做出，agent / 服务令牌不能代答；
+ * 具体是否允许由服务判定——只有该运行的发起人能读取与回答，其他成员 403。
+ */
+export declare class QuestionsController {
+    private readonly questions;
+    constructor(questions: QuestionsService);
+    get(principal: Principal, org: OrgContext, id: string): Promise<{
+        question: QuestionView;
+    }>;
+    answer(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof AnswerBody>): Promise<{
+        question: QuestionView;
+    }>;
+}
+export {};

package/dist/tools/questions.controller.js

@@ -0,0 +1,58 @@
+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 } from "@nestjs/common";
+import { z } from "zod";
+import { QUESTIONS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+/** 回答体：`answer` 的形状由服务按表单校验（`validateAnswer`，不符 → `validation_failed`）。 */
+const AnswerBody = z.object({ answer: z.record(z.string().max(200), z.unknown()) }).strict();
+/**
+ * 输入请求（`ask_user`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
+ * 动作用 `approvals.decide`（访客起、仅限用户主体）：回答必须由人做出，agent / 服务令牌不能代答；
+ * 具体是否允许由服务判定——只有该运行的发起人能读取与回答，其他成员 403。
+ */
+let QuestionsController = class QuestionsController {
+    questions;
+    constructor(questions) {
+        this.questions = questions;
+    }
+    async get(principal, org, id) {
+        const p = requireUser(principal);
+        return { question: await this.questions.get(org.orgId, id, p.account.id) };
+    }
+    async answer(principal, org, id, body) {
+        const p = requireUser(principal);
+        const { state: _state, ...view } = await this.questions.answer(id, p.account.id, body.answer, org.orgId);
+        return { question: view };
+    }
+};
+__decorate([
+    Get(":id"),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], QuestionsController.prototype, "get", null);
+__decorate([
+    Post(":id/answer"),
+    HttpCode(200),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Body(new ZodPipe(AnswerBody)))
+], QuestionsController.prototype, "answer", null);
+QuestionsController = __decorate([
+    Controller("api/v1/orgs/:orgId/questions"),
+    __param(0, Inject(QUESTIONS))
+], QuestionsController);
+export { QuestionsController };

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

@@ -0,0 +1,103 @@
+import { type FormAnswer, type InputForm, 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";
+type Trx = Transaction<KernelDatabase>;
+export type QuestionStatus = "pending" | "answered" | "expired" | "cancelled";
+/** 一条输入请求（`ask_user`、插件工具的 `input_required`、MCP elicitation 共用）。 */
+export interface QuestionRecord {
+    id: string;
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    callId: string;
+    /** 同一调用的第几轮（从 1 起，最多 3 轮）。 */
+    attempt: number;
+    toolKey: string;
+    step: number;
+    form: InputForm;
+    state: unknown;
+    status: QuestionStatus;
+    answer: FormAnswer | null;
+    answeredBy: string | null;
+    answeredAt: string | null;
+    expiresAt: string;
+    createdAt: string;
+}
+/** 新建输入请求（tools 节点在处理函数返回 `input_required` 时调用）。 */
+export interface QuestionAskInput {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    step: number;
+    callId: string;
+    attempt: number;
+    toolKey: string;
+    form: InputForm;
+    state: unknown;
+}
+export interface QuestionsServiceDeps {
+    db: KernelDb;
+    eventLog: EventLog;
+    config: () => KernelConfig;
+    log: Pick<Logger, "warn">;
+    /**
+     * 回答提交之后调用（恰好一次：只有把 pending 改掉的那次回答会调用），用于续跑。失败只记日志（回答已生效）。
+     */
+    onAnswered?: (question: QuestionRecord) => Promise<void>;
+}
+/** 网页读取输入请求的视图（不含插件 state：那是工具内部的续跑数据）。 */
+export type QuestionView = Omit<QuestionRecord, "state">;
+/**
+ * 输入请求：新建（tools 节点）、回答（只有对话发起人）、超时与取消（等待机制）。
+ * 状态全部在 PG：回答 / 超时 / 取消都在事务里 `SELECT … FOR UPDATE` 该行，多副本并发时恰好一个生效，
+ * 只有生效的那次写 `question_answered`。HTTP 接口见 questions.controller.ts。
+ */
+export declare class QuestionsService {
+    private readonly deps;
+    constructor(deps: QuestionsServiceDeps);
+    /**
+     * 新建 pending 输入请求（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `question_asked`，同一事务。
+     * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录，事件按 `question_asked:<id>` 幂等。
+     */
+    ask(input: QuestionAskInput): Promise<QuestionRecord>;
+    /**
+     * 读一条输入请求（网页展示表单用）：只有该运行的发起人（其他人 → 403 `forbidden`）；
+     * 不属于该组织 / 不存在 → `question.not_found`。
+     */
+    get(orgId: string, questionId: string, accountId: string): Promise<QuestionView>;
+    /** 某个调用的全部输入请求（按轮次升序）。 */
+    forCall(runId: string, callId: string): Promise<QuestionRecord[]>;
+    /**
+     * 回答：只有该运行的发起人（其他人 → 403 `forbidden`；传 `orgId` 时别的组织的输入请求 → `question.not_found`）；非 pending 或已到期 →
+     * `question.already_answered`；答案不符合表单（`validateAnswer`）→ `validation_failed`。
+     * 同一事务写状态与 `question_answered`（幂等键 `question_answered:<id>`）；提交后发布事件并调用 `onAnswered`（续跑）。
+     * 传 `orgId` 时还要求输入请求属于该组织（HTTP 接口用）。
+     */
+    answer(questionId: string, accountId: string, answer: unknown, orgId?: string): Promise<QuestionRecord>;
+    /**
+     * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `question_answered{expired}`。
+     * 返回 `expired`（本次生效）/ `not_due`（尚未到期）/ `settled`（已回答、已取消或不存在）。
+     */
+    expire(questionId: string): Promise<{
+        outcome: "expired" | "not_due" | "settled";
+        record?: QuestionRecord;
+    }>;
+    /**
+     * 在事务 `t` 内取消运行的全部 pending 输入请求（运行在等待中被中止），各写 `question_answered{cancelled}`。
+     * 返回被取消的记录；调用方提交后发布事件。
+     */
+    cancelPendingIn(t: Trx, runId: string): Promise<QuestionRecord[]>;
+    /**
+     * 在事务 `t` 内取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
+     * 即「其作为处理人」的提问；成员离职时调用），走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、
+     * 写 `question_answered{cancelled}`。返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件。
+     */
+    cancelPendingFor(t: Trx, orgId: string, accountId: string): Promise<{
+        records: QuestionRecord[];
+        seqs: Map<string, number>;
+    }>;
+    private answeredEvent;
+}
+export {};