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

package/dist/storage/purge.js

@@ -1,8 +1,22 @@
+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 { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-/** 维护任务：清理已删除组织的对象存储（任务名与 scheduler id 不含 `:`）。 */
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { StorageService } from "./storage.service.js";
+/** 定时任务：清理已删除组织的对象存储（名字不含 `:`），每小时整点。 */
 export const STORAGE_PURGE_JOB = "storage-org-purge";
-export const STORAGE_PURGE_SCHEDULER_ID = "storage-org-purge-hourly";
-export const STORAGE_PURGE_EVERY_MS = 3_600_000;
 /** 每次运行最多处理的组织数（成功与失败合计）。 */
 const PURGE_BATCH = 100;
 /** 认领超过这么久仍未完成（运行中途退出）就可被重新认领。 */
@@ -73,3 +87,41 @@ export async function purgeDeletedOrgStorage(d) {
     }
     return purged;
 }
+/**
+ * The hourly `storage-org-purge` job (fixed period: `@LockedCron`, once per tick across replicas):
+ * {@link purgeDeletedOrgStorage} with `storage.purgeDeletedOrgsAfterDays`.
+ */
+let StoragePurgeJob = class StoragePurgeJob {
+    db;
+    storage;
+    config;
+    lockService;
+    log;
+    constructor(db, storage, config, lockService, log) {
+        this.db = db;
+        this.storage = storage;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async run() {
+        await purgeDeletedOrgStorage({
+            db: this.db,
+            storage: this.storage,
+            afterDays: this.config.get().storage.purgeDeletedOrgsAfterDays,
+            log: this.log,
+        });
+    }
+};
+__decorate([
+    LockedCron("0 * * * *", { name: STORAGE_PURGE_JOB })
+], StoragePurgeJob.prototype, "run", null);
+StoragePurgeJob = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(KernelConfigService)),
+    __param(3, Inject(LockService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], StoragePurgeJob);
+export { StoragePurgeJob };

package/dist/storage/storage.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Object storage (`object-store@1` with the kernel's key prefixes): the one {@link StorageService}
+ * (the hourly `storage-org-purge` job, `StoragePurgeJob`, is the worker role's: `WorkerModule`).
+ */
+export declare class StorageModule {
+}

package/dist/storage/storage.module.js

@@ -0,0 +1,23 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { ExtensionRegistryModule } from "../extensions/registry.js";
+import { StorageService } from "./storage.service.js";
+/**
+ * Object storage (`object-store@1` with the kernel's key prefixes): the one {@link StorageService}
+ * (the hourly `storage-org-purge` job, `StoragePurgeJob`, is the worker role's: `WorkerModule`).
+ */
+let StorageModule = class StorageModule {
+};
+StorageModule = __decorate([
+    Module({
+        imports: [ExtensionRegistryModule],
+        providers: [StorageService],
+        exports: [StorageService],
+    })
+], StorageModule);
+export { StorageModule };

package/dist/storage/storage.service.d.ts

@@ -1,4 +1,6 @@
 import { ExtensionPointUnavailableError, type ExtensionStorage, type ObjectStore } from "@capybara-hq/plugin-sdk";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
 export { StorageKeyError } from "./prefix.js";
 /** 部署级对象的键前缀（见 {@link StorageService.deployment}）。 */
 export declare const DEPLOYMENT_PREFIX = "deployment/";
@@ -8,22 +10,25 @@ export declare const storageUnavailable: () => ExtensionPointUnavailableError;
 export declare const MAX_PRESIGN_TTL_SECONDS = 604800;
 /** 把预签名有效期取整并限制在 1..{@link MAX_PRESIGN_TTL_SECONDS}；不是有限数时抛 RangeError。 */
 export declare function clampPresignTtl(ttlSeconds: number): number;
-export interface StorageServiceDeps {
+/** Where a {@link PrefixedStorage} gets its object store and the extensions that may hold data. */
+export interface StorageSource {
     /** 当前的 `object-store@1` 提供方；每次调用时取（提供方在插件加载过程中才就绪）。 */
     provider: () => ObjectStore | undefined;
     /** 可能存过数据的插件名（删除组织数据时逐个删 `plugins/<插件>/<orgId>/`）。 */
     plugins: () => Promise<string[]>;
 }
 /**
- * 内核的对象存储服务（扩展模型 §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 declare class StorageService {
+export declare class PrefixedStorage {
     private readonly d;
-    constructor(d: StorageServiceDeps);
+    constructor(d: StorageSource);
     /** 是否有对象存储提供方。 */
     get available(): boolean;
     /** 依赖存储的 HTTP 功能在入口调用：没有提供方时抛 `ApiError("storage.unavailable")`（503）。 */
@@ -42,3 +47,12 @@ export declare class StorageService {
     deleteOrg(orgId: string): Promise<number>;
     private require;
 }
+/**
+ * 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.
+ */
+export declare class StorageService extends PrefixedStorage {
+    constructor(registry: ExtensionRegistry, db: KernelDb);
+}

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/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,14 +7,14 @@ 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";
+import { APPROVAL_DENY_REASON_MAX_CHARS, ApprovalsService, } from "./approvals.service.js";
 const ListQuery = z
     .object({ status: z.enum(["pending", "approved", "denied", "expired", "cancelled"]).optional() })
     .strict();
@@ -39,6 +39,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 +72,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 +88,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 +127,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.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;
@@ -44,6 +44,11 @@ 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;
@@ -94,29 +99,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 +132,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 +149,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;