@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/runtime/maintenance.js

@@ -9,6 +9,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { getQueueToken, OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
 import { Inject, Injectable, Module } from "@nestjs/common";
+import { BG_WAKE_JOB } from "../background/wake-rules.js";
+import { OWNED_PLUGIN_CLEANUP_JOB } from "../catalog/job-ids.js";
+import { OwnedPluginCleanup, OwnedPluginCleanupModule } from "../catalog/owned-plugin-cleanup.js";
 import { configuredProcessor } from "../infra/queue/configured-processor.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { removeRetiredSchedulers } from "../infra/queue/retired-schedulers.js";
@@ -18,7 +21,7 @@ import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { DIRECTORY_SYNC_JOB, DirectorySync } from "../orgs/directory-sync.js";
 import { OrgsModule } from "../orgs/orgs.module.js";
-import { runSandboxDestroyFor, SANDBOX_DESTROY_FOR_JOB } from "../sandbox/jobs.js";
+import { runSandboxDestroyFor, runSandboxResetFiles, SANDBOX_DESTROY_FOR_JOB, SANDBOX_RESET_FILES_JOB, } from "../sandbox/jobs.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { ToolDrift } from "../tools/drift.js";
@@ -26,6 +29,7 @@ import { DRIFT_CONNECTOR_JOB } from "../tools/job-ids.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { RETIRED_SCHEDULER_IDS } from "./retired-schedulers.js";
+import { RunQueue } from "./run-queue.js";
 import { RuntimeModule } from "./runtime.module.js";
 import { WAIT_TIMEOUT_JOB, Waits } from "./waits.js";
 export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
@@ -33,9 +37,10 @@ export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 export const MAINTENANCE_CONCURRENCY = 5;
 /**
  * The one consumer of `cap-kernel-maintenance` (decision R11 of the Nest kernel spec): dispatches
- * each one-off job by name to its domain (`wait-timeout` → {@link Waits}, `sandbox-destroy-for` →
- * {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
- * {@link DirectorySync}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
+ * each one-off job by name to its domain (`wait-timeout` → {@link Waits}, `sandbox-destroy-for` and
+ * `sandbox-reset-files` → {@link SandboxService}, `drift-connector` → {@link ToolDrift}, `directory-sync` →
+ * {@link DirectorySync}, `bg-wake` → {@link RunQueue.ensureRun}, `owned-plugin-cleanup` →
+ * {@link OwnedPluginCleanup}). The name of a periodic job (a `@LockedCron` / `@LockedInterval` job,
  * such as `sandbox-suspend-idle`) runs that job's body once ({@link ScheduledRuns.runNow}), as the
  * maintenance handlers did when those jobs were schedulers on this queue: an operator's or a
  * test's one-off run, not a second schedule (decision R23 of the Nest kernel spec). Any other
@@ -46,15 +51,19 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
     sandbox;
     drift;
     directory;
+    runs;
+    ownedCleanup;
     scheduled;
     log;
     queue;
-    constructor(waits, sandbox, drift, directory, scheduled, log, queue) {
+    constructor(waits, sandbox, drift, directory, runs, ownedCleanup, scheduled, log, queue) {
         super();
         this.waits = waits;
         this.sandbox = sandbox;
         this.drift = drift;
         this.directory = directory;
+        this.runs = runs;
+        this.ownedCleanup = ownedCleanup;
         this.scheduled = scheduled;
         this.log = log;
         this.queue = queue;
@@ -82,6 +91,9 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
             case SANDBOX_DESTROY_FOR_JOB:
                 await runSandboxDestroyFor(this.sandbox, this.log, job);
                 return;
+            case SANDBOX_RESET_FILES_JOB:
+                await runSandboxResetFiles(this.sandbox, job);
+                return;
             case DRIFT_CONNECTOR_JOB: {
                 const { orgId, connectorId, trigger } = job.data;
                 await this.drift.check(orgId, connectorId, trigger);
@@ -90,6 +102,17 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
             case DIRECTORY_SYNC_JOB:
                 await this.directory.runSyncJob(job.data);
                 return;
+            // the end of a conversation's wake window (background Bash spec §3)
+            case BG_WAKE_JOB: {
+                // fired before the window ended (clock skew): it reschedules under its next retry id
+                const { conversationId, retry } = job.data;
+                await this.runs.ensureRun(conversationId, { wakeRetry: (retry ?? 0) + 1 });
+                return;
+            }
+            // a removed org-owned plugin's extension (plugin scope phase 3, P3-20)
+            case OWNED_PLUGIN_CLEANUP_JOB:
+                await this.ownedCleanup.run(job.data.itemId);
+                return;
             default:
                 if (await this.scheduled.runNow(job.name))
                     return;
@@ -115,9 +138,11 @@ MaintenanceProcessor = __decorate([
     __param(1, Inject(SandboxService)),
     __param(2, Inject(ToolDrift)),
     __param(3, Inject(DirectorySync)),
-    __param(4, Inject(ScheduledRuns)),
-    __param(5, Inject(KERNEL_LOGGER)),
-    __param(6, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+    __param(4, Inject(RunQueue)),
+    __param(5, Inject(OwnedPluginCleanup)),
+    __param(6, Inject(ScheduledRuns)),
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
 ], MaintenanceProcessor);
 export { MaintenanceProcessor };
 /**
@@ -137,6 +162,8 @@ MaintenanceModule = __decorate([
             SandboxModule,
             ToolsModule,
             OrgsModule,
+            // the removed org plugins' cleanup and its daily sweep (worker-only through this module)
+            OwnedPluginCleanupModule,
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
         providers: [

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

@@ -1,6 +1,7 @@
-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 { EventLog } from "../conversations/event-log.js";
+import type { AppendEvent, EventLog } from "../conversations/event-log.js";
+import { type ConversationEvent } from "../conversations/events.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import type { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import type { ToolRegistry, UnavailableTool } from "../tools/registry.js";
@@ -8,22 +9,38 @@ 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 轮次额度收尾）。 */
 export declare 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 declare 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 declare const BUDGET_WRAP_UP_REMINDER: string;
+/** Why a run makes its final, tool-less call: its step limit, or its tree's token budget. */
+export type WrapUpReason = "max_steps" | "budget";
+export { TOOLS_UNSUPPORTED_REMINDER } from "./context/reminders.js";
 /** 不可用工具提醒的前缀（模型可见，英文）。 */
 export declare const TOOLS_UNAVAILABLE_PREFIX = "The following tools are unavailable in this run: ";
 /** 本 run 中此前有工具不可用、现在全部恢复时的提醒（模型可见，英文）。 */
 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;
-/** 流式增量的出口（推给前端等订阅方）；`step_reset` 表示丢弃本步已推出的增量、重新开始。 */
+/**
+ * `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`
+ * is logged) carry no delta: the run worker's sink writes and then clears the step's live draft on
+ * them (spec 2026-11-07 §3.2) and publishes neither.
+ */
 export type StreamSink = (delta: {
-    kind: "text" | "thinking" | "step_reset";
+    kind: "text" | "thinking" | "step_reset" | "stream_end" | "step_end";
     runId: string;
     step: number;
     text?: string;
@@ -94,9 +111,12 @@ export interface ModelStepInput {
     conversationKind?: ConversationKindForHooks;
     /** A sub-agent's run: where it was dispatched from (hook payloads carry it as `parent`). */
     parent?: SubagentParent;
+    /** A sub-agent's run without a live parent (a child case's eval replay, `LoopContext`). */
+    subagent?: boolean;
     /**
-     * A sub-agent's run (phase C): the parent run whose `subagent_tokens_used` counts every usage
-     * event this step writes (step, wrap-up and compaction calls; spec §8.3).
+     * A sub-agent's run (phase C): the parent run whose budget run's `subagent_tokens_used` counts
+     * every usage event this step writes (step, wrap-up and compaction calls; spec §8.3, agent map
+     * spec §6).
      */
     parentRunId?: string;
     /**
@@ -149,8 +169,31 @@ export declare function runModelStep(deps: ModelStepDeps, input: ModelStepInput)
  * 单轮收尾：到达步数上限时调用一次。写入收尾 `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 declare function runFinalWrapUp(deps: ModelStepDeps, input: ModelStepInput, reason?: WrapUpReason): Promise<ModelStepResult>;
+/**
+ * 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 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.
  */
-export declare function runFinalWrapUp(deps: ModelStepDeps, input: ModelStepInput): Promise<ModelStepResult>;
+export declare function appendCounted(deps: {
+    eventLog: Pick<EventLog, "append" | "notify">;
+    stepLog: Pick<StepLog, "appendCounted">;
+}, input: {
+    conversationId: string;
+    parentRunId?: string | undefined;
+    /** The run's budget window (agent map spec §6), when known; else the parent run's. */
+    budgetRunId?: string | undefined;
+    parent?: {
+        budgetRunId?: string | undefined;
+    } | undefined;
+}, events: AppendEvent[]): Promise<ConversationEvent[]>;
 /** {@link assembleModelRequest} 的输入。 */
 export interface AssembleModelRequestInput extends Omit<BuildModelRequestInput, "tools"> {
     /** 本步解析出的工具；模型不支持工具（`capabilities.tools` 为 false）时不带。 */
@@ -174,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

@@ -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).
@@ -128,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 = {
@@ -147,10 +180,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 +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);
         // 有不可用工具 → 列出；此前列过、现在全部恢复 → 说明已恢复，避免过时的「不可用」成为最后一句
         // （收尾调用不得调用工具，可用性变化不写）。
@@ -181,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, [
             {
@@ -201,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,
@@ -222,21 +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.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;
@@ -485,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 });
@@ -655,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 },
@@ -670,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,
@@ -695,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",
@@ -784,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,
@@ -835,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，本次运行照常以原错误失败