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

package/dist/runtime/context/skills.js

@@ -1,13 +1,23 @@
-/** 加载技能的内置工具名。 */
-export const SKILL_LOAD = "skill_load";
+import { SKILL_LOAD } from "../../tools/builtin-names.js";
+export const SKILL_TEXTS = Object.freeze({
+    skillsCatalogHeader: "Skills are available in this conversation. A skill is a set of instructions, sometimes with " +
+        "scripts or other files, for a specific kind of task. When a task matches a skill's description, " +
+        `call ${SKILL_LOAD} with the skill's name to read its instructions before you start; do not guess ` +
+        "what a skill says. Available skills:",
+    newSkills: `New skills (call ${SKILL_LOAD} with the name to use one):`,
+    updatedSkills: `Updated skills (call ${SKILL_LOAD} again before relying on earlier instructions):`,
+    currentSkills: "Skills available in this conversation now (this replaces any earlier list of skills; call " +
+        `${SKILL_LOAD} with a name to read a skill's instructions):`,
+    invokedSkills: (names) => `Skills the user invoked earlier in this conversation: ${names.join(", ")}. Call ${SKILL_LOAD} with a name to read its instructions again.`,
+    pinnedSkillsHeader: "Pinned skills: the owner of this agent pinned these skills, so their instructions apply " +
+        `throughout this conversation. Follow them without calling ${SKILL_LOAD}; call ${SKILL_LOAD} ` +
+        "only to copy a pinned skill's files into the sandbox.",
+});
 /** 目录开头的说明（system 缓存段里的第一份目录）。 */
-export const SKILLS_CATALOG_HEADER = "Skills are available in this conversation. A skill is a set of instructions, sometimes with " +
-    "scripts or other files, for a specific kind of task. When a task matches a skill's description, " +
-    `call ${SKILL_LOAD} with the skill's name to read its instructions before you start; do not guess ` +
-    "what a skill says. Available skills:";
+export const SKILLS_CATALOG_HEADER = SKILL_TEXTS.skillsCatalogHeader;
 /** 按码点比较名字（与区域设置无关，结果确定）。 */
 const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
-/** 目录里每个技能描述最多的码点数（超出确定地截断；`skill_load` 仍返回完整正文）。 */
+/** 目录里每个技能描述最多的码点数（超出确定地截断；`Skill` 仍返回完整正文）。 */
 export const CATALOG_DESCRIPTION_MAX_CHARS = 300;
 /** 折叠成一行，按码点截到 {@link CATALOG_DESCRIPTION_MAX_CHARS}。 */
 function shortDescription(d) {
@@ -21,8 +31,8 @@ function shortDescription(d) {
 const line = (s) => `- ${s.name}: ${shortDescription(s.description)}`;
 const lines = (skills) => [...skills].sort(byName).map(line).join("\n");
 /** 第一份目录（进 system 缓存段），按名字排序。 */
-export function skillsCatalogText(skills) {
-    return `${SKILLS_CATALOG_HEADER}\n${lines(skills)}`;
+export function skillsCatalogText(skills, texts = SKILL_TEXTS) {
+    return `${texts.skillsCatalogHeader}\n${lines(skills)}`;
 }
 /** 两份快照是否相同（按 id、版本、名字、描述与来源）。顺序无关。 */
 export function sameSkills(a, b) {
@@ -66,16 +76,23 @@ export function sameSnapshot(a, b) {
 /**
  * The catalog differences between two snapshots. `pinnedIds` (the next snapshot's pinned ids, phase
  * B) are left out of `updated`: a pinned skill's new body is rendered by {@link pinnedChangeText},
- * and the pinned header says not to call `skill_load` for it.
+ * and the pinned header says not to call `Skill` for it.
  */
 function catalogChanges(prev, next, pinnedIds) {
     const before = new Map(prev.map((s) => [s.id, s]));
     const after = new Map(next.map((s) => [s.id, s]));
-    const added = next.filter((s) => !before.has(s.id));
-    const removed = prev.filter((s) => !after.has(s.id));
+    // A skill renamed under its id (the platform components migration renames a clashing org skill)
+    // reads as its old name removed and its new name added: the model calls skills by name.
+    const renamed = (s, other) => {
+        const o = other.get(s.id);
+        return o !== undefined && o.name !== s.name;
+    };
+    const added = next.filter((s) => !before.has(s.id) || renamed(s, before));
+    const removed = prev.filter((s) => !after.has(s.id) || renamed(s, after));
     const updated = next.filter((s) => {
         const p = before.get(s.id);
         return (p !== undefined &&
+            p.name === s.name &&
             !pinnedIds?.has(s.id) &&
             (p.version !== s.version || p.description !== s.description || p.source !== s.source));
     });
@@ -86,14 +103,14 @@ function catalogChanges(prev, next, pinnedIds) {
  * 试用草稿被拒绝 / 批准了别人的同号版本时，内容变了而版本号可能不变）。
  * `prev` 为上一份快照（没有为空）。
  */
-export function skillsChangeText(prev, next, pinnedIds) {
+export function skillsChangeText(prev, next, pinnedIds, texts = SKILL_TEXTS) {
     const { added, updated, removed } = catalogChanges(prev, next, pinnedIds);
     const parts = ["The skills available in this conversation have changed."];
     if (added.length > 0) {
-        parts.push(`New skills (call ${SKILL_LOAD} with the name to use one):\n${lines(added)}`);
+        parts.push(`${texts.newSkills}\n${lines(added)}`);
     }
     if (updated.length > 0) {
-        parts.push(`Updated skills (call ${SKILL_LOAD} again before relying on earlier instructions):\n${lines(updated)}`);
+        parts.push(`${texts.updatedSkills}\n${lines(updated)}`);
     }
     if (removed.length > 0) {
         parts.push(`Removed skills (no longer available; do not use them): ${[...removed]
@@ -106,22 +123,21 @@ export function skillsChangeText(prev, next, pinnedIds) {
     return parts.join("\n\n");
 }
 /** 压缩摘要之后补上的「当前目录」（与 system 里的第一份不同时）：完整列出，替代之前的目录与提醒。 */
-export function skillsCurrentText(skills) {
+export function skillsCurrentText(skills, texts = SKILL_TEXTS) {
     if (skills.length === 0) {
         return "No skills are available in this conversation now (this replaces any earlier list of skills).";
     }
-    return ("Skills available in this conversation now (this replaces any earlier list of skills; call " +
-        `${SKILL_LOAD} with a name to read a skill's instructions):\n${lines(skills)}`);
+    return `${texts.currentSkills}\n${lines(skills)}`;
 }
 // ---- Skills a person invoked (phase D spec §4.4; model-visible, English) ----
 /**
  * The line restored after a compaction summary whose range holds inline skill invocations
  * (`names`: distinct, code point order); empty for none. Bodies are not re-injected.
  */
-export function invokedSkillsText(names) {
+export function invokedSkillsText(names, texts = SKILL_TEXTS) {
     if (names.length === 0)
         return "";
-    return `Skills the user invoked earlier in this conversation: ${names.join(", ")}. Call ${SKILL_LOAD} with a name to read its instructions again.`;
+    return texts.invokedSkills(names);
 }
 /** The distinct names (code point order) of the inline invocations in `events` up to `upToSeq`. */
 export function invokedSkillNames(events, upToSeq) {
@@ -180,16 +196,14 @@ export function systemSkillsCatalog(events) {
 }
 // ---- Pinned skills and the tool-name map (phase B, spec §9.1, §9.4; model-visible, English) ----
 /** The header of the pinned skills in the system cache segment. */
-export const PINNED_SKILLS_HEADER = "Pinned skills: the owner of this agent pinned these skills, so their instructions apply " +
-    `throughout this conversation. Follow them without calling ${SKILL_LOAD}; call ${SKILL_LOAD} ` +
-    "only to copy a pinned skill's files into the sandbox.";
+export const PINNED_SKILLS_HEADER = SKILL_TEXTS.pinnedSkillsHeader;
 /** One pinned skill with its body. */
 export function pinnedBlock(p) {
     return `<pinned_skill name="${p.name}" version="${p.version}">\n${p.body.trim()}\n</pinned_skill>`;
 }
 /** The pinned skills of the system snapshot (non-empty), after the catalog. */
-export function pinnedSystemText(pinned) {
-    return `${PINNED_SKILLS_HEADER}\n\n${pinned.map(pinnedBlock).join("\n\n")}`;
+export function pinnedSystemText(pinned, texts = SKILL_TEXTS) {
+    return `${texts.pinnedSkillsHeader}\n\n${pinned.map(pinnedBlock).join("\n\n")}`;
 }
 /**
  * The pinned change notice between two snapshots ({@link samePinned} false): each entry that is new
@@ -233,7 +247,7 @@ export function toolMapChangeText(next) {
  * nothing else differs: logs before phase B render exactly as before), the pinned change, the
  * tool-name map change; joined by blank lines.
  */
-export function snapshotChangeText(prev, next) {
+export function snapshotChangeText(prev, next, texts = SKILL_TEXTS) {
     const prevSkills = prev?.skills ?? [];
     const pinnedDiff = !samePinned(prev?.pinned, next.pinned);
     const mapDiff = prev?.toolMap !== next.toolMap;
@@ -247,7 +261,7 @@ export function snapshotChangeText(prev, next) {
         : !sameSkills(prevSkills, next.skills);
     const parts = [];
     if (catalogDiff || (!pinnedDiff && !mapDiff)) {
-        parts.push(skillsChangeText(prevSkills, next.skills, pinnedIds));
+        parts.push(skillsChangeText(prevSkills, next.skills, pinnedIds, texts));
     }
     if (pinnedDiff)
         parts.push(pinnedChangeText(prev?.pinned, next.pinned));
@@ -260,10 +274,10 @@ export function snapshotChangeText(prev, next) {
  * current catalog (when the skills differ from the system snapshot's), the current pinned skills
  * (when they differ), the tool-name map (when it differs); joined by blank lines, "" for nothing.
  */
-export function snapshotCurrentText(system, covered) {
+export function snapshotCurrentText(system, covered, texts = SKILL_TEXTS) {
     const parts = [];
     if (!sameSkills(system?.skills ?? [], covered.skills)) {
-        parts.push(skillsCurrentText(covered.skills));
+        parts.push(skillsCurrentText(covered.skills, texts));
     }
     if (!samePinned(system?.pinned, covered.pinned))
         parts.push(pinnedCurrentText(covered.pinned));
@@ -273,10 +287,10 @@ export function snapshotCurrentText(system, covered) {
     return parts.join("\n\n");
 }
 /** The system snapshot's text after the agent's instructions: catalog, pinned skills, tool map. */
-export function snapshotSystemText(s) {
-    let text = skillsCatalogText(s.skills);
+export function snapshotSystemText(s, texts = SKILL_TEXTS) {
+    let text = skillsCatalogText(s.skills, texts);
     if (s.pinned && s.pinned.length > 0)
-        text += `\n\n${pinnedSystemText(s.pinned)}`;
+        text += `\n\n${pinnedSystemText(s.pinned, texts)}`;
     if (s.toolMap !== undefined)
         text += `\n\n${s.toolMap}`;
     return text;

package/dist/runtime/context/tool-changes.d.ts

@@ -0,0 +1,27 @@
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+/**
+ * Tool set changes mid-conversation (tool naming spec §9.1). The kernel resolves the tools on every
+ * step, so an extension switched on in the org, a connector set up or a sub-agent roster added
+ * changes the next request's tool list; earlier answers in the history ("I have no web search")
+ * would still contradict it. A step whose resolved set differs from the one the previous request
+ * offered logs a `tools_changed` event before its request; request building renders it at its
+ * position as a system message ({@link toolsChangedText}).
+ */
+export type ToolsChange = Pick<EventPayload<"tools_changed">, "added" | "removed">;
+/**
+ * The tool set the conversation's previous model request offered, from the log alone: the last
+ * `model_call`'s `tools` and `catalog` keys (with `ToolSearch` the catalog holds the deferred
+ * tools, so the union is the whole resolved set), then any `tools_changed` logged after it (a
+ * step that logged its change and crashed before its request: the change is not logged twice).
+ * Skipped: a `model_call` without recorded tools (older logs) and a call whose tools were left out
+ * because its model has no tool support (empty, with that step's unsupported reminder): those say
+ * nothing about the resolved set. Null when no request offered a known set yet.
+ */
+export declare function previousToolSet(events: readonly ConversationEvent[]): Set<string> | null;
+/**
+ * The change from the previous request's tool set to `current` (sorted names), or null: before
+ * the conversation's first request (its list is the baseline) and when nothing changed.
+ */
+export declare function toolSetChange(events: readonly ConversationEvent[], current: readonly string[]): ToolsChange | null;
+/** The model-visible text of a `tools_changed` event (English). */
+export declare function toolsChangedText(change: ToolsChange): string;

package/dist/runtime/context/tool-changes.js

@@ -0,0 +1,60 @@
+import { TOOLS_UNSUPPORTED_REMINDER } from "./reminders.js";
+/**
+ * The tool set the conversation's previous model request offered, from the log alone: the last
+ * `model_call`'s `tools` and `catalog` keys (with `ToolSearch` the catalog holds the deferred
+ * tools, so the union is the whole resolved set), then any `tools_changed` logged after it (a
+ * step that logged its change and crashed before its request: the change is not logged twice).
+ * Skipped: a `model_call` without recorded tools (older logs) and a call whose tools were left out
+ * because its model has no tool support (empty, with that step's unsupported reminder): those say
+ * nothing about the resolved set. Null when no request offered a known set yet.
+ */
+export function previousToolSet(events) {
+    const unsupported = new Set();
+    for (const e of events) {
+        if (e.type === "reminder" && e.payload.text === TOOLS_UNSUPPORTED_REMINDER) {
+            unsupported.add(`${e.runId ?? ""}\u0000${e.payload.step}`);
+        }
+    }
+    let known = null;
+    for (const e of events) {
+        if (e.type === "model_call") {
+            const { tools, catalog } = e.payload.request;
+            if (tools === undefined)
+                continue;
+            const keys = [...tools, ...(catalog ?? [])].map((t) => t.key);
+            if (keys.length === 0 && unsupported.has(`${e.runId ?? ""}\u0000${e.payload.step}`))
+                continue;
+            known = new Set(keys);
+        }
+        else if (e.type === "tools_changed" && known !== null) {
+            for (const k of e.payload.removed)
+                known.delete(k);
+            for (const k of e.payload.added)
+                known.add(k);
+        }
+    }
+    return known;
+}
+/**
+ * The change from the previous request's tool set to `current` (sorted names), or null: before
+ * the conversation's first request (its list is the baseline) and when nothing changed.
+ */
+export function toolSetChange(events, current) {
+    const before = previousToolSet(events);
+    if (before === null)
+        return null;
+    const now = new Set(current);
+    const added = [...now].filter((k) => !before.has(k)).sort();
+    const removed = [...before].filter((k) => !now.has(k)).sort();
+    return added.length === 0 && removed.length === 0 ? null : { added, removed };
+}
+/** The model-visible text of a `tools_changed` event (English). */
+export function toolsChangedText(change) {
+    const parts = ["Your tools changed."];
+    if (change.added.length > 0)
+        parts.push(`Now available: ${change.added.join(", ")}.`);
+    if (change.removed.length > 0)
+        parts.push(`No longer available: ${change.removed.join(", ")}.`);
+    parts.push("Use the current tool list; it replaces anything said earlier in this conversation about which tools you have.");
+    return parts.join(" ");
+}

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

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

package/dist/runtime/hook-calls.js

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

package/dist/runtime/langgraph-loop.d.ts

@@ -32,7 +32,9 @@ export interface LangGraphLoopHooks {
  * 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 节点时若回复已在日志里，

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,24 +37,52 @@ 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` 行，统一承载 `ask_user`、
+ * 运行在等什么人处理：审批（`approvals` 行）或输入请求（`questions` 行，统一承载 `AskUserQuestion`、
  * 插件工具的 `input_required` 与 MCP elicitation）。`expiresAt` 为 ISO 时间。
  * `subagents` (phase C, spec §7.2): sub-agents dispatched in a step are still running; the id is
  * `sa-<runId>-<step>` (no `:`, it is part of BullMQ job ids).

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, "destroyDevice" | "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