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

package/dist/extensions/host.d.ts

@@ -1,15 +1,25 @@
 import { type ExtensionManifest, type ExtensionPointRef, type ToolHandler, type ToolSpec, type UiContribution } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
 import type { core } from "zod";
-import { type KernelDeps, type Route } from "../ctx/create-ctx.js";
+import type { KernelAppOptions } from "../app.js";
+import type { BusSubscriber } from "../ctx/bus.js";
+import { type Route } from "../ctx/create-ctx.js";
+import type { Keyring } from "../ctx/secrets.js";
 import type { PluginRouteTable } from "../http/plugin-dispatch.js";
+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 type { KernelLogger } from "../log.js";
+import { EmbedTokens } from "../ui/embed-token.js";
 import type { UiActionHandler, UiRender } from "../ui/registry.js";
-import { type PendingExtension } from "./approvals.js";
+import { ExtensionApprovals, type PendingExtension } from "./approvals.js";
 import { HookRegistry } from "./hooks.js";
-import { type InflightTracker } from "./inflight.js";
-import type { DesiredExtension } from "./installs.js";
+import type { InflightTracker } from "./inflight.js";
+import { type DesiredExtension, ExtensionInstalls } from "./installs.js";
 import { type ExtensionInstance } from "./instance.js";
 import { type PermissionSet } from "./permission-set.js";
-import type { ExtensionSource, ReplicaStatusStore } from "./sources.js";
+import { type ExtensionPointEntry, ExtensionRegistry } from "./registry.js";
+import { type ExtensionSource, ReplicaStatusStore } from "./sources.js";
 /**
  * 插件部署配置（校验后）中非密钥部分的摘要：先把 schema 里所有 secret 叶子（`configFields` 可达路径，
  * 加载时 `assertSecretsReachable` 已保证密钥都在这些路径上）换成固定占位值，再取 sha256(键排序 JSON) 前 16 位十六进制。
@@ -26,18 +36,7 @@ export interface LoadedUiContribution {
     render?: UiRender;
     action?: UiActionHandler;
 }
-/** One item of {@link ExtensionHost.list}. */
-export interface ExtensionPointEntry {
-    plugin: string;
-    capability: ExtensionPointRef;
-    impl: unknown;
-    /** 插件清单的 version。 */
-    version: string;
-    /** 部署配置摘要，见 {@link deploymentConfigHash}。 */
-    configHash: string;
-    /** 提供方实例的在途计数（connector / sandbox / model-provider 的 `impl` 已经包成计入它的代理）。 */
-    inflight: InflightTracker;
-}
+export type { ExtensionPointEntry } from "./registry.js";
 /** One item of {@link ExtensionHost.inspect}. */
 export interface InspectedExtension {
     /** Always `config`: the startup config `extensions` list. */
@@ -95,8 +94,20 @@ export interface ExtensionLoadPlan {
 }
 /** 插件宿主：解析、校验配置、迁移、setup，并登记插件提供的能力与路由。 */
 export declare class ExtensionHost {
-    private readonly deps;
-    private readonly extensionConfig;
+    /** The process's extension registry (one provider, shared with other domains). */
+    private readonly registry;
+    /**
+     * The deployment's desired state (one way, spec §3): install record names (with the
+     * config-declared ones the extensions "known to the deployment": routes of one not active on
+     * this replica answer 503, an unknown name 404; cached {@link KNOWN_NAMES_TTL_MS}) and each
+     * extension's effective deployment config (the startup config plus the fields stored in PG, C10).
+     */
+    private readonly installs;
+    private readonly approvals;
+    /** This replica's load status table (`extension_replica_status`): every load result writes a row. */
+    private readonly status;
+    private readonly config;
+    private readonly log;
     /**
      * Only resolves extensions and runs migrations in dependency order: no deployment config check, no
      * setup, no Redis (for `capybara migrate`). Like `load()` it checks secret markers first
@@ -134,8 +145,6 @@ export declare class ExtensionHost {
     static inspect(specifiers: string[], opts?: {
         resolveFrom?: string;
     }): Promise<InspectedExtension[]>;
-    /** 本进程生效的插件实例（C17）：消费方每次实时取，不缓存实现对象。 */
-    private readonly registry;
     /**
      * M-1: plugin → mount points where deployment state expects `policy` hooks. A per-replica copy of PG
      * deployment state (like the registry), rebuilt on every load / converge, never written elsewhere.
@@ -157,10 +166,6 @@ export declare class ExtensionHost {
     private readonly imports;
     /** 串行化 unload / reload（同一时刻只做一件，依赖方的连锁处理不交错）。 */
     private lifecycle;
-    private readonly drainMs;
-    private readonly disposeTimeoutMs;
-    private readonly reloadSetupTimeoutMs;
-    private readonly installedNames;
     /** 安装记录里的插件名缓存（TTL + 注册表变化时作废）。 */
     private installedCache;
     /** 本次因权限待批准（或依赖待批准插件）而未加载的插件。 */
@@ -199,53 +204,52 @@ export declare class ExtensionHost {
     /** 已创建、尚未登记（setup 进行中）的 ctx：close() 时立即关闭，不等 setup 返回。 */
     private settingUp;
     private readonly resolveFrom;
-    private readonly onSecrets;
-    private readonly autoApprove;
-    private readonly status;
-    private readonly storedConfig;
+    /** What every extension's `ctx` is built from (kernel side only; nothing Nest crosses into `ctx`). */
+    private readonly deps;
     /** 配置声明插件的部署配置最近一次判定是否合法（后台列表用；没判定过时按启动配置校验）。 */
     private readonly configValidity;
     /** 已告警过的「部署配置不合法」（插件名 → 说明；每个周期都会重新判定，同一说明只告警一次）。 */
     private readonly configWarned;
     /**
-     * @param opts.resolveFrom The directory bare package names are resolved from, default
-     * `process.cwd()`; a relative path is made absolute against the cwd at construction.
-     * Absolute paths and `file:` URL extension specifiers are used as they are;
-     * bare package names are resolved with `createRequire(<resolveFrom>/noop.js).resolve`, so an
-     * extension package's exports must expose the `default` (or `require`) condition.
-     * @param opts.autoApprove Approve extension permissions automatically (config
-     * `extensionPermissions.autoApprove`, development and trials only): extensions needing approval write a
-     * snapshot with source auto and load as usual. Default false: extensions pending approval do not
-     * load (see {@link pending}).
-     * @param opts.status This replica's load status table (`extension_replica_status`): every
-     * extension's load result writes a row.
-     */
-    constructor(deps: KernelDeps, extensionConfig?: Record<string, unknown>, opts?: {
-        resolveFrom?: string;
-        onSecrets?: (values: string[]) => void;
-        autoApprove?: boolean;
-        status?: ReplicaStatusStore;
-        /** 撤销实例时在途调用的排空时限（毫秒），默认 30s；内核传 `extensionHost.drainSeconds`。 */
-        drainMs?: () => number;
-        /** 插件 `dispose()` 的时限（毫秒），默认 10s；内核传 `extensionHost.disposeTimeoutSeconds`。 */
-        disposeTimeoutMs?: () => number;
-        /** 运行中重新加载时 setup 的时限（毫秒），默认 60s；内核传 `extensionHost.reloadSetupTimeoutSeconds`。 */
-        reloadSetupTimeoutMs?: () => number;
-        /** Hook time limit in milliseconds, default 5 s; the kernel passes `hooks.timeoutMs` (hot). */
-        hookTimeoutMs?: () => number;
-        /**
-         * 安装记录里的插件名（T11 安装记录，任何 desired_state）：与配置声明的一起构成「部署已知」的插件，
-         * 不在本副本生效时它们的路由返回 503，完全未知的名字 404。缓存 {@link KNOWN_NAMES_TTL_MS}。
-         */
-        installedNames?: () => Promise<string[]>;
-        /**
-         * The extension's effective deployment config (C10): the startup config (`fileValue`, file /
-         * Nacos merged with env) plus the fields stored in PG
-         * (`ExtensionDeploymentConfigService.effective`), not validated yet. Without it only the startup
-         * config is used.
-         */
-        deploymentConfig?: (plugin: string, fileValue: unknown, schema: core.$ZodType | undefined) => Promise<unknown>;
-    });
+     * The host builds each extension's `ctx` from the injected kernel services: the pool for
+     * `ctx.db` on the extension's schema, Redis for `kv` / `lock` / `bus` and the queues, the
+     * keyring for `secrets`. The config is read per call (`extensionConfig`, the drain and setup
+     * time limits, `extensionPermissions.autoApprove`).
+     *
+     * `KERNEL_APP_OPTIONS.resolveFrom`: the directory bare package names are resolved from, default
+     * `process.cwd()`; a relative path is made absolute against the cwd at construction. Absolute
+     * paths and `file:` URL extension specifiers are used as they are; bare package names are
+     * resolved with `createRequire(<resolveFrom>/noop.js).resolve`, so an extension package's exports
+     * must expose the `default` (or `require`) condition.
+     */
+    constructor(
+    /** The process's extension registry (one provider, shared with other domains). */
+    registry: ExtensionRegistry, 
+    /**
+     * The deployment's desired state (one way, spec §3): install record names (with the
+     * config-declared ones the extensions "known to the deployment": routes of one not active on
+     * this replica answer 503, an unknown name 404; cached {@link KNOWN_NAMES_TTL_MS}) and each
+     * extension's effective deployment config (the startup config plus the fields stored in PG, C10).
+     */
+    installs: ExtensionInstalls, approvals: ExtensionApprovals, 
+    /** This replica's load status table (`extension_replica_status`): every load result writes a row. */
+    status: ReplicaStatusStore, config: KernelConfigService, kdb: KernelDb, redis: Redis, busSubscriber: BusSubscriber, keyring: Keyring, embedTokens: EmbedTokens, locks: LockService, log: KernelLogger, options: Pick<KernelAppOptions, "resolveFrom">);
+    /** The startup config's `extensionConfig` (file / Nacos merged with env). */
+    private get extensionConfig();
+    /** `extensionPermissions.autoApprove` (development and trials only; see `planApprovals`). */
+    private get autoApprove();
+    /** In-flight calls of a revoked instance are drained within this (`extensionHost.drainSeconds`). */
+    private drainMs;
+    /** An extension's `dispose()` time limit (`extensionHost.disposeTimeoutSeconds`). */
+    private disposeTimeoutMs;
+    /** `setup` time limit of a reload in a running process (`extensionHost.reloadSetupTimeoutSeconds`). */
+    private reloadSetupTimeoutMs;
+    /**
+     * Records the config-declared extensions the CLI inspected (the CLI loads none): their names,
+     * manifests and permission sets for {@link declared} / {@link declaredPlugins}, and whether
+     * their deployment config is valid (the CLI merges and checks it like a replica would).
+     */
+    noteInspected(inspected: InspectedExtension[], configValid: ReadonlyMap<string, boolean>): void;
     /**
      * Imports each extension module (default export) and initializes them in dependency order; may be
      * called only once. An array is the same as `{ config: [...] }`.
@@ -302,7 +306,7 @@ export declare class ExtensionHost {
      * 插件此刻的部署配置（未校验）：启动配置补上 PG 里保存的字段（C10，见构造参数 `deploymentConfig`）。
      */
     private rawConfigOf;
-    /** 把一份已校验部署配置里的密钥值交给 onSecrets（日志打码）。 */
+    /** 把一份已校验部署配置里的密钥值登记到日志打码。 */
     private reportSecrets;
     /**
      * 安装记录收敛到 PG 期望状态（启动第 3 步与运行中的 {@link converge} 共用，C16）；`desired` 为期望启用的记录。