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

package/dist/runtime/model-call.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { isModelError, isRetryableKind, ModelError, sanitizeParams, } from "@capybara-hq/plugin-sdk";
 import { MEDIA_EXCLUDED_MAX_IDS } from "../conversations/events.js";
 import { ApiError } from "../errors.js";
@@ -6,16 +7,23 @@ import { hasInvocation, skillLoadOffered } from "../skills/catalog.js";
 import { buildModelRequest, latestSummary, mediaRefs, planMedia, } from "./context/build.js";
 import { acceptSummary, buildCompactionRequest, compactionBackoff, compactionPlan, shouldCompact, } from "./context/compaction.js";
 import { guardToolPairs } from "./context/pairing.js";
-import { turnLimitReminder } from "./context/reminders.js";
+import { TOOLS_UNSUPPORTED_REMINDER, turnLimitReminder } from "./context/reminders.js";
 import { calibrate, estimateTokens } from "./context/tokens.js";
+import { toolSetChange } from "./context/tool-changes.js";
 import { fireObserve, hookDeniedAudit, hookDeniedEvent, hookRequestOf, hookScope, recordHookDenial, } from "./hook-calls.js";
 import { MediaCache } from "./media-cache.js";
 import { ProviderListError } from "./providers.js";
-import { subagentBudgetUsedUp } from "./subagents/limits.js";
+import { budgetRunOf, subagentBudgetUsedUp } from "./subagents/limits.js";
 /** 单轮收尾的尾部提醒（模型可见，英文；spec 6 轮次额度收尾）。 */
 export const WRAP_UP_REMINDER = "Step limit reached. Do not call tools. Summarize what you found and what remains for the user.";
-/** 所用模型不支持工具（`capabilities.tools` 为 false）时的提醒（模型可见，英文）。 */
-export const TOOLS_UNSUPPORTED_REMINDER = "Tools are unavailable for this model. Answer without calling tools.";
+/**
+ * The tail reminder of a sub-agent's final call once its tree used its token budget (model-visible,
+ * English; sub-agents spec §8.3): the child hands back what it found instead of ending with nothing.
+ */
+export const BUDGET_WRAP_UP_REMINDER = "The sub-agents' token budget is used up, so this is your last reply. Do not call tools. " +
+    "Report what you found so far, with the sources and details that matter, and what remains " +
+    "unfinished.";
+export { TOOLS_UNSUPPORTED_REMINDER } from "./context/reminders.js";
 /** 不可用工具提醒的前缀（模型可见，英文）。 */
 export const TOOLS_UNAVAILABLE_PREFIX = "The following tools are unavailable in this run: ";
 /** 本 run 中此前有工具不可用、现在全部恢复时的提醒（模型可见，英文）。 */
@@ -24,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;
 /**
@@ -70,6 +81,10 @@ const idem = {
     reminder: (runId, step) => `reminder:${runId}:${step}`,
     toolsUnavailable: (runId, step) => `tools_unavailable:${runId}:${step}`,
     toolsUnsupported: (runId, step) => `tools_unsupported:${runId}:${step}`,
+    toolsChanged: (runId, step, keys) => `tools_changed:${runId}:${step}:${createHash("sha256")
+        .update(JSON.stringify([...keys].sort()))
+        .digest("hex")
+        .slice(0, 16)}`,
     modelCall: modelCallIdemKey,
     hookDenied: (runId, step, attempt) => `hook_denied:${runId}:${step}:${attempt}`,
     /** Usage of a compaction call: `n` is the compaction attempt (consecutive failures + 1). */
@@ -88,18 +103,24 @@ class StepAborted extends Error {
  * 模型看到的一切先写进日志（`model_call` / `reminder` / `compaction_summary`），请求可由日志还原。
  */
 export function runModelStep(deps, input) {
-    return runStep(deps, input, false);
+    return runStep(deps, input, null);
 }
 /**
  * 单轮收尾：到达步数上限时调用一次。写入收尾 `reminder`（位于请求末尾）；照常带工具（历史里有工具调用时
  * 部分供应商要求请求声明工具，也保持缓存前缀稳定），但 `toolChoice: "none"`——模型只能回复文本。
  * 其余与 `runModelStep` 相同（幂等、降级、中止）。
+ *
+ * `reason: "budget"`: a sub-agent whose tree used its token budget makes this one call to hand back
+ * what it found (sub-agents spec §8.3); it is not stopped by the budget again (one call over).
  */
-export function runFinalWrapUp(deps, input) {
-    return runStep(deps, input, true);
+export function runFinalWrapUp(deps, input, reason = "max_steps") {
+    return runStep(deps, input, reason);
 }
-async function runStep(deps, input, wrapUp) {
-    const { conversationId, runId, step, signal } = input;
+async function runStep(deps, input, 
+/** The final call's reason, or null for an ordinary step. */
+wrapUpReason) {
+    const wrapUp = wrapUpReason !== null;
+    const { conversationId, runId, step, signal, sink } = input;
     const existing = await findExisting(deps.eventLog, conversationId, runId, step);
     if (existing) {
         // resumed after a crash between writing usage and enqueueing it: enqueue again (job id dedupes)
@@ -108,6 +129,8 @@ async function runStep(deps, input, wrapUp) {
             if (u)
                 void deps.usageReport.enqueue(conversationId, u.seq);
         }
+        // a crash between the assistant_message and clearing its draft leaves one behind
+        sink({ kind: "step_end", runId, step });
         return existing;
     }
     const runtime = deps.config.get().runtime;
@@ -117,6 +140,11 @@ async function runStep(deps, input, wrapUp) {
         if (signal.aborted)
             throw new StepAborted();
         let events = await readAll(deps.eventLog, conversationId);
+        // an earlier execution of this run already sent this step (it streamed, then crashed or was
+        // handed over): this one starts at offset 0, so viewers drop that attempt's draft first
+        if (events.some((e) => e.type === "model_call" && e.runId === runId && e.payload.step === step)) {
+            sink({ kind: "step_reset", runId, step });
+        }
         // sticky (M-4): a model.request denial already logged for this step (any attempt, e.g. a crash
         // after recording it) is final: fail the same way, before compaction or any model call. Read from
         // the events just loaded, so it costs no query (M-2).
@@ -132,6 +160,8 @@ async function runStep(deps, input, wrapUp) {
         const resolved = await deps.tools.forAgent(input.orgId, {
             tools: input.agent.tools ?? [],
             subagents: input.agent.subagents,
+            child: input.parent !== undefined || input.parentRunId !== undefined || input.subagent === true,
+            forkChild: input.parent?.forSkill === true,
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {
@@ -147,10 +177,12 @@ async function runStep(deps, input, wrapUp) {
         const beforeCompaction = events.length;
         events = await maybeCompact(deps, input, events, runtime, tools);
         // a sub-agent checks its budget again after a compaction call, so the step's own request is
-        // not a second call over the cap (review M5; the loop checks before each step)
-        if (input.parentRunId !== undefined &&
+        // not a second call over the cap (review M5; the loop checks before each step); the budget
+        // wrap-up is the one call allowed over it
+        if (wrapUpReason !== "budget" &&
+            input.parentRunId !== undefined &&
             events.length !== beforeCompaction &&
-            (await subagentBudgetUsedUp(deps.db, deps.config, input.orgId, input.parentRunId))) {
+            (await subagentBudgetUsedUp(deps.db, deps.config, input.orgId, input.parent?.budgetRunId ?? (await budgetRunOf(deps.db, input.parentRunId))))) {
             return {
                 content: [],
                 stopReason: "end_turn",
@@ -160,6 +192,19 @@ async function runStep(deps, input, wrapUp) {
                 budget: true,
             };
         }
+        // the tool set changed since the previous request (an extension switched on, a sub-agent
+        // roster added): tell the model before this request (tool naming spec §9.1). Keyed by the new
+        // set, so a retried step finds it in the log (previousToolSet applies it) and writes nothing
+        const toolKeys = resolved.tools.map((t) => t.key);
+        const change = toolSetChange(events, toolKeys);
+        if (change !== null) {
+            events = await appendLocal(deps.eventLog, conversationId, events, {
+                type: "tools_changed",
+                runId,
+                idemKey: idem.toolsChanged(runId, step, toolKeys),
+                payload: { step, ...change },
+            });
+        }
         const last = lastToolsReminder(events, runId);
         // 有不可用工具 → 列出；此前列过、现在全部恢复 → 说明已恢复，避免过时的「不可用」成为最后一句
         // （收尾调用不得调用工具，可用性变化不写）。
@@ -181,7 +226,7 @@ async function runStep(deps, input, wrapUp) {
                 });
             }
         }
-        const { outcome, ref } = await ladder(deps, input, events, runtime, tools, wrapUp, streamed);
+        const { outcome, ref } = await ladder(deps, input, events, runtime, tools, wrapUpReason, streamed);
         // assistant_message 与 usage 同一次 append = 同一事务。
         const appended = await appendCounted(deps, input, [
             {
@@ -201,6 +246,7 @@ async function runStep(deps, input, wrapUp) {
         const usageEvent = appended.find((e) => e.type === "usage");
         if (deps.usageReport && usageEvent)
             void deps.usageReport.enqueue(conversationId, usageEvent.seq);
+        sink({ kind: "step_end", runId, step });
         return {
             content: outcome.content,
             stopReason: outcome.stopReason,
@@ -222,6 +268,7 @@ async function runStep(deps, input, wrapUp) {
                 payload: { step, content, stopReason: "aborted" },
             },
         ]);
+        sink({ kind: "step_end", runId, step });
         return { content, stopReason: "aborted", reused: false, aborted: true, usage: null };
     }
 }
@@ -229,7 +276,7 @@ async function runStep(deps, input, wrapUp) {
  * Appends a model call's events (its reply or compaction outcome with its `usage`; also the usage
  * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`). For a
  * sub-agent's run (`input.parentRunId`) in one transaction that also adds the tokens of the usage
- * events it newly wrote to the parent run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
+ * events it newly wrote to the budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
  * event already in the log (an idempotent hit after a crash) adds nothing, so each call counts
  * exactly once.
  */
@@ -237,7 +284,8 @@ export async function appendCounted(deps, input, events) {
     const { conversationId, parentRunId } = input;
     if (parentRunId === undefined)
         return deps.eventLog.append(conversationId, events);
-    const out = await deps.stepLog.appendCounted(conversationId, parentRunId, events);
+    const budgetRunId = input.budgetRunId ?? input.parent?.budgetRunId;
+    const out = await deps.stepLog.appendCounted(conversationId, { parentRunId, ...(budgetRunId !== undefined && { budgetRunId }) }, events);
     if (out.toSeq !== null)
         await deps.eventLog.notify(conversationId, out.toSeq);
     return out.written;
@@ -486,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 });
@@ -656,13 +704,19 @@ 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, wrapUp, streamed) {
+async function ladder(deps, input, events, runtime, tools, wrapUpReason, streamed) {
     const { conversationId, runId, step, signal, sink, agent } = input;
-    const turnReminder = wrapUp
-        ? WRAP_UP_REMINDER
-        : turnLimitReminder(step, input.maxSteps ?? runtime.maxSteps);
+    const wrapUp = wrapUpReason !== null;
+    const turnReminder = wrapUpReason === "budget"
+        ? BUDGET_WRAP_UP_REMINDER
+        : wrapUp
+            ? WRAP_UP_REMINDER
+            : turnLimitReminder(step, input.maxSteps ?? runtime.maxSteps);
     let evs = events;
     const rungs = [
         { ref: agent.model, fallback: false },
@@ -671,12 +725,16 @@ async function ladder(deps, input, events, runtime, tools, wrapUp, streamed) {
     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,
@@ -696,8 +754,11 @@ async function ladder(deps, input, events, runtime, tools, wrapUp, streamed) {
         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",
@@ -785,6 +846,8 @@ async function ladder(deps, input, events, runtime, tools, wrapUp, streamed) {
                     sink({ kind: "thinking", runId, step, text: ev.text });
                 }
             });
+            // the draft's last write, before the assistant_message is logged
+            sink({ kind: "stream_end", runId, step });
             if (scope && deps.hooks) {
                 fireObserve(deps.hooks, "model.response", {
                     ...scope,
@@ -836,6 +899,16 @@ async function ladder(deps, input, events, runtime, tools, wrapUp, streamed) {
                 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 {