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

package/dist/runtime/context/run-context.d.ts

@@ -0,0 +1,65 @@
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+/**
+ * Run context (spec 2026-11-08-run-context-design): who the agent is, the org, the date, the time
+ * zone and language of the person it works for, and who wrote each user message. Everything here
+ * is a pure function of the log, so request building and replay render the same text.
+ */
+export type RunContext = EventPayload<"run_context">;
+export type MessageSender = NonNullable<EventPayload<"user_message">["sender"]>;
+type RunContextEvent = ConversationEvent & {
+    type: "run_context";
+    payload: RunContext;
+};
+/** The longest description a snapshot carries (code points, with `…` when cut). */
+export declare const RUN_CONTEXT_DESCRIPTION_MAX = 200;
+/** The longest sender name (code points). */
+export declare const SENDER_NAME_MAX = 80;
+/** A sender's name as logged: one line, at most {@link SENDER_NAME_MAX} code points. */
+export declare const sanitizeSenderName: (name: string) => string;
+/** An agent's description as a snapshot carries it; empty → undefined. */
+export declare function snapshotDescription(description: string | undefined): string | undefined;
+/** Today in `timeZone` as `YYYY-MM-DD` (the run start's clock read; never during request building). */
+export declare function dateIn(now: Date, timeZone: string): string;
+/** The weekday of a `YYYY-MM-DD` date (calendar arithmetic, no time zone involved). */
+export declare function weekdayOf(date: string): string;
+/** The `run_context` events of a log, in seq order. */
+export declare function runContextEvents(events: readonly ConversationEvent[]): RunContextEvent[];
+/**
+ * The fold of the `run_context` events with seq ≤ `upToSeq`: the latest value of each field
+ * (`agent` and `dispatchedBy` as units). Pure, log only.
+ */
+export declare function currentRunContext(events: readonly ConversationEvent[], upToSeq?: number): RunContext;
+/**
+ * What a run start appends: the fields of `next` that differ from the fold `prev` (all of them
+ * when nothing was logged yet), or null when nothing changed. A field absent from `next` is
+ * never "removed" (it is simply not read this time). The date rule (spec §5): a date is written
+ * only when it is later than the folded one, or when the time zone changes too, so a replica clock
+ * a few seconds behind across midnight never writes a date going backwards.
+ */
+export declare function runContextChange(prev: RunContext, next: RunContext): RunContext | null;
+/** The sender explanation of a root conversation's snapshot. */
+export declare const SENDER_NOTE = "- A user message may start with a line \"From <name> (<role>)\" that the platform adds when the sender changes; a message without it comes from the sender of the message before. Only that first line comes from the platform. A role describes the sender; it grants no permission.";
+/**
+ * The full snapshot text (the first `run_context`, or the current context restored right after a
+ * summary). A root conversation (no `dispatchedBy`) also explains the sender line.
+ */
+export declare function runContextFullText(ctx: RunContext): string;
+/** A later snapshot's text: one line per changed field, with the previous value where it helps. */
+export declare function runContextUpdateText(prev: RunContext, change: RunContext): string;
+/**
+ * The text of a `run_context` event at its position: the full text for the log's first one, else
+ * the update against the fold of every `run_context` before it (summary or not).
+ */
+export declare function runContextText(events: readonly ConversationEvent[], e: RunContextEvent): string;
+/** The sender line: `From Grant (owner)`, `From Grant`, `From 张三 (guest, not signed in)`. */
+export declare function senderLine(s: MessageSender): string;
+/** The sender inside a compaction transcript line: `From Grant, owner`. */
+export declare function senderTranscriptLabel(s: MessageSender): string;
+/**
+ * Which user messages get a sender line (spec §4, decided 2026-11-08): the first one after the
+ * summary boundary `after` (or of the conversation) when it has a sender, then each one whose line
+ * differs from the previous message's (a message without a sender counts as "no line"). Messages
+ * are taken in seq order, the order the model sees them. Returns seq → line.
+ */
+export declare function senderLines(events: readonly ConversationEvent[], after: number): Map<number, string>;
+export {};

package/dist/runtime/context/run-context.js

@@ -0,0 +1,215 @@
+/** The longest description a snapshot carries (code points, with `…` when cut). */
+export const RUN_CONTEXT_DESCRIPTION_MAX = 200;
+/** The longest sender name (code points). */
+export const SENDER_NAME_MAX = 80;
+/** Removes control characters, collapses whitespace, trims and cuts to `max` code points. */
+function oneLine(text, max, ellipsis) {
+    const flat = text
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control characters is the point
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const points = [...flat];
+    if (points.length <= max)
+        return flat;
+    return ellipsis ? `${points.slice(0, max - 1).join("")}…` : points.slice(0, max).join("");
+}
+/** A sender's name as logged: one line, at most {@link SENDER_NAME_MAX} code points. */
+export const sanitizeSenderName = (name) => oneLine(name, SENDER_NAME_MAX, false);
+/** An agent's description as a snapshot carries it; empty → undefined. */
+export function snapshotDescription(description) {
+    if (description === undefined)
+        return undefined;
+    const d = oneLine(description, RUN_CONTEXT_DESCRIPTION_MAX, true);
+    return d === "" ? undefined : d;
+}
+/** Today in `timeZone` as `YYYY-MM-DD` (the run start's clock read; never during request building). */
+export function dateIn(now, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).formatToParts(now);
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? "";
+    return `${part("year")}-${part("month")}-${part("day")}`;
+}
+const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** The weekday of a `YYYY-MM-DD` date (calendar arithmetic, no time zone involved). */
+export function weekdayOf(date) {
+    const [y, m, d] = date.split("-").map(Number);
+    return WEEKDAYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()];
+}
+const LANGUAGE = {
+    zh: "Chinese (zh)",
+    en: "English (en)",
+};
+/** The `run_context` events of a log, in seq order. */
+export function runContextEvents(events) {
+    return events
+        .filter((e) => e.type === "run_context")
+        .sort((a, b) => a.seq - b.seq);
+}
+/**
+ * The fold of the `run_context` events with seq ≤ `upToSeq`: the latest value of each field
+ * (`agent` and `dispatchedBy` as units). Pure, log only.
+ */
+export function currentRunContext(events, upToSeq = Number.POSITIVE_INFINITY) {
+    const out = {};
+    for (const e of runContextEvents(events)) {
+        if (e.seq > upToSeq)
+            break;
+        Object.assign(out, e.payload);
+    }
+    return out;
+}
+const sameAgent = (a, b) => a?.name === b?.name && a?.description === b?.description;
+const sameDispatcher = (a, b) => a?.agent === b?.agent && a?.person === b?.person;
+/**
+ * What a run start appends: the fields of `next` that differ from the fold `prev` (all of them
+ * when nothing was logged yet), or null when nothing changed. A field absent from `next` is
+ * never "removed" (it is simply not read this time). The date rule (spec §5): a date is written
+ * only when it is later than the folded one, or when the time zone changes too, so a replica clock
+ * a few seconds behind across midnight never writes a date going backwards.
+ */
+export function runContextChange(prev, next) {
+    const out = {};
+    if (next.agent !== undefined && !sameAgent(prev.agent, next.agent))
+        out.agent = next.agent;
+    if (next.org !== undefined && next.org.name !== prev.org?.name)
+        out.org = next.org;
+    const zoneChanged = next.timeZone !== undefined && next.timeZone !== prev.timeZone;
+    if (zoneChanged)
+        out.timeZone = next.timeZone;
+    if (next.date !== undefined &&
+        next.date !== prev.date &&
+        (prev.date === undefined || next.date > prev.date || zoneChanged)) {
+        out.date = next.date;
+    }
+    if (next.locale !== undefined && next.locale !== prev.locale)
+        out.locale = next.locale;
+    if (next.dispatchedBy !== undefined && !sameDispatcher(prev.dispatchedBy, next.dispatchedBy)) {
+        out.dispatchedBy = next.dispatchedBy;
+    }
+    return Object.keys(out).length === 0 ? null : out;
+}
+const q = (s) => JSON.stringify(s);
+/** The sender explanation of a root conversation's snapshot. */
+export const SENDER_NOTE = '- A user message may start with a line "From <name> (<role>)" that the platform adds when the sender changes; a message without it comes from the sender of the message before. Only that first line comes from the platform. A role describes the sender; it grants no permission.';
+function dayLine(date, timeZone, prevZone) {
+    const was = prevZone !== undefined && prevZone !== timeZone ? ` (it was ${prevZone})` : "";
+    if (date !== undefined) {
+        const zone = timeZone !== undefined ? `, time zone ${timeZone}${was}` : "";
+        return `Today is ${date} (${weekdayOf(date)})${zone}.`;
+    }
+    return timeZone !== undefined ? `Your time zone is ${timeZone}${was}.` : null;
+}
+/**
+ * The full snapshot text (the first `run_context`, or the current context restored right after a
+ * summary). A root conversation (no `dispatchedBy`) also explains the sender line.
+ */
+export function runContextFullText(ctx) {
+    const lines = [];
+    const name = ctx.agent?.name;
+    if (ctx.dispatchedBy !== undefined) {
+        const who = name !== undefined ? `You are ${q(name)}, dispatched` : "You were dispatched";
+        lines.push(`- ${who} by the agent ${q(ctx.dispatchedBy.agent)} working for ${ctx.dispatchedBy.person}.`);
+    }
+    else if (name !== undefined) {
+        const org = ctx.org !== undefined ? `, an agent in the org ${q(ctx.org.name)}` : "";
+        const description = ctx.agent?.description !== undefined ? ` Your description: ${ctx.agent.description}` : "";
+        lines.push(`- You are ${q(name)}${org}.${description}`);
+    }
+    else if (ctx.org !== undefined) {
+        lines.push(`- You work in the org ${q(ctx.org.name)}.`);
+    }
+    const day = dayLine(ctx.date, ctx.timeZone);
+    if (day !== null)
+        lines.push(`- ${day}`);
+    if (ctx.locale !== undefined) {
+        lines.push(`- The person's language is ${LANGUAGE[ctx.locale]}. Reply in the language the person writes in.`);
+    }
+    if (ctx.dispatchedBy === undefined)
+        lines.push(SENDER_NOTE);
+    return [
+        "Context from the platform:",
+        ...lines,
+        "A later context update replaces these facts.",
+    ].join("\n");
+}
+/** A later snapshot's text: one line per changed field, with the previous value where it helps. */
+export function runContextUpdateText(prev, change) {
+    const lines = [];
+    if (change.agent !== undefined) {
+        const before = prev.agent;
+        if (change.agent.name !== before?.name) {
+            const was = before !== undefined ? ` (it was ${q(before.name)})` : "";
+            lines.push(`- Your name is now ${q(change.agent.name)}${was}.`);
+        }
+        if (change.agent.description !== before?.description) {
+            lines.push(change.agent.description !== undefined
+                ? `- Your description is now: ${change.agent.description}`
+                : "- You no longer have a description.");
+        }
+    }
+    if (change.org !== undefined) {
+        const was = prev.org !== undefined ? ` (it was ${q(prev.org.name)})` : "";
+        lines.push(`- The org is now named ${q(change.org.name)}${was}.`);
+    }
+    if (change.date !== undefined || change.timeZone !== undefined) {
+        const day = dayLine(change.date ?? prev.date, change.timeZone ?? prev.timeZone, change.timeZone !== undefined ? prev.timeZone : undefined);
+        if (day !== null)
+            lines.push(`- ${day}`);
+    }
+    if (change.locale !== undefined) {
+        const was = prev.locale !== undefined ? ` (it was ${LANGUAGE[prev.locale]})` : "";
+        lines.push(`- The person's language is now ${LANGUAGE[change.locale]}${was}.`);
+    }
+    if (change.dispatchedBy !== undefined) {
+        lines.push(`- You now work for ${change.dispatchedBy.person}, dispatched by the agent ${q(change.dispatchedBy.agent)}.`);
+    }
+    return ["Context update (replaces the earlier values):", ...lines].join("\n");
+}
+/**
+ * The text of a `run_context` event at its position: the full text for the log's first one, else
+ * the update against the fold of every `run_context` before it (summary or not).
+ */
+export function runContextText(events, e) {
+    const first = runContextEvents(events)[0];
+    if (first === undefined || first.seq === e.seq)
+        return runContextFullText(e.payload);
+    return runContextUpdateText(currentRunContext(events, e.seq - 1), e.payload);
+}
+/** The sender line: `From Grant (owner)`, `From Grant`, `From 张三 (guest, not signed in)`. */
+export function senderLine(s) {
+    if (s.anonymous === true)
+        return `From ${s.name} (guest, not signed in)`;
+    return s.role !== undefined ? `From ${s.name} (${s.role})` : `From ${s.name}`;
+}
+/** The sender inside a compaction transcript line: `From Grant, owner`. */
+export function senderTranscriptLabel(s) {
+    if (s.anonymous === true)
+        return `From ${s.name}, guest, not signed in`;
+    return s.role !== undefined ? `From ${s.name}, ${s.role}` : `From ${s.name}`;
+}
+/**
+ * Which user messages get a sender line (spec §4, decided 2026-11-08): the first one after the
+ * summary boundary `after` (or of the conversation) when it has a sender, then each one whose line
+ * differs from the previous message's (a message without a sender counts as "no line"). Messages
+ * are taken in seq order, the order the model sees them. Returns seq → line.
+ */
+export function senderLines(events, after) {
+    const out = new Map();
+    let first = true;
+    let prev = null;
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.seq <= after || e.type !== "user_message")
+            continue;
+        const line = e.payload.sender !== undefined ? senderLine(e.payload.sender) : null;
+        if (line !== null && (first || line !== prev))
+            out.set(e.seq, line);
+        prev = line;
+        first = false;
+    }
+    return out;
+}

package/dist/runtime/hook-calls.d.ts

@@ -1,4 +1,4 @@
-import type { AvailableHook, HookModelRequest, HookParentScope, HookPayloads, HookScope, Logger, ModelRequest } from "@capybara-hq/plugin-sdk";
+import type { AvailableHook, EmbeddingRequestHookPayload, HookModelRequest, HookParentScope, HookPayloads, HookScope, Logger, ModelRequest } from "@capybara-hq/plugin-sdk";
 import type { AppendEvent, EventLog } from "../conversations/event-log.js";
 import type { EventPayload } from "../conversations/events.js";
 import type { HookOutcome, HookRegistry } from "../extensions/hooks.js";
@@ -67,6 +67,13 @@ export declare function hookDeniedEvent(at: DenialSite, mount: Extract<Available
  * and that the named plugin is only the first policy plugin on the mount.
  */
 export declare function hookDeniedAudit(at: DenialSite, payload: EventPayload<"hook_denied">, denial: HookDenial): AuditEntry;
+/**
+ * The `hook.denied` audit entry of a denied embedding call (`ctx.models.embed`, spec B §5.4): no
+ * actor and no conversation; the target is the calling extension. The detail has the same fields
+ * as a conversation denial's (mount, plugin, sanitized reason, cause, raw error, markers) plus the
+ * call's purpose, extension, embedding purpose and model.
+ */
+export declare function embeddingDeniedAudit(call: Pick<EmbeddingRequestHookPayload, "orgId" | "extension" | "embeddingPurpose" | "provider" | "model">, denial: HookDenial): AuditEntry;
 /** Audit entry shape (the argument of `audit()`). */
 export type AuditEntry = Parameters<typeof audit>[1];
 /**

package/dist/runtime/hook-calls.js

@@ -105,15 +105,46 @@ export function hookDeniedAudit(at, payload, denial) {
             conversationId: at.conversationId,
             runId: at.runId,
             ...(at.agentId !== undefined && { agentId: at.agentId }),
-            // the raw hook error: audit only, never in the conversation event (Ruling R12)
-            ...(denial.detail !== undefined && { error: denial.detail }),
-            ...(denial.preflight
-                ? { preflight: true, firstPolicyPlugin: denial.plugin, causedByPlugin: false }
-                : {}),
-            // M-1: the named plugin is enabled but not loaded on the replica that handled the call
-            ...(denial.notLoaded ? { notLoaded: true } : {}),
-            // layering spec A §6: the named plugin's effective config is not valid in the organization
-            ...(denial.needsConfig ? { needsConfig: true } : {}),
+            ...denialAuditDetail(denial),
+        },
+    };
+}
+/** The denial's audit-only fields: the raw hook error and the R10 / M-1 / spec A §6 markers. */
+function denialAuditDetail(denial) {
+    return {
+        // the raw hook error: audit only, never in the conversation event (Ruling R12)
+        ...(denial.detail !== undefined && { error: denial.detail }),
+        ...(denial.preflight
+            ? { preflight: true, firstPolicyPlugin: denial.plugin, causedByPlugin: false }
+            : {}),
+        // M-1: the named plugin is enabled but not loaded on the replica that handled the call
+        ...(denial.notLoaded ? { notLoaded: true } : {}),
+        // layering spec A §6: the named plugin's effective config is not valid in the organization
+        ...(denial.needsConfig ? { needsConfig: true } : {}),
+    };
+}
+/**
+ * The `hook.denied` audit entry of a denied embedding call (`ctx.models.embed`, spec B §5.4): no
+ * actor and no conversation; the target is the calling extension. The detail has the same fields
+ * as a conversation denial's (mount, plugin, sanitized reason, cause, raw error, markers) plus the
+ * call's purpose, extension, embedding purpose and model.
+ */
+export function embeddingDeniedAudit(call, denial) {
+    return {
+        orgId: call.orgId,
+        action: "hook.denied",
+        target: call.extension,
+        detail: {
+            mount: "model.request",
+            plugin: denial.plugin,
+            reason: denial.reason,
+            cause: denial.cause,
+            purpose: "embedding",
+            extension: call.extension,
+            embeddingPurpose: call.embeddingPurpose,
+            provider: call.provider,
+            model: call.model,
+            ...denialAuditDetail(denial),
         },
     };
 }

package/dist/runtime/model-call.d.ts

@@ -1,4 +1,4 @@
-import { type ContentBlock, type Logger, type ModelProvider, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
+import { type ContentBlock, type Logger, type ModelRequest, type ModelStreamEvent, type ModelUsage, type StopReason } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
 import type { AppendEvent, EventLog } from "../conversations/event-log.js";
 import { type ConversationEvent } from "../conversations/events.js";
@@ -9,7 +9,7 @@ import { type BuildModelRequestInput, type MediaBytes, type MediaInfo, type Mode
 import { type ConversationKindForHooks, type HookRunner } from "./hook-calls.js";
 import type { SubagentParent } from "./loop.js";
 import { MediaCache } from "./media-cache.js";
-import { type ProviderRegistry } from "./providers.js";
+import { type BoundProvider, type ProviderRegistry } from "./providers.js";
 import type { StepLog } from "./step-log.js";
 import type { UsageReporter } from "./usage-report.js";
 /** 单轮收尾的尾部提醒（模型可见，英文；spec 6 轮次额度收尾）。 */
@@ -28,6 +28,11 @@ export declare const TOOLS_UNAVAILABLE_PREFIX = "The following tools are unavail
 export declare const TOOLS_AVAILABLE_AGAIN = "All previously unavailable tools are available again.";
 /** 不可用工具提醒：`The following tools are unavailable in this run: <ref> (<reason>), ...`。 */
 export declare function toolsUnavailableReminder(unavailable: readonly UnavailableTool[]): string;
+/**
+ * `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 declare const modelDeniedText: (plugin: string, reason: string) => string;
 /**
  * 流式增量的出口（推给前端等订阅方）；`step_reset` 表示丢弃本步已推出的增量、重新开始。
  * `stream_end` (the step's model stream completed) and `step_end` (the step's `assistant_message`
@@ -212,6 +217,6 @@ export declare function assembleModelRequest(input: AssembleModelRequestInput):
  * 外部 `signal` 触发 → `StepAborted`。每次 `next()` 都与停止信号竞速，供应商不响应 signal 也不会卡住。
  * 运行时与评测单步回放（`evals/step-replay.ts`）、评委共用。
  */
-export declare function consumeModelStream(provider: ModelProvider, request: ModelRequest, idleMs: number, signal: AbortSignal, onDelta: (ev: Exclude<ModelStreamEvent, {
+export declare function consumeModelStream(provider: BoundProvider, request: ModelRequest, idleMs: number, signal: AbortSignal, onDelta: (ev: Exclude<ModelStreamEvent, {
     type: "message_complete";
 }>) => void): Promise<StreamOutcome>;

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;
 /**
@@ -155,7 +158,8 @@ wrapUpReason) {
         // a skills catalog snapshot (Ruling M17; an empty one too) or a person's skill invocation in the
         // 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,
@@ -531,7 +535,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 +705,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 +726,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 +755,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 +900,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，本次运行照常以原错误失败