@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

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";

package/dist/runtime/maintenance.d.ts

@@ -1,80 +1,56 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Job, type JobsOptions } from "bullmq";
-import type { KernelDb } from "../db/kernel-schema.js";
+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;
 /**
- * 内核维护队列（不含 `:`）：等待超时任务（`wait-timeout`，见 waits.ts）与周期性维护（输出存档清理、
- * 工具漂移检测（见 tools/drift.ts）、等待兜底扫描（`wait-sweep`，见 waits.ts）、沙箱的空闲休眠与不活跃销毁
- * （见 sandbox/lifecycle.ts）等）。整个队列只有一个 Worker（只在 `worker` 角色上启动），
- * 按任务名分派给登记的处理函数。
- * 与运行队列分开：运行 worker 的处理函数、stalled / 失败处理都按「一个任务 = 一次运行」设计；
- * 维护任务短、无会话锁与配额。
+ * 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` 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
+ * name is warned and completes. The producers are the domains' own (same names, ids and options).
  */
-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">;
+export declare class MaintenanceProcessor extends WorkerHost<Worker> {
+    private readonly waits;
+    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, "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
+     * worker role starts.
+     */
+    removeRetiredSchedulers(): Promise<void>;
+    process(job: Job, token?: string): Promise<void>;
+    /** Starts consuming (worker role, after the extensions loaded; built with `autorun: false`). */
+    start(): void;
+    private dispatch;
+    failed(job: Job | undefined, err: Error): void;
+    error(err: Error): void;
 }
 /**
- * 维护队列的生产方与（worker 角色上的）唯一 Worker。状态都在 Redis / PG，没有进程内定时器：
- * 周期任务用 BullMQ job scheduler（`upsertJobScheduler` 幂等，多副本重复调用只有一个 scheduler）。
+ * The maintenance queue's consumer: {@link MaintenanceProcessor}. Imported only by the worker role
+ * (`WorkerModule`), so other roles get no processor and no BullMQ worker. It never starts by
+ * itself: the worker role (`WorkerRole`) removes the retired job schedulers and starts it after the
+ * extensions loaded.
  */
-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;
+export declare class MaintenanceModule {
 }