@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/tools/policy.d.ts

@@ -1,20 +1,7 @@
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } 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>;
+export { R3_FIXED_ASK_TOOL_KEYS, R3_SHARED_AGENT_ONLY_TOOL_KEYS } from "./builtin-names.js";
 /** 取更严的策略（`allow < ask < deny`）。 */
 export declare function stricter(a: ToolPolicy, b: ToolPolicy | undefined): ToolPolicy;
 export interface PolicyInput {
@@ -47,7 +34,7 @@ export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" |
  * - 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
+ *   grants are the root conversation's (agent map spec §7); 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），
@@ -57,4 +44,4 @@ export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" |
  *
  * 结果为 `ask` 时返回审批请求，默认指向发起人本人；记住的授权把 `ask` 放行时返回 `{ grant }`（按 allow 执行）。
  */
-export declare function createDecidePolicy(db: KernelDb): DecidePolicy;
+export declare function createDecidePolicy(db: KernelSchemaDb): DecidePolicy;

package/dist/tools/policy.js

@@ -1,21 +1,9 @@
 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"]);
+import { R3_FIXED_ASK_TOOL_KEYS, R3_SHARED_AGENT_ONLY_TOOL_KEYS, SANDBOX_ASK_TOOL_NAMES, } from "./builtin-names.js";
+import { normalizeStoredDefinitionIn } from "./legacy-data.js";
+export { R3_FIXED_ASK_TOOL_KEYS, R3_SHARED_AGENT_ONLY_TOOL_KEYS } from "./builtin-names.js";
 const RANK = { allow: 0, ask: 1, deny: 2 };
 /** 取更严的策略（`allow < ask < deny`）。 */
 export function stricter(a, b) {
@@ -48,6 +36,17 @@ export function isFixedAsk(tool, visibility, skillWritePolicy) {
     return !(builtinOnly && visibility === "private" && skillWritePolicy !== "ask");
 }
 const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
+/**
+ * An agent's tightening for a call: its policy on the tool key and, for a per-call key
+ * (`Platform:<operation>`), on that key, the stricter of the two (a policy can only tighten).
+ */
+function overrideOf(policies, toolKey, policyKey) {
+    const own = asOverride(policies?.[toolKey]);
+    if (policyKey === toolKey)
+        return own;
+    const s = stricter(own ?? "allow", asOverride(policies?.[policyKey]));
+    return s === "allow" ? undefined : s;
+}
 /**
  * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
  * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
@@ -57,7 +56,7 @@ const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
  * - 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
+ *   grants are the root conversation's (agent map spec §7); 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），
@@ -69,7 +68,11 @@ const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
  */
 export function createDecidePolicy(db) {
     return async (tool, agentDef, ctx) => {
-        let connectorDefault = tool.defaultPolicy;
+        // a per-call policy (Platform tool spec §6.2): its key replaces the tool key for policies,
+        // grants and approvals, and its policy replaces the tool's default
+        const call = ctx.callPolicy ?? null;
+        const policyKey = call?.key ?? tool.key;
+        let connectorDefault = call?.policy ?? tool.defaultPolicy;
         let connectorId = null;
         let hashCurrent = true;
         if (tool.source.kind === "connector") {
@@ -113,7 +116,7 @@ export function createDecidePolicy(db) {
             }
         }
         // 运行所用版本可能是加 toolPolicies 字段之前保存的：缺省为空
-        const runOverride = asOverride(agentDef.toolPolicies?.[tool.key]);
+        const runOverride = overrideOf(agentDef.toolPolicies, tool.key, policyKey);
         const current = await db
             .selectFrom("agents")
             .innerJoin("agent_versions", (j) => j
@@ -122,11 +125,15 @@ export function createDecidePolicy(db) {
             .select(["agent_versions.definition", "agents.visibility"])
             .where("agents.id", "=", ctx.agentId)
             .executeTakeFirst();
-        const currentPolicies = current?.definition?.toolPolicies;
-        const currentOverride = asOverride(currentPolicies?.[tool.key]);
+        // stored raw: an rc version's keys read as current keys, so its deny keeps applying (§8.3)
+        const currentDef = current === undefined
+            ? undefined
+            : await normalizeStoredDefinitionIn(db, ctx.orgId, current.definition);
+        const currentPolicies = currentDef?.toolPolicies;
+        const currentOverride = overrideOf(currentPolicies, tool.key, policyKey);
         let strictest = stricter(runOverride ?? "allow", currentOverride);
         if (ctx.parentConversationId !== undefined && ctx.parentAgentDiffers !== false) {
-            strictest = stricter(strictest, await parentAgentOverride(db, tool.key, ctx));
+            strictest = stricter(strictest, await parentAgentOverride(db, tool.key, policyKey, ctx));
         }
         const agentOverride = strictest === "allow" ? undefined : strictest;
         let escalateTo = null;
@@ -142,10 +149,13 @@ export function createDecidePolicy(db) {
             if (!roleAtLeast(m.role, tool.requiredRole))
                 escalateTo = tool.requiredRole;
         }
-        // 可见性实时读（R5）：共享 agent 的 skill_write 固定 ask，私有 agent 不问（见 R3_SHARED_AGENT_ONLY_TOOL_KEYS）
+        // 可见性实时读（R5）：共享 agent 的 SkillWrite 固定 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 writePolicy = currentDef?.skills?.writePolicy;
+        // `remember: false` on a call that is not a plain allow (an org / platform operation, or a read
+        // an agent tightened to ask): every call asks, grants never apply. A read (`allow`) never asks.
+        const fixedAsk = isFixedAsk(tool, current?.visibility, writePolicy) ||
+            (call !== null && !call.remember && (call.policy !== "allow" || agentOverride !== undefined));
         const input = {
             connectorDefault,
             ...(agentOverride !== undefined && { agentOverride }),
@@ -156,7 +166,7 @@ export function createDecidePolicy(db) {
         if (pre === "deny")
             return "deny";
         if (pre === "ask" && !fixedAsk && escalateTo === null && hashCurrent) {
-            input.grant = await findGrant(db, tool, connectorId, ctx);
+            input.grant = await findGrant(db, tool, policyKey, connectorId, ctx);
         }
         const result = decide(input);
         if (result === "allow" && escalateTo === null) {
@@ -164,7 +174,7 @@ export function createDecidePolicy(db) {
             return pre === "ask" && input.grant !== null ? { grant: input.grant } : "allow";
         }
         const ask = {
-            toolKey: tool.key,
+            toolKey: policyKey,
             specHash: tool.specHash,
             connectorId,
             requestedFor: escalateTo === null ? ctx.accountId : null,
@@ -193,7 +203,7 @@ export function createDecidePolicy(db) {
  * 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) {
+async function parentAgentOverride(db, toolKey, policyKey, ctx) {
     const row = await db
         .selectFrom("conversations as c")
         .innerJoin("agents as a", "a.id", "c.agent_id")
@@ -203,22 +213,26 @@ async function parentAgentOverride(db, toolKey, ctx) {
         .executeTakeFirst();
     if (!row || row.id === ctx.agentId)
         return undefined;
-    const policies = row.definition.toolPolicies;
-    return asOverride(policies?.[toolKey]);
+    // stored raw: an rc version's keys read as current keys, so its deny keeps applying (§8.3)
+    const policies = (await normalizeStoredDefinitionIn(db, ctx.orgId, row.definition))
+        .toolPolicies;
+    return overrideOf(policies, toolKey, policyKey);
 }
 /**
- * A grant matching the current definition hash and source connector: this conversation's first,
+ * A grant matching the current definition hash and source connector, keyed by the call's policy key
+ * (the tool key, or a per-call key such as `Platform:<operation>`): 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.
+ * the root conversation of its tree (agent map spec §7), so the root and every sub-agent at any
+ * depth are approved once.
  */
-async function findGrant(db, tool, connectorId, ctx) {
+async function findGrant(db, tool, policyKey, 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("conversation_id", "=", ctx.rootConversationId ?? ctx.conversationId)
+        .where("tool_key", "=", policyKey)
         .where(sameConnector)
         .executeTakeFirst();
     if (session?.spec_hash === tool.specHash)
@@ -229,7 +243,7 @@ async function findGrant(db, tool, connectorId, ctx) {
         .where("org_id", "=", ctx.orgId)
         .where("account_id", "=", ctx.accountId)
         .where("agent_id", "=", ctx.agentId)
-        .where("tool_key", "=", tool.key)
+        .where("tool_key", "=", policyKey)
         .where(sameConnector)
         .executeTakeFirst();
     return always?.spec_hash === tool.specHash ? "always" : null;

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

@@ -1,13 +1,13 @@
 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";
+import { QuestionsService, type 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`。
+ * 输入请求（`AskUserQuestion`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
  * 动作用 `approvals.decide`（访客起、仅限用户主体）：回答必须由人做出，agent / 服务令牌不能代答；
  * 具体是否允许由服务判定——只有该运行的发起人能读取与回答，其他成员 403。
  */

package/dist/tools/questions.controller.js

@@ -7,16 +7,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 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 { 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 { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { QuestionsService } from "./questions.service.js";
 /** 回答体：`answer` 的形状由服务按表单校验（`validateAnswer`，不符 → `validation_failed`）。 */
 const AnswerBody = z.object({ answer: z.record(z.string().max(200), z.unknown()) }).strict();
+class QuestionAnswerBody extends createZodDto(AnswerBody, "QuestionAnswerBody") {
+}
 /**
- * 输入请求（`ask_user`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
+ * 输入请求（`AskUserQuestion`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
  * 动作用 `approvals.decide`（访客起、仅限用户主体）：回答必须由人做出，agent / 服务令牌不能代答；
  * 具体是否允许由服务判定——只有该运行的发起人能读取与回答，其他成员 403。
  */
@@ -49,10 +52,10 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, Body(new ZodPipe(AnswerBody)))
+    __param(3, ZBody(QuestionAnswerBody))
 ], QuestionsController.prototype, "answer", null);
 QuestionsController = __decorate([
     Controller("api/v1/orgs/:orgId/questions"),
-    __param(0, Inject(QUESTIONS))
+    __param(0, Inject(QuestionsService))
 ], QuestionsController);
 export { QuestionsController };

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

@@ -1,11 +1,11 @@
-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>;
+import { type FormAnswer, type InputForm } from "@capybara-hq/plugin-sdk";
+import { EventLog } from "../conversations/event-log.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
 export type QuestionStatus = "pending" | "answered" | "expired" | "cancelled";
-/** 一条输入请求（`ask_user`、插件工具的 `input_required`、MCP elicitation 共用）。 */
+/** 一条输入请求（`AskUserQuestion`、插件工具的 `input_required`、MCP elicitation 共用）。 */
 export interface QuestionRecord {
     id: string;
     orgId: string;
@@ -37,31 +37,30 @@ export interface QuestionAskInput {
     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。
+ *
+ * An answer is announced after the commit as the domain event `question.answered` (exactly once),
+ * which the run's waits follow to resume it (spec §3b; the wait sweep resumes a run whose resume was
+ * lost). Events are appended in the context's transaction (`EventLog.appendIn`).
  */
 export declare class QuestionsService {
-    private readonly deps;
-    constructor(deps: QuestionsServiceDeps);
+    private readonly db;
+    private readonly config;
+    private readonly eventLog;
+    private readonly events;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, eventLog: Pick<EventLog, "appendIn" | "notify">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost);
     /**
      * 新建 pending 输入请求（`expires_at` = 现在 + `tools.approvalTimeoutHours`）并写 `question_asked`，同一事务。
      * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录，事件按 `question_asked:<id>` 幂等。
      */
     ask(input: QuestionAskInput): Promise<QuestionRecord>;
+    private askIn;
     /**
      * 读一条输入请求（网页展示表单用）：只有该运行的发起人（其他人 → 403 `forbidden`）；
      * 不属于该组织 / 不存在 → `question.not_found`。
@@ -76,6 +75,7 @@ export declare class QuestionsService {
      * 传 `orgId` 时还要求输入请求属于该组织（HTTP 接口用）。
      */
     answer(questionId: string, accountId: string, answer: unknown, orgId?: string): Promise<QuestionRecord>;
+    private answerIn;
     /**
      * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `question_answered{expired}`。
      * 返回 `expired`（本次生效）/ `not_due`（尚未到期）/ `settled`（已回答、已取消或不存在）。
@@ -84,20 +84,21 @@ export declare class QuestionsService {
         outcome: "expired" | "not_due" | "settled";
         record?: QuestionRecord;
     }>;
+    private expireIn;
     /**
-     * 在事务 `t` 内取消运行的全部 pending 输入请求（运行在等待中被中止），各写 `question_answered{cancelled}`。
-     * 返回被取消的记录；调用方提交后发布事件。
+     * 在调用方的事务内（`mandatory`）取消运行的全部 pending 输入请求（运行在等待中被中止），各写
+     * `question_answered{cancelled}`。返回被取消的记录；调用方提交后发布事件。
      */
-    cancelPendingIn(t: Trx, runId: string): Promise<QuestionRecord[]>;
+    cancelPendingIn(runId: string): Promise<QuestionRecord[]>;
     /**
-     * 在事务 `t` 内取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
+     * 在调用方的事务内（`mandatory`）取消某组织里由 `accountId` 发起的运行上的全部 pending 输入请求（只有运行发起人能回答，
      * 即「其作为处理人」的提问；成员离职时调用），走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、
      * 写 `question_answered{cancelled}`。返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件。
      */
-    cancelPendingFor(t: Trx, orgId: string, accountId: string): Promise<{
+    cancelPendingFor(orgId: string, accountId: string): Promise<{
         records: QuestionRecord[];
         seqs: Map<string, number>;
     }>;
+    /** `question_answered` in the current transaction; returns its seq. */
     private answeredEvent;
 }
-export {};