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

package/dist/runtime/waits.d.ts

@@ -1,6 +1,7 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import { type OnApplicationShutdown } from "@nestjs/common";
 import { type Job, type Queue } from "bullmq";
+import { BackgroundTaskStopper } from "../background/stop.js";
 import { EventLog } from "../conversations/event-log.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -17,6 +18,7 @@ import { type WaitingFor } from "./loop.js";
 import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { RunFinish } from "./run-finish.js";
 import { RunQueue } from "./run-queue.js";
+import { SubagentDeliveries } from "./subagents/deliveries.js";
 /** 等待超时任务所在的内核维护队列（见 maintenance.ts）。 */
 export { MAINTENANCE_QUEUE_NAME };
 /** 等待超时任务的名字与 jobId（每个审批 / 输入请求一个，重复投递被 BullMQ 忽略）。 */
@@ -42,16 +44,29 @@ export interface WaitSweepResult {
     /** 运行已终态、被本次扫描取消的审批 / 输入请求。 */
     cancelled: number;
     /**
-     * Finished parent runs whose open `Agent` calls had no `tool_result`, repaired (final review
-     * I3: the next run would send an unpaired tool call, which providers refuse).
+     * Finished runs whose fork invocation had no report, repaired (`pairStoppedForks`; the next run
+     * would build on a fork lead without its report).
      */
     repaired: number;
     /** Queued sub-agent runs, and chat runs queued by a resume, whose job was lost, enqueued again. */
     requeued: number;
     /** Running sub-agent runs without job or lock, failed `run.orphaned` and reported to the parent. */
     orphaned: number;
-    /** Active sub-agent runs of a finished parent run, asked to stop. */
+    /**
+     * Active fork sub-agent runs of a finished parent run, and active sub-agent runs of a deleted
+     * conversation's tree, asked to stop.
+     */
     stopped: number;
+    /**
+     * Finished background sub-agent runs whose `finished` delivery was never written (the finisher
+     * died after the child's terminal commit), delivered (agent map spec §10).
+     */
+    delivered: number;
+    /**
+     * Idle sub-agents with a parked message no run took (a `SendMessage` that reached a run after
+     * its last model call, whose replica died before the post-run `ensureRun`), started again.
+     */
+    restarted: number;
 }
 /** The data of a wait timeout job; `subagents` waits also carry their run and step. */
 export interface WaitTimeoutData {
@@ -90,11 +105,16 @@ export declare class Waits implements OnApplicationShutdown {
     private readonly abort;
     /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
     private readonly timeouts;
+    private readonly events;
     private readonly log;
+    /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
+    private readonly background;
+    /** Delivers a background child's finish to its parent ({@link childFinished}). */
+    private readonly deliveries;
     readonly txHost: TransactionHost;
     /** Drops the `run.orphaned` subscription (the events may outlive this instance). */
     private readonly unsubscribe;
-    constructor(kdb: KernelDb, eventLog: EventLog, approvals: Pick<ApprovalsService, "expire" | "cancelPendingIn">, questions: Pick<QuestionsService, "expire" | "cancelPendingIn">, runQueue: Pick<RunQueue, "enqueue" | "repairOrphan" | "abortIfOrphaned">, 
+    constructor(kdb: KernelDb, eventLog: EventLog, approvals: Pick<ApprovalsService, "expire" | "cancelPendingIn">, questions: Pick<QuestionsService, "expire" | "cancelPendingIn">, runQueue: Pick<RunQueue, "enqueue" | "repairOrphan" | "abortIfOrphaned" | "ensureRun">, 
     /**
      * Writes, in the caller's transaction, the results of a stopped run's open `Agent` calls;
      * `fire` runs their observe hooks after the commit.
@@ -109,7 +129,11 @@ export declare class Waits implements OnApplicationShutdown {
      */
     abort: Pick<RunAbort, "requested" | "request">, 
     /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
-    timeouts: Pick<Queue, "add">, events: KernelEvents, log: Pick<Logger, "error" | "warn">, txHost: TransactionHost);
+    timeouts: Pick<Queue, "add">, events: KernelEvents, log: Pick<Logger, "error" | "warn">, 
+    /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
+    background: Pick<BackgroundTaskStopper, "stopSubagentTasks">, 
+    /** Delivers a background child's finish to its parent ({@link childFinished}). */
+    deliveries: Pick<SubagentDeliveries, "childFinished">, txHost: TransactionHost);
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
     onApplicationShutdown(): void;
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
@@ -132,12 +156,14 @@ export declare class Waits implements OnApplicationShutdown {
     suspend(runId: string, conversationId: string, waitingFor: WaitingFor, abort?: RunAbortBy): Promise<void>;
     /**
      * A sub-agent's run waits for an approval or an input (sub-agents spec §9): appends
-     * `subagent_waiting` to the parent conversation (idem `subagent_waiting:<childRunId>:<waitId>`),
-     * so the web and the channel outbound show the card there. The approval or question itself stays
-     * the child run's, with the parent run's starter as the person asked. Not a run of a sub-agent,
-     * or a `subagents` wait: nothing. Display only: a failure is logged, the wait goes on.
+     * `subagent_waiting` to the **root** conversation of its tree, whatever its depth (agent map spec
+     * §7, {@link rootSurfaceOf}; idem `subagent_waiting:<childRunId>:<waitId>`), so the web and the
+     * channel outbound show the card where the person looks. The approval or question itself stays
+     * the child run's, with the run's trigger account (inherited down the chain) as the person asked.
+     * Not a run of a sub-agent, or a `subagents` wait: nothing. Display only: a failure is logged,
+     * the wait goes on.
      */
-    private surfaceInParent;
+    private surfaceInRoot;
     /**
      * 续跑：一条条件更新 `waiting → queued`（且该运行没有 pending 的审批 / 输入请求），把本次等待时长累加进
      * `waited_ms`，记下续跑任务的 jobId；成功（只有一个调用方）则投递运行任务并返回 true。
@@ -177,9 +203,9 @@ export declare class Waits implements OnApplicationShutdown {
     private sweepOverdue;
     /**
      * Sub-agents waits past their `runs.wait_expires_at` (their timeout job was lost): expired the
-     * way the timeout job would ({@link expire}: the step's active children stop as `timed out`, the
-     * parent resumes once they are done). The step is the run's latest dispatch step: a waiting run
-     * has active children only from the step it waits in. A run stays here until its children have
+     * way the timeout job would ({@link expire}: the fork invocation's active child stops as
+     * `timed out`, the parent resumes once it is done). Only fork invocations wait (agent map spec
+     * §5.4); their step is the run's fork dispatch step. A run stays here until its children have
      * stopped; a pass that neither stopped a child nor resumed the run is not counted.
      */
     private sweepOverdueSubagents;
@@ -193,22 +219,56 @@ export declare class Waits implements OnApplicationShutdown {
      */
     private sweepSubagentOrphans;
     /**
-     * Finished parent runs (past the grace period, within the last day) with an `Agent` call that has
-     * no `tool_result` (final review I3): a terminal path that skipped `stopOpenAgentCalls`, such as
-     * an old replica's abort, would otherwise leave an unpaired tool call that every later request of
-     * the conversation sends and providers refuse. Each is repaired under the conversation row lock
-     * with the normal `stopOpenCalls` (a child that ended gives its result, an active one the
-     * stopped text; idempotency keys make it safe against the regular paths); its active children
-     * are then stopped by {@link sweepChildrenOfFinished}.
+     * Idle sub-agent conversations (no active run, not deleted) with a message newer than what they
+     * consumed, written past the grace period and within the last day: a `SendMessage` that reached a
+     * run after its last model call is started by that run's post-job `ensureRun`
+     * (`RunQueue.childWakeIn`), which a replica dying after the terminal commit skips. Re-derived with
+     * the same `ensureRun` (its rules decide: a paused root starts nothing). A sub-agent whose last
+     * run was stopped (`aborted`) can never start from a message, so it is left out here, and the
+     * newest conversations come first (active within the last day), so parked messages that cannot
+     * start never fill the batch. Returns how many runs started.
+     */
+    private sweepParkedMessages;
+    /**
+     * Finished runs (past the grace period, within the last day) triggered by a fork invocation that
+     * has no report ({@link unreportedForkRuns}): a terminal path that skipped
+     * `stopOpenAgentCalls`, such as an old replica's abort, would otherwise leave a fork lead without
+     * its report. Each is repaired under the conversation row lock with the normal
+     * `stopOpenAgentCalls` (an ended child gives its result, an active one the stopped text;
+     * idempotency keys make it safe against the regular paths); an active fork child is then stopped
+     * by {@link sweepForkChildrenOfFinished}. An `Agent` call has its result from its dispatch (agent
+     * map spec §4.1).
      */
     private sweepOpenAgentCalls;
     /** One run's repair of {@link sweepOpenAgentCalls}; its observe hooks go back through `st`. */
     private repairOpenAgentCallsIn;
     /**
-     * Active sub-agent runs of a parent run that finished more than the grace period ago (spec §7.5,
-     * §12: a parent's terminal state stops its children; this is the backstop) → stopped.
+     * Active fork sub-agent runs (phase D, `for_skill`) of a parent run that finished more than the
+     * grace period ago (§12: the run's terminal state stops its fork child and reports it stopped;
+     * this is the backstop) → stopped. Background `Agent` children of a finished run are the normal
+     * case and keep running (agent map spec §5.4).
+     */
+    private sweepForkChildrenOfFinished;
+    /**
+     * Active sub-agent runs with a deleted ancestor (agent map spec §10: deleting the root stops the
+     * whole tree; the delete's own {@link stopTree} is the normal path, this the backstop for a crash
+     * between marking the root deleted and stopping its tree, or a dispatch that raced it) → stopped
+     * on the deleter's behalf (no account). No grace period: nothing in a deleted tree should run.
+     */
+    private sweepTreesOfDeletedRoots;
+    /**
+     * Background sub-agent runs that finished more than the grace period ago (within the last day)
+     * whose parent has no `subagent_finished` for them (agent map spec §10: the finisher died after
+     * the child's terminal commit; the finish path writes `subagent_finished` and the delivery in one
+     * transaction) → {@link childFinished}, idempotent against a late finisher. Keyed on the child
+     * run, so a run nobody dispatched (a wake run, §5.3) is repaired too, and on
+     * `subagent_finished`, not on the delivery, so a child that finished before background
+     * dispatch (its result was the `Agent` call's, its `subagent_finished` written then) is never
+     * delivered a second time. Fork invocations' runs, a run without a terminal event in its log
+     * (nothing to deliver), a conversation never dispatched and a child whose parent conversation
+     * was deleted are skipped; only a written delivery counts.
      */
-    private sweepChildrenOfFinished;
+    private sweepUndelivered;
     /**
      * 扫描 2：waiting 超过宽限期、却已没有 pending 等待的运行（决定提交后进程崩溃、续跑投递失败回滚等）→
      * {@link resume}（条件更新 `waiting → queued` + 投递）。续跑任务的 jobId 用该运行最近一次等待的 id
@@ -216,8 +276,8 @@ export declare class Waits implements OnApplicationShutdown {
      */
     private sweepStuckRuns;
     /**
-     * The id of the run's latest wait (by creation time): an approval, an input request or a
-     * sub-agent dispatch, whose wait id is its child run id (the id the child's finisher resumes
+     * The id of the run's latest wait (by creation time): an approval, an input request or a fork
+     * invocation's dispatch, whose wait id is its child run id (the id the child's finisher resumes
      * with, so a sweep resume and a late finisher resume share one job id).
      */
     private lastWaitId;
@@ -230,7 +290,7 @@ export declare class Waits implements OnApplicationShutdown {
     private scheduleTimeout;
     /**
      * Whether the wait is over: an approval or input request is no longer pending (decided, expired
-     * or cancelled); `subagents`: no child run of the run is active.
+     * or cancelled); `subagents`: the run's fork invocation child is no longer active.
      */
     private isSettled;
     /** 审批所在的步（`approval_requested` 事件里记的）。 */
@@ -241,18 +301,30 @@ export declare class Waits implements OnApplicationShutdown {
      */
     private stoppedResults;
     /**
-     * After a child run's terminal state committed (sub-agents spec §7.3): appends
-     * `subagent_finished` to the parent log (idempotent; allowed while the parent waits, it is not
-     * model-visible) and tries {@link resume}`(parentRunId, childRunId)`. Every finishing child tries;
-     * the conditional resume lets exactly one succeed, the last to see all its siblings terminal. A
-     * run that is not a dispatched child, or not terminal yet, is left alone. A crash in between is
-     * repaired by the wait sweep and by the parent's tools node, which writes a missing
-     * `subagent_finished` itself.
+     * After a child run's terminal state committed (sub-agents spec §7.3, agent map spec §4.5,
+     * §5.2): a background child's run, whether dispatched, sent a message or woken
+     * ({@link deliveryRowOfChildRun}), is delivered to its parent
+     * ({@link SubagentDeliveries.childFinished}: `subagent_finished` and a `finished` delivery,
+     * idempotent by the run); a fork invocation's child (phase D, `for_skill`) appends
+     * `subagent_finished` (idempotent; not model-visible) and tries
+     * {@link resume}`(parentRunId, childRunId)`, which succeeds once its parent run waits on nothing
+     * else. A run of a conversation never dispatched, or not terminal yet, is left alone. A crash in
+     * between is repaired by the wait sweep (the orphan repair calls this again). A fork child's
+     * running background tasks the terminal run started are then stopped (not those of a later run);
+     * a stopped background child's are all stopped, whichever of its runs started them; a background
+     * child that ended on its own keeps them, and their finish wakes it (agent map spec §5.3). True
+     * when a background child's finish was written by this call.
+     */
+    childFinished(childRunId: string): Promise<boolean>;
+    /**
+     * Whether the conversation has an active run other than `runId`, or one created after it (a
+     * sub-agent started again after `runId` ended).
      */
-    childFinished(childRunId: string): Promise<void>;
+    private hasLaterRun;
     /**
-     * Stops the active children of a parent run (sub-agents spec §12), or only those dispatched in
-     * `opts.step`: a `waiting` child through its own {@link abortWaiting}, a `queued` / `running` one
+     * Stops the active fork invocation child of a parent run (sub-agents spec §12, phase D;
+     * `for_skill`), or only one dispatched in `opts.step`; background `Agent` children are never
+     * stopped with the run that dispatched them (agent map spec §5.4, §6): a `waiting` child through its own {@link abortWaiting}, a `queued` / `running` one
      * that no worker holds directly (`RunQueue.abortIfOrphaned`), any other through
      * `RunAbort.request` (the cross-replica broadcast plus the marker key, so a child that starts
      * later still sees it), after which a child found `waiting` is stopped through `abortWaiting`
@@ -267,6 +339,43 @@ export declare class Waits implements OnApplicationShutdown {
         step?: number;
         detail?: RunAbortDetail;
     }): Promise<number>;
+    /**
+     * Stops a sub-agent with its descendants (agent map spec §6: stopping an agent of the map stops
+     * it and everything below it; deleting the root stops the whole tree): every active run of
+     * `conversationId` (unless `includeSelf` is false) and of each sub-agent conversation below it,
+     * shallowest first, each the way {@link stopChildren} stops a child (a stopped agent delivers its
+     * finish to its own parent as `aborted`). A run a worker holds ends later; its worker's
+     * {@link stopDescendantsOfStopped} stops what it dispatched after this read. Then the running
+     * background tasks of every covered sub-agent conversation stop, whether it was running or idle.
+     * Returns the number of runs asked to stop.
+     *
+     * Lock order: nothing is held across runs. Each run's stop is its own transaction (or none), and
+     * one that writes the terminal state locks that run's conversation row, then its run row, the
+     * order of `StepLog.appendCounted` (conversation row, then the root's budget run row) and of
+     * dispatch (conversation, run, budget run). No stop here locks a budget run, let alone before a
+     * descendant's conversation row, so the order is never inverted.
+     */
+    stopTree(conversationId: string, byAccountId: string | null, opts?: {
+        includeSelf?: boolean;
+    }): Promise<number>;
+    /**
+     * After a sub-agent run's terminal commit (its worker): a run a person stopped (`run_aborted`
+     * with an account and no `detail`; only {@link stopTree} stops a sub-agent's run that way) stops
+     * the active runs below its conversation as well, so a descendant it dispatched after the tree
+     * stop read the tree still stops (dispatch needs its run `running`, so after its terminal commit
+     * the set is final). Any other end leaves its children running (agent map spec §5.4). Returns
+     * the number of runs asked to stop. A root conversation's run never stops its children here.
+     */
+    stopDescendantsOfStopped(runId: string): Promise<number>;
+    /**
+     * Stops one active sub-agent run: a `waiting` one through its own {@link abortWaiting}, a
+     * `queued` / `running` one that no worker holds directly (`RunQueue.abortIfOrphaned`, then
+     * reported through {@link childFinished}), any other through `RunAbort.request` (the
+     * cross-replica broadcast plus the marker key, so a run that starts later still sees it), after
+     * which a run found `waiting` is stopped through `abortWaiting` too. True when it was stopped
+     * while waiting.
+     */
+    private stopRun;
 }
 /**
  * Phase D: finished chat runs (past the grace period, within the last day) triggered by a fork