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

package/dist/storage/prefix.js

@@ -0,0 +1,104 @@
+/**
+ * 对象存储的键前缀与校验（扩展模型 §5）：插件 `plugins/<插件名>/<orgId>/`，内核 `kernel/<orgId>/`。
+ * 任何拼出来会落到前缀之外的键一律拒绝；校验发生在调用提供方之前。
+ */
+/** 加前缀后的键长度上限（S3 的键上限是 1024 字节，这里按 UTF-8 字节计）。 */
+export const MAX_STORAGE_KEY_BYTES = 1024;
+/** 键或前缀不合法（越出前缀、组织 id 不是 UUID 等）。消息为英文、不含键之外的内部信息。 */
+export class StorageKeyError extends Error {
+    constructor(message) {
+        super(`invalid storage key: ${message}`);
+        this.name = "StorageKeyError";
+    }
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** 插件名规则同清单（`defineExtension` 的 name 校验）。 */
+const EXTENSION_NAME_RE = /^[a-z][a-z0-9-]{1,40}$/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拒绝控制字符
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+/** 字面的 `${`（POST 策略的变量起始符）。 */
+const TEMPLATE_START = "${";
+/**
+ * 组织 id 必须是 UUID；统一转成小写，同一组织不论大小写都落到同一个前缀
+ * （内核生成的组织 id 本来就是小写）。
+ */
+export function normalizeOrgId(orgId) {
+    if (typeof orgId !== "string" || !UUID_RE.test(orgId)) {
+        throw new StorageKeyError("organization id must be a UUID");
+    }
+    return orgId.toLowerCase();
+}
+/** 插件名必须符合清单规则（不含 `/`、`..`）。 */
+export function assertPluginName(plugin) {
+    if (typeof plugin !== "string" || !EXTENSION_NAME_RE.test(plugin)) {
+        throw new StorageKeyError(`plugin name "${plugin}" is not valid`);
+    }
+}
+/**
+ * 校验调用方给的相对键（`allowEmpty` 时是列举 / 批量删除的前缀，空串表示全部）：
+ * 不能以 `/` 开头，不能有 `.` / `..` 段，不能含 `\`、控制字符与 `${`
+ * （S3 POST 策略会把键里的 `${filename}` 换成上传方给的文件名，键就不再是签名时的那个）。
+ */
+function assertRelative(key, allowEmpty) {
+    if (typeof key !== "string")
+        throw new StorageKeyError("key must be a string");
+    if (key === "") {
+        if (allowEmpty)
+            return;
+        throw new StorageKeyError("key must not be empty");
+    }
+    if (key.startsWith("/"))
+        throw new StorageKeyError("key must not start with '/'");
+    if (key.includes("\\"))
+        throw new StorageKeyError("key must not contain '\\'");
+    if (CONTROL_RE.test(key))
+        throw new StorageKeyError("key must not contain control characters");
+    if (key.includes(TEMPLATE_START))
+        throw new StorageKeyError(`key must not contain '${TEMPLATE_START}'`);
+    for (const seg of key.split("/")) {
+        if (seg === "." || seg === "..") {
+            throw new StorageKeyError("key must not contain '.' or '..' segments");
+        }
+    }
+}
+/** 一个组织下的键空间：把相对键拼成完整键，把完整键还原成相对键。 */
+export class KeySpace {
+    prefix;
+    /** @param prefix 以 `/` 结尾的完整前缀（如 `plugins/x/<orgId>/`）。 */
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    /** 对象键：非空，拼接后不超过 {@link MAX_STORAGE_KEY_BYTES}。 */
+    key(key) {
+        assertRelative(key, false);
+        return this.checkLength(this.prefix + key);
+    }
+    /** 列举 / 批量删除的前缀：可以为空（表示该组织下的全部）。 */
+    listPrefix(prefix) {
+        assertRelative(prefix, true);
+        return this.checkLength(this.prefix + prefix);
+    }
+    /** 完整键是否在本前缀下。 */
+    owns(full) {
+        return full.startsWith(this.prefix) && full.length > this.prefix.length;
+    }
+    /** 去掉前缀（调用方先用 {@link owns} 过滤）。 */
+    strip(full) {
+        return full.slice(this.prefix.length);
+    }
+    checkLength(full) {
+        if (Buffer.byteLength(full, "utf8") > MAX_STORAGE_KEY_BYTES) {
+            throw new StorageKeyError(`key is longer than ${MAX_STORAGE_KEY_BYTES} bytes with its prefix`);
+        }
+        return full;
+    }
+}
+/** 插件在某组织下的前缀 `plugins/<插件>/<orgId>/`。 */
+export function pluginPrefix(plugin, orgId) {
+    assertPluginName(plugin);
+    return `plugins/${plugin}/${normalizeOrgId(orgId)}/`;
+}
+/** 内核在某组织下的前缀 `kernel/<orgId>/`。 */
+export function kernelPrefix(orgId) {
+    return `kernel/${normalizeOrgId(orgId)}/`;
+}

package/dist/storage/purge.d.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { StorageService } from "./storage.service.js";
+/** 维护任务：清理已删除组织的对象存储（任务名与 scheduler id 不含 `:`）。 */
+export declare const STORAGE_PURGE_JOB = "storage-org-purge";
+export declare const STORAGE_PURGE_SCHEDULER_ID = "storage-org-purge-hourly";
+export declare const STORAGE_PURGE_EVERY_MS = 3600000;
+/**
+ * 删除「软删除超过 `afterDays` 天、尚未清理存储」的组织的全部对象（`StorageService.deleteOrg`），
+ * 成功后写 `orgs.storage_purged_at`，之后不再处理。返回本次清理的组织数。
+ * 没有对象存储提供方时什么也不做（不认领、不标记，装上提供方后再清理）。
+ *
+ * 每个组织三步，不在事务里做网络调用：
+ * 1. 认领：一条 `UPDATE … RETURNING`（子查询 `FOR UPDATE SKIP LOCKED`）写 `storage_purge_claimed_at`，
+ *    只认领未被认领、或认领已超过 {@link CLAIM_STALE_MINUTES} 分钟的组织。同一时刻的并发认领只有一方成功；
+ *    但认领不是租约：持有方删得比 {@link CLAIM_STALE_MINUTES} 还久（或已退出）时，别的副本会重新认领，两方可能
+ *    同时删同一组织的对象，先结束的一方还会清掉对方的认领。这是可以接受的：`deleteOrg` 幂等，`storage_purged_at`
+ *    只在删除成功后写，最坏只是重复删除或下一轮再删一次；
+ * 2. 在事务外删除对象（`deleteOrg` 幂等）；
+ * 3. 成功：写 `storage_purged_at` 并清空认领；失败：清空认领（下一次运行重试），本次运行不再碰它。
+ */
+export declare function purgeDeletedOrgStorage(d: {
+    db: KernelDb;
+    storage: StorageService;
+    afterDays: number;
+    log: Pick<Logger, "info" | "warn">;
+}): Promise<number>;

package/dist/storage/purge.js

@@ -0,0 +1,75 @@
+import { sql } from "kysely";
+/** 维护任务：清理已删除组织的对象存储（任务名与 scheduler id 不含 `:`）。 */
+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;
+/** 认领超过这么久仍未完成（运行中途退出）就可被重新认领。 */
+const CLAIM_STALE_MINUTES = 60;
+/**
+ * 删除「软删除超过 `afterDays` 天、尚未清理存储」的组织的全部对象（`StorageService.deleteOrg`），
+ * 成功后写 `orgs.storage_purged_at`，之后不再处理。返回本次清理的组织数。
+ * 没有对象存储提供方时什么也不做（不认领、不标记，装上提供方后再清理）。
+ *
+ * 每个组织三步，不在事务里做网络调用：
+ * 1. 认领：一条 `UPDATE … RETURNING`（子查询 `FOR UPDATE SKIP LOCKED`）写 `storage_purge_claimed_at`，
+ *    只认领未被认领、或认领已超过 {@link CLAIM_STALE_MINUTES} 分钟的组织。同一时刻的并发认领只有一方成功；
+ *    但认领不是租约：持有方删得比 {@link CLAIM_STALE_MINUTES} 还久（或已退出）时，别的副本会重新认领，两方可能
+ *    同时删同一组织的对象，先结束的一方还会清掉对方的认领。这是可以接受的：`deleteOrg` 幂等，`storage_purged_at`
+ *    只在删除成功后写，最坏只是重复删除或下一轮再删一次；
+ * 2. 在事务外删除对象（`deleteOrg` 幂等）；
+ * 3. 成功：写 `storage_purged_at` 并清空认领；失败：清空认领（下一次运行重试），本次运行不再碰它。
+ */
+export async function purgeDeletedOrgStorage(d) {
+    if (!d.storage.available)
+        return 0;
+    let purged = 0;
+    const failed = [];
+    while (purged + failed.length < PURGE_BATCH) {
+        const claimed = await d.db
+            .updateTable("orgs")
+            .set({ storage_purge_claimed_at: sql `now()` })
+            .where("id", "=", d.db
+            .selectFrom("orgs")
+            .select("id")
+            .where("deleted_at", "is not", null)
+            .where("storage_purged_at", "is", null)
+            .where("deleted_at", "<", sql `now() - make_interval(days => ${d.afterDays})`)
+            .where((eb) => eb.or([
+            eb("storage_purge_claimed_at", "is", null),
+            eb("storage_purge_claimed_at", "<", sql `now() - make_interval(mins => ${CLAIM_STALE_MINUTES})`),
+        ]))
+            .$if(failed.length > 0, (q) => q.where("id", "not in", failed))
+            .orderBy("deleted_at")
+            .limit(1)
+            .forUpdate()
+            .skipLocked())
+            .returning("id")
+            .executeTakeFirst();
+        if (!claimed)
+            return purged;
+        const orgId = claimed.id;
+        try {
+            const objects = await d.storage.deleteOrg(orgId);
+            await d.db
+                .updateTable("orgs")
+                .set({ storage_purged_at: sql `now()`, storage_purge_claimed_at: null })
+                .where("id", "=", orgId)
+                .execute();
+            purged++;
+            d.log.info("deleted organization storage purged", { orgId, objects });
+        }
+        catch (err) {
+            failed.push(orgId);
+            d.log.warn("cannot purge deleted organization storage; will retry", { orgId, err });
+            await d.db
+                .updateTable("orgs")
+                .set({ storage_purge_claimed_at: null })
+                .where("id", "=", orgId)
+                .execute()
+                .catch((e) => d.log.warn("cannot release storage purge claim", { orgId, err: e }));
+        }
+    }
+    return purged;
+}

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

@@ -0,0 +1,44 @@
+import { ExtensionPointUnavailableError, type ExtensionStorage, type ObjectStore } from "@capybara-hq/plugin-sdk";
+export { StorageKeyError } from "./prefix.js";
+/** 部署级对象的键前缀（见 {@link StorageService.deployment}）。 */
+export declare const DEPLOYMENT_PREFIX = "deployment/";
+/** 没有对象存储提供方时的错误（HTTP 层映射为 `storage.unavailable`，503）。 */
+export declare const storageUnavailable: () => ExtensionPointUnavailableError;
+/** 预签名 URL 的有效期上限（秒）：SigV4 预签名最长 7 天。 */
+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 {
+    /** 当前的 `object-store@1` 提供方；每次调用时取（提供方在插件加载过程中才就绪）。 */
+    provider: () => ObjectStore | undefined;
+    /** 可能存过数据的插件名（删除组织数据时逐个删 `plugins/<插件>/<orgId>/`）。 */
+    plugins: () => Promise<string[]>;
+}
+/**
+ * 内核的对象存储服务（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。
+ * - 插件经 {@link forPlugin} 拿到 `ctx.storage`：键落在 `plugins/<插件>/<orgId>/` 下；
+ * - 内核功能经 {@link kernel} 用 `kernel/<orgId>/`；
+ * - 返回给调用方的键（`head` / `get` / `put` / `list`）都去掉前缀，列举结果只保留本前缀下的对象。
+ * 没有提供方时各方法 reject `storage.unavailable`（{@link available} 为 false）。本身无状态，可多副本共用。
+ */
+export declare class StorageService {
+    private readonly d;
+    constructor(d: StorageServiceDeps);
+    /** 是否有对象存储提供方。 */
+    get available(): boolean;
+    /** 依赖存储的 HTTP 功能在入口调用：没有提供方时抛 `ApiError("storage.unavailable")`（503）。 */
+    assertAvailable(): void;
+    /** 插件的 `ctx.storage`：每个方法先校验 orgId 与键，再加前缀 `plugins/<plugin>/<orgId>/`。 */
+    forPlugin(plugin: string): ExtensionStorage;
+    /** 内核在该组织下的存储（前缀 `kernel/<orgId>/`）。orgId 不是 UUID 时立即抛 StorageKeyError。 */
+    kernel(orgId: string): ObjectStore;
+    /**
+     * 内核的部署级存储（前缀 {@link DEPLOYMENT_PREFIX}，不属于任何组织，如插件包
+     * `deployment/plugins/blobs/<sha256>.tgz`）。{@link deleteOrg} 不触及。
+     */
+    deployment(): ObjectStore;
+    private scopedStore;
+    /** 删除该组织的全部对象：`kernel/<orgId>/` 与每个插件的 `plugins/<插件>/<orgId>/`。返回删除数。 */
+    deleteOrg(orgId: string): Promise<number>;
+    private require;
+}

package/dist/storage/storage.service.js

@@ -0,0 +1,145 @@
+import { ExtensionPointUnavailableError, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { KeySpace, kernelPrefix, normalizeOrgId, pluginPrefix } from "./prefix.js";
+export { StorageKeyError } from "./prefix.js";
+/** 部署级对象的键前缀（见 {@link StorageService.deployment}）。 */
+export const DEPLOYMENT_PREFIX = "deployment/";
+/** 没有对象存储提供方时的错误（HTTP 层映射为 `storage.unavailable`，503）。 */
+export const storageUnavailable = () => new ExtensionPointUnavailableError("storage.unavailable: object storage is not available in this deployment");
+/** 预签名 URL 的有效期上限（秒）：SigV4 预签名最长 7 天。 */
+export const MAX_PRESIGN_TTL_SECONDS = 604_800;
+/** 把预签名有效期取整并限制在 1..{@link MAX_PRESIGN_TTL_SECONDS}；不是有限数时抛 RangeError。 */
+export function clampPresignTtl(ttlSeconds) {
+    if (typeof ttlSeconds !== "number" || !Number.isFinite(ttlSeconds)) {
+        throw new RangeError("storage: ttlSeconds must be a finite number");
+    }
+    return Math.min(MAX_PRESIGN_TTL_SECONDS, Math.max(1, Math.floor(ttlSeconds)));
+}
+/**
+ * 内核的对象存储服务（扩展模型 §5）：在 `object-store@1` 提供方之上加前缀隔离。
+ * - 插件经 {@link forPlugin} 拿到 `ctx.storage`：键落在 `plugins/<插件>/<orgId>/` 下；
+ * - 内核功能经 {@link kernel} 用 `kernel/<orgId>/`；
+ * - 返回给调用方的键（`head` / `get` / `put` / `list`）都去掉前缀，列举结果只保留本前缀下的对象。
+ * 没有提供方时各方法 reject `storage.unavailable`（{@link available} 为 false）。本身无状态，可多副本共用。
+ */
+export class StorageService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /** 是否有对象存储提供方。 */
+    get available() {
+        return this.d.provider() !== undefined;
+    }
+    /** 依赖存储的 HTTP 功能在入口调用：没有提供方时抛 `ApiError("storage.unavailable")`（503）。 */
+    assertAvailable() {
+        if (!this.available) {
+            throw new ApiError("storage.unavailable", "Object storage is not available in this deployment; install an object-store plugin");
+        }
+    }
+    /** 插件的 `ctx.storage`：每个方法先校验 orgId 与键，再加前缀 `plugins/<plugin>/<orgId>/`。 */
+    forPlugin(plugin) {
+        // 先按一个合法的组织 id 校验插件名：名字不合法时立即抛错，而不是等到第一次调用
+        pluginPrefix(plugin, "00000000-0000-0000-0000-000000000000");
+        const space = (orgId) => new KeySpace(pluginPrefix(plugin, orgId));
+        const run = async (orgId, fn) => {
+            const store = this.require();
+            return fn(new ScopedStore(store, space(orgId)));
+        };
+        return {
+            put: (orgId, key, body, opts) => run(orgId, (s) => s.put(key, body, opts)),
+            get: (orgId, key, opts) => run(orgId, (s) => s.get(key, opts)),
+            head: (orgId, key) => run(orgId, (s) => s.head(key)),
+            delete: (orgId, key) => run(orgId, (s) => s.delete(key)),
+            deletePrefix: (orgId, prefix) => run(orgId, (s) => s.deletePrefix(prefix)),
+            list: (orgId, prefix, opts) => run(orgId, (s) => s.list(prefix, opts)),
+            presignGet: (orgId, key, opts) => run(orgId, (s) => s.presignGet(key, opts)),
+            presignPut: (orgId, key, opts) => run(orgId, (s) => s.presignPut(key, opts)),
+        };
+    }
+    /** 内核在该组织下的存储（前缀 `kernel/<orgId>/`）。orgId 不是 UUID 时立即抛 StorageKeyError。 */
+    kernel(orgId) {
+        return this.scopedStore(new KeySpace(kernelPrefix(orgId)));
+    }
+    /**
+     * 内核的部署级存储（前缀 {@link DEPLOYMENT_PREFIX}，不属于任何组织，如插件包
+     * `deployment/plugins/blobs/<sha256>.tgz`）。{@link deleteOrg} 不触及。
+     */
+    deployment() {
+        return this.scopedStore(new KeySpace(DEPLOYMENT_PREFIX));
+    }
+    scopedStore(ks) {
+        const scoped = () => new ScopedStore(this.require(), ks);
+        return {
+            put: async (key, body, opts) => scoped().put(key, body, opts),
+            get: async (key, opts) => scoped().get(key, opts),
+            head: async (key) => scoped().head(key),
+            delete: async (key) => scoped().delete(key),
+            deletePrefix: async (prefix) => scoped().deletePrefix(prefix),
+            list: async (prefix, opts) => scoped().list(prefix, opts),
+            presignGet: async (key, opts) => scoped().presignGet(key, opts),
+            presignPut: async (key, opts) => scoped().presignPut(key, opts),
+        };
+    }
+    /** 删除该组织的全部对象：`kernel/<orgId>/` 与每个插件的 `plugins/<插件>/<orgId>/`。返回删除数。 */
+    async deleteOrg(orgId) {
+        const store = this.require();
+        normalizeOrgId(orgId);
+        let n = await store.deletePrefix(kernelPrefix(orgId));
+        for (const plugin of new Set(await this.d.plugins())) {
+            n += await store.deletePrefix(pluginPrefix(plugin, orgId));
+        }
+        return n;
+    }
+    require() {
+        const store = this.d.provider();
+        if (!store)
+            throw storageUnavailable();
+        return store;
+    }
+}
+/** 一个前缀下的 ObjectStore 视图：键先校验再拼接，返回的键去掉前缀。 */
+class ScopedStore {
+    store;
+    space;
+    constructor(store, space) {
+        this.store = store;
+        this.space = space;
+    }
+    rel(h, key) {
+        return { ...h, key };
+    }
+    async put(key, body, opts) {
+        return this.rel(await this.store.put(this.space.key(key), body, opts), key);
+    }
+    async get(key, opts) {
+        const r = await this.store.get(this.space.key(key), opts);
+        return r ? { head: this.rel(r.head, key), body: r.body } : null;
+    }
+    async head(key) {
+        const h = await this.store.head(this.space.key(key));
+        return h ? this.rel(h, key) : null;
+    }
+    async delete(key) {
+        await this.store.delete(this.space.key(key));
+    }
+    async deletePrefix(prefix) {
+        return this.store.deletePrefix(this.space.listPrefix(prefix));
+    }
+    async list(prefix, opts) {
+        const r = await this.store.list(this.space.listPrefix(prefix), opts);
+        // 防御：提供方返回了前缀之外的键时丢掉，调用方永远看不到别的前缀
+        const items = r.items
+            .filter((i) => this.space.owns(i.key))
+            .map((i) => this.rel(i, this.space.strip(i.key)));
+        return r.cursor === undefined ? { items } : { items, cursor: r.cursor };
+    }
+    async presignGet(key, opts) {
+        const ttlSeconds = clampPresignTtl(opts.ttlSeconds);
+        return this.store.presignGet(this.space.key(key), { ...opts, ttlSeconds });
+    }
+    async presignPut(key, opts) {
+        const ttlSeconds = clampPresignTtl(opts.ttlSeconds);
+        return this.store.presignPut(this.space.key(key), { ...opts, ttlSeconds });
+    }
+}

package/dist/text.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Characters people-facing one-line labels (conversation titles, tool titles) never carry: format
+ * characters (Unicode Cf: bidi marks, overrides and isolates U+061C, U+200E/F, U+202A–202E,
+ * U+2066–2069; zero-width and invisible ones like U+200B, U+2060, U+FEFF; tag characters) except
+ * ZWNJ (U+200C) and ZWJ (U+200D), which Persian and other scripts and emoji sequences need. The same
+ * rule as the plugin SDK's `validateToolPresentation` and connector-mcp's title cleaning.
+ *
+ * Global: for `String.replace` only. Never call `.test()` / `.exec()` on it (a global regex keeps
+ * `lastIndex` between calls); use {@link CONTROL_OR_HIDDEN_RE} to test.
+ */
+export declare const HIDDEN_FORMAT_RE: RegExp;
+/** {@link HIDDEN_FORMAT_RE} plus control characters (Cc, newlines included). */
+export declare const CONTROL_OR_HIDDEN_RE: RegExp;

package/dist/text.js

@@ -0,0 +1,13 @@
+/**
+ * Characters people-facing one-line labels (conversation titles, tool titles) never carry: format
+ * characters (Unicode Cf: bidi marks, overrides and isolates U+061C, U+200E/F, U+202A–202E,
+ * U+2066–2069; zero-width and invisible ones like U+200B, U+2060, U+FEFF; tag characters) except
+ * ZWNJ (U+200C) and ZWJ (U+200D), which Persian and other scripts and emoji sequences need. The same
+ * rule as the plugin SDK's `validateToolPresentation` and connector-mcp's title cleaning.
+ *
+ * Global: for `String.replace` only. Never call `.test()` / `.exec()` on it (a global regex keeps
+ * `lastIndex` between calls); use {@link CONTROL_OR_HIDDEN_RE} to test.
+ */
+export const HIDDEN_FORMAT_RE = /(?![\u200C\u200D])\p{Cf}/gu;
+/** {@link HIDDEN_FORMAT_RE} plus control characters (Cc, newlines included). */
+export const CONTROL_OR_HIDDEN_RE = /(?![\u200C\u200D])[\p{Cc}\p{Cf}]/u;

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

@@ -0,0 +1,53 @@
+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";
+declare const ListQuery: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        approved: "approved";
+        cancelled: "cancelled";
+        denied: "denied";
+        expired: "expired";
+        pending: "pending";
+    }>>;
+}, z.core.$strict>;
+declare const DecisionBody: z.ZodObject<{
+    decision: z.ZodEnum<{
+        approve: "approve";
+        deny: "deny";
+    }>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        always: "always";
+        once: "once";
+        session: "session";
+    }>>;
+    note: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * 工具调用审批（`/api/v1/orgs/:orgId/approvals`，`approvals.decide`：访客起、仅限用户主体——agent 不能审批，R2）。
+ * 能否看到 / 处理某条审批由 `requested_for` / `approver_role` 判定（见 `ApprovalsService`），看不到的一律 404。
+ */
+export declare class ApprovalsController {
+    private readonly approvals;
+    constructor(approvals: ApprovalsService);
+    list(principal: Principal, org: OrgContext, q: z.infer<typeof ListQuery>): Promise<{
+        approvals: ApprovalView[];
+    }>;
+    get(principal: Principal, org: OrgContext, id: string): Promise<{
+        approval: ApprovalView;
+    }>;
+    decide(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof DecisionBody>): Promise<{
+        approval: ApprovalRecord;
+    }>;
+}
+/** 本人的「以后都允许」授权（`/api/v1/orgs/:orgId/me/tool-grants`）：查看与撤销，只动自己的。 */
+export declare class ToolGrantsController {
+    private readonly approvals;
+    constructor(approvals: ApprovalsService);
+    list(principal: Principal, org: OrgContext): Promise<{
+        grants: ToolGrantView[];
+    }>;
+    revoke(principal: Principal, org: OrgContext, agentId: string, toolKey: string): Promise<void>;
+}
+export {};

package/dist/tools/approvals.controller.js

@@ -0,0 +1,128 @@
+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, Delete, Get, HttpCode, Inject, Param, Post, Query, } 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 { 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();
+const DecisionBody = z
+    .object({
+    decision: z.enum(["approve", "deny"]),
+    scope: z.enum(["once", "session", "always"]).optional(),
+    note: z.string().max(1000).optional(),
+    /** Only with `deny`: passed to the model with the denied call's result. */
+    // no control characters but newline and tab, and no format characters (bidi, invisible; ZWNJ
+    // and ZWJ allowed): the title rule (final review m1; PG also rejects NUL)
+    reason: z
+        .string()
+        .trim()
+        .min(1)
+        .max(APPROVAL_DENY_REASON_MAX_CHARS)
+        .refine((r) => !CONTROL_OR_HIDDEN_RE.test(r.replace(/[\n\t]/g, " ")), "reason must not contain control or format characters")
+        .optional(),
+})
+    .strict()
+    .refine((b) => b.reason === undefined || b.decision === "deny", {
+    path: ["reason"],
+    message: "A reason can only be given with deny",
+});
+/**
+ * 工具调用审批（`/api/v1/orgs/:orgId/approvals`，`approvals.decide`：访客起、仅限用户主体——agent 不能审批，R2）。
+ * 能否看到 / 处理某条审批由 `requested_for` / `approver_role` 判定（见 `ApprovalsService`），看不到的一律 404。
+ */
+let ApprovalsController = class ApprovalsController {
+    approvals;
+    constructor(approvals) {
+        this.approvals = approvals;
+    }
+    async list(principal, org, q) {
+        const p = requireUser(principal);
+        return { approvals: await this.approvals.list(org.orgId, p.account.id, q.status) };
+    }
+    async get(principal, org, id) {
+        const p = requireUser(principal);
+        return { approval: await this.approvals.get(org.orgId, id, p.account.id) };
+    }
+    async decide(principal, org, id, body) {
+        const p = requireUser(principal);
+        return {
+            approval: await this.approvals.decide(org.orgId, id, p.account.id, body, patTokenId(p)),
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Query(new ZodPipe(ListQuery)))
+], ApprovalsController.prototype, "list", null);
+__decorate([
+    Get(":id"),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], ApprovalsController.prototype, "get", null);
+__decorate([
+    Post(":id/decision"),
+    HttpCode(200),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Body(new ZodPipe(DecisionBody)))
+], ApprovalsController.prototype, "decide", null);
+ApprovalsController = __decorate([
+    Controller("api/v1/orgs/:orgId/approvals"),
+    __param(0, Inject(APPROVALS))
+], ApprovalsController);
+export { ApprovalsController };
+/** 本人的「以后都允许」授权（`/api/v1/orgs/:orgId/me/tool-grants`）：查看与撤销，只动自己的。 */
+let ToolGrantsController = class ToolGrantsController {
+    approvals;
+    constructor(approvals) {
+        this.approvals = approvals;
+    }
+    async list(principal, org) {
+        const p = requireUser(principal);
+        return { grants: await this.approvals.listGrants(org.orgId, p.account.id) };
+    }
+    async revoke(principal, org, agentId, toolKey) {
+        const p = requireUser(principal);
+        await this.approvals.revokeGrant(org.orgId, p.account.id, agentId, toolKey, patTokenId(p));
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], ToolGrantsController.prototype, "list", null);
+__decorate([
+    Delete(":agentId/:toolKey"),
+    HttpCode(204),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Param("toolKey"))
+], ToolGrantsController.prototype, "revoke", null);
+ToolGrantsController = __decorate([
+    Controller("api/v1/orgs/:orgId/me/tool-grants"),
+    __param(0, Inject(APPROVALS))
+], ToolGrantsController);
+export { ToolGrantsController };