@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/runtime/conversation-lock.js

@@ -1,97 +1,87 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { LockService } from "../infra/lock/lock.service.js";
 /** 会话运行锁的默认 TTL（毫秒）：持有方每 `ttlMs / 3` 续租一次。 */
 export const CONVERSATION_LOCK_TTL_MS = 30_000;
 /** 会话运行锁的键前缀。 */
 const RUN_LOCK_PREFIX = "capk:conv-run:";
-const RENEW = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('PEXPIRE', KEYS[1], ARGV[2])
-end
-return 0
-`;
-const RELEASE = `
-if redis.call('GET', KEYS[1]) == ARGV[1] then
-  return redis.call('DEL', KEYS[1])
-end
-return 0
-`;
 /**
- * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
- * 带 TTL；持有期间由本进程的定时器每 `ttlMs / 3` 续租（本进程持有的锁的续租，允许的进程内定时器）。
- * 持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ * A per-conversation lease on {@link LockService.hold}: key `<prefix><conversationId>`, value the
+ * holder's run id (other replicas read it with {@link holder}), renewed every TTL/3 by the lock
+ * service while held; a crashed holder's key expires within the TTL and another replica can take
+ * it. Built by {@link ConversationLock} (the run lock) and its {@link ConversationLock.scoped}
+ * views (the same lock for another purpose, e.g. the channel delivery `capk:channel-deliver:`).
+ * A loss is logged once, by the lock service (`lock lost`, with the key).
  */
-export class ConversationLock {
-    redis;
-    log;
+export class ConversationLeases {
+    locks;
     keyPrefix;
-    /** `keyPrefix`：同样语义、按会话互斥的其他用途用别的前缀（如渠道出站投递 `capk:channel-deliver:`）。 */
-    constructor(redis, log, keyPrefix = RUN_LOCK_PREFIX) {
-        this.redis = redis;
-        this.log = log;
+    constructor(locks, keyPrefix) {
+        this.locks = locks;
         this.keyPrefix = keyPrefix;
     }
     lockKey(conversationId) {
         return `${this.keyPrefix}${conversationId}`;
     }
     async acquire(conversationId, runId, ttlMs = CONVERSATION_LOCK_TTL_MS) {
-        const key = this.lockKey(conversationId);
-        const ok = await this.redis.set(key, runId, "PX", ttlMs, "NX");
-        if (ok !== "OK")
+        const held = await this.locks.hold(this.lockKey(conversationId), runId, ttlMs);
+        if (!held)
             return null;
-        const redis = this.redis;
-        const log = this.log;
-        let lost = false;
-        let timer;
-        const lostCallbacks = [];
-        const stop = () => {
-            clearInterval(timer);
-            timer = undefined;
-        };
-        const lease = {
-            conversationId,
-            runId,
-            get lost() {
-                return lost;
-            },
-            async renew() {
-                if (lost)
-                    return false;
-                const r = Number(await redis.eval(RENEW, 1, key, runId, ttlMs));
-                if (r !== 1) {
-                    lost = true;
-                    stop();
-                    log?.warn("conversation run lock lost", { conversationId, runId });
-                    for (const cb of lostCallbacks.splice(0))
-                        cb();
-                }
-                return r === 1;
-            },
-            async release() {
-                stop();
-                await redis.eval(RELEASE, 1, key, runId);
-            },
-            abandon: stop,
-            onLost(cb) {
-                if (lost)
-                    cb();
-                else
-                    lostCallbacks.push(cb);
-            },
-        };
-        timer = setInterval(() => {
-            lease.renew().catch((err) => log?.warn("conversation run lock renew failed", { err }));
-        }, Math.max(1, Math.floor(ttlMs / 3)));
-        timer.unref();
-        return lease;
+        return toLease(held, conversationId, runId);
     }
     /**
      * 释放某个运行持有的锁（只在仍由该 runId 持有时删除），不需要 Lease：用于 BullMQ 已判定任务失败
      * （例如持有者崩溃、stalled 次数超限）后清理死去持有者留下的锁，不必等 TTL 过期。
      */
     async releaseFor(conversationId, runId) {
-        await this.redis.eval(RELEASE, 1, this.lockKey(conversationId), runId);
+        await this.locks.releaseIf(this.lockKey(conversationId), runId);
     }
     /** 当前持有者的 runId；无人持有 → null。 */
     holder(conversationId) {
-        return this.redis.get(this.lockKey(conversationId));
+        return this.locks.holderOf(this.lockKey(conversationId));
     }
 }
+function toLease(held, conversationId, runId) {
+    return {
+        conversationId,
+        runId,
+        get lost() {
+            return held.lost.aborted;
+        },
+        renew: () => held.renew(),
+        release: () => held.release(),
+        abandon: () => held.abandon(),
+        onLost(cb) {
+            if (held.lost.aborted)
+                cb();
+            else
+                held.lost.addEventListener("abort", () => cb(), { once: true });
+        },
+    };
+}
+/**
+ * 会话级运行锁（spec 4.3「同一会话同一时刻只跑一轮」）：Redis 键 `capk:conv-run:<id>`，值为 runId，
+ * 带 TTL，由 {@link LockService} 每 TTL/3 续租。持有方崩溃时停止续租，锁在 TTL 后过期，其他副本可以取得。
+ */
+let ConversationLock = class ConversationLock extends ConversationLeases {
+    constructor(locks) {
+        super(locks, RUN_LOCK_PREFIX);
+    }
+    /** The same per-conversation lease under another key prefix (another purpose). */
+    scoped(keyPrefix) {
+        return new ConversationLeases(this.locks, keyPrefix);
+    }
+};
+ConversationLock = __decorate([
+    Injectable(),
+    __param(0, Inject(LockService))
+], ConversationLock);
+export { ConversationLock };

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

@@ -1,9 +1,9 @@
-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 { KernelDb } from "../db/kernel-schema.js";
 import type { HookOutcome, HookRegistry } from "../extensions/hooks.js";
-import { audit } from "../identity/audit.js";
+import type { audit } from "../identity/audit.js";
+import type { StepLog } from "./step-log.js";
 /** What the runtime needs from the host's hook registry (absent in eval replays). */
 export type HookRunner = Pick<HookRegistry, "run" | "has">;
 /**
@@ -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];
 /**
@@ -75,8 +82,8 @@ export type AuditEntry = Parameters<typeof audit>[1];
  * denial rethrows it before running the hooks again, so no second audit entry is written.
  */
 export declare function recordHookDenial(d: {
-    db: KernelDb;
     eventLog: EventLog;
+    stepLog: Pick<StepLog, "appendAudited">;
 }, at: DenialSite, mount: Extract<AvailableHook, "model.request" | "tool.preExecute">, denial: HookDenial, where: {
     step: number;
     attempt?: number;

package/dist/runtime/hook-calls.js

@@ -1,4 +1,3 @@
-import { audit } from "../identity/audit.js";
 /**
  * The scope for hook payloads, or null when hooks must not fire: no registry (eval replays omit it),
  * a conversation that is neither `chat` nor `subagent`, or missing identity fields. A sub-agent's
@@ -106,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),
         },
     };
 }
@@ -125,11 +157,7 @@ export async function recordHookDenial(d, at, mount, denial, where) {
     if (await d.eventLog.findByIdem(at.conversationId, at.idemKey))
         return;
     const event = hookDeniedEvent(at, mount, denial, where);
-    const written = await d.db.transaction().execute(async (t) => {
-        const out = await d.eventLog.append(at.conversationId, [event], t);
-        await audit(t, hookDeniedAudit(at, event.payload, denial));
-        return out;
-    });
+    const written = await d.stepLog.appendAudited(at.conversationId, [event], hookDeniedAudit(at, event.payload, denial));
     if (written.length > 0) {
         await d.eventLog.notify(at.conversationId, Math.max(...written.map((e) => e.seq)));
     }

package/dist/runtime/job-ids.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the runtime's fixed-period jobs had before they became
+ * `@LockedCron` jobs: an upgraded deployment still has them in Redis, so the
+ * worker removes them at start (`RETIRED_SCHEDULER_IDS`). A leaf module: the maintenance worker
+ * imports it without the runtime's providers.
+ */
+/** The wait sweep's old scheduler (every 10 minutes). */
+export declare const WAIT_SWEEP_SCHEDULER_ID = "wait-sweep-every-10m";
+/** The usage sweeper's old scheduler (every minute). */
+export declare const USAGE_SWEEP_SCHEDULER_ID = "usage-report-sweep-every";

package/dist/runtime/job-ids.js

@@ -0,0 +1,10 @@
+/**
+ * The maintenance job scheduler ids the runtime's fixed-period jobs had before they became
+ * `@LockedCron` jobs: an upgraded deployment still has them in Redis, so the
+ * worker removes them at start (`RETIRED_SCHEDULER_IDS`). A leaf module: the maintenance worker
+ * imports it without the runtime's providers.
+ */
+/** The wait sweep's old scheduler (every 10 minutes). */
+export const WAIT_SWEEP_SCHEDULER_ID = "wait-sweep-every-10m";
+/** The usage sweeper's old scheduler (every minute). */
+export const USAGE_SWEEP_SCHEDULER_ID = "usage-report-sweep-every";

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 节点时若回复已在日志里，
@@ -112,7 +127,7 @@ export class LangGraphLoop {
     build(ctx) {
         const timedOut = () => Date.now() >= ctx.limits.deadline;
         // 本次运行的附件字节缓存：各步共用，运行结束即丢弃（只是优化，见 MediaCache）
-        const mediaCache = new MediaCache(this.stepDeps.config().attachments.requestMediaBytes);
+        const mediaCache = new MediaCache(this.stepDeps.config.get().attachments.requestMediaBytes);
         const input = (step, absorbedUpToSeq) => ({
             orgId: ctx.orgId,
             conversationId: ctx.conversationId,
@@ -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,5 +1,6 @@
 import type { AgentDefinition } from "../agents/definition.js";
-import type { ConversationEvent } from "../conversations/events.js";
+import type { KernelConfig } from "../config/schema.js";
+import type { AbsorbableEvent } from "../conversations/events.js";
 import type { StreamSink } from "./model-call.js";
 /** 一次运行交给 loop 的上下文（spec 4.4）。 */
 export interface LoopContext {
@@ -21,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;
@@ -35,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).
@@ -91,3 +121,9 @@ export type LoopOutcome =
 export interface AgentLoop {
     run(ctx: LoopContext): Promise<LoopOutcome>;
 }
+/**
+ * The wait of a step whose sub-agents still run (spec §7.2): id `sa-<runId>-<step>`, expiring after
+ * the approval timeout plus one run's duration plus 10 minutes (a child may itself wait for an
+ * approval); the timeout is a safety net.
+ */
+export declare function subagentsWait(runId: string, step: number, config: Pick<KernelConfig, "tools" | "runtime">, now?: number): WaitingFor;

package/dist/runtime/loop.js

@@ -5,3 +5,17 @@
 export const subagentWaitingIdemKey = (childRunId, waitId) => `subagent_waiting:${childRunId}:${waitId}`;
 /** The id of a run's `subagents` wait in `step` (part of BullMQ job ids, so no `:`). */
 export const subagentsWaitId = (runId, step) => `sa-${runId}-${step}`;
+/**
+ * The wait of a step whose sub-agents still run (spec §7.2): id `sa-<runId>-<step>`, expiring after
+ * the approval timeout plus one run's duration plus 10 minutes (a child may itself wait for an
+ * approval); the timeout is a safety net.
+ */
+export function subagentsWait(runId, step, config, now = Date.now()) {
+    const ms = config.tools.approvalTimeoutHours * 3_600_000 + config.runtime.maxRunSeconds * 1000 + 600_000;
+    return {
+        kind: "subagents",
+        id: subagentsWaitId(runId, step),
+        expiresAt: new Date(now + ms).toISOString(),
+        step,
+    };
+}

package/dist/runtime/maintenance-queue.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The kernel maintenance queue (no `:`): wait timeouts (`wait-timeout`, see waits.ts), one-off
+ * maintenance (sandbox destruction, connector drift, directory sync); no periodic jobs any more
+ * (they are `@LockedCron` / `@LockedInterval` jobs). The queue has one Worker (started on the `worker` role only) that
+ * dispatches by job name to the registered handlers. Separate from the run queues: their handler,
+ * stalled and failure handling assume "one job = one run"; maintenance jobs are short, with no
+ * conversation lock or quota. A leaf module, so providers that add jobs (orgs/directory-sync.ts)
+ * import the name without importing the worker (which imports their scheduler ids back).
+ */
+export declare const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";

package/dist/runtime/maintenance-queue.js

@@ -0,0 +1,10 @@
+/**
+ * The kernel maintenance queue (no `:`): wait timeouts (`wait-timeout`, see waits.ts), one-off
+ * maintenance (sandbox destruction, connector drift, directory sync); no periodic jobs any more
+ * (they are `@LockedCron` / `@LockedInterval` jobs). The queue has one Worker (started on the `worker` role only) that
+ * dispatches by job name to the registered handlers. Separate from the run queues: their handler,
+ * stalled and failure handling assume "one job = one run"; maintenance jobs are short, with no
+ * conversation lock or quota. A leaf module, so providers that add jobs (orgs/directory-sync.ts)
+ * import the name without importing the worker (which imports their scheduler ids back).
+ */
+export const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";