@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/runtime/model-call.js

@@ -1,25 +1,29 @@
+import { createHash } from "node:crypto";
 import { isModelError, isRetryableKind, ModelError, sanitizeParams, } from "@capybara-hq/plugin-sdk";
-import { sql } from "kysely";
 import { MEDIA_EXCLUDED_MAX_IDS } from "../conversations/events.js";
 import { ApiError } from "../errors.js";
-import { usageTokens } from "../evals/budget.js";
 import { ExtensionUnloadedError } from "../extensions/inflight.js";
-import { audit } from "../identity/audit.js";
 import { hasInvocation, skillLoadOffered } from "../skills/catalog.js";
-import { recordToolSpecs } from "../tools/specs.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 中此前有工具不可用、现在全部恢复时的提醒（模型可见，英文）。 */
@@ -28,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;
 /**
@@ -74,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). */
@@ -92,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)
@@ -112,15 +129,22 @@ 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().runtime;
+    const runtime = deps.config.get().runtime;
     /** 本次尝试已流出的文本；中止时写进 aborted 的 assistant_message。 */
     const streamed = { text: "" };
     try {
         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,10 +156,15 @@ async function runStep(deps, input, wrapUp) {
         }
         // 每步实时解析（连接器 / 插件状态可能在步骤之间变化），解析结果记在 model_call；收尾调用同样带工具
         // a skills catalog snapshot (Ruling M17; an empty one too) or a person's skill invocation in the
-        // log → skill_load is offered (see skillLoadOffered)
+        // log → Skill is offered (see skillLoadOffered)
         const resolved = await deps.tools.forAgent(input.orgId, {
-            tools: input.agent.tools ?? [],
+            disabledTools: input.agent.disabledTools,
+            subagentTools: input.agent.subagentTools,
             subagents: input.agent.subagents,
+            child: input.parent !== undefined || input.parentRunId !== undefined || input.subagent === true,
+            forkChild: input.parent?.forSkill === true,
+            sandboxConversationId: input.parent?.rootConversationId ?? input.conversationId,
+            replay: input.conversationKind === "eval",
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {
@@ -145,16 +174,18 @@ async function runStep(deps, input, wrapUp) {
                 looked: new Set(),
                 info: new Map(),
                 bytes: new Map(),
-                run: input.mediaCache ?? new MediaCache(deps.config().attachments.requestMediaBytes),
+                run: input.mediaCache ?? new MediaCache(deps.config.get().attachments.requestMediaBytes),
             },
         };
         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",
@@ -164,6 +195,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);
         // 有不可用工具 → 列出；此前列过、现在全部恢复 → 说明已恢复，避免过时的「不可用」成为最后一句
         // （收尾调用不得调用工具，可用性变化不写）。
@@ -185,7 +229,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, [
             {
@@ -205,6 +249,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,
@@ -226,43 +271,24 @@ 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 };
     }
 }
 /**
- * Appends a model call's events (its reply or compaction outcome with its `usage`). For a
+ * 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.
  */
-async function appendCounted(deps, input, events) {
+export async function appendCounted(deps, input, events) {
     const { conversationId, parentRunId } = input;
     if (parentRunId === undefined)
         return deps.eventLog.append(conversationId, events);
-    const out = await deps.db.transaction().execute(async (t) => {
-        // the conversation row lock the append takes anyway, taken first to read the seq before it
-        const before = await t
-            .selectFrom("conversations")
-            .select("last_seq")
-            .where("id", "=", conversationId)
-            .forUpdate()
-            .executeTakeFirstOrThrow();
-        const written = await deps.eventLog.append(conversationId, events, t);
-        const fresh = written.filter((e) => e.seq > Number(before.last_seq));
-        let tokens = 0;
-        for (const e of fresh)
-            if (e.type === "usage")
-                tokens += usageTokens(e.payload);
-        if (tokens > 0) {
-            await t
-                .updateTable("runs")
-                .set({ subagent_tokens_used: sql `subagent_tokens_used + ${tokens}` })
-                .where("id", "=", parentRunId)
-                .execute();
-        }
-        return { written, toSeq: fresh.length > 0 ? Math.max(...fresh.map((e) => e.seq)) : null };
-    });
+    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;
@@ -401,7 +427,7 @@ function buildRequest(deps, events, input, info, params, runtime, tools, wrapUp)
         ...(wrapUp && { toolChoice: "none" }),
         mediaInfo: tools.media.info,
         media: tools.media.bytes,
-        mediaBudgetBytes: deps.config().attachments.requestMediaBytes,
+        mediaBudgetBytes: deps.config.get().attachments.requestMediaBytes,
         defaultMaxOutputTokens: runtime.maxOutputTokens,
     });
     return {
@@ -434,7 +460,7 @@ async function loadMedia(deps, input, events, info, tools) {
         for (const id of look)
             cache.looked.add(id);
     }
-    const budget = deps.config().attachments.requestMediaBytes;
+    const budget = deps.config.get().attachments.requestMediaBytes;
     const plan = planMedia(events, info, cache.info, budget);
     const runKey = (id) => MediaCache.key(id, cache.info.get(id), plan.caps.get(id));
     const need = [];
@@ -511,7 +537,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 });
@@ -589,11 +615,7 @@ async function maybeCompact(deps, input, events, runtime, tools) {
                 plugin: verdict.plugin,
                 cause: verdict.cause,
             });
-            const written = await deps.db.transaction().execute(async (t) => {
-                const out = await deps.eventLog.append(conversationId, [failed], t);
-                await audit(t, entry);
-                return out;
-            });
+            const written = await deps.stepLog.appendAudited(conversationId, [failed], entry);
             if (written.length > 0) {
                 await deps.eventLog.notify(conversationId, Math.max(...written.map((e) => e.seq)));
             }
@@ -685,13 +707,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 },
@@ -700,12 +728,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,
@@ -725,8 +757,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",
@@ -783,29 +818,26 @@ async function ladder(deps, input, events, runtime, tools, wrapUp, streamed) {
             // 请求里的工具定义（含目录里的）按指纹存进 tool_specs，与 model_call 同一事务
             // （请求可由日志 + tool_specs 还原）
             const sent = new Set([...meta.tools, ...(meta.catalog ?? [])].map((t) => t.specHash));
-            const written = await deps.db.transaction().execute(async (t) => {
-                await recordToolSpecs(t, tools.list.filter((x) => sent.has(x.specHash)));
-                return deps.eventLog.append(conversationId, [
-                    {
-                        type: "model_call",
-                        runId,
-                        idemKey: idem.modelCall(runId, step, attempt),
-                        payload: {
-                            step,
-                            attempt,
-                            provider: rung.ref.provider,
-                            model: rung.ref.model,
-                            fallback: rung.fallback,
-                            request: {
-                                ...meta,
-                                maxOutputTokens: request.maxOutputTokens,
-                                ...(params.dropped.length > 0 && { droppedParams: params.dropped }),
-                                estimatedInputTokens: estimate,
-                            },
+            const written = await deps.stepLog.appendWithSpecs(conversationId, tools.list.filter((x) => sent.has(x.specHash)), [
+                {
+                    type: "model_call",
+                    runId,
+                    idemKey: idem.modelCall(runId, step, attempt),
+                    payload: {
+                        step,
+                        attempt,
+                        provider: rung.ref.provider,
+                        model: rung.ref.model,
+                        fallback: rung.fallback,
+                        request: {
+                            ...meta,
+                            maxOutputTokens: request.maxOutputTokens,
+                            ...(params.dropped.length > 0 && { droppedParams: params.dropped }),
+                            estimatedInputTokens: estimate,
                         },
                     },
-                ], t);
-            });
+                },
+            ]);
             await deps.eventLog.notify(conversationId, Math.max(...written.map((e) => e.seq)));
             sentAt = Date.now();
             const outcome = await consumeModelStream(provider, request, info.streamIdleTimeoutMs ?? runtime.streamIdleMs, signal, (ev) => {
@@ -817,6 +849,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,
@@ -868,6 +902,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,15 +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";
-/** 单个供应商 `listModels()` 的时限（毫秒）：一个卡住的供应商不拖住整个列表与解析。 */
-export declare const LIST_MODELS_TIMEOUT_MS = 10000;
+import { EffectiveConfigs } from "../extensions/effective-config.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+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;
@@ -18,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;
 }
-/** 一个供应商在后台的视图：供应商名即插件名；`status: "error"` 时 `models` 为空、`error` 为内核的说明。 */
+/** 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` 为内核的说明。
+ * `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 调用方照常
@@ -39,48 +93,125 @@ 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`，
- * 不合规的供应商不可用（不可重试）。
- * 每个供应商的模型列表（`@2` 形状）缓存在 Redis `capk:models:<provider>:v<主版本>:<插件版本>:<部署配置摘要>`（EX 600），不放进程内存，
- * 多副本共享同一份缓存。
+ * 同一插件两者都提供时用 `@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. 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?;
-    private readonly opts;
-    constructor(host: ProviderHost, kv: Redis, log?: Pick<Logger, "warn"> | undefined, opts?: {
-        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) 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(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;
-    /** 每个已安装供应商及其模型（按插件加载顺序）；列模型失败或声明不合规的供应商跳过并记 warn。 */
-    list(): Promise<{
+    /** The provider's validated model list, cached under `key` (see {@link modelsKey}). */
+    private validatedModels;
+    /** 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 {
 }