@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/runtime/hook-calls.js

@@ -0,0 +1,136 @@
+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
+ * scope carries `parent` (where it was dispatched from).
+ */
+export function hookScope(hooks, s) {
+    if (!hooks || (s.conversationKind !== "chat" && s.conversationKind !== "subagent"))
+        return null;
+    if (s.accountId === undefined || s.agentId === undefined)
+        return null;
+    return {
+        orgId: s.orgId,
+        accountId: s.accountId,
+        agentId: s.agentId,
+        agentVersion: s.agentVersion,
+        conversationId: s.conversationId,
+        runId: s.runId,
+        ...(s.parent !== undefined && {
+            parent: {
+                conversationId: s.parent.conversationId,
+                runId: s.parent.runId,
+                callId: s.parent.callId,
+            },
+        }),
+    };
+}
+/**
+ * Fires observe-only hooks (`model.response`, `tool.postExecute`) without waiting. `signal` must be
+ * run-scoped (not a per-call controller aborted when the call ends), or the hooks would be cut off.
+ */
+export function fireObserve(hooks, mount, payload, signal, log) {
+    if (!hooks.has(mount))
+        return;
+    hooks.run(mount, payload, signal).catch((err) => {
+        // run() only rejects when the caller aborted: nothing to do
+        if (!signal.aborted)
+            log.warn("observe hooks failed to dispatch", { mount, err });
+    });
+}
+/** Decoded size of standard padded base64, in bytes. */
+const base64Bytes = (data) => {
+    const pad = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+    return Math.max(0, Math.floor(data.length / 4) * 3 - pad);
+};
+/**
+ * The `model.request` payload's request (F10, I-3): the request sent to the provider with every image
+ * and document block replaced by a {@link HookMediaPlaceholder} (`kind`, `mediaType`, decoded `size`),
+ * so hook payloads carry neither media bytes nor attachment ids. Media never sits outside user
+ * messages, but every message is projected anyway. Building the copy also keeps the per-call clone
+ * and freeze of the payload small. A `ref` source should never reach here (the kernel resolves refs
+ * before sending); it becomes a placeholder of size 0 and logs a warning.
+ */
+export function hookRequestOf(request, log) {
+    let refs = 0;
+    const project = (b) => {
+        if (b.type !== "image" && b.type !== "document")
+            return b;
+        if (b.source.kind === "ref")
+            refs++;
+        return {
+            type: "media_omitted",
+            kind: b.type,
+            mediaType: b.mediaType,
+            size: b.source.kind === "base64" ? base64Bytes(b.source.data) : 0,
+        };
+    };
+    const messages = request.messages.map((m) => m.role === "system" ? m : { role: m.role, content: m.content.map(project) });
+    if (refs > 0) {
+        log?.warn("attachment refs reached a model.request hook payload", {
+            model: request.model,
+            refs,
+        });
+    }
+    return { ...request, messages };
+}
+/** The `hook_denied` event of a denial (not model-visible: request building skips it). */
+export function hookDeniedEvent(at, mount, denial, where) {
+    return {
+        type: "hook_denied",
+        runId: at.runId,
+        idemKey: at.idemKey,
+        payload: {
+            mount,
+            plugin: denial.plugin,
+            reason: denial.reason,
+            cause: denial.cause,
+            step: where.step,
+            ...(where.attempt !== undefined && { attempt: where.attempt }),
+            ...(where.callId !== undefined && { callId: where.callId }),
+        },
+    };
+}
+/**
+ * The `hook.denied` audit entry of a denial. For an R10 denial (`preflight`) it says that no plugin ran
+ * and that the named plugin is only the first policy plugin on the mount.
+ */
+export function hookDeniedAudit(at, payload, denial) {
+    return {
+        ...(at.accountId !== undefined && { actorAccountId: at.accountId }),
+        orgId: at.orgId,
+        action: "hook.denied",
+        target: at.conversationId,
+        detail: {
+            ...payload,
+            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 } : {}),
+        },
+    };
+}
+/**
+ * Writes a model request's `hook_denied` event and its audit entry in one transaction (the tool path
+ * writes them with the `tool_result` instead). Idempotent by idem key: a resumed run that finds the
+ * denial rethrows it before running the hooks again, so no second audit entry is written.
+ */
+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;
+    });
+    if (written.length > 0) {
+        await d.eventLog.notify(at.conversationId, Math.max(...written.map((e) => e.seq)));
+    }
+}

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

@@ -0,0 +1,52 @@
+import type { ToolPipeline } from "../tools/pipeline.js";
+import type { KyselyCheckpointSaver } from "./checkpointer.js";
+import type { AgentLoop, LoopContext, LoopOutcome } from "./loop.js";
+import { type ModelStepDeps, type ModelStepResult } from "./model-call.js";
+import type { SubagentStep } from "./subagents/progress.js";
+import { type SkillForks } from "./subagents/skill-fork.js";
+/** loop 的依赖：单步模型调用依赖 + 工具执行管线（tools 节点）。 */
+export interface LoopDeps extends ModelStepDeps {
+    toolPipeline: Pick<ToolPipeline, "runStep">;
+    /**
+     * After a sub-agent's tools node finished a step: publishes its progress on the parent's topic
+     * (sub-agents spec §14.2, `publishSubagentProgress`). Never throws. Replays omit it.
+     */
+    subagentProgress?(s: SubagentStep): Promise<void>;
+    /**
+     * Phase D forked skills: in the run's first `prepare`, a fork invocation the run absorbed is
+     * dispatched (live) or its recorded report appended (full-run replay), before any model call.
+     * Without it a fork invocation is answered like any message.
+     */
+    skillForks?: SkillForks;
+}
+/** 测试钩子。 */
+export interface LangGraphLoopHooks {
+    /**
+     * `model` / `wrapUp` 节点里 `runModelStep` / `runFinalWrapUp` 返回之后、节点返回之前调用：
+     * 抛错即模拟「回复已写入日志、checkpoint 尚未保存」时进程崩溃。
+     */
+    afterModelStep?(runId: string, step: number, result: ModelStepResult): Promise<void>;
+}
+/**
+ * 默认 AgentLoop：LangGraph 状态图，checkpoint 存在内核的 `KyselyCheckpointSaver`（thread_id = runId），
+ * 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;
+ * 模型中止或正常结束 → 结束。`durability: "sync"`：每个节点的 checkpoint 在下一个节点开始前落库。
+ *
+ * 幂等：`runModelStep` / `runFinalWrapUp` 按 (runId, step) 幂等，续跑重新执行 model 节点时若回复已在日志里，
+ * 直接复用（不再调用模型）；tools 节点按 (runId, callId) 幂等：已有结果的调用跳过，「有开始无结果」的
+ * 调用记为结果未知、不再执行（spec 4.3）。
+ *
+ * 等人处理（Task 9）：tools 节点遇到需要审批 / 用户输入的调用时抛 {@link LoopSuspended}，run 返回 `suspended`；
+ * worker 把运行置为 waiting、释放会话锁与配额，处理后新任务从同一 checkpoint 续跑 tools 节点。
+ */
+export declare class LangGraphLoop implements AgentLoop {
+    private readonly saver;
+    private readonly stepDeps;
+    private readonly hooks;
+    constructor(saver: KyselyCheckpointSaver, stepDeps: LoopDeps, hooks?: LangGraphLoopHooks);
+    run(ctx: LoopContext): Promise<LoopOutcome>;
+    private build;
+}

package/dist/runtime/langgraph-loop.js

@@ -0,0 +1,247 @@
+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 { isForkInvocation } from "./subagents/skill-fork.js";
+/**
+ * 图状态：只记录进度，消息每步从事件日志重建（runModelStep 自己读日志），checkpoint 很小。
+ * - `step`：当前（最近一次进入的）步骤编号，prepare 节点 +1；
+ * - `consumedUpToSeq`：已吸收的最大 user_message seq；
+ * - `lastStopReason`：最近一步模型调用的停止原因；
+ * - `outcome`：图的结束方式（在决定结束的节点里写入，续跑已结束的图时直接读出，不依赖当前时间）。
+ *
+ * 所有 channel 都是默认的 LastValue（不用实验性的 DeltaChannel，也没有子图）：
+ * 每个 checkpoint 自带完整状态，`pruneToLatest` 之后仍能独立还原（R19）。
+ */
+const LoopState = Annotation.Root({
+    step: Annotation(),
+    consumedUpToSeq: Annotation(),
+    lastStopReason: Annotation(),
+    outcome: Annotation(),
+});
+const INITIAL = { step: 0, consumedUpToSeq: 0, lastStopReason: null, outcome: null };
+/**
+ * prepare 节点在停机信号下抛出：本次 invoke 以它结束，checkpoint 停在 prepare 之前
+ * （LangGraph 把出错的任务记为该 checkpoint 上的 pending error，`invoke(null)` 续跑时重新执行它）。
+ *
+ * 选它而不是 `interrupt()` / `GraphInterrupt`：`interrupt()` 是「等待人类输入」语义，续跑需要
+ * `Command({ resume })`，且节点会从头重放；停机只是「换个进程从同一位置继续」，用普通异常即可，
+ * 续跑时 prepare 正常重新执行，语义更直接。
+ */
+class LoopInterrupted extends Error {
+    constructor() {
+        super("agent loop interrupted at a step boundary");
+        this.name = "LoopInterrupted";
+    }
+}
+/**
+ * tools 节点在某个调用需要等人处理（审批 / 输入请求）时抛出：与 {@link LoopInterrupted} 相同的机制——
+ * 本次 invoke 以它结束，checkpoint 停在 tools 之前，处理后 `invoke(null)` 重新执行 tools 节点
+ * （按 (runId, callId) 幂等：已有结果的调用跳过，读到审批 / 输入结果的调用继续）。
+ *
+ * 不用 `interrupt()`：续跑由另一个副本的新任务发起，读到的结果都在 PG（审批 / 输入请求表）里，
+ * 不需要经 `Command({ resume })` 传值；用普通异常与停机共用一条已验证的续跑路径。
+ */
+class LoopSuspended extends Error {
+    waitingFor;
+    constructor(waitingFor) {
+        super("agent loop suspended waiting for a human");
+        this.waitingFor = waitingFor;
+        this.name = "LoopSuspended";
+    }
+}
+/**
+ * 默认 AgentLoop：LangGraph 状态图，checkpoint 存在内核的 `KyselyCheckpointSaver`（thread_id = runId），
+ * 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;
+ * 模型中止或正常结束 → 结束。`durability: "sync"`：每个节点的 checkpoint 在下一个节点开始前落库。
+ *
+ * 幂等：`runModelStep` / `runFinalWrapUp` 按 (runId, step) 幂等，续跑重新执行 model 节点时若回复已在日志里，
+ * 直接复用（不再调用模型）；tools 节点按 (runId, callId) 幂等：已有结果的调用跳过，「有开始无结果」的
+ * 调用记为结果未知、不再执行（spec 4.3）。
+ *
+ * 等人处理（Task 9）：tools 节点遇到需要审批 / 用户输入的调用时抛 {@link LoopSuspended}，run 返回 `suspended`；
+ * worker 把运行置为 waiting、释放会话锁与配额，处理后新任务从同一 checkpoint 续跑 tools 节点。
+ */
+export class LangGraphLoop {
+    saver;
+    stepDeps;
+    hooks;
+    constructor(saver, stepDeps, hooks = {}) {
+        this.saver = saver;
+        this.stepDeps = stepDeps;
+        this.hooks = hooks;
+    }
+    async run(ctx) {
+        const graph = this.build(ctx);
+        const config = {
+            configurable: { thread_id: ctx.runId },
+            // 每步最多 3 个超步（prepare、model、tools），再加 wrapUp 与余量。
+            recursionLimit: ctx.limits.maxSteps * 3 + 10,
+            durability: "sync",
+        };
+        const existing = await this.saver.getTuple({ configurable: { thread_id: ctx.runId } });
+        let final;
+        try {
+            if (existing) {
+                const snapshot = await graph.getState(config);
+                // 续跑 model / wrapUp 节点：此前进程可能已流出半截内容，先让订阅方丢弃。
+                if (snapshot.next.includes("model") || snapshot.next.includes("wrapUp")) {
+                    ctx.sink({ kind: "step_reset", runId: ctx.runId, step: snapshot.values.step });
+                }
+                final = (await graph.invoke(null, config));
+            }
+            else {
+                final = (await graph.invoke(INITIAL, config));
+            }
+        }
+        catch (e) {
+            if (e instanceof LoopInterrupted)
+                return { kind: "interrupted" };
+            if (e instanceof LoopSuspended)
+                return { kind: "suspended", waitingFor: e.waitingFor };
+            throw e;
+        }
+        const outcome = final.outcome ?? "completed";
+        return outcome === "aborted"
+            ? { kind: "aborted" }
+            : { kind: outcome, consumedUpToSeq: final.consumedUpToSeq };
+    }
+    build(ctx) {
+        const timedOut = () => Date.now() >= ctx.limits.deadline;
+        // 本次运行的附件字节缓存：各步共用，运行结束即丢弃（只是优化，见 MediaCache）
+        const mediaCache = new MediaCache(this.stepDeps.config().attachments.requestMediaBytes);
+        const input = (step, absorbedUpToSeq) => ({
+            orgId: ctx.orgId,
+            conversationId: ctx.conversationId,
+            runId: ctx.runId,
+            step,
+            agent: ctx.agent,
+            agentVersion: ctx.agentVersion,
+            signal: ctx.signal,
+            sink: ctx.sink,
+            absorbedUpToSeq,
+            maxSteps: ctx.limits.maxSteps,
+            mediaCache,
+            agentId: ctx.agentId,
+            accountId: ctx.triggerAccountId,
+            ...(ctx.conversationKind !== undefined && { conversationKind: ctx.conversationKind }),
+            ...(ctx.parent !== undefined && { parentRunId: ctx.parent.runId, parent: ctx.parent }),
+        });
+        const deps = this.stepDeps;
+        const hooks = this.hooks;
+        const prepare = async (s) => {
+            if (ctx.shutdown.aborted)
+                throw new LoopInterrupted();
+            // 先查截止时间、再吸收（R33）：超时结束的运行不得消费它没有回复的消息，
+            // 否则 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)
+            if (ctx.parent !== undefined &&
+                (await subagentBudgetUsedUp(deps.db, deps.config, ctx.orgId, ctx.parent.runId))) {
+                return { 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);
+            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,
+            // `forkBoundary`, makes it the last message there); its sub-agent runs, and its report is
+            // logged, before any model call. Found anywhere among the absorbed messages (the replay
+            // feeds them by the original absorption, without the boundary). A sub-agent's task message
+            // carries the record too, but a child never dispatches.
+            const fork = firstStep && ctx.parent === undefined ? absorbed.find(isForkInvocation) : undefined;
+            if (fork !== undefined && deps.skillForks) {
+                const r = await deps.skillForks.advance({ ctx, fork });
+                if (r.kind === "suspend")
+                    throw new LoopSuspended(r.waitingFor);
+                if (r.kind === "aborted") {
+                    return { consumedUpToSeq: consumed, lastStopReason: "aborted", outcome: "aborted" };
+                }
+                if (r.kind === "end")
+                    return { consumedUpToSeq: consumed, outcome: "completed" };
+            }
+            return { step: s.step + 1, consumedUpToSeq: consumed, outcome: null };
+        };
+        const model = async (s) => {
+            const r = await runModelStep(deps, input(s.step, s.consumedUpToSeq));
+            await hooks.afterModelStep?.(ctx.runId, s.step, r);
+            if (r.budget)
+                return { outcome: "budget" };
+            if (r.aborted) {
+                return { lastStopReason: "aborted", outcome: timedOut() ? "max_duration" : "aborted" };
+            }
+            return {
+                lastStopReason: r.stopReason,
+                outcome: r.stopReason === "tool_use" ? null : "completed",
+            };
+        };
+        // 本步的全部工具调用都写下结果后才回到 prepare（不在「已记录调用、未记录结果」之间构建请求）。
+        // 某个调用需要等人处理时抛 LoopSuspended（该调用之后的调用留到续跑时处理）。
+        const tools = async (s) => {
+            const r = await deps.toolPipeline.runStep({
+                orgId: ctx.orgId,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId,
+                step: s.step,
+                agentId: ctx.agentId,
+                agentVersion: ctx.agentVersion,
+                agent: ctx.agent,
+                accountId: ctx.triggerAccountId,
+                signal: ctx.signal,
+                deadline: ctx.limits.deadline,
+                ...(ctx.conversationKind !== undefined && { conversationKind: ctx.conversationKind }),
+                ...(ctx.parent !== undefined && { parent: ctx.parent }),
+            });
+            if (r.kind === "suspended")
+                throw new LoopSuspended(r.waitingFor);
+            if (ctx.parent !== undefined) {
+                // fire and forget: an ephemeral message never delays the child's next step (a slow count
+                // or a reconnecting Redis); each message carries absolute counts, so order does not
+                // matter (batch 11 m2)
+                void deps
+                    .subagentProgress?.({
+                    parentConversationId: ctx.parent.conversationId,
+                    conversationId: ctx.conversationId,
+                    runId: ctx.runId,
+                    step: s.step,
+                })
+                    ?.catch(() => { });
+            }
+            return {};
+        };
+        const wrapUp = async (s) => {
+            const r = await runFinalWrapUp(deps, input(s.step, s.consumedUpToSeq));
+            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",
+            };
+        };
+        return new StateGraph(LoopState)
+            .addNode("prepare", prepare)
+            .addNode("model", model)
+            .addNode("tools", tools)
+            .addNode("wrapUp", wrapUp)
+            .addEdge(START, "prepare")
+            .addConditionalEdges("prepare", (s) => {
+            // (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";
+        }, ["model", "wrapUp", END])
+            .addConditionalEdges("model", (s) => (s.outcome === null ? "tools" : END), [
+            "tools",
+            END,
+        ])
+            .addEdge("tools", "prepare")
+            .addEdge("wrapUp", END)
+            .compile({ checkpointer: this.saver });
+    }
+}

package/dist/runtime/loop.d.ts

@@ -0,0 +1,93 @@
+import type { AgentDefinition } from "../agents/definition.js";
+import type { ConversationEvent } from "../conversations/events.js";
+import type { StreamSink } from "./model-call.js";
+/** 一次运行交给 loop 的上下文（spec 4.4）。 */
+export interface LoopContext {
+    /** 会话所属组织。 */
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    /** 会话的 agent（工具调用上下文、策略判定用）。 */
+    agentId: string;
+    /** 发起本次运行的人（对话发起人）：工具调用用其个人凭据，审计记为 actor。 */
+    triggerAccountId: string;
+    agent: AgentDefinition;
+    agentVersion: number;
+    /** 用户中止或到达 deadline 时触发：进行中的模型调用立即停下。 */
+    signal: AbortSignal;
+    /**
+     * 停机信号（与用户中止不同）：loop 在下一个步骤边界返回 `interrupted`，不打断进行中的步骤。
+     */
+    shutdown: AbortSignal;
+    sink: StreamSink;
+    /**
+     * 下一个步骤间隙要吸收的插话：返回 seq > afterSeq 的 user_message（且只含本轮开始时尚未被消费的，
+     * 即 seq 也大于会话的 `consumed_seq`），按 seq 升序。loop 记录吸收到的最大 seq 作为 `consumedUpToSeq`。
+     */
+    pendingUserMessages(afterSeq: number): Promise<ConversationEvent[]>;
+    limits: {
+        maxSteps: number;
+        deadline: number;
+    };
+    /**
+     * Kind of the conversation: plugin hooks fire for `chat` and `subagent` (F10, P-18, sub-agents
+     * spec §11). Eval replays pass `eval`; when absent, hooks do not fire.
+     */
+    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).
+     */
+    parent?: SubagentParent;
+}
+/** Where a sub-agent's run was dispatched from (its `subagent_dispatches` row). */
+export interface SubagentParent {
+    conversationId: string;
+    runId: string;
+    callId: 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;
+}
+/**
+ * 运行在等什么人处理：审批（`approvals` 行）或输入请求（`questions` 行，统一承载 `ask_user`、
+ * 插件工具的 `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).
+ */
+export interface WaitingFor {
+    kind: "approval" | "input" | "subagents";
+    id: string;
+    expiresAt: string;
+    /** `subagents` only: the step whose sub-agents the run waits for (its timeout stops them). */
+    step?: number;
+}
+/**
+ * Idempotency key of a parent's `subagent_waiting` event: one per child run and wait (an approval
+ * or question id, or `connect-<callId>` for a connect card).
+ */
+export declare const subagentWaitingIdemKey: (childRunId: string, waitId: string) => string;
+/** The id of a run's `subagents` wait in `step` (part of BullMQ job ids, so no `:`). */
+export declare const subagentsWaitId: (runId: string, step: number) => string;
+export type LoopOutcome = 
+/** `budget`: a sub-agent run stopped at its parent run's token cap (phase C). */
+{
+    kind: "completed" | "max_steps" | "max_duration" | "budget";
+    consumedUpToSeq: number;
+} | {
+    kind: "aborted";
+}
+/** 停机：已在步骤边界保存好进度，任务需要回到队列。 */
+ | {
+    kind: "interrupted";
+}
+/** 等待人处理：checkpoint 停在 tools 节点之前，处理后从这里续跑。 */
+ | {
+    kind: "suspended";
+    waitingFor: WaitingFor;
+};
+export interface AgentLoop {
+    run(ctx: LoopContext): Promise<LoopOutcome>;
+}

package/dist/runtime/loop.js

@@ -0,0 +1,7 @@
+/**
+ * Idempotency key of a parent's `subagent_waiting` event: one per child run and wait (an approval
+ * or question id, or `connect-<callId>` for a connect card).
+ */
+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}`;

package/dist/runtime/maintenance.d.ts

@@ -0,0 +1,80 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type Job, type JobsOptions } from "bullmq";
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * 内核维护队列（不含 `:`）：等待超时任务（`wait-timeout`，见 waits.ts）与周期性维护（输出存档清理、
+ * 工具漂移检测（见 tools/drift.ts）、等待兜底扫描（`wait-sweep`，见 waits.ts）、沙箱的空闲休眠与不活跃销毁
+ * （见 sandbox/lifecycle.ts）等）。整个队列只有一个 Worker（只在 `worker` 角色上启动），
+ * 按任务名分派给登记的处理函数。
+ * 与运行队列分开：运行 worker 的处理函数、stalled / 失败处理都按「一个任务 = 一次运行」设计；
+ * 维护任务短、无会话锁与配额。
+ */
+export declare const MAINTENANCE_QUEUE_NAME = "cap-kernel-maintenance";
+/** 输出存档清理：任务名、job scheduler id（不含 `:`）、周期与每批删除行数。 */
+export declare const OUTPUT_CLEANUP_JOB = "output-cleanup";
+export declare const OUTPUT_CLEANUP_SCHEDULER_ID = "output-cleanup-hourly";
+export declare const OUTPUT_CLEANUP_EVERY_MS = 3600000;
+export declare const OUTPUT_CLEANUP_BATCH = 1000;
+/**
+ * Periodic marketplace refresh (C26): job name and job scheduler id (no `:`), every
+ * `marketplaces.refreshIntervalMinutes`. One scheduler for all replicas; the handler refreshes each
+ * enabled marketplace in turn (see catalog/marketplaces.service.ts). The values keep their old
+ * names: the scheduler id is stored in Redis, and renaming it would leave the old scheduler behind.
+ */
+export declare const MARKETPLACES_REFRESH_JOB = "catalogs-refresh";
+export declare const MARKETPLACES_REFRESH_SCHEDULER_ID = "catalogs-refresh-every";
+/**
+ * Cleanup of plugin (app bundle) import staging (T25, F-AE): job name and job scheduler id (no
+ * `:`), hourly; deletes expired (24-hour) staging rows and their object storage prefixes (see
+ * catalog/plugin-import.ts `PluginImport.cleanupExpired`). The values keep their old names: the
+ * scheduler id is stored in Redis, so renaming it would leave the old scheduler behind.
+ */
+export declare const PLUGIN_STAGING_CLEANUP_JOB = "app-staging-cleanup";
+export declare const PLUGIN_STAGING_CLEANUP_SCHEDULER_ID = "app-staging-cleanup-hourly";
+export declare const PLUGIN_STAGING_CLEANUP_EVERY_MS = 3600000;
+/** 维护任务的处理函数（`token` 供 `moveToDelayed` 等使用）。 */
+export type MaintenanceHandler = (job: Job, token: string | undefined) => Promise<void>;
+/** 由其他模块登记的周期任务（如漂移检测）：scheduler id 与任务名不含 `:`，周期在登记时读取。 */
+export interface MaintenanceSchedule {
+    id: string;
+    name: string;
+    everyMs: () => number;
+}
+/**
+ * 删除已过期（`expires_at < now()`）的输出存档，每批 `batch` 行，直到删完；返回删除的总行数。
+ * 每批一条独立语句（不开长事务）；多个 worker 同时清理时 `SKIP LOCKED` 互不等待。
+ */
+export declare function deleteExpiredOutputs(db: KernelDb, batch?: number): Promise<number>;
+export interface MaintenanceDeps {
+    db: KernelDb;
+    redisUrl: string;
+    log: Pick<Logger, "error" | "warn" | "info">;
+}
+/**
+ * 维护队列的生产方与（worker 角色上的）唯一 Worker。状态都在 Redis / PG，没有进程内定时器：
+ * 周期任务用 BullMQ job scheduler（`upsertJobScheduler` 幂等，多副本重复调用只有一个 scheduler）。
+ */
+export declare class Maintenance {
+    private readonly d;
+    private queue;
+    private queueConn;
+    private worker;
+    private workerConn;
+    private closed;
+    private readonly handlers;
+    private readonly schedules;
+    constructor(d: MaintenanceDeps);
+    /** 登记某个任务名的处理函数（构造期调用；Worker 启动前后都可）。 */
+    handle(name: string, fn: MaintenanceHandler): void;
+    /** 登记一个周期任务（构造期调用；`ensureSchedules` 时一并 upsert）。 */
+    schedule(s: MaintenanceSchedule): void;
+    /** 投递一个维护任务。 */
+    add(name: string, data: unknown, opts: JobsOptions): Promise<void>;
+    /** 登记周期任务的 job scheduler（幂等；worker 角色启动时调用）。 */
+    ensureSchedules(): Promise<void>;
+    /** 启动维护队列的 Worker（只在含 `worker` 角色的进程）。 */
+    startWorker(): void;
+    close(): Promise<void>;
+    private getQueue;
+    private process;
+}