@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.24

package/dist/runtime/waits.d.ts

@@ -1,14 +1,12 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import { type OnApplicationShutdown } from "@nestjs/common";
-import { type Job, type Queue } from "bullmq";
+import { type Job } 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";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
-import { LockService } from "../infra/lock/lock.service.js";
-import type { KernelLogger } from "../log.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { ApprovalsService } from "../tools/approvals.service.js";
 import { ToolPipeline } from "../tools/pipeline.js";
 import { QuestionsService } from "../tools/questions.service.js";
@@ -17,6 +15,7 @@ import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { type WaitingFor } from "./loop.js";
 import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
 import { RunFinish } from "./run-finish.js";
+import { RunResume, resumeJobId } from "./run-jobs.js";
 import { RunQueue } from "./run-queue.js";
 import { SubagentDeliveries } from "./subagents/deliveries.js";
 /** 等待超时任务所在的内核维护队列（见 maintenance.ts）。 */
@@ -24,50 +23,8 @@ export { MAINTENANCE_QUEUE_NAME };
 /** 等待超时任务的名字与 jobId（每个审批 / 输入请求一个，重复投递被 BullMQ 忽略）。 */
 export declare const WAIT_TIMEOUT_JOB = "wait-timeout";
 export declare const waitTimeoutJobId: (waitId: string) => string;
-/** 续跑任务的 jobId：与按消息生成的 `run-<conversationId>-<seq>` 不冲突，同一等待只会续跑一次。 */
-export declare const resumeJobId: (conversationId: string, waitId: string) => string;
-/**
- * 等待兜底扫描（Task 22）：任务名、job scheduler id（不含 `:`）、周期、宽限期与每类每次最多处理的条数。
- * 宽限期：waiting 超过它、等待却已全部处理的运行才视为「续跑丢失」，避免与正常续跑（暂停后的复查等）竞争。
- */
-export declare const WAIT_SWEEP_JOB = "wait-sweep";
-/** The maintenance scheduler the sweep ran on before it became a `@LockedCron` (retired). */
-export { WAIT_SWEEP_SCHEDULER_ID } from "./job-ids.js";
-export declare const WAIT_SWEEP_GRACE_MS = 60000;
-export declare const WAIT_SWEEP_BATCH = 500;
-/** 一次扫描（本副本）实际生效的修复数。 */
-export interface WaitSweepResult {
-    /** 过期仍 pending、被本次扫描按超时处理的审批 / 输入请求。 */
-    expired: number;
-    /** 等待已全部处理、被本次扫描续跑的 waiting 运行。 */
-    resumed: number;
-    /** 运行已终态、被本次扫描取消的审批 / 输入请求。 */
-    cancelled: number;
-    /**
-     * 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 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;
-}
+/** A resumed run's job id (`run-<conversationId>-resume-<waitId>`; `RunResume` owes it). */
+export { resumeJobId };
 /** The data of a wait timeout job; `subagents` waits also carry their run and step. */
 export interface WaitTimeoutData {
     kind: WaitingFor["kind"];
@@ -76,18 +33,22 @@ export interface WaitTimeoutData {
     step?: number;
 }
 /**
- * 运行等待人处理（spec 4.4 / Task 9）：暂停、续跑、超时与中止。状态全部在 PG（`runs.status = 'waiting'`、
- * `approvals` / `questions` 行），延迟与重试走 BullMQ（维护队列的 `wait-timeout` 任务），没有进程内状态。
+ * Runs waiting for a person (spec 4.4 / Task 9): suspend, resume, timeout and stop. All state is in
+ * PG (`runs.status = 'waiting'`, the `approvals` / `questions` rows); delays and retries are BullMQ
+ * jobs (the maintenance queue's `wait-timeout`) owed through the outbox; no in-process state.
  *
- * 只续跑一次：`resume` 是一条条件更新 `waiting → queued`（且该运行已没有 pending 的等待），并发调用只有一个成功，
- * 成功者投递 jobId 为 `run-<conversationId>-resume-<waitId>` 的运行任务。人工决定、超时任务、
- * 暂停后的复查都可能调用它，谁先谁后都只有一次续跑。
+ * One resume only: a resume locks the run row and moves it `waiting → queued` only when it waits on
+ * nothing else, owing the run job `run-<conversationId>-resume-<waitId>` in the same transaction
+ * (transactional outbox spec §6). A decision does it in its own transaction
+ * (`RunResume.resumeIn`); the timeout job, the suspend's re-check and a fork child's finish
+ * through {@link resume}. Whichever comes first, the run resumes once.
  */
 export declare class Waits implements OnApplicationShutdown {
     private readonly kdb;
     private readonly eventLog;
     private readonly approvals;
     private readonly questions;
+    /** Stops a queued or running sub-agent no worker holds directly ({@link stopRun}). */
     private readonly runQueue;
     /**
      * Writes, in the caller's transaction, the results of a stopped run's open `Agent` calls;
@@ -103,9 +64,10 @@ export declare class Waits implements OnApplicationShutdown {
      * `waiting` is set. Children are stopped through `request`.
      */
     private readonly abort;
-    /** The maintenance queue: wait timeout jobs (`MaintenanceProcessor` consumes them). */
-    private readonly timeouts;
-    private readonly events;
+    /** Owes the wait timeout jobs (`MaintenanceProcessor` consumes them) with the suspend. */
+    private readonly outbox;
+    /** The resume of a waiting run, in the caller's transaction ({@link resume}). */
+    private readonly resumes;
     private readonly log;
     /** Stops a finished sub-agent run's background tasks ({@link childFinished}). */
     private readonly background;
@@ -114,7 +76,9 @@ export declare class Waits implements OnApplicationShutdown {
     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" | "ensureRun">, 
+    constructor(kdb: KernelDb, eventLog: EventLog, approvals: Pick<ApprovalsService, "expire" | "cancelPendingIn">, questions: Pick<QuestionsService, "expire" | "cancelPendingIn">, 
+    /** Stops a queued or running sub-agent no worker holds directly ({@link stopRun}). */
+    runQueue: Pick<RunQueue, "abortIfOrphaned">, 
     /**
      * Writes, in the caller's transaction, the results of a stopped run's open `Agent` calls;
      * `fire` runs their observe hooks after the commit.
@@ -128,8 +92,10 @@ export declare class Waits implements OnApplicationShutdown {
      * `waiting` is set. Children are stopped through `request`.
      */
     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">, 
+    /** Owes the wait timeout jobs (`MaintenanceProcessor` consumes them) with the suspend. */
+    outbox: Pick<OutboxService, "add">, 
+    /** The resume of a waiting run, in the caller's transaction ({@link resume}). */
+    resumes: Pick<RunResume, "resumeIn">, 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}). */
@@ -139,21 +105,22 @@ export declare class Waits implements OnApplicationShutdown {
     /** The context's handle (the transaction of a `@Transactional` method, else the pool). */
     private get db();
     /**
-     * 兜底扫描（维护队列每 10 分钟一次，防延迟任务 / 续跑丢失）。每项修复都复用常规路径，与并发的超时任务、
-     * 人工决定、其他副本的扫描竞争时由行锁与条件更新保证只生效一次；每项生效的修复记一行 warn（只含 id）。
-     * 顺序：先取消终态运行的等待（这些不该再按超时处理），再处理过期的等待，最后续跑「续跑丢失」的运行。
-     * 单项失败只记日志，不影响其他项。
+     * After the loop returned `suspended` (the worker released the conversation lock and the quota):
+     * in one transaction the conditional `running → waiting` (recording `waiting_since`) and the
+     * wait's timeout job (`runAt` = `expiresAt`); then a re-check whether the wait is already
+     * settled: a decision that came while the run was still `running` did not resume it, so the
+     * re-check does.
+     * A run no longer running (ended by another path) → nothing.
+     * A stop received while suspending (`abort`), or found in the stop marker after `waiting` is set
+     * → the wait is cancelled and the run ended as {@link abortWaiting} does (a stop arriving after
+     * `waiting` is set is handled by `POST .../abort`, which sees `waiting`; neither side misses it).
      */
-    sweep(): Promise<WaitSweepResult>;
+    suspend(runId: string, conversationId: string, waitingFor: WaitingFor, abort?: RunAbortBy): Promise<void>;
     /**
-     * loop 返回 `suspended` 之后（worker 已释放会话锁与配额）：条件更新 `running → waiting`（记 `waiting_since`），
-     * 投递延迟到 `expiresAt` 的超时任务，再复查一次等待是否已被处理——处理者的 `resume` 可能发生在本次置 waiting
-     * 之前（那时条件更新不成立），复查保证这种情况下仍会续跑。
-     * 运行已不是 running（例如已被其他路径结束）→ 什么都不做。
-     * 暂停时已收到用户中止（`abort`），或置 waiting 之后补查到中止标记 → 直接按 {@link abortWaiting} 取消等待并结束
-     * 运行（置 waiting 之后到达的中止由 `POST .../abort` 看到 waiting 直接处理，两边不会都漏掉）。
+     * {@link suspend}'s transaction: the conditional `running → waiting` and the wait's timeout job
+     * owed with it ({@link oweTimeout}). False when the run was no longer running (nothing written).
      */
-    suspend(runId: string, conversationId: string, waitingFor: WaitingFor, abort?: RunAbortBy): Promise<void>;
+    private suspendIn;
     /**
      * A sub-agent's run waits for an approval or an input (sub-agents spec §9): appends
      * `subagent_waiting` to the **root** conversation of its tree, whatever its depth (agent map spec
@@ -165,9 +132,9 @@ export declare class Waits implements OnApplicationShutdown {
      */
     private surfaceInRoot;
     /**
-     * 续跑：一条条件更新 `waiting → queued`（且该运行没有 pending 的审批 / 输入请求），把本次等待时长累加进
-     * `waited_ms`，记下续跑任务的 jobId；成功（只有一个调用方）则投递运行任务并返回 true。
-     * 投递失败 → 撤回为 waiting（等待时长已计入，重新从现在起计），之后超时任务到点会再次续跑，并抛出。
+     * Resumes the run in its own transaction (`RunResume.resumeIn`: locks the run row and, when it
+     * is `waiting` on nothing else, sets it `queued` and owes its resume job); true when this call
+     * queued it. The wait timeout, the suspend's re-check and a fork child's finish use it; the decisions call `RunResume.resumeIn` in their own transactions.
      */
     resume(runId: string, waitId: string): Promise<boolean>;
     /**
@@ -191,103 +158,16 @@ export declare class Waits implements OnApplicationShutdown {
     abortWaiting(conversationId: string, runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<boolean>;
     /** {@link abortWaiting}'s transaction; the open `Agent` calls it wrote go back through `st`. */
     private abortWaitingIn;
-    /** 扫描 3：运行已终态（如暂停途中失败）仍 pending 的审批 / 输入请求 → 取消（写决定 / 回答事件）。 */
-    private sweepFinishedRuns;
-    /**
-     * 同一事务里锁会话行与运行行（与 {@link abortWaiting} 同序），运行仍是终态时取消其 pending 等待；
-     * 提交后发布事件。返回取消的条数（并发的另一副本拿到锁时已无 pending → 0）。
-     */
-    private cancelWaitsOfFinished;
-    private cancelWaitsOfFinishedIn;
-    /** 扫描 1：`expires_at < now()` 仍 pending 的审批 / 输入请求 → 与超时任务同一路径（置 expired、写事件、续跑）。 */
-    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 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;
-    /**
-     * Sub-agent runs nobody will run (spec §7.5; `RunQueue.repairOrphan`, the same orphan test as
-     * `ensureRun`, which never runs for a child): `queued` past the grace period without a job → enqueued
-     * again (the dispatch committed, its enqueue was lost); `running` without job and lock → failed
-     * `run.orphaned` and reported to the parent, which then resumes. Also a chat run left `queued`
-     * by a resume whose enqueue was lost (final review m8): enqueued again under its resume job id
-     * (`ensureRun` would only repair it at the conversation's next message).
-     */
-    private sweepSubagentOrphans;
-    /**
-     * 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 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 sweepUndelivered;
-    /**
-     * 扫描 2：waiting 超过宽限期、却已没有 pending 等待的运行（决定提交后进程崩溃、续跑投递失败回滚等）→
-     * {@link resume}（条件更新 `waiting → queued` + 投递）。续跑任务的 jobId 用该运行最近一次等待的 id
-     * （与人工决定 / 超时任务一致，已投递过的同一续跑被 BullMQ 去重）。
-     */
-    private sweepStuckRuns;
-    /**
-     * 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;
     /**
      * A `wait-timeout` job (dispatched by `MaintenanceProcessor`): expires the wait,
      * or delays the job again until the wait's expiry when it ran early.
      */
     processTimeout(job: Job<WaitTimeoutData>, token: string | undefined): Promise<void>;
-    /** 投递超时任务（延迟到 expiresAt）。失败只记日志：人工处理仍可续跑，只是不会自动超时。 */
-    private scheduleTimeout;
+    /**
+     * Owes the wait's timeout job (`wait-timeout-<waitId>`, `runAt` = the wait's deadline) in the
+     * suspend's transaction (transactional outbox spec §6 "Resumes and timeouts").
+     */
+    private oweTimeout;
     /**
      * Whether the wait is over: an approval or input request is no longer pending (decided, expired
      * or cancelled); `subagents`: the run's fork invocation child is no longer active.
@@ -309,7 +189,8 @@ export declare class Waits implements OnApplicationShutdown {
      * `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
+     * between is repaired by the `deliver-to-parent` job its terminal transaction owed (the
+     * `run-orphan-check` calls this too). 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
@@ -377,34 +258,3 @@ export declare class Waits implements OnApplicationShutdown {
      */
     private stopRun;
 }
-/**
- * Phase D: finished chat runs (past the grace period, within the last day) triggered by a fork
- * invocation that has no report (dispatched or not); the wait sweep writes it
- * (`pairStoppedForks`).
- */
-export declare function unreportedForkRuns(db: KernelSchemaDb): Promise<{
-    parent_run_id: string;
-    parent_conversation_id: string;
-}[]>;
-/**
- * A decided approval / answered question resumes the waiting run on this replica (domain events,
- * spec §3b; the wait sweep resumes a run whose resume was lost). Its IM delivery follows the same
- * events (`ChannelJobs`).
- */
-export declare class DecisionResumer implements OnApplicationShutdown {
-    private readonly unsubscribe;
-    constructor(waits: Pick<Waits, "resume">, events: Pick<KernelEvents, "on">);
-    /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
-    onApplicationShutdown(): void;
-}
-/**
- * The wait sweep, every 10 minutes, once across replicas: {@link Waits.sweep}. Replaces
- * the maintenance scheduler `wait-sweep-every-10m` (retired at worker start).
- */
-export declare class WaitSweepJob {
-    private readonly waits;
-    readonly lockService: LockService;
-    readonly log: KernelLogger;
-    constructor(waits: Pick<Waits, "sweep">, lockService: LockService, log: KernelLogger);
-    run(): Promise<void>;
-}