@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/runtime/providers.d.ts

@@ -1,18 +1,25 @@
-import { type ExtensionPointRef, type Logger, type ModelInfo, type ModelProvider, type ModelProviderV1 } from "@capybara-hq/plugin-sdk";
+import { type EmbedRequest, type EmbedResult, type ExtensionManifest, type ExtensionPointRef, type Logger, type ModelInfo, type ModelKind, type ModelProvider, type ModelProviderV1, type ModelRequest, type ModelStreamEvent } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import type { ModelRef } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
+import { EffectiveConfigs } from "../extensions/effective-config.js";
 import { CacheService } from "../infra/cache/cache.service.js";
-/** 单个供应商 `listModels()` 的时限（毫秒）：一个卡住的供应商不拖住整个列表与解析。 */
-export declare const LIST_MODELS_TIMEOUT_MS = 10000;
-/** Optional provider: the `listModels()` time limit (ms) instead of {@link LIST_MODELS_TIMEOUT_MS} (tests). */
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { ModelEnablement } from "../models/enablement.js";
+/**
+ * Optional provider: the `listModels()` time limit (ms) instead of the config's
+ * `models.listTimeoutMs` (tests).
+ */
 export declare const LIST_MODELS_TIMEOUT: unique symbol;
 /**
  * 列表视图（后台模型页、组织模型页）里列模型失败的供应商在这么多秒内直接标 error、不再请求（Redis，多副本共享）。
  * 只用于列表；`resolve`（运行时）照常每次请求，失败由降级梯子重试。
  */
 export declare const LIST_FAILURE_TTL_SECONDS = 15;
-/** The host view the registry needs: a subset of `ExtensionHost.list` (version and digest optional, for test doubles). */
+/**
+ * The host view the registry needs: a subset of `ExtensionRegistry` (version, digest and
+ * `current` optional, for test doubles).
+ */
 export interface ProviderHost {
     list(extensionPointName: string): {
         plugin: string;
@@ -21,14 +28,58 @@ export interface ProviderHost {
         version?: string;
         configHash?: string;
     }[];
+    /** The running instance: its manifest (deployment schema) and platform config. */
+    current?(plugin: string): {
+        manifest: ExtensionManifest;
+        config: unknown;
+    } | undefined;
+}
+/** A listed model with its kind normalised: absent means `chat`, an unknown kind is `other`. */
+export type KernelModelInfo = Omit<ModelInfo, "kind"> & {
+    kind: ModelKind | "other";
+};
+/**
+ * A model of a view that shows disabled models too: the platform view of `listWithStatus` (`disabled`
+ * = on the platform's list) and an org's `catalog` (`disabled` = on the org's list). Absent in the
+ * enabled-only views.
+ */
+export type ListedModelInfo = KernelModelInfo & {
+    disabled?: boolean;
+};
+/** A model `resolve` returns: only `chat` and `embedding` models are callable. */
+export type ResolvedModelInfo = Omit<ModelInfo, "kind"> & {
+    kind: "chat" | "embedding";
+};
+/**
+ * The kind a `resolve` caller needs (default `chat`: every streaming caller); `callable` accepts
+ * either callable kind (a purpose target checked against the purpose's own kind).
+ */
+export type ExpectedKind = "chat" | "embedding" | "callable";
+/**
+ * A provider bound to one org's call options (`orgId` and the effective config, spec B §5.5): the
+ * kernel's callers pass only the signal. Built per `resolve`, never cached; the config stays in
+ * the closure (never on the object, so logging or serialising it shows no secret).
+ */
+export interface BoundProvider {
+    stream(req: ModelRequest, opts: {
+        signal: AbortSignal;
+    }): AsyncIterable<ModelStreamEvent>;
+    /** Present when the provider implements `embed`. */
+    embed?(req: EmbedRequest, opts: {
+        signal: AbortSignal;
+    }): Promise<EmbedResult>;
 }
-/** 一个供应商在后台的视图：供应商名即插件名；`status: "error"` 时 `models` 为空、`error` 为内核的说明。 */
+/**
+ * 一个供应商在后台的视图：供应商名即插件名；`status: "error"` 时 `models` 为空、`error` 为内核的说明。
+ * `org_configured` (the platform view only): the platform config leaves a required overridable
+ * field empty, so each org configures the provider itself; no list.
+ */
 export interface ProviderStatus {
     provider: string;
     plugin: string;
-    status: "ok" | "error";
+    status: "ok" | "error" | "org_configured";
     error?: string;
-    models: ModelInfo[];
+    models: ListedModelInfo[];
 }
 /**
  * 供应商的 `listModels()` 失败（上游不可用等）。仍是 `agent.model_unavailable`，HTTP 调用方照常
@@ -42,61 +93,124 @@ export declare class ProviderListError extends ApiError {
 /**
  * 把 `model-provider@1` 实现包成 `@2`：
  * - `listModels`：`parameters` 由 `capabilities.effort` 推导（为真时只有 effort 旋钮，否则为空）；
+ *   an `@1` model is always a chat model: `kind` and `embedding` are dropped (an `@1` provider has
+ *   no `embed`); the per-call options are not passed (an `@1` provider reads `ctx.config`);
  * - `stream`：`params.effort` 映射为 `req.effort`，其余参数丢弃（`@1` 没有对应字段）；
- *   没有 `params.effort` 时保留请求自带的 `effort`。
+ *   没有 `params.effort` 时保留请求自带的 `effort`；only the signal is passed.
  */
 export declare function adaptModelProviderV1(impl: ModelProviderV1): ModelProvider;
 /**
  * 模型供应商注册表：供应商即提供 `model-provider` 能力的插件（以插件名为供应商名）。
  * 同时支持 `model-provider@1`（经 {@link adaptModelProviderV1} 适配）与 `@2`；
- * 同一插件两者都提供时用 `@2`。`@2` 的 `listModels()` 结果先过 `assertValidDeclarations`，
- * 不合规的供应商不可用（不可重试）。
- * Each provider's model list (`@2`-shaped) is cached in Redis (`@Cacheable`, key
+ * 同一插件两者都提供时用 `@2`。
+ *
+ * Org-bound (spec B §5.5, A §6): every list and call is made for an org with the provider's
+ * effective config there (`EffectiveConfigs.get`), passed as `{ orgId, config }`; a provider whose
+ * effective config is not valid in the org offers no models there, and neither does one the org
+ * explicitly turned off (its own extension switch row off, spec A §8; a provider with no switch row
+ * stays usable). The admin view (no org) lists with the platform config.
+ *
+ * Each list is validated per model (spec B §5.1): kinds are normalised (absent = `chat`, unknown =
+ * `other`); a chat model failing `assertValidDeclarations`, or an `embedding` model without
+ * `embedding` info or from a provider without `embed`, is dropped with a warn, the rest of the
+ * provider stays usable. Only `chat` and `embedding` models resolve.
+ *
+ * Each list (`@2`-shaped) is cached in Redis (`@Cacheable`, key
  * `cache:capk:models:<provider>:v<major>:<plugin version>:<config digest>`, 600 s), never in
- * process memory: every replica shares it.
+ * process memory: every replica shares it. The digest is the platform config's for every org that
+ * follows the platform (one shared list), and a per-org digest for an org's own copy.
  */
 export declare class ProviderRegistry {
     private readonly host;
+    private readonly effective;
     readonly cacheService: CacheService;
     private readonly kv;
+    private readonly config;
+    private readonly enablement;
     private readonly log?;
-    /** The `listModels()` time limit. */
-    private readonly listTimeoutMs;
-    constructor(host: ProviderHost, cacheService: CacheService, kv: Redis, log?: Pick<Logger, "warn"> | undefined, 
-    /** The `listModels()` time limit. */
-    listTimeoutMs?: number);
+    /** Overrides `models.listTimeoutMs` (tests). */
+    private readonly listTimeoutOverride?;
+    constructor(host: ProviderHost, effective: Pick<EffectiveConfigs, "get">, cacheService: CacheService, kv: Redis, config: Pick<KernelConfigService, "get">, enablement: Pick<ModelEnablement, "disabled" | "switchedOff">, log?: Pick<Logger, "warn"> | undefined, 
+    /** Overrides `models.listTimeoutMs` (tests). */
+    listTimeoutOverride?: number | undefined);
     /** `listModels()` 加时限（到时按失败处理，供应商的调用留在后台、结果丢弃）。 */
     private listModelsWithTimeout;
     /**
      * Whether at least one model-provider extension is loaded on this replica (enabled, configured,
-     * set up). Read from the extension host only: never calls a vendor, so a provider whose vendor
-     * is down still counts (org readiness, web-order spec §3.8).
+     * set up) with a valid effective config in `orgId`. Read from extension state and the org's
+     * config only: never calls a vendor, so a provider whose vendor is down still counts (org
+     * readiness, web-order spec §3.8).
      */
-    hasProvider(): boolean;
+    hasProvider(orgId: string): Promise<boolean>;
     /** 每个插件取一个实现（`@2` 优先），按插件首次出现的顺序；不支持的主版本记 warn 后忽略。 */
     private providers;
+    /**
+     * The call options and list digest of `p` for `orgId`, or for the platform when `orgId` is
+     * undefined (the admin view). An org: its effective config (not valid -> `needs_config`); the
+     * platform's digest while it follows the platform, a per-org one for its copy. The platform: its
+     * own config (a required overridable field left empty -> `org_configured`). `off`: the
+     * extensions the org explicitly turned off (`ModelEnablement.switchedOff`) -> `switched_off`.
+     */
+    private target;
     private models;
     /** The provider's validated model list, cached under `key` (see {@link modelsKey}). */
     private validatedModels;
-    /** 每个已安装供应商及其模型（按插件加载顺序）；列模型失败或声明不合规的供应商跳过并记 warn。 */
-    list(): Promise<{
+    /** One warn per (provider, model, config digest) within {@link DROPPED_WARN_TTL_SECONDS}. */
+    private warnDropped;
+    /**
+     * 每个供应商及其模型（按插件加载顺序），for `orgId`：列模型失败或在该组织需要配置的供应商跳过。Only
+     * enabled models (neither the platform nor the org disabled them, spec B §5.3), optionally of
+     * one `kind`.
+     */
+    list(orgId: string, opts?: {
+        kind?: ModelKind | "other";
+    }): Promise<{
         provider: string;
-        models: ModelInfo[];
+        models: KernelModelInfo[];
     }[]>;
     /**
-     * 每个已安装供应商及其状态（按插件加载顺序，后台用）：列模型失败（含超过 {@link LIST_MODELS_TIMEOUT_MS}）或声明
-     * 不合规的标 `error`、`models` 为空，不影响其他供应商；列模型失败的在 {@link LIST_FAILURE_TTL_SECONDS} 秒内不再请求。`error` 只是内核自己的英文说明（不透出上游错误原文，原文记 warn 日志）。
+     * An org's catalog (the org settings page, spec B §5.3): every provider as in
+     * {@link listWithStatus} for the org, with every model the platform left on, each carrying
+     * `disabled` for the org's own list. Reads the same cached lists (no extra provider call).
      */
-    listWithStatus(): Promise<ProviderStatus[]>;
+    catalog(orgId: string): Promise<ProviderStatus[]>;
     /**
-     * 解析模型引用，返回 `@2` 形状的供应商实现（`@1` 已适配）与模型信息。
-     * 供应商未安装、模型不存在或参数声明不合规 → `agent.model_unavailable`；
+     * 每个已安装供应商及其状态（按插件加载顺序），for `orgId` (enabled models only), or the platform
+     * view when undefined (`/admin/models`: every model, `disabled` from the platform's list only).
+     * See {@link statuses} for the statuses.
+     */
+    listWithStatus(orgId?: string): Promise<ProviderStatus[]>;
+    /**
+     * 每个已安装供应商的完整列表与状态，for `orgId` or the platform: 列模型失败（含超过
+     * `models.listTimeoutMs`）的标 `error`、`models` 为空，不影响其他供应商；列模型失败的在
+     * {@link LIST_FAILURE_TTL_SECONDS} 秒内不再请求。An org where the provider needs configuration gets
+     * `error`; the platform view of a provider whose platform config leaves a required overridable
+     * field empty gets `org_configured`. `error` 只是内核自己的英文说明（不透出上游错误原文，原文记 warn
+     * 日志）。No disabled list applied.
+     */
+    private statuses;
+    /**
+     * 解析模型引用 for `orgId`，返回绑定到该组织调用选项的供应商与模型信息。
+     * 供应商未安装、在该组织需要配置、模型不存在（或被丢弃）、不是 `opts.kind`（default `chat`: a
+     * streaming caller never gets an embedding model）或被平台 / 该组织停用 → `agent.model_unavailable`；
      * 供应商 `listModels()` 失败 → `ProviderListError`（同一错误码，运行时视为可重试）。
      */
-    resolve(ref: ModelRef): Promise<{
-        provider: ModelProvider;
-        info: ModelInfo;
+    resolve(orgId: string, ref: ModelRef, opts?: {
+        kind?: ExpectedKind;
+    }): Promise<{
+        provider: BoundProvider;
+        info: ResolvedModelInfo;
     }>;
+    /**
+     * The model's info in the platform view (deployment-level settings such as a purpose's
+     * deployment default; no call is ever made there), by {@link resolve}'s rules. A provider each
+     * org configures itself has no platform list: `agent.model_unavailable`. Only the platform's
+     * disabled list applies.
+     */
+    platformInfo(ref: ModelRef, opts?: {
+        kind?: ExpectedKind;
+    }): Promise<ResolvedModelInfo>;
+    private lookup;
 }
 /** The model provider registry (one instance; the models and agents domains read it). */
 export declare class ProvidersModule {