@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/storage/storage.service.js

@@ -1,5 +1,17 @@
-import { ExtensionPointUnavailableError, } from "@capybara-hq/plugin-sdk";
+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 { ExtensionPointUnavailableError, OBJECT_STORE_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 import { KeySpace, kernelPrefix, normalizeOrgId, pluginPrefix } from "./prefix.js";
 export { StorageKeyError } from "./prefix.js";
 /** 部署级对象的键前缀（见 {@link StorageService.deployment}）。 */
@@ -16,13 +28,15 @@ export function clampPresignTtl(ttlSeconds) {
     return Math.min(MAX_PRESIGN_TTL_SECONDS, Math.max(1, Math.floor(ttlSeconds)));
 }
 /**
- * 内核的对象存储服务（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。
+ * 前缀隔离的对象存储（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。A plain class over a
+ * {@link StorageSource}: the kernel's one instance is the {@link StorageService} provider; an
+ * extension's `ctx.storage` and the CLI build their own over their own source.
  * - 插件经 {@link forPlugin} 拿到 `ctx.storage`：键落在 `plugins/<插件>/<orgId>/` 下；
  * - 内核功能经 {@link kernel} 用 `kernel/<orgId>/`；
  * - 返回给调用方的键（`head` / `get` / `put` / `list`）都去掉前缀，列举结果只保留本前缀下的对象。
  * 没有提供方时各方法 reject `storage.unavailable`（{@link available} 为 false）。本身无状态，可多副本共用。
  */
-export class StorageService {
+export class PrefixedStorage {
     d;
     constructor(d) {
         this.d = d;
@@ -98,6 +112,33 @@ export class StorageService {
         return store;
     }
 }
+/**
+ * The kernel's object storage (one provider): the object store is the first loaded `object-store@1`
+ * provider in the {@link ExtensionRegistry} (read per call: it is ready only after the extensions
+ * load); the extensions that may hold data are those ever approved (permission snapshots, including
+ * uninstalled ones) plus the loaded ones.
+ */
+let StorageService = class StorageService extends PrefixedStorage {
+    constructor(registry, db) {
+        super({
+            provider: () => registry.list("object-store").find((e) => e.capability === OBJECT_STORE_EXTENSION_POINT)
+                ?.impl,
+            plugins: async () => {
+                const rows = await db
+                    .selectFrom("extension_permission_snapshots")
+                    .select("plugin")
+                    .execute();
+                return [...rows.map((r) => r.plugin), ...registry.manifests().map((m) => m.name)];
+            },
+        });
+    }
+};
+StorageService = __decorate([
+    Injectable(),
+    __param(0, Inject(ExtensionRegistry)),
+    __param(1, Inject(KernelDb))
+], StorageService);
+export { StorageService };
 /** 一个前缀下的 ObjectStore 视图：键先校验再拼接，返回的键去掉前缀。 */
 class ScopedStore {
     store;

package/dist/time-zone.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+/** Whether `tz` is an IANA time zone this runtime knows (run context spec §3.3, §3.4). */
+export declare function isTimeZone(tz: string): boolean;
+/** An IANA time zone name, checked with `Intl.DateTimeFormat`. */
+export declare const IanaTimeZone: z.ZodString;

package/dist/time-zone.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/** Whether `tz` is an IANA time zone this runtime knows (run context spec §3.3, §3.4). */
+export function isTimeZone(tz) {
+    if (tz === "" || tz.length > 64)
+        return false;
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** An IANA time zone name, checked with `Intl.DateTimeFormat`. */
+export const IanaTimeZone = z
+    .string()
+    .min(1)
+    .max(64)
+    .refine(isTimeZone, "must be an IANA time zone name, such as Asia/Shanghai");

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { type ApprovalRecord, type ApprovalsService, type ApprovalView, type ToolGrantView } from "./approvals.service.js";
+import { type ApprovalRecord, ApprovalsService, type ApprovalView, type ToolGrantView } from "./approvals.service.js";
 declare const ListQuery: z.ZodObject<{
     status: z.ZodOptional<z.ZodEnum<{
         approved: "approved";

package/dist/tools/approvals.controller.js

@@ -7,17 +7,16 @@ 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, Delete, Get, HttpCode, Inject, Param, Post, Query, } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
 import { z } from "zod";
-import { APPROVALS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { CONTROL_OR_HIDDEN_RE } from "../text.js";
-import { APPROVAL_DENY_REASON_MAX_CHARS, } from "./approvals.service.js";
-const ListQuery = z
-    .object({ status: z.enum(["pending", "approved", "denied", "expired", "cancelled"]).optional() })
-    .strict();
+import { ApprovalsListQuerySchema } from "./approvals.schemas.js";
+import { APPROVAL_DENY_REASON_MAX_CHARS, ApprovalsService, } from "./approvals.service.js";
+const ListQuery = ApprovalsListQuerySchema;
 const DecisionBody = z
     .object({
     decision: z.enum(["approve", "deny"]),
@@ -39,6 +38,10 @@ const DecisionBody = z
     path: ["reason"],
     message: "A reason can only be given with deny",
 });
+class ApprovalsListQuery extends createZodDto(ListQuery, "ApprovalsListQuery") {
+}
+class ApprovalDecisionBody extends createZodDto(DecisionBody, "ApprovalDecisionBody") {
+}
 /**
  * 工具调用审批（`/api/v1/orgs/:orgId/approvals`，`approvals.decide`：访客起、仅限用户主体——agent 不能审批，R2）。
  * 能否看到 / 处理某条审批由 `requested_for` / `approver_role` 判定（见 `ApprovalsService`），看不到的一律 404。
@@ -68,7 +71,7 @@ __decorate([
     OrgAction("approvals.decide"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Query(new ZodPipe(ListQuery)))
+    __param(2, ZQuery(ApprovalsListQuery))
 ], ApprovalsController.prototype, "list", null);
 __decorate([
     Get(":id"),
@@ -84,11 +87,11 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, Body(new ZodPipe(DecisionBody)))
+    __param(3, ZBody(ApprovalDecisionBody))
 ], ApprovalsController.prototype, "decide", null);
 ApprovalsController = __decorate([
     Controller("api/v1/orgs/:orgId/approvals"),
-    __param(0, Inject(APPROVALS))
+    __param(0, Inject(ApprovalsService))
 ], ApprovalsController);
 export { ApprovalsController };
 /** 本人的「以后都允许」授权（`/api/v1/orgs/:orgId/me/tool-grants`）：查看与撤销，只动自己的。 */
@@ -123,6 +126,6 @@ __decorate([
 ], ToolGrantsController.prototype, "revoke", null);
 ToolGrantsController = __decorate([
     Controller("api/v1/orgs/:orgId/me/tool-grants"),
-    __param(0, Inject(APPROVALS))
+    __param(0, Inject(ApprovalsService))
 ], ToolGrantsController);
 export { ToolGrantsController };

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `GET /approvals?status=`: absent lists every status. */
+export declare const ApprovalsListQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        cancelled: "cancelled";
+        denied: "denied";
+        expired: "expired";
+        pending: "pending";
+    }>>;
+}, z.core.$strict>;
+/** `:id` of `GET /approvals/:id`, as the route takes it (`@Param`). */
+export declare const ApprovalPathParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The approval reads a Platform operation mirrors. Deciding (`POST /approvals/:id/decision`) is a
+ * person's act and stays excluded (spec §6.4, §14.1 item 2), so it has no entry here.
+ */
+export declare const APPROVAL_ROUTES: readonly RouteSchemas[];

package/dist/tools/approvals.schemas.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+/** `GET /approvals?status=`: absent lists every status. */
+export const ApprovalsListQuerySchema = z
+    .object({ status: z.enum(["pending", "approved", "denied", "expired", "cancelled"]).optional() })
+    .strict();
+/** `:id` of `GET /approvals/:id`, as the route takes it (`@Param`). */
+export const ApprovalPathParams = z.object({ id: z.string() });
+/**
+ * The approval reads a Platform operation mirrors. Deciding (`POST /approvals/:id/decision`) is a
+ * person's act and stays excluded (spec §6.4, §14.1 item 2), so it has no entry here.
+ */
+export const APPROVAL_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/approvals", query: ApprovalsListQuerySchema },
+    { route: "GET /api/v1/orgs/:orgId/approvals/:id", params: ApprovalPathParams },
+];

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

@@ -1,11 +1,11 @@
-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 LocalizedName } 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";
 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;
@@ -32,6 +32,16 @@ export interface ApprovalRecord {
     decidedAt: string | null;
     /** The reason given with a denial (null otherwise). */
     denyReason: string | null;
+    /** The kernel-rendered summary of the call (a per-call policy's; null otherwise). */
+    summary: {
+        zh: string;
+        en: string;
+    } | null;
+    /**
+     * The scopes the decider may choose: stored with the approval (a per-call policy that may not
+     * be remembered stores `["once"]`), else derived: only "once" for a role escalation.
+     */
+    scopes: ApprovalScope[];
     expiresAt: string;
     createdAt: string;
 }
@@ -44,13 +54,19 @@ export interface ApprovalView extends ApprovalRecord {
         name: string;
         slug: string;
     } | null;
+    /** An extension tool's plugin (`plugin__<plugin>__<tool>`) and its display name (display only). */
+    extension: {
+        name: string;
+        displayName: LocalizedName;
+    } | 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>`.
+     * 网页中该会话的路径（不含语言前缀）。A sub-agent's approval, at any depth, links to the root
+     * conversation of its tree with the sub-agent open: `/chat/<root>?subagent=<child>` (agent map
+     * spec §7).
      */
     conversationPath: string;
     /** Set when the approval belongs to a sub-agent: the conversation it was dispatched from. */
@@ -77,6 +93,13 @@ export interface ApprovalRequestInput {
     attempt?: number;
     /** Which rule asked (written to `approval_requested.policy`; display only). */
     policy?: ApprovalPolicySource;
+    /** The kernel-rendered summary of the call (per-call policies). */
+    summary?: {
+        zh: string;
+        en: string;
+    };
+    /** The scopes the decider may choose; unset: derived (see {@link ApprovalRecord.scopes}). */
+    scopes?: ApprovalScope[];
 }
 export interface DecisionInput {
     decision: "approve" | "deny";
@@ -94,29 +117,28 @@ export interface ToolGrantView {
     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` 审批行，多副本并发处理同一审批时恰好一个生效。
+ *
+ * A decision is announced after the commit as the domain event `approval.decided` (exactly once:
+ * only the decision that changed the row from pending), 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`) and published after the commit.
  */
 export declare class ApprovalsService {
-    private readonly deps;
-    constructor(deps: ApprovalsServiceDeps);
+    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`）并写 `approval_requested`，同一事务。
      * 按 (run_id, call_id, attempt) 幂等：已存在则返回已有记录（不覆盖），事件按 `approval_requested:<approvalId>` 幂等。
      */
     request(input: ApprovalRequestInput): Promise<ApprovalRecord>;
+    private requestIn;
     /** 当前用户能处理的审批（新的在前，最多 {@link APPROVALS_LIST_MAX} 条）；`status` 缺省为全部。 */
     list(orgId: string, accountId: string, status?: ApprovalStatus): Promise<ApprovalView[]>;
     /** 详情；当前用户不能处理的一律 `approval.not_found`（不泄露存在）。 */
@@ -128,6 +150,7 @@ export declare class ApprovalsService {
      * 提交后发布事件并调用 `onDecided`。
      */
     decide(orgId: string, id: string, accountId: string, body: DecisionInput, actorTokenId?: string): Promise<ApprovalRecord>;
+    private decideIn;
     /**
      * 详情，不做处理人校验（内核内部用：渠道出站投递组装 IM 审批卡片）；不存在返回 null。
      * 不得直接回给请求方——HTTP 接口用 {@link get}。
@@ -144,26 +167,29 @@ export declare class ApprovalsService {
         outcome: "expired" | "not_due" | "settled";
         record?: ApprovalRecord;
     }>;
+    private expireIn;
     /**
-     * 在事务 `t` 内取消运行的全部 pending 审批（运行在等待中被中止），各写 `approval_decided{cancelled}`
-     * （处理人为 null）。返回被取消的记录；调用方提交后发布事件。
+     * 在调用方的事务内（`mandatory`）取消运行的全部 pending 审批（运行在等待中被中止），各写
+     * `approval_decided{cancelled}`（处理人为 null）。返回被取消的记录；调用方提交后发布事件。
      */
-    cancelPendingIn(t: Trx, runId: string): Promise<ApprovalRecord[]>;
+    cancelPendingIn(runId: string): Promise<ApprovalRecord[]>;
     /**
-     * 在事务 `t` 内取消某组织里指定由 `accountId` 处理（`requested_for`）的全部 pending 审批（成员离职），
+     * 在调用方的事务内（`mandatory`）取消某组织里指定由 `accountId` 处理（`requested_for`）的全部 pending 审批（成员离职），
      * 走与 {@link cancelPendingIn} 相同的取消路径：置 cancelled、写 `approval_decided{cancelled}`（处理人为 null）。
      * 返回被取消的记录与各会话写到的最大 seq；调用方提交后发布事件（并可续跑对应运行）。
      */
-    cancelPendingFor(t: Trx, orgId: string, accountId: string): Promise<{
+    cancelPendingFor(orgId: string, accountId: string): Promise<{
         records: ApprovalRecord[];
         seqs: Map<string, number>;
     }>;
-    /** 系统写的 `approval_decided`（超时 / 取消，处理人为 null），返回事件 seq。 */
+    /** 系统写的 `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 revokeGrantIn;
+    /** The member's current role, read in the context's transaction when there is one. */
     private roleOf;
     /** agent id → 当前版本定义里的名字。 */
     private agentNames;