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

package/dist/runtime/model-call.js

@@ -32,8 +32,11 @@ export const TOOLS_AVAILABLE_AGAIN = "All previously unavailable tools are avail
 export function toolsUnavailableReminder(unavailable) {
     return `${TOOLS_UNAVAILABLE_PREFIX}${unavailable.map((u) => `${u.ref} (${u.reason})`).join(", ")}`;
 }
-/** `run_failed` message of a model request denied by a policy hook (user-facing, never model-visible). */
-const modelDeniedText = (plugin, reason) => `Model request blocked by the "${plugin}" policy hook: ${reason}`;
+/**
+ * `run_failed` message of a model request denied by a policy hook (user-facing, never model-visible);
+ * also the message of the `model.hook_denied` error a denied `ctx.models.embed` call rejects with.
+ */
+export const modelDeniedText = (plugin, reason) => `Model request blocked by the "${plugin}" policy hook: ${reason}`;
 /** 可重试错误在同一模型上重试前的默认等待（供应商未给 retryAfterMs 时）。 */
 const DEFAULT_RETRY_DELAY_MS = 1000;
 /**
@@ -531,7 +534,7 @@ async function maybeCompact(deps, input, events, runtime, tools) {
     let provider;
     let info;
     try {
-        ({ provider, info } = await deps.registry.resolve(input.agent.model));
+        ({ provider, info } = await deps.registry.resolve(input.orgId, input.agent.model));
     }
     catch (err) {
         deps.log.warn("compaction skipped: model unavailable", { model: input.agent.model, err });
@@ -701,7 +704,10 @@ function mergeLocal(events, written) {
  * 每次尝试解析出模型后、写 `model_call` 之前写本步的尾部提醒（均按本步幂等，只写一次）：所用模型不支持工具而本步有工具
  * → {@link TOOLS_UNSUPPORTED_REMINDER}；然后是轮次提醒或收尾提醒（收尾提醒因此位于请求末尾）。
  * 每次实际尝试写自己的 `model_call`（attempt 从 1 连续递增，跳过的不计）；重试前经 sink 发 `step_reset`。
- * 不可重试的失败或梯子用尽 → `RunError`。
+ * 不可重试的失败或梯子用尽 → `RunError`; except that the agent's own model failing to resolve as
+ * `agent.model_unavailable` (gone from the list, disabled since the agent was saved, its provider
+ * not configured in the org: spec B §5.3) goes straight to `agent.fallback` when there is one,
+ * without the same-model retry.
  */
 async function ladder(deps, input, events, runtime, tools, wrapUpReason, streamed) {
     const { conversationId, runId, step, signal, sink, agent } = input;
@@ -719,12 +725,16 @@ async function ladder(deps, input, events, runtime, tools, wrapUpReason, streame
     if (agent.fallback)
         rungs.push({ ref: agent.fallback, fallback: true });
     let last;
+    /** The agent's model did not resolve (`agent.model_unavailable`): only the fallback is left. */
+    let mainUnavailable = false;
     let attempt = 0;
     // hooks fire only for chat runs that have a registry (eval replays omit it, P-18)
     const scope = hookScope(deps.hooks, input);
     /** 本次尝试发出的请求里带了字节的附件（供应商拒收时写 media_excluded）。 */
     let sentMedia = [];
     for (const rung of rungs) {
+        if (mainUnavailable && !rung.fallback)
+            continue;
         if (last && !rung.fallback && (last.retryAfterMs ?? 0) > MAX_RETRY_AFTER_MS) {
             deps.log.warn("model retry skipped: suggested wait exceeds cap", {
                 conversationId,
@@ -744,8 +754,11 @@ async function ladder(deps, input, events, runtime, tools, wrapUpReason, streame
         sentMedia = [];
         /** When the request went out (model.response fires only for sent requests). */
         let sentAt;
+        /** Whether this attempt resolved its model (a failure before it is a resolve failure). */
+        let resolved = false;
         try {
-            const { provider, info } = await deps.registry.resolve(rung.ref);
+            const { provider, info } = await deps.registry.resolve(input.orgId, rung.ref);
+            resolved = true;
             if (tools.list.length > 0 && !info.capabilities.tools) {
                 evs = await appendLocal(deps.eventLog, conversationId, evs, {
                     type: "reminder",
@@ -886,6 +899,16 @@ async function ladder(deps, input, events, runtime, tools, wrapUpReason, streame
                 retryable: f.retryable,
                 error: f.message,
             });
+            if (!resolved &&
+                !rung.fallback &&
+                agent.fallback &&
+                err instanceof ApiError &&
+                !(err instanceof ProviderListError) &&
+                err.code === "agent.model_unavailable") {
+                mainUnavailable = true;
+                last = f;
+                continue;
+            }
             if (!f.retryable) {
                 if (REJECTS_MEDIA.has(f.code) && sentMedia.length > 0) {
                     // 记录失败不能掩盖原来的失败码：只记 warn，本次运行照常以原错误失败

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 {