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

package/dist/runtime/run-queue.d.ts

@@ -1,18 +1,21 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { Queue } from "bullmq";
 import { EventLog } from "../conversations/event-log.js";
-import type { ConversationKind } from "../db/kernel-schema.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.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 { ToolPipeline } from "../tools/pipeline.js";
 import type { RunAbortDetail } from "./abort.js";
 import { KyselyCheckpointSaver } from "./checkpointer.js";
 import { ConversationLock } from "./conversation-lock.js";
 import { RunFinish } from "./run-finish.js";
-import { type RunJobData, RunJobs } from "./run-jobs.js";
-export { ACTIVE_RUN_STATUSES, RUN_QUEUE_NAME, type RunJobData, runJobId, runQueueNameFor, SUBAGENT_RUN_QUEUE_NAME, } from "./run-jobs.js";
+import { RunJobs } from "./run-jobs.js";
+export { ACTIVE_RUN_STATUSES, ENSURE_RUN_BACKSTOP_MS, ENSURE_RUN_JOB, type EnsureRunJobData, ensureRunJobId, RUN_QUEUE_NAME, type RunJobData, runJobId, runQueueNameFor, SUBAGENT_RUN_QUEUE_NAME, } from "./run-jobs.js";
+/**
+ * Test seam (`KernelOverride`): returns true to make {@link RunQueue.ensureRun} throw before it
+ * does anything (Redis unreachable, or a direct call after a commit that never happened). The
+ * kernel never provides it.
+ */
+export declare const ENSURE_RUN_FAILS: unique symbol;
 /**
  * 运行队列（生产方）：`ensureRun` 在会话有未消费的用户消息、且没有进行中的运行时插入 `runs` 行并投递任务。
  * 「是否已有运行」以 PG 为准（会话行锁内检查 `runs` 中的 queued / running），并参考会话锁的持有者；
@@ -24,32 +27,25 @@ export declare class RunQueue {
     private readonly lock;
     private readonly jobs;
     private readonly finisher;
-    /** 运行以孤儿结束（标记失败 / 直接中止）后删除它的 checkpoint thread（thread_id = runId）。 */
+    /** An orphan aborted directly loses its checkpoint thread (thread_id = runId). */
     private readonly checkpoints;
-    /** The run's open `Agent` call results, in the orphan repair's transaction (sub-agents spec §12). */
-    private readonly pipeline;
-    private readonly events;
     private readonly log;
     readonly txHost: TransactionHost;
     private readonly config;
     /** The producer side of the delayed `bg-wake` job (`MaintenanceProcessor` consumes it). */
     private readonly maintenance;
+    private readonly ensureFails;
     constructor(kdb: KernelDb, eventLog: EventLog, lock: Pick<ConversationLock, "holder">, jobs: RunJobs, finisher: Pick<RunFinish, "finishIn">, 
-    /** 运行以孤儿结束（标记失败 / 直接中止）后删除它的 checkpoint thread（thread_id = runId）。 */
-    checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, 
-    /** The run's open `Agent` call results, in the orphan repair's transaction (sub-agents spec §12). */
-    pipeline: Pick<ToolPipeline, "stopOpenAgentCalls">, events: KernelEvents, log: Pick<Logger, "error" | "warn">, txHost: TransactionHost, config: KernelConfigService, 
+    /** An orphan aborted directly loses its checkpoint thread (thread_id = runId). */
+    checkpoints: Pick<KyselyCheckpointSaver, "deleteThread">, log: Pick<Logger, "error" | "warn">, txHost: TransactionHost, config: KernelConfigService, 
     /** The producer side of the delayed `bg-wake` job (`MaintenanceProcessor` consumes it). */
-    maintenance: Pick<Queue, "add">);
+    maintenance: Pick<Queue, "add">, ensureFails?: () => boolean);
     private get db();
-    /**
-     * The `beforeTerminal` of an orphan repair: writes the run's open `Agent` call results in the
-     * repair's transaction; `fire()` runs their observe hooks after the commit (review m1).
-     */
-    private stopOpenCalls;
     /**
      * 有未消费的用户消息（最新 user_message 的 seq > `consumed_seq`）、会话锁无人持有、
-     * 且没有 queued / running / waiting 的运行时：插入 `runs`（queued）并投递任务，返回 runId；否则返回 null。
+     * 且没有 queued / running / waiting 的运行时：插入 `runs`（queued），返回 runId；否则返回 null。
+     * The run's job is owed in the same transaction (transactional outbox spec §6): the outbox
+     * delivers it after the commit, so a queued run never lacks its job.
      *
      * The boundary (`trigger_seq`) is that newest message; with none unconsumed, the queue's head
      * once it is sent; with no head either, a wake-eligible finished background task or sub-agent
@@ -58,13 +54,11 @@ export declare class RunQueue {
      * event inside the wake window schedules the delayed `bg-wake` job instead. A sub-agent's
      * conversation is only woken this way ({@link childWakeIn}).
      *
-     * 孤儿清理（R29，按需进行，没有定时器）：已有的 queued / running 运行若 BullMQ 任务已不存在、
-     * 会话锁也无人持有（queued 的还要超过宽限期），说明没有任何 worker 会再执行它——写
-     * `run_failed { code: "run.orphaned" }` 把它标记为失败（consumed_seq 推进到它的触发消息），
-     * 再按常规判断是否起新一轮，并删除它的 checkpoint thread。会话因此不会永远卡在「有运行」。
-     * 除了写入消息后，打开 SSE、读事件、运行结束后也会调用它（幂等），孤儿因此在有人查看时就被清理。
+     * An active run (queued, running or waiting) is left alone: a run nobody runs any more is the
+     * `run-orphan-check`'s to repair (transactional outbox spec §6), never this call's, and reads
+     * never call it.
      *
-     * agent 已软删除的会话不起新运行（孤儿清理照常进行）。
+     * A conversation whose agent is soft-deleted starts no run.
      */
     ensureRun(conversationId: string, 
     /** From the `bg-wake` job: it fired `wakeRetry - 1` times before its window ended. */
@@ -73,6 +67,20 @@ export declare class RunQueue {
     }): Promise<string | null>;
     /** {@link ensureRun}'s transaction: what it decided goes back through `st`. */
     private ensureRunIn;
+    /**
+     * The job id of a new run for `seq` (in {@link ensureRunIn}'s transaction, read from PG only):
+     * the trigger's `runJobId` for its first run; a later run of the same trigger (a run that hit its
+     * deadline leaves the messages it did not absorb unconsumed, R34) gets `<runJobId>-<n>`,
+     * recorded in `runs.job_id`, so its job is never taken for the earlier run's (BullMQ ignores an
+     * add under the id of a job it still holds).
+     */
+    private jobIdFor;
+    /**
+     * Owes the new run's job in {@link ensureRunIn}'s transaction, before its run row is written.
+     * False (logged): the same job id is still owed, so the caller writes no run (a second run of
+     * one trigger; the conversation's unique active run makes this a should-not-happen).
+     */
+    private oweJob;
     /**
      * {@link ensureRunIn} for a sub-agent's conversation (agent map spec §5.3), under its row lock.
      * Its runs from a task, or from a message to an idle sub-agent, are started by the dispatch
@@ -84,8 +92,7 @@ export declare class RunQueue {
      * started again only by its parent. Both read the queue and the trigger account's access on the root
      * of its tree; a message needs no wake setting and has no wake window. The run counts against
      * the root's budget window and runs on the sub-agent queue under `runJobId(child, boundary
-     * seq)`. An active run is left to the orphan repair after the commit (`repairRunId`), never
-     * started past.
+     * seq)`. An active run is never started past (one nobody runs is the `run-orphan-check`'s).
      */
     private childWakeIn;
     /**
@@ -101,10 +108,24 @@ export declare class RunQueue {
      * Re-derives the wakes a paused root held for its tree (agent map spec §5.3: a paused root queue
      * holds the wakes of the whole tree): after the root's queue is unpaused, {@link ensureRun} on
      * every sub-agent conversation below it that has an unconsumed wake event or message and no
-     * active run (the root itself is the caller's own `ensureRun`). Errors are logged; the next
-     * event, run end or page opening of that conversation re-derives its wake.
+     * active run (the root itself is the caller's own `ensureRun`). Errors are logged; the
+     * ensure-run backstop the releasing transaction owed ({@link oweHeldTreeIn}) wakes it later.
      */
     wakeHeldTree(rootId: string): Promise<void>;
+    /**
+     * Owes, in the caller's transaction (the one that unpauses the root's queue or sends its item
+     * now), the ensure-run backstop of every sub-agent {@link wakeHeldTree} would wake after the
+     * commit, under the sub-agent's newest seq (transactional outbox spec §6): a process that dies
+     * before that call leaves no held wake behind. A root whose queue is still paused (or that is
+     * deleted) releases nothing and owes nothing.
+     */
+    oweHeldTreeIn(rootId: string): Promise<void>;
+    /**
+     * The sub-agent conversations below `rootId` a paused root holds: not deleted, with an
+     * unconsumed wake event (a finished background task, a delivery) or message, and no active run;
+     * with their org and newest seq. Reads only (no row locks).
+     */
+    private heldTree;
     /**
      * Schedules the delayed `bg-wake` job at the end of the conversation's wake window (after the
      * commit): one job per conversation and window end, so finishes inside one window share it. It
@@ -113,41 +134,29 @@ export declare class RunQueue {
      */
     private scheduleWake;
     /**
-     * Enqueues a run job under the caller's job id (resumes, dispatches, repairs), with the same
-     * options as {@link ensureRun} (see {@link RunJobs.enqueue}).
+     * Owes the ensure-run backstop of `conversationId` in the caller's transaction
+     * ({@link oweEnsureRun}): `seq` is the event the transaction wrote, `orgId` the conversation's.
      */
-    enqueue(data: RunJobData, jobId: string, kind?: ConversationKind): Promise<void>;
+    oweEnsureRun(conversationId: string, seq: number | string, orgId: string): Promise<boolean>;
     /**
-     * 中止一个孤儿运行（`POST .../abort` 用）：运行仍是 queued / running、会话锁无人持有、BullMQ 任务已不存在
-     * （queued 的还要超过宽限期，判定同 {@link ensureRun} 的孤儿清理）时，没有任何 worker 会收到中止广播——
-     * 直接写 `run_aborted`、status 置为 aborted、consumed_seq 至少推进到触发消息，返回 true。
-     * 不是孤儿（有人在执行或即将执行）或运行已结束 → 返回 false，由调用方走广播中止。
+     * Stops an orphaned run directly (`POST .../abort`, a tree stop): a `running` run whose
+     * conversation lock is free and whose BullMQ job is gone hears no stop broadcast, so its
+     * `run_aborted` is written here (status aborted, `consumed_seq` at least to its trigger): true. Not
+     * an orphan (someone runs it; a queued run's job is owed, or lost and re-added by the
+     * `run-orphan-check`, whose worker then sees the stop marker) or already finished: false, and the
+     * caller broadcasts the stop.
      */
     abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null, detail?: RunAbortDetail): Promise<boolean>;
     private abortOrphanIn;
-    /**
-     * Repairs an orphaned run of a conversation nobody else repairs on demand (a sub-agent's: no
-     * `ensureRun` ever runs for it; sub-agents spec §7.5), with the same orphan test as
-     * {@link ensureRun}: the conversation lock is free, the run is still `queued` / `running`, its
-     * job is gone, and a `queued` one is past the grace period.
-     * - `queued` (the dispatch or resume committed, its enqueue was lost) → enqueued again under its
-     *   own job id (`runs.job_id`, else the trigger's), so concurrent repairs on several replicas
-     *   still leave one job: `"requeued"`;
-     * - `running` (its worker died without a terminal state and BullMQ dropped the job) → marked
-     *   failed `run.orphaned`; the caller reports it to the parent: `"failed"`.
-     * Not an orphan, or already finished → null.
-     */
-    repairOrphan(conversationId: string, runId: string): Promise<"requeued" | "failed" | null>;
-    private repairOrphanIn;
     /** 会话当前未结束的运行（调用方已持有会话行锁）。 */
     private activeRun;
     /**
-     * 未结束的运行是否已是孤儿（调用方已确认会话锁无人持有）：waiting → 否（等人处理，本来就没有任务，
-     * 由人工决定或超时任务续跑）；queued 且仍在宽限期内 → 否（任务可能还没投递）；BullMQ 任务（续跑任务按
-     * `runs.job_id`）仍存在 → 否；否则是。
+     * Whether an active run is an orphan for {@link abortIfOrphaned} (the caller saw the conversation
+     * lock free): a `running` one whose BullMQ job (a resume's under `runs.job_id`) is gone. A
+     * `waiting` one never is (no job by design), nor a `queued` one (its job is owed in the
+     * transaction that queued it).
      */
     private isOrphan;
     /** 删除已结束运行的 checkpoint thread（失败只记日志）。 */
     private dropCheckpoints;
-    private deleteQueued;
 }