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

package/dist/extensions/deployment-config.js

@@ -0,0 +1,394 @@
+import { isDeepStrictEqual } from "node:util";
+import { sql } from "kysely";
+import { configFields, describeSchema, getPath, secretValues } from "../config/fields.js";
+import { fieldSource } from "../config/sources.js";
+import { createSecrets } from "../ctx/secrets.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { configToJsonSchema } from "./config-json-schema.js";
+import { toIssues } from "./org-config.js";
+/** 部署级插件配置的密钥存在 `capybara.secrets` 的这个 org_id 下（不是真实组织；namespace `kernel`）。 */
+export const DEPLOYMENT_SECRETS_ORG = "_deployment";
+/** 内核自己的 secrets 命名空间（`kernel` 是保留插件名）。 */
+const SECRETS_NAMESPACE = "kernel";
+const SECRET_KEY_PREFIX = "plugin-deployment-config:";
+const secretKey = (plugin, path) => `${SECRET_KEY_PREFIX}${plugin}:${path}`;
+/**
+ * 部署配置保存之后（kernel bus 主题，频道 `cap:kernel:plugin-deployment-config`，payload `{ plugin }`）：
+ * 各副本重读并校验——只改了 hot 字段就地替换，改了非 hot 字段重新加载实例，不合法保持当前值并告警；
+ * 插件此刻待配置时，下一次 reconcile 加载它。
+ */
+export const PLUGIN_DEPLOYMENT_CONFIG_TOPIC = "plugin-deployment-config";
+/** 由 zod schema 得出字段清单（`configFields`：对象路径上的叶子，secret 向下继承）。 */
+export function schemaFields(schema) {
+    if (!schema)
+        return [];
+    return configFields(schema).map((f) => ({
+        path: f.path,
+        secret: f.meta?.secret === true,
+        hot: f.meta?.hot === true,
+    }));
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** 按点路径设值，缺失的中间对象自动创建；中间节点不是对象时放弃。 */
+function setDeep(obj, path, value) {
+    const segs = path.split(".");
+    let node = obj;
+    for (const seg of segs.slice(0, -1)) {
+        const next = node[seg];
+        if (next === undefined)
+            node[seg] = {};
+        else if (!isObj(next))
+            return;
+        node = node[seg];
+    }
+    node[segs[segs.length - 1]] = value;
+}
+/** 按点路径删除键；删完变空的中间对象一并删掉。 */
+function deleteDeep(obj, path) {
+    const segs = path.split(".");
+    const chain = [obj];
+    let node = obj;
+    for (const seg of segs.slice(0, -1)) {
+        if (!isObj(node))
+            return;
+        node = node[seg];
+        if (!isObj(node))
+            return;
+        chain.push(node);
+    }
+    delete chain[chain.length - 1][segs[segs.length - 1]];
+    for (let i = chain.length - 1; i > 0; i--) {
+        if (Object.keys(chain[i]).length > 0)
+            break;
+        delete chain[i - 1][segs[i - 1]];
+    }
+}
+/** 叶子点路径（对象递归；其余都是叶子）。 */
+function leafPaths(value, prefix = "", out = []) {
+    if (isObj(value)) {
+        for (const [k, v] of Object.entries(value))
+            leafPaths(v, prefix ? `${prefix}.${k}` : k, out);
+    }
+    else if (prefix !== "")
+        out.push(prefix);
+    return out;
+}
+/** 启动配置（文件 / 环境变量合并后的值）是否覆盖了这个字段：给了它、它下面的值，或在祖先上给了非对象值。 */
+function coveredBy(fileValue, path) {
+    let node = fileValue;
+    for (const seg of path.split(".")) {
+        if (node === undefined)
+            return false;
+        if (!isObj(node))
+            return true;
+        node = node[seg];
+    }
+    return node !== undefined;
+}
+/**
+ * 合并一个插件的部署配置（C10 的优先级：环境变量 > 文件 / Nacos > PG > schema 默认值）：以启动配置
+ * （`fileValue`，已含环境变量）为底，逐字段补上 PG 里保存、而启动配置没有覆盖的值。按字段合并：启动配置给了的字段
+ * 整个以它为准（不与 PG 的值深合并）。`fields` 为字段点路径（没有 schema 时用 PG 值的叶子路径）。默认值由校验补上。
+ */
+export function mergeDeploymentConfig(stored, fileValue, fields = leafPaths(stored)) {
+    if (fileValue !== undefined && !isObj(fileValue))
+        return fileValue;
+    const out = structuredClone(fileValue ?? {});
+    for (const path of fields) {
+        const v = getPath(stored, path);
+        if (v === undefined || coveredBy(fileValue, path))
+            continue;
+        setDeep(out, path, structuredClone(v));
+    }
+    return out;
+}
+/**
+ * PG 里一个插件保存的部署配置（非密钥字段 + 解密的密钥字段，按点路径放回对象）。只并入 `secretPaths`（当前
+ * schema 里是密钥的字段）的密钥：旧版本留下、现在已不是密钥或已删掉的字段不解密、不并入（否则会被当成明文回显
+ * 或保存）。
+ */
+export async function readStoredDeploymentConfig(db, keyring, plugin, opts) {
+    let q = db
+        .selectFrom("extension_deployment_configs")
+        .select("config")
+        .where("plugin", "=", plugin);
+    if (opts.forUpdate)
+        q = q.forUpdate();
+    const row = await q.executeTakeFirst();
+    const out = structuredClone(row?.config ?? {});
+    const prefix = secretKey(plugin, "");
+    const wanted = new Set(opts.secretPaths);
+    if (wanted.size === 0)
+        return out;
+    const keys = await db
+        .selectFrom("secrets")
+        .select("key")
+        .where("namespace", "=", SECRETS_NAMESPACE)
+        .where("org_id", "=", DEPLOYMENT_SECRETS_ORG)
+        .execute();
+    const secrets = createSecrets(db, keyring, SECRETS_NAMESPACE);
+    for (const { key } of keys) {
+        if (!key.startsWith(prefix) || !wanted.has(key.slice(prefix.length)))
+            continue;
+        const v = await secrets.get(DEPLOYMENT_SECRETS_ORG, key);
+        if (v !== null)
+            setDeep(out, key.slice(prefix.length), JSON.parse(v));
+    }
+    return out;
+}
+/** 字段清单里的密钥字段路径。 */
+export const secretPathsOf = (fields) => fields.filter((f) => f.secret).map((f) => f.path);
+/** JSON Schema 转换按 schema 对象缓存（清单不可变）。 */
+const jsonSchemaCache = new WeakMap();
+function jsonSchemaOf(schema) {
+    let js = jsonSchemaCache.get(schema);
+    if (!js) {
+        js = configToJsonSchema(schema);
+        jsonSchemaCache.set(schema, js);
+    }
+    return structuredClone(js);
+}
+/** 某字段 zod 叶子上的默认值（整份配置不合法、校验没能补上默认值时，视图仍按它显示）。 */
+function defaultOf(schema, path) {
+    const f = configFields(schema).find((x) => x.path === path);
+    if (!f)
+        return { has: false };
+    const d = describeSchema(f.schema);
+    return d.hasDefault ? { has: true, value: d.defaultValue } : { has: false };
+}
+/**
+ * Deployment-level extension config (D8 / C10): non-secret fields are stored in
+ * `extension_deployment_configs`, each secret field encrypted in `capybara.secrets` (namespace
+ * `kernel`, org `_deployment`, key `plugin-deployment-config:<plugin>:<path>`). Fields present in the
+ * startup config (file / Nacos / env) are read-only and show their source; the effective value
+ * follows {@link mergeDeploymentConfig}. No in-process state, shared by every replica.
+ * Secret values are never echoed: responses only say "set", audits only record which paths changed.
+ */
+export class ExtensionDeploymentConfigService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /** 插件的生效部署配置（未校验）：启动配置为底，补上 PG 里保存的字段。`schema` 给出时按它的字段合并。 */
+    async effective(plugin, fileValue, schema) {
+        const stored = await readStoredDeploymentConfig(this.d.db, this.d.keyring, plugin, {
+            secretPaths: secretPathsOf(schemaFields(schema)),
+        });
+        const fields = schema ? configFields(schema).map((f) => f.path) : undefined;
+        return mergeDeploymentConfig(stored, fileValue, fields);
+    }
+    /** Admin view; an extension unknown to the deployment -> `extension.not_found`. */
+    async view(plugin) {
+        const info = await this.info(plugin);
+        const stored = await this.d.db
+            .transaction()
+            .setIsolationLevel("repeatable read")
+            .setAccessMode("read only")
+            .execute((t) => readStoredDeploymentConfig(t, this.d.keyring, plugin, {
+            secretPaths: secretPathsOf(info.fields),
+        }));
+        return this.render(plugin, info, stored);
+    }
+    /**
+     * Saves some fields: `values` keyed by field dot path, `null` = clear (back to the default),
+     * omitted = unchanged.
+     * - Unknown to the deployment -> `extension.not_found`; no deployment config, unknown field, or
+     *   invalid after merging (except a problem in a read-only startup-config field itself) ->
+     *   `extension.config_invalid` (details carry only paths and messages);
+     * - a field present in the startup config (file / Nacos / env) -> 409 `extension.config_readonly`.
+     * In a transaction, first `lockEnterpriseAdminsAndAuthorize` (re-checks the enterprise admin under
+     * the lock), then an advisory lock per extension; audit `extension.deployment_config_updated`
+     * (detail only `changedPaths`). After the commit publishes {@link PLUGIN_DEPLOYMENT_CONFIG_TOPIC} and
+     * applies it on this replica right away.
+     */
+    async put(plugin, values, actor, actorTokenId) {
+        const info = await this.info(plugin);
+        if (info.fields.length === 0) {
+            throw new ApiError("extension.config_invalid", `Extension ${plugin} has no deployment config`);
+        }
+        const byPath = new Map(info.fields.map((f) => [f.path, f]));
+        const unknown = Object.keys(values).filter((p) => !byPath.has(p));
+        if (unknown.length > 0) {
+            throw new ApiError("extension.config_invalid", `Unknown deployment config fields for extension ${plugin}`, unknown.map((path) => ({ path, message: "unknown field" })));
+        }
+        const sources = this.d.sources[plugin];
+        const readonly = Object.keys(values).filter((p) => fieldSource(sources, p) !== undefined);
+        if (readonly.length > 0) {
+            throw new ApiError("extension.config_readonly", `These deployment config fields of extension ${plugin} are set in the startup config (file, Nacos or environment) and are read-only here: ${readonly.join(", ")}`, readonly.map((path) => ({ path, source: fieldSource(sources, path) })));
+        }
+        const fileValue = this.d.fileConfig()[plugin];
+        const fieldPaths = info.fields.map((f) => f.path);
+        let saved;
+        let changed = [];
+        await this.d.db.transaction().execute(async (t) => {
+            await lockEnterpriseAdminsAndAuthorize(t, actor);
+            await sql `SELECT pg_advisory_xact_lock(hashtext(${`capybara.plugin-deployment-config:${plugin}`}))`.execute(t);
+            const before = await readStoredDeploymentConfig(t, this.d.keyring, plugin, {
+                forUpdate: true,
+                secretPaths: secretPathsOf(info.fields),
+            });
+            const next = structuredClone(before);
+            for (const [path, v] of Object.entries(values)) {
+                if (v === null)
+                    deleteDeep(next, path);
+                else
+                    setDeep(next, path, structuredClone(v));
+            }
+            if (info.schema) {
+                const r = info.schema.safeParse(mergeDeploymentConfig(next, fileValue, fieldPaths));
+                if (!r.success) {
+                    // 启动配置里只读字段自己的问题这里改不了（照样保存，插件保持待配置），其余拒绝
+                    const issues = toIssues(r.error).filter((i) => i.path === "" || fieldSource(sources, i.path) === undefined);
+                    if (issues.length > 0) {
+                        throw new ApiError("extension.config_invalid", `Invalid deployment config for extension ${plugin}`, issues);
+                    }
+                }
+            }
+            changed = Object.keys(values)
+                .filter((p) => !isDeepStrictEqual(getPath(before, p), getPath(next, p)))
+                .sort();
+            saved = next;
+            if (changed.length === 0)
+                return;
+            const plain = structuredClone(next);
+            const secrets = createSecrets(t, this.d.keyring, SECRETS_NAMESPACE);
+            for (const f of info.fields) {
+                if (!f.secret)
+                    continue;
+                deleteDeep(plain, f.path);
+                if (!(f.path in values))
+                    continue;
+                const v = getPath(next, f.path);
+                if (v === undefined)
+                    await secrets.delete(DEPLOYMENT_SECRETS_ORG, secretKey(plugin, f.path));
+                else
+                    await secrets.set(DEPLOYMENT_SECRETS_ORG, secretKey(plugin, f.path), JSON.stringify(v));
+            }
+            await t
+                .insertInto("extension_deployment_configs")
+                .values({ plugin, config: JSON.stringify(plain), updated_by: actor })
+                .onConflict((oc) => oc.column("plugin").doUpdateSet({
+                config: JSON.stringify(plain),
+                updated_by: actor,
+                updated_at: new Date(),
+            }))
+                .execute();
+            await audit(t, {
+                actorAccountId: actor,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                action: "extension.deployment_config_updated",
+                target: plugin,
+                detail: { changedPaths: changed },
+            });
+        });
+        const stored = saved ?? {};
+        if (info.schema && this.d.onSecrets) {
+            const values = secretValues(info.schema, mergeDeploymentConfig(stored, fileValue, fieldPaths));
+            if (values.length > 0)
+                this.d.onSecrets(values);
+        }
+        if (changed.length > 0) {
+            try {
+                await this.d.bus?.publish(PLUGIN_DEPLOYMENT_CONFIG_TOPIC, { plugin });
+            }
+            catch (err) {
+                this.d.log.warn("cannot publish plugin-deployment-config after saving", { plugin, err });
+            }
+            try {
+                await this.d.applyLocal?.(plugin);
+            }
+            catch (err) {
+                this.d.log.error("applying the plugin deployment config on this replica failed", {
+                    plugin,
+                    err,
+                });
+            }
+        }
+        return this.render(plugin, info, stored);
+    }
+    async info(plugin) {
+        const info = await this.d.schemaOf(plugin);
+        if (!info) {
+            throw new ApiError("extension.not_found", `Extension ${plugin} is not known to this deployment`);
+        }
+        return info;
+    }
+    render(plugin, info, stored) {
+        const fileValue = this.d.fileConfig()[plugin];
+        const sources = this.d.sources[plugin];
+        const raw = mergeDeploymentConfig(stored, fileValue, info.fields.map((f) => f.path));
+        let effective = raw;
+        let valid = true;
+        let issues = [];
+        if (info.schema) {
+            const r = info.schema.safeParse(raw);
+            if (r.success)
+                effective = r.data;
+            else {
+                valid = false;
+                issues = toIssues(r.error);
+            }
+        }
+        const fields = info.fields.map((f) => {
+            const from = fieldSource(sources, f.path);
+            let value = getPath(effective, f.path);
+            let source;
+            if (from !== undefined)
+                source = from;
+            else if (getPath(stored, f.path) !== undefined)
+                source = "db";
+            else {
+                const d = info.schema ? defaultOf(info.schema, f.path) : { has: false };
+                if (value === undefined && d.has)
+                    value = d.value;
+                source = value === undefined ? "unset" : "default";
+            }
+            const base = {
+                path: f.path,
+                secret: f.secret,
+                hot: f.hot,
+                source,
+                readonly: from !== undefined,
+            };
+            if (f.secret)
+                return { ...base, set: value !== undefined };
+            return value === undefined ? base : { ...base, value: structuredClone(value) };
+        });
+        return {
+            plugin,
+            version: info.version,
+            configurable: info.fields.length > 0,
+            fields,
+            schema: info.schema ? jsonSchemaOf(info.schema) : null,
+            valid,
+            validated: info.schema !== undefined,
+            issues,
+        };
+    }
+}
+/**
+ * 本副本拿不到模块时（未加载的安装记录）按包内审阅过的静态清单给出字段（没有 zod schema：不校验，加载时再校验）。
+ */
+export async function staticDeploymentSchema(db, plugin) {
+    const row = await db
+        .selectFrom("extension_installs")
+        .innerJoin("extension_packages", "extension_packages.sha256", "extension_installs.sha256")
+        .select(["extension_installs.version", "extension_packages.section"])
+        .where("extension_installs.name", "=", plugin)
+        .executeTakeFirst();
+    if (!row)
+        return undefined;
+    // new rows hold the plugin's extension section, pre-0.1.0 rows the old capybara section; both
+    // carry the static manifest
+    const section = row.section;
+    return {
+        version: row.version,
+        fields: (section.manifest.config?.deployment ?? []).map((f) => ({
+            path: f.path,
+            secret: f.secret,
+            hot: f.hot,
+        })),
+    };
+}

package/dist/extensions/enabled.d.ts

@@ -0,0 +1,31 @@
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * Which extensions an organization has enabled. Two sources, and every reader goes through these
+ * helpers so none of them misses one:
+ * - `extension_org_configs.enabled` (the org's own switch);
+ * - every required bootstrap plugin (`extension_installs.required`, package ecosystem spec §7):
+ *   enabled in every org, existing and future, without an org config row, whatever such a row says.
+ * Neither checks that the extension is loaded on this replica or enabled on the deployment; callers
+ * that need that check it themselves, as before. `db` may be a transaction.
+ */
+/** The names of the extensions enabled in `orgId` (a subquery with one column, `plugin`). */
+export declare function enabledExtensionsQuery(db: KernelDb, orgId: string): import("kysely").SelectQueryBuilder<import("../db/kernel-schema.js").KernelDatabase & {
+    eoc: import("../db/kernel-schema.js").ExtensionOrgConfigsTable;
+}, "eoc", {
+    plugin: string;
+}>;
+/**
+ * Every (org, extension) pair that is enabled, for queries that join it (columns `org_id`,
+ * `plugin`): `.innerJoin(enabledExtensionsByOrg(db).as("en"), (j) => j.onRef("en.org_id", …)…)`.
+ * Soft-deleted orgs are included, as their org config rows are; callers filter `orgs.deleted_at`.
+ */
+export declare function enabledExtensionsByOrg(db: KernelDb): import("kysely").SelectQueryBuilder<import("../db/kernel-schema.js").KernelDatabase & {
+    eoc: import("../db/kernel-schema.js").ExtensionOrgConfigsTable;
+}, "eoc", {
+    org_id: string;
+    plugin: string;
+}>;
+/** Whether `plugin` is enabled in `orgId` (see the file header). */
+export declare function isExtensionEnabled(db: KernelDb, orgId: string, plugin: string): Promise<boolean>;
+/** The names of the required bootstrap plugins (installed with `required`). */
+export declare function requiredExtensions(db: KernelDb): Promise<Set<string>>;

package/dist/extensions/enabled.js

@@ -0,0 +1,55 @@
+import { sql } from "kysely";
+/**
+ * Which extensions an organization has enabled. Two sources, and every reader goes through these
+ * helpers so none of them misses one:
+ * - `extension_org_configs.enabled` (the org's own switch);
+ * - every required bootstrap plugin (`extension_installs.required`, package ecosystem spec §7):
+ *   enabled in every org, existing and future, without an org config row, whatever such a row says.
+ * Neither checks that the extension is loaded on this replica or enabled on the deployment; callers
+ * that need that check it themselves, as before. `db` may be a transaction.
+ */
+/** The names of the extensions enabled in `orgId` (a subquery with one column, `plugin`). */
+export function enabledExtensionsQuery(db, orgId) {
+    return db
+        .selectFrom("extension_org_configs as eoc")
+        .select("eoc.plugin as plugin")
+        .where("eoc.org_id", "=", orgId)
+        .where("eoc.enabled", "=", true)
+        .union(db
+        .selectFrom("extension_installs as ri")
+        .select("ri.name as plugin")
+        .where("ri.required", "=", true));
+}
+/**
+ * Every (org, extension) pair that is enabled, for queries that join it (columns `org_id`,
+ * `plugin`): `.innerJoin(enabledExtensionsByOrg(db).as("en"), (j) => j.onRef("en.org_id", …)…)`.
+ * Soft-deleted orgs are included, as their org config rows are; callers filter `orgs.deleted_at`.
+ */
+export function enabledExtensionsByOrg(db) {
+    return db
+        .selectFrom("extension_org_configs as eoc")
+        .select(["eoc.org_id as org_id", "eoc.plugin as plugin"])
+        .where("eoc.enabled", "=", true)
+        .union(db
+        .selectFrom("orgs as ro")
+        .innerJoin("extension_installs as ri", (j) => j.on("ri.required", "=", true))
+        .select(["ro.id as org_id", "ri.name as plugin"]));
+}
+/** Whether `plugin` is enabled in `orgId` (see the file header). */
+export async function isExtensionEnabled(db, orgId, plugin) {
+    const row = await db
+        .selectFrom(enabledExtensionsQuery(db, orgId).as("en"))
+        .select(sql `1`.as("one"))
+        .where("en.plugin", "=", plugin)
+        .executeTakeFirst();
+    return row !== undefined;
+}
+/** The names of the required bootstrap plugins (installed with `required`). */
+export async function requiredExtensions(db) {
+    const rows = await db
+        .selectFrom("extension_installs")
+        .select("name")
+        .where("required", "=", true)
+        .execute();
+    return new Set(rows.map((r) => r.name));
+}

package/dist/extensions/hooks.d.ts

@@ -0,0 +1,161 @@
+import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import type { KernelConfig } from "../config/schema.js";
+import { type InflightTracker } from "./inflight.js";
+/** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 5000;
+/**
+ * Longest plugin-authored deny reason kept, in UTF-16 code units (the `hook_denied` event's limit;
+ * the model-visible denial quotes it).
+ */
+export declare const HOOK_REASON_MAX_CHARS = 500;
+/** In-flight observe calls allowed per plugin on one replica; overflow is dropped with a warning. */
+export declare const OBSERVE_INFLIGHT_MAX = 64;
+/** Reason used when a plugin denies with an empty (or whitespace-only) reason. */
+export declare const EMPTY_DENY_REASON = "(no reason given)";
+/**
+ * Result of running the policy hooks of a mount point. `reason` is model-visible: the plugin's own
+ * (sanitized) text for `deny`, a generic sentence for `hook_error` / `timeout`. `detail` is the raw
+ * error for logs and audit only, never for the model.
+ */
+export type HookOutcome = {
+    allowed: true;
+} | {
+    allowed: false;
+    plugin: string;
+    reason: string;
+    cause: "deny" | "hook_error" | "timeout";
+    detail?: string;
+    /**
+     * R10: the hooks could not run at all (organization lookup or payload copy failed); `plugin` is
+     * only the first policy plugin on the mount, not the cause.
+     */
+    preflight?: true;
+    /**
+     * M-1: `plugin` declares a policy hook on this mount (`permissions.policyHooks`), is enabled and
+     * approved, but is not loaded on this replica: the call fails closed without running any hook.
+     */
+    notLoaded?: true;
+};
+/** A hook a plugin instance registered through `ctx.hooks.on` (kept on the instance, like tools). */
+export interface RegisteredHook {
+    mount: AvailableHook;
+    handler: HookHandler<AvailableHook>;
+    mode: HookOptions["mode"];
+}
+/** What the registry needs from a plugin instance (satisfied by `ExtensionInstance`). */
+export interface HookSource {
+    readonly name: string;
+    readonly hooks: readonly RegisteredHook[];
+    readonly inflight: InflightTracker;
+}
+/** Error text that never throws itself (a hostile `message` getter or `toString`). */
+export declare function errMsg(e: unknown): string;
+/**
+ * Sanitizes a plugin-authored deny reason for the model: control characters become spaces,
+ * whitespace collapses, and the text is clipped to {@link HOOK_REASON_MAX_CHARS} UTF-16 code units
+ * (never splitting a surrogate pair). An empty result becomes {@link EMPTY_DENY_REASON}.
+ */
+export declare function sanitizeDenyReason(raw: string): string;
+/** Clips to at most `max` UTF-16 code units, ending in "…", without splitting a surrogate pair. */
+export declare function clipText(s: string, max: number): string;
+/** Deep-freezes a structured clone in place (typed arrays cannot be frozen and are left as they are). */
+export declare function deepFreeze<T>(v: T): T;
+/** Validates a registration; throws a plain Error (permission checks happen in the ctx). */
+export declare function checkHookRegistration(plugin: string, mount: string, handler: unknown, opts: HookOptions | undefined): void;
+/** Longest raw error kept in `HookOutcome.detail` (characters). */
+export declare const HOOK_DETAIL_MAX_CHARS = 2048;
+/**
+ * Runs the hooks of this process's **active** plugin instances (one registry per replica, like
+ * tools). Hooks live on each instance (`ctx.hooks.on` records them in the instance ledger), and the
+ * registry resolves them from the host's active instances on every call: after an upgrade only the
+ * new generation fires, and unloading or disabling an instance stops its hooks. Every hook call runs
+ * through the instance's `inflight.run`, so revocation drains it (up to `extensionHost.drainSeconds`).
+ *
+ * {@link run} (Ruling R11):
+ * 1. If the caller's signal is aborted, throw its reason (an abort is never a deny).
+ * 2. Resolve the organization's enabled plugins (every run, not cached) and make one deep-frozen
+ *    `structuredClone` of the payload. If either throws (Ruling R10): with any policy hook on the
+ *    mount, deny with a generic reason (`hook_error`); with only observe hooks, allow and warn.
+ *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
+ *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
+ *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
+ *    of plugins that are not loaded are simply missing.
+ * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
+ *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
+ *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
+ *    revoked (`ExtensionUnloadedError`) reruns once on the plugin's current generation, if one is active
+ *    and enabled; otherwise the call is denied.
+ * 4. Observe hooks (resolved again from the active instances) are then dispatched concurrently, fire-and-forget, whether or not the call was
+ *    denied (never awaited on the call path). At most {@link OBSERVE_INFLIGHT_MAX} run per plugin on
+ *    this replica; overflow is dropped. Their verdicts are ignored; errors, timeouts and drops are
+ *    logged at most once per plugin and mount per minute (Redis counter with a TTL, shared by
+ *    replicas).
+ *
+ * The in-flight observe counter is per replica on purpose (it bounds this process's work); it is not
+ * cross-request state anybody reads back. Callers fire hooks only for chat conversations, never in
+ * eval replays, and skip building the payload when {@link has} is false.
+ */
+export declare class HookRegistry {
+    private readonly d;
+    /** In-flight observe calls per plugin on this replica (see {@link OBSERVE_INFLIGHT_MAX}). */
+    private readonly observing;
+    constructor(d: {
+        /** The host's active instances (read on every call). */
+        instances(): readonly HookSource[];
+        /** The active instance of a plugin (the current generation), if any. */
+        current(plugin: string): HookSource | undefined;
+        /**
+         * Plugins that deployment state expects to run policy hooks on a mount point (M-1): enabled and
+         * approved, with `permissions.policyHooks` listing it in the approved snapshot. In-process (refreshed by the host on every reconcile), so asking costs no
+         * I/O. Absent: none.
+         */
+        expectedPolicy?(mount: PolicyHook): readonly string[];
+        enabledPlugins(orgId: string): Promise<Set<string>>;
+        redis: Redis;
+        config: () => {
+            hooks: Pick<KernelConfig["hooks"], "timeoutMs">;
+        };
+        log: Logger;
+    });
+    /**
+     * Whether calls on the mount point need {@link run}: an active instance has a hook on it, or a plugin
+     * expected to run policy hooks on it is not loaded here (M-1). In-process only (regardless of
+     * organization), so callers skip building payloads and log lookups when it is false.
+     */
+    has(mount: AvailableHook): boolean;
+    /**
+     * Plugins expected to run policy hooks on the mount (deployment state) that have no active instance
+     * on this replica, sorted by name. A loaded plugin that registered no policy hook is not listed.
+     */
+    private unloadedPolicy;
+    /**
+     * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
+     * call runs through the instance's `inflight.run`.
+     */
+    handlers(mount: "usage.report"): {
+        plugin: string;
+        handler: HookHandler<"usage.report">;
+    }[];
+    /** Runs the hooks of a mount point (see the class comment). */
+    run<K extends Exclude<AvailableHook, "usage.report">>(mount: K, payload: HookPayloads[K], signal: AbortSignal): Promise<HookOutcome>;
+    /**
+     * The M-1 denial: `missing` (sorted) are enabled policy plugins that are not loaded on this replica.
+     * The model-visible reason is generic; the detail and a throttled warning name the plugin for the
+     * admin.
+     */
+    private notLoadedDenial;
+    /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
+    private entries;
+    /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */
+    private runPolicies;
+    /** Fire-and-forget observe call through the instance's in-flight tracker, capped per plugin. */
+    private dispatchObserve;
+    /**
+     * Calls one handler with its own signal (aborted on timeout or when `s` aborts). Rejects with
+     * `s.reason` when `s` aborts first, so callers can tell an abort from a hook failure.
+     */
+    private call;
+    /** Logs a warning at most once per plugin, mount and kind per minute (counter in Redis, TTL). */
+    private warnOnce;
+}