@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

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

@@ -0,0 +1,85 @@
+import type { ExtensionContext, Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { EventLog } from "../conversations/event-log.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { type StreamSink } from "./model-call.js";
+/** How long a draft lives without a write (a step that keeps streaming keeps refreshing it). */
+export declare const DRAFT_TTL_SECONDS = 600;
+/** At most one write per step per window, plus the one at the end of the model stream. */
+export declare const DRAFT_FLUSH_MS = 200;
+/** One step's draft: `{ text, thinking }` as JSON (spec 2026-11-07 §3.2). */
+export declare const draftKey: (runId: string, step: number) => string;
+/** What one step of a run has streamed so far. */
+export interface RunDraft {
+    step: number;
+    text: string;
+    thinking: string;
+}
+/** A draft of a conversation's active run (the `event: draft` frame's data). */
+export interface LiveDraft extends RunDraft {
+    runId: string;
+}
+/**
+ * Live drafts (spec 2026-11-07-run-input-and-live-drafts §3.2): what each step of a running run
+ * has streamed so far, kept in Redis so a viewer that (re)connects on any replica gets the text
+ * already shown, then the deltas from there on.
+ *
+ * The writer is the process executing the run: it holds the step's draft in memory (only for the
+ * runs it executes; {@link release} drops them when the execution ends) and writes it at most once
+ * per {@link DRAFT_FLUSH_MS}: on the first delta past the window, or, when deltas stop inside it,
+ * by one trailing one-shot timer per held step (process-local, unref'd, cancelled by a write,
+ * {@link clear} and {@link release}), plus once when the model stream ends ({@link flush}). Writes are issued before the delta is published, on the same
+ * connection as the bus publish, so a viewer that sees a delta past its snapshot and asks again
+ * gets a draft at least that far whenever that delta was written. Every write refreshes the
+ * {@link DRAFT_TTL_SECONDS} TTL; {@link clear} deletes the step's draft once its
+ * `assistant_message` is logged or the step is reset. Redis failures are logged, never thrown to
+ * the run: a draft is a convenience, the log stays the truth.
+ */
+export declare class RunDrafts {
+    private readonly redis;
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly log;
+    private readonly held;
+    constructor(redis: Redis, kdb: KernelDb, eventLog: Pick<EventLog, "findByIdem">, log: Pick<Logger, "warn">);
+    private get db();
+    /** Adds a delta to the step's draft; writes it when the last write is a window old. */
+    append(runId: string, step: number, channel: "text" | "thinking", text: string): void;
+    /** The end of the step's model stream: writes what the window still holds. */
+    flush(runId: string, step: number): void;
+    /** Deletes the step's draft (its `assistant_message` is logged, or the step starts over). */
+    clear(runId: string, step: number): void;
+    /**
+     * Drops what this process holds for the run (its execution here ended: finished, suspended,
+     * handed over). Redis keeps what was written: another worker may continue the run, and a step
+     * that never ended is not shown once the run is no longer running (TTL removes it).
+     */
+    release(runId: string): void;
+    /** The run's steps with a draft, by step. */
+    read(runId: string): Promise<RunDraft[]>;
+    /**
+     * The drafts a viewer of the conversation is shown: steps of its running run (or only `runId`)
+     * whose `assistant_message` is not logged. Redis is read before the log, so a step finalized
+     * meanwhile is either skipped here or its `assistant_message` reaches the viewer after the draft.
+     */
+    live(conversationId: string, runId?: string): Promise<LiveDraft[]>;
+    /** Whether the run belongs to the conversation (the draft route's 404). */
+    runOf(conversationId: string, runId: string): Promise<boolean>;
+    private drop;
+    private write;
+}
+/** What {@link streamSink} uses. */
+export interface StreamSinkDeps {
+    bus: Pick<ExtensionContext["bus"], "publish">;
+    drafts: Pick<RunDrafts, "append" | "flush" | "clear">;
+    log: Pick<Logger, "warn">;
+}
+/**
+ * The run's stream sink (one per execution of a run): publishes deltas on the conversation's topic
+ * (`conv.<id>`, shared with `{ kind: "events" }`, so a subscriber on any replica gets them) with
+ * `offset`, the characters of that channel (text or thinking) this attempt of the step streamed
+ * before the delta, and keeps the step's live draft. `step_reset` clears the draft and both
+ * offsets; `stream_end` / `step_end` only flush / clear the draft and are not published. A failed
+ * publish is only logged: deltas are drafts, the `assistant_message` in the log is the truth.
+ */
+export declare function streamSink(conversationId: string, deps: StreamSinkDeps): StreamSink;

package/dist/runtime/run-drafts.js

@@ -0,0 +1,230 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { conversationTopic, EventLog, } from "../conversations/event-log.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
+import { assistantIdemKey } from "./model-call.js";
+/** How long a draft lives without a write (a step that keeps streaming keeps refreshing it). */
+export const DRAFT_TTL_SECONDS = 600;
+/** At most one write per step per window, plus the one at the end of the model stream. */
+export const DRAFT_FLUSH_MS = 200;
+/** One step's draft: `{ text, thinking }` as JSON (spec 2026-11-07 §3.2). */
+export const draftKey = (runId, step) => `capk:run-draft:${runId}:${step}`;
+/** The steps of a run that have a draft (a set, so a reader finds them without a key scan). */
+const stepsKey = (runId) => `capk:run-draft-steps:${runId}`;
+const parse = (step, v) => {
+    if (v === null)
+        return null;
+    try {
+        const d = JSON.parse(v);
+        return {
+            step,
+            text: typeof d.text === "string" ? d.text : "",
+            thinking: typeof d.thinking === "string" ? d.thinking : "",
+        };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Live drafts (spec 2026-11-07-run-input-and-live-drafts §3.2): what each step of a running run
+ * has streamed so far, kept in Redis so a viewer that (re)connects on any replica gets the text
+ * already shown, then the deltas from there on.
+ *
+ * The writer is the process executing the run: it holds the step's draft in memory (only for the
+ * runs it executes; {@link release} drops them when the execution ends) and writes it at most once
+ * per {@link DRAFT_FLUSH_MS}: on the first delta past the window, or, when deltas stop inside it,
+ * by one trailing one-shot timer per held step (process-local, unref'd, cancelled by a write,
+ * {@link clear} and {@link release}), plus once when the model stream ends ({@link flush}). Writes are issued before the delta is published, on the same
+ * connection as the bus publish, so a viewer that sees a delta past its snapshot and asks again
+ * gets a draft at least that far whenever that delta was written. Every write refreshes the
+ * {@link DRAFT_TTL_SECONDS} TTL; {@link clear} deletes the step's draft once its
+ * `assistant_message` is logged or the step is reset. Redis failures are logged, never thrown to
+ * the run: a draft is a convenience, the log stays the truth.
+ */
+let RunDrafts = class RunDrafts {
+    redis;
+    kdb;
+    eventLog;
+    log;
+    held = new Map();
+    constructor(redis, kdb, eventLog, log) {
+        this.redis = redis;
+        this.kdb = kdb;
+        this.eventLog = eventLog;
+        this.log = log;
+    }
+    get db() {
+        return this.kdb.db;
+    }
+    /** Adds a delta to the step's draft; writes it when the last write is a window old. */
+    append(runId, step, channel, text) {
+        let h = this.held.get(runId);
+        if (h?.step !== step) {
+            if (h)
+                this.drop(runId, h);
+            h = {
+                step,
+                text: "",
+                thinking: "",
+                writtenAt: Number.NEGATIVE_INFINITY,
+                dirty: false,
+                timer: undefined,
+            };
+            this.held.set(runId, h);
+        }
+        h[channel] += text;
+        h.dirty = true;
+        const elapsed = Date.now() - h.writtenAt;
+        if (elapsed >= DRAFT_FLUSH_MS)
+            this.write(runId, h);
+        else if (h.timer === undefined) {
+            // held: written when the window ends even if no delta follows (a tool input, a pause)
+            h.timer = setTimeout(() => {
+                h.timer = undefined;
+                this.flush(runId, step);
+            }, DRAFT_FLUSH_MS - elapsed).unref();
+        }
+    }
+    /** The end of the step's model stream: writes what the window still holds. */
+    flush(runId, step) {
+        const h = this.held.get(runId);
+        if (h?.step === step && h.dirty)
+            this.write(runId, h);
+    }
+    /** Deletes the step's draft (its `assistant_message` is logged, or the step starts over). */
+    clear(runId, step) {
+        const h = this.held.get(runId);
+        if (h?.step === step)
+            this.drop(runId, h);
+        this.redis
+            .multi()
+            .del(draftKey(runId, step))
+            .srem(stepsKey(runId), String(step))
+            .exec()
+            .catch((err) => this.log.warn("run draft clear failed", { runId, step, err }));
+    }
+    /**
+     * Drops what this process holds for the run (its execution here ended: finished, suspended,
+     * handed over). Redis keeps what was written: another worker may continue the run, and a step
+     * that never ended is not shown once the run is no longer running (TTL removes it).
+     */
+    release(runId) {
+        const h = this.held.get(runId);
+        if (h)
+            this.drop(runId, h);
+    }
+    /** The run's steps with a draft, by step. */
+    async read(runId) {
+        const steps = (await this.redis.smembers(stepsKey(runId)))
+            .map(Number)
+            .filter((n) => Number.isSafeInteger(n))
+            .sort((a, b) => a - b);
+        if (steps.length === 0)
+            return [];
+        const values = await this.redis.mget(steps.map((s) => draftKey(runId, s)));
+        return steps.flatMap((s, i) => parse(s, values[i] ?? null) ?? []);
+    }
+    /**
+     * The drafts a viewer of the conversation is shown: steps of its running run (or only `runId`)
+     * whose `assistant_message` is not logged. Redis is read before the log, so a step finalized
+     * meanwhile is either skipped here or its `assistant_message` reaches the viewer after the draft.
+     */
+    async live(conversationId, runId) {
+        let q = this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("conversation_id", "=", conversationId)
+            .where("status", "=", "running");
+        if (runId !== undefined)
+            q = q.where("id", "=", runId);
+        const out = [];
+        for (const run of await q.execute()) {
+            for (const d of await this.read(run.id)) {
+                const final = await this.eventLog.findByIdem(conversationId, assistantIdemKey(run.id, d.step));
+                if (final === undefined)
+                    out.push({ runId: run.id, ...d });
+            }
+        }
+        return out;
+    }
+    /** Whether the run belongs to the conversation (the draft route's 404). */
+    async runOf(conversationId, runId) {
+        const row = await this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("id", "=", runId)
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst();
+        return row !== undefined;
+    }
+    drop(runId, h) {
+        clearTimeout(h.timer);
+        h.timer = undefined;
+        this.held.delete(runId);
+    }
+    write(runId, h) {
+        clearTimeout(h.timer);
+        h.timer = undefined;
+        h.writtenAt = Date.now();
+        h.dirty = false;
+        const { step } = h;
+        this.redis
+            .multi()
+            .set(draftKey(runId, step), JSON.stringify({ text: h.text, thinking: h.thinking }), "EX", DRAFT_TTL_SECONDS)
+            .sadd(stepsKey(runId), String(step))
+            .expire(stepsKey(runId), DRAFT_TTL_SECONDS)
+            .exec()
+            .catch((err) => this.log.warn("run draft write failed", { runId, step, err }));
+    }
+};
+RunDrafts = __decorate([
+    Injectable(),
+    __param(0, Inject(REDIS)),
+    __param(1, Inject(KernelDb)),
+    __param(2, Inject(EventLog)),
+    __param(3, Inject(KERNEL_LOGGER))
+], RunDrafts);
+export { RunDrafts };
+/**
+ * The run's stream sink (one per execution of a run): publishes deltas on the conversation's topic
+ * (`conv.<id>`, shared with `{ kind: "events" }`, so a subscriber on any replica gets them) with
+ * `offset`, the characters of that channel (text or thinking) this attempt of the step streamed
+ * before the delta, and keeps the step's live draft. `step_reset` clears the draft and both
+ * offsets; `stream_end` / `step_end` only flush / clear the draft and are not published. A failed
+ * publish is only logged: deltas are drafts, the `assistant_message` in the log is the truth.
+ */
+export function streamSink(conversationId, deps) {
+    let at = { runId: "", step: -1, text: 0, thinking: 0 };
+    const publish = (msg) => deps.bus
+        .publish(conversationTopic(conversationId), msg)
+        .catch((err) => deps.log.warn("stream delta publish failed", { conversationId, err }));
+    return (d) => {
+        if (d.kind === "stream_end")
+            return deps.drafts.flush(d.runId, d.step);
+        if (d.kind === "step_end")
+            return deps.drafts.clear(d.runId, d.step);
+        if (at.runId !== d.runId || at.step !== d.step || d.kind === "step_reset") {
+            at = { runId: d.runId, step: d.step, text: 0, thinking: 0 };
+        }
+        if (d.kind === "step_reset") {
+            deps.drafts.clear(d.runId, d.step);
+            void publish({ kind: "delta", runId: d.runId, step: d.step, delta: "step_reset" });
+            return;
+        }
+        const text = d.text ?? "";
+        const offset = at[d.kind];
+        at[d.kind] += text.length;
+        deps.drafts.append(d.runId, d.step, d.kind, text);
+        void publish({ kind: "delta", runId: d.runId, step: d.step, delta: d.kind, text, offset });
+    };
+}

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

@@ -34,12 +34,10 @@ export declare class RunJobs {
     queue(name?: string): Queue<RunJobData>;
     /** A run job by id on the queue `name`, or undefined. */
     getJob(jobId: string, name?: string): Promise<Job<RunJobData> | undefined>;
-    /** Adds a conversation run job (`ensureRun`'s own enqueue). */
-    add(data: RunJobData, jobId: string): Promise<void>;
     /**
-     * Enqueues a run job under the caller's job id (resumes, dispatches, repairs). The queue follows
-     * the conversation's kind (a sub-agent's runs go to {@link SUBAGENT_RUN_QUEUE_NAME}); pass
-     * `kind` when the caller knows it, else it is read.
+     * Enqueues a run job under the caller's job id (`ensureRun`, resumes, dispatches, repairs). The
+     * queue follows the conversation's kind (a sub-agent's runs go to
+     * {@link SUBAGENT_RUN_QUEUE_NAME}); pass `kind` when the caller knows it, else it is read.
      */
     enqueue(data: RunJobData, jobId: string, kind?: ConversationKind): Promise<void>;
 }

package/dist/runtime/run-jobs.js

@@ -54,14 +54,10 @@ let RunJobs = class RunJobs {
     getJob(jobId, name = RUN_QUEUE_NAME) {
         return this.queue(name).getJob(jobId);
     }
-    /** Adds a conversation run job (`ensureRun`'s own enqueue). */
-    async add(data, jobId) {
-        await this.queue().add("run", data, { jobId, ...RUN_JOB_OPTIONS });
-    }
     /**
-     * Enqueues a run job under the caller's job id (resumes, dispatches, repairs). The queue follows
-     * the conversation's kind (a sub-agent's runs go to {@link SUBAGENT_RUN_QUEUE_NAME}); pass
-     * `kind` when the caller knows it, else it is read.
+     * Enqueues a run job under the caller's job id (`ensureRun`, resumes, dispatches, repairs). The
+     * queue follows the conversation's kind (a sub-agent's runs go to
+     * {@link SUBAGENT_RUN_QUEUE_NAME}); pass `kind` when the caller knows it, else it is read.
      */
     async enqueue(data, jobId, kind) {
         const k = kind ??

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

@@ -52,9 +52,11 @@ export declare class RunQueue {
      * 且没有 queued / running / waiting 的运行时：插入 `runs`（queued）并投递任务，返回 runId；否则返回 null。
      *
      * 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 (background
-     * Bash spec §3, {@link wakeDecisionIn}): the run is then attributed to the task's trigger
-     * account, and a finish inside the wake window schedules the delayed `bg-wake` job instead.
+     * once it is sent; with no head either, a wake-eligible finished background task or sub-agent
+     * delivery (background Bash spec §3, agent map spec §5.3, {@link wakeDecisionIn}): the run is
+     * then attributed to the event's trigger account and joins the tree's budget window, and an
+     * 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 会再执行它——写
@@ -71,6 +73,38 @@ export declare class RunQueue {
     }): Promise<string | null>;
     /** {@link ensureRun}'s transaction: what it decided goes back through `st`. */
     private ensureRunIn;
+    /**
+     * {@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
+     * (`Agent`, `SendMessage`), which also records the dispatch. Here it is started from a parent's
+     * message that reached its run after that run's last model call (agent map spec §10: a message
+     * racing the run's end starts a new run, never lost); and it is woken by its own background
+     * task's finish or a delivery from its own sub-agent, under the same rules as a chat
+     * conversation. Neither happens once its last run was stopped (`aborted`): a stopped sub-agent is
+     * 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.
+     */
+    private childWakeIn;
+    /**
+     * The newest unconsumed message of an idle sub-agent (a `SendMessage` its last run did not absorb)
+     * as a run boundary, or null: none; the root's queue is paused or the root deleted (the
+     * message waits for the unpause, {@link wakeHeldTree}); or its author can no longer send to the
+     * root (it waits for a later run). The caller already refused a stopped sub-agent (last run
+     * `aborted`): a message that reached it while running and then stopped is parked, and the next
+     * run its parent starts absorbs it. Called under the sub-agent's row lock.
+     */
+    private pendingMessageIn;
+    /**
+     * 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.
+     */
+    wakeHeldTree(rootId: string): Promise<void>;
     /**
      * 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