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

package/dist/runtime/loop.d.ts

@@ -22,8 +22,8 @@ export interface LoopContext {
     shutdown: AbortSignal;
     sink: StreamSink;
     /**
-     * 下一个步骤间隙要吸收的事件：返回 seq > afterSeq 的可吸收事件（`user_message` 与
-     * `background_task_finished`, `isAbsorbable`；且只含本轮开始时尚未被消费的，
+     * 下一个步骤间隙要吸收的事件：返回 seq > afterSeq 的可吸收事件（`user_message`、
+     * `background_task_finished` 与 `subagent_delivery`, `isAbsorbable`；且只含本轮开始时尚未被消费的，
      * 即 seq 也大于会话的 `consumed_seq`），按 seq 升序。loop 记录吸收到的最大 seq 作为 `consumedUpToSeq`。
      */
     pendingAbsorbable(afterSeq: number): Promise<AbsorbableEvent[]>;
@@ -37,21 +37,49 @@ export interface LoopContext {
      */
     conversationKind?: "chat" | "eval" | "subagent";
     /**
-     * Set for a sub-agent's run (phase C): the dispatch this run serves. Its tools use the parent
-     * conversation's sandbox (spec §10.1), and it never dispatches sub-agents itself (depth 1).
+     * Set for a sub-agent's run (phase C): the dispatch this run serves. Its tools use the root
+     * conversation's sandbox (spec §10.1), and it dispatches sub-agents only while its depth is
+     * below `subagents.maxDepth` (agent map spec §4.1).
      */
     parent?: SubagentParent;
+    /**
+     * The run is a sub-agent's without a live `parent`: a child case's eval replay. Its requests
+     * offer the message tools a sub-agent has (`SendMessage`, `SubagentHandback`), as the recorded
+     * run's did; not for a fork invocation's child (`SubagentParent.forSkill`). Implied by `parent`.
+     */
+    subagent?: boolean;
 }
 /** Where a sub-agent's run was dispatched from (its `subagent_dispatches` row). */
 export interface SubagentParent {
     conversationId: string;
     runId: string;
     callId: string;
+    /**
+     * The parent conversation's depth below the root (0: the parent is the root); this run's own
+     * depth is one more (agent map spec §6, `conversations.subagent_depth`).
+     */
+    depth: number;
+    /** The root conversation of the tree: its sandbox is the one every sub-agent works in. */
+    rootConversationId: string;
     /**
      * The child runs another org agent than its parent conversation's (§5.5, `template.source`
      * `agent`): only then the parent agent's current policies are read on top of its own.
      */
     otherAgent?: boolean;
+    /**
+     * The tree's budget run of this child run (agent map spec §6): the run's own `budget_run_id`
+     * (a dispatched run's, or a wake run's current window of the root), else its dispatch row's, read
+     * once when the run starts. The loop's budget check and the token counter (`appendCounted`) use
+     * it; absent only when unknown, then read with `budgetRunOf(runId)` (the parent run's window,
+     * stale for a wake run, whose `runId` is the first dispatch's).
+     */
+    budgetRunId?: string;
+    /**
+     * The run is a person's fork invocation's child (phase D, its dispatch's `for_skill`): its parent
+     * run waits for its final reply as the skill's report, so it gets neither `SubagentHandback` nor
+     * `SendMessage` to its parent (agent map spec §5.4: the fork's behaviour does not change).
+     */
+    forSkill?: boolean;
 }
 /**
  * 运行在等什么人处理：审批（`approvals` 行）或输入请求（`questions` 行，统一承载 `AskUserQuestion`、

package/dist/runtime/maintenance.d.ts

@@ -1,5 +1,6 @@
 import { WorkerHost } from "@nestjs/bullmq";
 import type { Job, Queue, Worker } from "bullmq";
+import { OwnedPluginCleanup } from "../catalog/owned-plugin-cleanup.js";
 import { ScheduledRuns } from "../infra/schedule/scheduled-runs.js";
 import type { KernelLogger } from "../log.js";
 import { DirectorySync } from "../orgs/directory-sync.js";
@@ -12,9 +13,10 @@ export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 export declare 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}, `bg-wake` → {@link RunQueue.ensureRun}). 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
@@ -26,10 +28,11 @@ export declare class MaintenanceProcessor extends WorkerHost<Worker> {
     private readonly drift;
     private readonly directory;
     private readonly runs;
+    private readonly ownedCleanup;
     private readonly scheduled;
     private readonly log;
     private readonly queue;
-    constructor(waits: Pick<Waits, "processTimeout">, sandbox: Pick<SandboxService, "destroyFor">, drift: Pick<ToolDrift, "check">, directory: Pick<DirectorySync, "runSyncJob">, runs: Pick<RunQueue, "ensureRun">, scheduled: Pick<ScheduledRuns, "runNow">, log: Pick<KernelLogger, "error" | "warn">, queue: Pick<Queue, "removeJobScheduler">);
+    constructor(waits: Pick<Waits, "processTimeout">, sandbox: Pick<SandboxService, "destroyEnvironment" | "resetFileSystem">, drift: Pick<ToolDrift, "check">, directory: Pick<DirectorySync, "runSyncJob">, runs: Pick<RunQueue, "ensureRun">, ownedCleanup: Pick<OwnedPluginCleanup, "run">, scheduled: Pick<ScheduledRuns, "runNow">, log: Pick<KernelLogger, "error" | "warn">, queue: Pick<Queue, "removeJobScheduler">);
     /**
      * Removes the retired job schedulers (`RETIRED_SCHEDULER_IDS`, runtime/retired-schedulers.ts): every fixed-period
      * maintenance job is a `@LockedCron` / `@LockedInterval` now. Idempotent; called once when a

package/dist/runtime/maintenance.js

@@ -10,6 +10,8 @@ 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";
@@ -19,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";
@@ -35,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}, `bg-wake` → {@link RunQueue.ensureRun}). 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
@@ -49,16 +52,18 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
     drift;
     directory;
     runs;
+    ownedCleanup;
     scheduled;
     log;
     queue;
-    constructor(waits, sandbox, drift, directory, runs, 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;
@@ -86,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);
@@ -101,6 +109,10 @@ let MaintenanceProcessor = class MaintenanceProcessor extends WorkerHost {
                 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;
@@ -127,9 +139,10 @@ MaintenanceProcessor = __decorate([
     __param(2, Inject(ToolDrift)),
     __param(3, Inject(DirectorySync)),
     __param(4, Inject(RunQueue)),
-    __param(5, Inject(ScheduledRuns)),
-    __param(6, Inject(KERNEL_LOGGER)),
-    __param(7, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+    __param(5, Inject(OwnedPluginCleanup)),
+    __param(6, Inject(ScheduledRuns)),
+    __param(7, Inject(KERNEL_LOGGER)),
+    __param(8, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
 ], MaintenanceProcessor);
 export { MaintenanceProcessor };
 /**
@@ -149,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

@@ -14,17 +14,28 @@ 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` 表示丢弃本步已推出的增量、重新开始。 */
+/**
+ * 流式增量的出口（推给前端等订阅方）；`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;
@@ -95,9 +106,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;
     /**
@@ -150,13 +164,16 @@ 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): Promise<ModelStepResult>;
+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 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.
  */
@@ -166,6 +183,11 @@ export declare function appendCounted(deps: {
 }, 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"> {

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 中此前有工具不可用、现在全部恢复时的提醒（模型可见，英文）。 */
@@ -70,6 +78,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 +100,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 +126,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 +137,11 @@ async function runStep(deps, input, wrapUp) {
         if (signal.aborted)
             throw new StepAborted();
         let events = await readAll(deps.eventLog, conversationId);
+        // an earlier execution of this run already sent this step (it streamed, then crashed or was
+        // handed over): this one starts at offset 0, so viewers drop that attempt's draft first
+        if (events.some((e) => e.type === "model_call" && e.runId === runId && e.payload.step === step)) {
+            sink({ kind: "step_reset", runId, step });
+        }
         // sticky (M-4): a model.request denial already logged for this step (any attempt, e.g. a crash
         // after recording it) is final: fail the same way, before compaction or any model call. Read from
         // the events just loaded, so it costs no query (M-2).
@@ -132,6 +157,8 @@ async function runStep(deps, input, wrapUp) {
         const resolved = await deps.tools.forAgent(input.orgId, {
             tools: input.agent.tools ?? [],
             subagents: input.agent.subagents,
+            child: input.parent !== undefined || input.parentRunId !== undefined || input.subagent === true,
+            forkChild: input.parent?.forSkill === true,
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {
@@ -147,10 +174,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 +189,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 +223,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 +243,7 @@ async function runStep(deps, input, wrapUp) {
         const usageEvent = appended.find((e) => e.type === "usage");
         if (deps.usageReport && usageEvent)
             void deps.usageReport.enqueue(conversationId, usageEvent.seq);
+        sink({ kind: "step_end", runId, step });
         return {
             content: outcome.content,
             stopReason: outcome.stopReason,
@@ -222,6 +265,7 @@ async function runStep(deps, input, wrapUp) {
                 payload: { step, content, stopReason: "aborted" },
             },
         ]);
+        sink({ kind: "step_end", runId, step });
         return { content, stopReason: "aborted", reused: false, aborted: true, usage: null };
     }
 }
@@ -229,7 +273,7 @@ async function runStep(deps, input, wrapUp) {
  * Appends a model call's events (its reply or compaction outcome with its `usage`; also the usage
  * of a `WebFetch` extraction call, `tools/builtins/web/extract.ts`). For a
  * sub-agent's run (`input.parentRunId`) in one transaction that also adds the tokens of the usage
- * events it newly wrote to the parent run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
+ * events it newly wrote to the budget run's `subagent_tokens_used` (sub-agents spec §8.3): a usage
  * event already in the log (an idempotent hit after a crash) adds nothing, so each call counts
  * exactly once.
  */
@@ -237,7 +281,8 @@ export async function appendCounted(deps, input, events) {
     const { conversationId, parentRunId } = input;
     if (parentRunId === undefined)
         return deps.eventLog.append(conversationId, events);
-    const out = await deps.stepLog.appendCounted(conversationId, parentRunId, events);
+    const budgetRunId = input.budgetRunId ?? input.parent?.budgetRunId;
+    const out = await deps.stepLog.appendCounted(conversationId, { parentRunId, ...(budgetRunId !== undefined && { budgetRunId }) }, events);
     if (out.toSeq !== null)
         await deps.eventLog.notify(conversationId, out.toSeq);
     return out.written;
@@ -658,11 +703,14 @@ function mergeLocal(events, written) {
  * 每次实际尝试写自己的 `model_call`（attempt 从 1 连续递增，跳过的不计）；重试前经 sink 发 `step_reset`。
  * 不可重试的失败或梯子用尽 → `RunError`。
  */
-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 },
@@ -785,6 +833,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,

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

@@ -13,9 +13,11 @@ export declare class RunControl {
     private readonly abort;
     private readonly events;
     private readonly log;
-    constructor(queue: Pick<RunQueue, "ensureRun" | "abortIfOrphaned">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren">, abort: Pick<RunAbort, "request">, events: KernelEvents, log: Pick<KernelLogger, "error">);
+    constructor(queue: Pick<RunQueue, "ensureRun" | "abortIfOrphaned" | "wakeHeldTree">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, events: KernelEvents, log: Pick<KernelLogger, "error">);
     /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
     ensureRun(conversationId: string): Promise<string | null>;
+    /** After a root's queue was unpaused: the wakes it held for its tree ({@link RunQueue.wakeHeldTree}). */
+    wakeHeldTree(rootId: string): Promise<void>;
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
@@ -28,6 +30,14 @@ export declare class RunControl {
      * changed: `run.wait-stopped` lets the channel outbound update them.
      */
     abortWaiting(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /**
+     * Stops a sub-agent with its descendants, or with `includeSelf: false` only the sub-agent
+     * conversations below `conversationId` (agent map spec §6; {@link Waits.stopTree}). Returns
+     * the number of runs asked to stop.
+     */
+    stopTree(conversationId: string, byAccountId: string | null, opts?: {
+        includeSelf?: boolean;
+    }): Promise<number>;
     /** 请求中止运行（广播到所有副本）。 */
     requestAbort(runId: string, byAccountId: string | null): Promise<void>;
 }

package/dist/runtime/run-control.js

@@ -34,6 +34,10 @@ let RunControl = class RunControl {
     ensureRun(conversationId) {
         return this.queue.ensureRun(conversationId);
     }
+    /** After a root's queue was unpaused: the wakes it held for its tree ({@link RunQueue.wakeHeldTree}). */
+    wakeHeldTree(rootId) {
+        return this.queue.wakeHeldTree(rootId);
+    }
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
@@ -61,6 +65,14 @@ let RunControl = class RunControl {
         await this.events.emit("run.wait-stopped", { conversationId, runId });
         return r;
     }
+    /**
+     * Stops a sub-agent with its descendants, or with `includeSelf: false` only the sub-agent
+     * conversations below `conversationId` (agent map spec §6; {@link Waits.stopTree}). Returns
+     * the number of runs asked to stop.
+     */
+    stopTree(conversationId, byAccountId, opts = {}) {
+        return this.waits.stopTree(conversationId, byAccountId, opts);
+    }
     /** 请求中止运行（广播到所有副本）。 */
     requestAbort(runId, byAccountId) {
         return this.abort.request(runId, byAccountId);

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

@@ -0,0 +1,85 @@
+import type { ExtensionContext, Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { EventLog } from "../conversations/event-log.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type StreamSink } from "./model-call.js";
+/** How long a draft lives without a write (a step that keeps streaming keeps refreshing it). */
+export declare const DRAFT_TTL_SECONDS = 600;
+/** At most one write per step per window, plus the one at the end of the model stream. */
+export declare const DRAFT_FLUSH_MS = 200;
+/** One step's draft: `{ text, thinking }` as JSON (spec 2026-11-07 §3.2). */
+export declare const draftKey: (runId: string, step: number) => string;
+/** What one step of a run has streamed so far. */
+export interface RunDraft {
+    step: number;
+    text: string;
+    thinking: string;
+}
+/** A draft of a conversation's active run (the `event: draft` frame's data). */
+export interface LiveDraft extends RunDraft {
+    runId: string;
+}
+/**
+ * Live drafts (spec 2026-11-07-run-input-and-live-drafts §3.2): what each step of a running run
+ * has streamed so far, kept in Redis so a viewer that (re)connects on any replica gets the text
+ * already shown, then the deltas from there on.
+ *
+ * The writer is the process executing the run: it holds the step's draft in memory (only for the
+ * runs it executes; {@link release} drops them when the execution ends) and writes it at most once
+ * per {@link DRAFT_FLUSH_MS}: on the first delta past the window, or, when deltas stop inside it,
+ * by one trailing one-shot timer per held step (process-local, unref'd, cancelled by a write,
+ * {@link clear} and {@link release}), plus once when the model stream ends ({@link flush}). Writes are issued before the delta is published, on the same
+ * connection as the bus publish, so a viewer that sees a delta past its snapshot and asks again
+ * gets a draft at least that far whenever that delta was written. Every write refreshes the
+ * {@link DRAFT_TTL_SECONDS} TTL; {@link clear} deletes the step's draft once its
+ * `assistant_message` is logged or the step is reset. Redis failures are logged, never thrown to
+ * the run: a draft is a convenience, the log stays the truth.
+ */
+export declare class RunDrafts {
+    private readonly redis;
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly log;
+    private readonly held;
+    constructor(redis: Redis, kdb: KernelDb, eventLog: Pick<EventLog, "findByIdem">, log: Pick<Logger, "warn">);
+    private get db();
+    /** Adds a delta to the step's draft; writes it when the last write is a window old. */
+    append(runId: string, step: number, channel: "text" | "thinking", text: string): void;
+    /** The end of the step's model stream: writes what the window still holds. */
+    flush(runId: string, step: number): void;
+    /** Deletes the step's draft (its `assistant_message` is logged, or the step starts over). */
+    clear(runId: string, step: number): void;
+    /**
+     * Drops what this process holds for the run (its execution here ended: finished, suspended,
+     * handed over). Redis keeps what was written: another worker may continue the run, and a step
+     * that never ended is not shown once the run is no longer running (TTL removes it).
+     */
+    release(runId: string): void;
+    /** The run's steps with a draft, by step. */
+    read(runId: string): Promise<RunDraft[]>;
+    /**
+     * The drafts a viewer of the conversation is shown: steps of its running run (or only `runId`)
+     * whose `assistant_message` is not logged. Redis is read before the log, so a step finalized
+     * meanwhile is either skipped here or its `assistant_message` reaches the viewer after the draft.
+     */
+    live(conversationId: string, runId?: string): Promise<LiveDraft[]>;
+    /** Whether the run belongs to the conversation (the draft route's 404). */
+    runOf(conversationId: string, runId: string): Promise<boolean>;
+    private drop;
+    private write;
+}
+/** What {@link streamSink} uses. */
+export interface StreamSinkDeps {
+    bus: Pick<ExtensionContext["bus"], "publish">;
+    drafts: Pick<RunDrafts, "append" | "flush" | "clear">;
+    log: Pick<Logger, "warn">;
+}
+/**
+ * The run's stream sink (one per execution of a run): publishes deltas on the conversation's topic
+ * (`conv.<id>`, shared with `{ kind: "events" }`, so a subscriber on any replica gets them) with
+ * `offset`, the characters of that channel (text or thinking) this attempt of the step streamed
+ * before the delta, and keeps the step's live draft. `step_reset` clears the draft and both
+ * offsets; `stream_end` / `step_end` only flush / clear the draft and are not published. A failed
+ * publish is only logged: deltas are drafts, the `assistant_message` in the log is the truth.
+ */
+export declare function streamSink(conversationId: string, deps: StreamSinkDeps): StreamSink;