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

package/dist/runtime/langgraph-loop.js

@@ -1,14 +1,20 @@
 import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
 import { MediaCache } from "./media-cache.js";
 import { runFinalWrapUp, runModelStep, } from "./model-call.js";
-import { subagentBudgetUsedUp } from "./subagents/limits.js";
+import { budgetRunOf, subagentBudgetUsedUp } from "./subagents/limits.js";
 import { isForkInvocation } from "./subagents/skill-fork.js";
 /**
  * 图状态：只记录进度，消息每步从事件日志重建（runModelStep 自己读日志），checkpoint 很小。
  * - `step`：当前（最近一次进入的）步骤编号，prepare 节点 +1；
- * - `consumedUpToSeq`：已吸收的最大 user_message seq；
+ * - `consumedUpToSeq`：已吸收的最大可吸收事件 seq（user_message / background_task_finished /
+ *   subagent_delivery; a finish TaskOutput or TaskStop already reported is absorbed like any
+ *   other, rendered short）；
  * - `lastStopReason`：最近一步模型调用的停止原因；
  * - `outcome`：图的结束方式（在决定结束的节点里写入，续跑已结束的图时直接读出，不依赖当前时间）。
+ * - `budgetWrapUp`: set when a sub-agent's tree used its token budget after the run made a step: the
+ *   run goes to the `wrapUp` node for one tool-less call that hands back what it found, then ends
+ *   with `budget` (sub-agents spec §8.3). Null otherwise (the step limit routes there by `step`; a channel cannot share the
+ *   node's name).
  *
  * 所有 channel 都是默认的 LastValue（不用实验性的 DeltaChannel，也没有子图）：
  * 每个 checkpoint 自带完整状态，`pruneToLatest` 之后仍能独立还原（R19）。
@@ -18,8 +24,15 @@ const LoopState = Annotation.Root({
     consumedUpToSeq: Annotation(),
     lastStopReason: Annotation(),
     outcome: Annotation(),
+    budgetWrapUp: Annotation(),
 });
-const INITIAL = { step: 0, consumedUpToSeq: 0, lastStopReason: null, outcome: null };
+const INITIAL = {
+    step: 0,
+    consumedUpToSeq: 0,
+    lastStopReason: null,
+    outcome: null,
+    budgetWrapUp: null,
+};
 /**
  * prepare 节点在停机信号下抛出：本次 invoke 以它结束，checkpoint 停在 prepare 之前
  * （LangGraph 把出错的任务记为该 checkpoint 上的 pending error，`invoke(null)` 续跑时重新执行它）。
@@ -55,7 +68,9 @@ class LoopSuspended extends Error {
  * worker 崩溃后由其他副本从最近的 checkpoint 续跑（spec 4.4、Review Focus 1）。
  *
  * 图：`prepare → model →（tool_use）tools → prepare …`；prepare 发现步数超过上限 → `wrapUp` → 结束；
- * prepare finding the deadline passed, or (a sub-agent's run) its parent's token budget used up → end;
+ * prepare finding the deadline passed → end; a sub-agent's run finding its tree's token budget used
+ * up → `wrapUp` (one tool-less call that hands back its findings) → end, or end at once when the
+ * run has made no step yet (nothing new to report);
  * 模型中止或正常结束 → 结束。`durability: "sync"`：每个节点的 checkpoint 在下一个节点开始前落库。
  *
  * 幂等：`runModelStep` / `runFinalWrapUp` 按 (runId, step) 幂等，续跑重新执行 model 节点时若回复已在日志里，
@@ -129,6 +144,7 @@ export class LangGraphLoop {
             accountId: ctx.triggerAccountId,
             ...(ctx.conversationKind !== undefined && { conversationKind: ctx.conversationKind }),
             ...(ctx.parent !== undefined && { parentRunId: ctx.parent.runId, parent: ctx.parent }),
+            ...(ctx.subagent === true && { subagent: true }),
         });
         const deps = this.stepDeps;
         const hooks = this.hooks;
@@ -139,16 +155,19 @@ export class LangGraphLoop {
             // 否则 consumed_seq 越过它们、也不会再起新一轮。
             if (timedOut())
                 return { outcome: "max_duration" };
-            // a sub-agent stops before its next request once its parent run's children used their token
-            // budget (spec §8.3; fresh read, in-flight requests of siblings may overshoot by one each)
+            // a sub-agent stops before its next request once its tree used its token budget (spec §8.3,
+            // agent map §6: on the budget run; fresh read, in-flight requests of others may overshoot by
+            // one each). A run that made a step hands back what it found in one final tool-less call
+            // (one more over); a run stopped before its first step (a wake of a stopped tree) has
+            // nothing new to report and ends at once.
             if (ctx.parent !== undefined &&
-                (await subagentBudgetUsedUp(deps.db, deps.config, ctx.orgId, ctx.parent.runId))) {
-                return { outcome: "budget" };
+                (await subagentBudgetUsedUp(deps.db, deps.config, ctx.orgId, ctx.parent.budgetRunId ?? (await budgetRunOf(deps.db, ctx.parent.runId))))) {
+                return s.step > 0 ? { step: s.step + 1, budgetWrapUp: true } : { outcome: "budget" };
             }
             let consumed = s.consumedUpToSeq;
             // the run's first prepare (also when it runs again after a suspend on its fork's sub-agent)
             const firstStep = s.step === 0;
-            const absorbed = await ctx.pendingUserMessages(consumed);
+            const absorbed = await ctx.pendingAbsorbable(consumed);
             for (const m of absorbed)
                 consumed = Math.max(consumed, m.seq);
             // phase D: a run's own fork invocation is absorbed at step 1 (the run boundary,
@@ -172,8 +191,10 @@ export class LangGraphLoop {
         const model = async (s) => {
             const r = await runModelStep(deps, input(s.step, s.consumedUpToSeq));
             await hooks.afterModelStep?.(ctx.runId, s.step, r);
+            // budget used up by a compaction call before the step's request: hand back in the wrap-up,
+            // at this step (it logged no request)
             if (r.budget)
-                return { outcome: "budget" };
+                return { budgetWrapUp: true };
             if (r.aborted) {
                 return { lastStopReason: "aborted", outcome: timedOut() ? "max_duration" : "aborted" };
             }
@@ -217,11 +238,12 @@ export class LangGraphLoop {
             return {};
         };
         const wrapUp = async (s) => {
-            const r = await runFinalWrapUp(deps, input(s.step, s.consumedUpToSeq));
+            const budget = s.budgetWrapUp === true;
+            const r = await runFinalWrapUp(deps, input(s.step, s.consumedUpToSeq), budget ? "budget" : "max_steps");
             await hooks.afterModelStep?.(ctx.runId, s.step, r);
             return {
                 lastStopReason: r.aborted ? "aborted" : r.stopReason,
-                outcome: r.budget ? "budget" : r.aborted && !timedOut() ? "aborted" : "max_steps",
+                outcome: r.aborted && !timedOut() ? "aborted" : budget || r.budget ? "budget" : "max_steps",
             };
         };
         return new StateGraph(LoopState)
@@ -234,12 +256,9 @@ export class LangGraphLoop {
             // (aborted / completed: a fork invocation's run ended in its first prepare, phase D)
             if (s.outcome !== null)
                 return END;
-            return s.step > ctx.limits.maxSteps ? "wrapUp" : "model";
+            return s.budgetWrapUp === true || s.step > ctx.limits.maxSteps ? "wrapUp" : "model";
         }, ["model", "wrapUp", END])
-            .addConditionalEdges("model", (s) => (s.outcome === null ? "tools" : END), [
-            "tools",
-            END,
-        ])
+            .addConditionalEdges("model", (s) => (s.budgetWrapUp === true ? "wrapUp" : s.outcome === null ? "tools" : END), ["tools", "wrapUp", END])
             .addEdge("tools", "prepare")
             .addEdge("wrapUp", END)
             .compile({ checkpointer: this.saver });

package/dist/runtime/loop.d.ts

@@ -1,6 +1,6 @@
 import type { AgentDefinition } from "../agents/definition.js";
 import type { KernelConfig } from "../config/schema.js";
-import type { ConversationEvent } from "../conversations/events.js";
+import type { AbsorbableEvent } from "../conversations/events.js";
 import type { StreamSink } from "./model-call.js";
 /** 一次运行交给 loop 的上下文（spec 4.4）。 */
 export interface LoopContext {
@@ -22,10 +22,11 @@ export interface LoopContext {
     shutdown: AbortSignal;
     sink: StreamSink;
     /**
-     * 下一个步骤间隙要吸收的插话：返回 seq > afterSeq 的 user_message（且只含本轮开始时尚未被消费的，
+     * 下一个步骤间隙要吸收的事件：返回 seq > afterSeq 的可吸收事件（`user_message`、
+     * `background_task_finished` 与 `subagent_delivery`, `isAbsorbable`；且只含本轮开始时尚未被消费的，
      * 即 seq 也大于会话的 `consumed_seq`），按 seq 升序。loop 记录吸收到的最大 seq 作为 `consumedUpToSeq`。
      */
-    pendingUserMessages(afterSeq: number): Promise<ConversationEvent[]>;
+    pendingAbsorbable(afterSeq: number): Promise<AbsorbableEvent[]>;
     limits: {
         maxSteps: number;
         deadline: number;
@@ -36,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,19 +1,22 @@
 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";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { ToolDrift } from "../tools/drift.js";
+import { RunQueue } from "./run-queue.js";
 import { Waits } from "./waits.js";
 export { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 /** The maintenance worker's concurrency (as the hand-made worker had). */
 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}). 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
@@ -24,10 +27,12 @@ export declare class MaintenanceProcessor extends WorkerHost<Worker> {
     private readonly sandbox;
     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">, 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

@@ -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 { 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";
@@ -13,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;
@@ -94,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;
     /**
@@ -149,8 +164,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): 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 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 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）时不带。 */