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

package/dist/runtime/waits.d.ts

@@ -1,15 +1,22 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { EventLog } from "../conversations/event-log.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import type { ApprovalsService } from "../tools/approvals.service.js";
-import type { QuestionsService } from "../tools/questions.service.js";
-import type { RunAbortBy, RunAbortDetail } from "./abort.js";
-import type { KyselyCheckpointSaver } from "./checkpointer.js";
+import { type OnApplicationShutdown } from "@nestjs/common";
+import { type Job, type Queue } from "bullmq";
+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 { ApprovalsService } from "../tools/approvals.service.js";
+import { ToolPipeline } from "../tools/pipeline.js";
+import { QuestionsService } from "../tools/questions.service.js";
+import { RunAbort, type RunAbortBy, type RunAbortDetail } from "./abort.js";
+import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { type WaitingFor } from "./loop.js";
-import { MAINTENANCE_QUEUE_NAME, type Maintenance } from "./maintenance.js";
-import { type RunQueue } from "./run-queue.js";
-type KernelTrx = Transaction<KernelDatabase>;
+import { MAINTENANCE_QUEUE_NAME } from "./maintenance-queue.js";
+import { RunFinish } from "./run-finish.js";
+import { RunQueue } from "./run-queue.js";
 /** 等待超时任务所在的内核维护队列（见 maintenance.ts）。 */
 export { MAINTENANCE_QUEUE_NAME };
 /** 等待超时任务的名字与 jobId（每个审批 / 输入请求一个，重复投递被 BullMQ 忽略）。 */
@@ -22,8 +29,8 @@ export declare const resumeJobId: (conversationId: string, waitId: string) => st
  * 宽限期：waiting 超过它、等待却已全部处理的运行才视为「续跑丢失」，避免与正常续跑（暂停后的复查等）竞争。
  */
 export declare const WAIT_SWEEP_JOB = "wait-sweep";
-export declare const WAIT_SWEEP_SCHEDULER_ID = "wait-sweep-every-10m";
-export declare const WAIT_SWEEP_EVERY_MS = 600000;
+/** 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;
 /** 一次扫描（本副本）实际生效的修复数。 */
@@ -53,46 +60,6 @@ export interface WaitTimeoutData {
     runId?: string;
     step?: number;
 }
-export interface WaitsDeps {
-    db: KernelDb;
-    eventLog: EventLog;
-    approvals: Pick<ApprovalsService, "expire" | "cancelPendingIn">;
-    questions: Pick<QuestionsService, "expire" | "cancelPendingIn">;
-    runQueue: Pick<RunQueue, "enqueue" | "repairOrphan">;
-    /**
-     * Sub-agents (spec §7.5, §12): `stop` stops a parent run's active children (only those of `step`
-     * when given, with `detail` on their `run_aborted`; `stopChildren`), `finished` reports a finished child to its parent
-     * (`onChildFinished`). Wired by the kernel; without it the sweep skips sub-agent repairs.
-     */
-    subagents?: {
-        stop: (parentRunId: string, byAccountId: string | null, opts?: {
-            step?: number;
-            detail?: RunAbortDetail;
-        }) => Promise<number>;
-        finished: (childRunId: string) => Promise<void>;
-        /**
-         * Writes, in `t`, the results of a stopped run's open `agent` calls (`ToolPipeline.
-         * stopOpenAgentCalls`); `fire` runs its observe hooks after the commit.
-         */
-        stopOpenCalls?: (t: KernelTrx, runId: string) => Promise<{
-            steps: number[];
-            callIds: Set<string>;
-            toSeq?: number | null;
-            fire: () => void;
-        }>;
-    };
-    /** 等待中被中止的运行删除其 checkpoint thread。 */
-    checkpoints?: Pick<KyselyCheckpointSaver, "deleteThread">;
-    /**
-     * Reads the run's stop marker (`RunAbort.requested`): between suspending and becoming `waiting`
-     * the run has no subscriber, so a stop arriving then only sits in the marker; checked once after
-     * `waiting` is set.
-     */
-    abortRequested?: (runId: string) => Promise<RunAbortBy | null>;
-    /** 内核维护队列：超时任务投递到这里，处理函数在构造时登记（Worker 由它在 worker 角色上启动）。 */
-    maintenance: Pick<Maintenance, "add" | "handle" | "schedule">;
-    log: Pick<Logger, "error" | "warn">;
-}
 /**
  * 运行等待人处理（spec 4.4 / Task 9）：暂停、续跑、超时与中止。状态全部在 PG（`runs.status = 'waiting'`、
  * `approvals` / `questions` 行），延迟与重试走 BullMQ（维护队列的 `wait-timeout` 任务），没有进程内状态。
@@ -101,9 +68,52 @@ export interface WaitsDeps {
  * 成功者投递 jobId 为 `run-<conversationId>-resume-<waitId>` 的运行任务。人工决定、超时任务、
  * 暂停后的复查都可能调用它，谁先谁后都只有一次续跑。
  */
-export declare class Waits {
-    private readonly d;
-    constructor(d: WaitsDeps);
+export declare class Waits implements OnApplicationShutdown {
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly approvals;
+    private readonly questions;
+    private readonly runQueue;
+    /**
+     * Writes, in the caller's transaction, the results of a stopped run's open `agent` calls;
+     * `fire` runs their observe hooks after the commit.
+     */
+    private readonly pipeline;
+    private readonly finisher;
+    /** 等待中被中止的运行删除其 checkpoint thread。 */
+    private readonly checkpoints;
+    /**
+     * The run's stop marker (`RunAbort.requested`): between suspending and becoming `waiting` the
+     * run has no subscriber, so a stop arriving then only sits in the marker; checked once after
+     * `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 log;
+    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">, 
+    /**
+     * Writes, in the caller's transaction, the results of a stopped run's open `agent` calls;
+     * `fire` runs their observe hooks after the commit.
+     */
+    pipeline: Pick<ToolPipeline, "stopOpenAgentCalls">, finisher: Pick<RunFinish, "finishIn">, 
+    /** 等待中被中止的运行删除其 checkpoint thread。 */
+    checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, 
+    /**
+     * The run's stop marker (`RunAbort.requested`): between suspending and becoming `waiting` the
+     * run has no subscriber, so a stop arriving then only sits in the marker; checked once after
+     * `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">, 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). */
+    private get db();
     /**
      * 兜底扫描（维护队列每 10 分钟一次，防延迟任务 / 续跑丢失）。每项修复都复用常规路径，与并发的超时任务、
      * 人工决定、其他副本的扫描竞争时由行锁与条件更新保证只生效一次；每项生效的修复记一行 warn（只含 id）。
@@ -153,6 +163,8 @@ export declare class Waits {
      * 运行已不是 waiting（例如刚被续跑）→ 返回 false，由调用方走常规中止。
      */
     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;
     /**
@@ -160,6 +172,7 @@ export declare class Waits {
      * 提交后发布事件。返回取消的条数（并发的另一副本拿到锁时已无 pending → 0）。
      */
     private cancelWaitsOfFinished;
+    private cancelWaitsOfFinishedIn;
     /** 扫描 1：`expires_at < now()` 仍 pending 的审批 / 输入请求 → 与超时任务同一路径（置 expired、写事件、续跑）。 */
     private sweepOverdue;
     /**
@@ -189,6 +202,8 @@ export declare class Waits {
      * are then stopped by {@link sweepChildrenOfFinished}.
      */
     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.
@@ -206,7 +221,11 @@ export declare class Waits {
      * with, so a sweep resume and a late finisher resume share one job id).
      */
     private lastWaitId;
-    private process;
+    /**
+     * 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;
     /**
@@ -221,13 +240,62 @@ export declare class Waits {
      * 等待中的调用给取消说明，其余（排在等待调用之后、尚未执行的）给「未执行」说明。
      */
     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.
+     */
+    childFinished(childRunId: string): Promise<void>;
+    /**
+     * 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
+     * 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`
+     * too. A child stopped here is reported to the parent at once (by `abortWaiting` itself, or
+     * {@link childFinished} after `abortIfOrphaned`); one stopped by its worker is reported by that
+     * worker. Returns the number of children asked to stop.
+     *
+     * `byAccountId` is the person whose action stops them, or null when the kernel stops them on the
+     * parent's behalf; a child stopped with null reports the §4.4 "parent's stop" text.
+     */
+    stopChildren(parentRunId: string, byAccountId: string | null, opts?: {
+        step?: number;
+        detail?: RunAbortDetail;
+    }): Promise<number>;
 }
 /**
  * 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: KernelDb): Promise<{
+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>;
+}