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

package/dist/runtime/run-context.service.js

@@ -0,0 +1,236 @@
+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, Optional } from "@nestjs/common";
+import { sql } from "kysely";
+import { EventLog } from "../conversations/event-log.js";
+import { latestWebLocale } from "../conversations/message-context.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { isTimeZone } from "../time-zone.js";
+import { currentRunContext, dateIn, runContextChange, sanitizeSenderName, snapshotDescription, } from "./context/run-context.js";
+/**
+ * Optional provider: the clock run start reads the date from and the `CurrentTime` builtin reads
+ * the time from (default `Date.now`; tests).
+ */
+export const RUN_CONTEXT_CLOCK = Symbol("RUN_CONTEXT_CLOCK");
+/** The idem key of a run's `run_context` (one per run at most). */
+export const runContextIdemKey = (runId) => `run_context:${runId}`;
+const cut = (s, max) => [...s].slice(0, max).join("");
+/**
+ * Run start's run context (spec 2026-11-08-run-context-design §5): compares the facts the run
+ * would show the model (its agent's name and description, the org's name, today's date, the time
+ * zone and language of the person whose message started it; for a sub-agent who dispatched it)
+ * with the fold of the conversation's `run_context` events, and appends only what differs (the
+ * first time: everything). Lazy: a rename writes nothing anywhere; the next run notices.
+ */
+let RunContextService = class RunContextService {
+    db;
+    eventLog;
+    txHost;
+    now;
+    constructor(db, eventLog, txHost, now = Date.now) {
+        this.db = db;
+        this.eventLog = eventLog;
+        this.txHost = txHost;
+        this.now = now;
+    }
+    clock() {
+        return new Date(this.now());
+    }
+    /** Records the run's context (see the class) and notifies after the commit. */
+    async record(input) {
+        const seq = await this.append(input);
+        if (seq !== null)
+            await this.eventLog.notify(input.conversationId, seq);
+    }
+    /**
+     * One transaction under the conversation row lock (as `lockLatestCatalog`): fold, read the
+     * current values, append when something differs, with the idem key `run_context:<runId>` (a
+     * retried run start finds its event, or finds nothing changed). Returns the seq written.
+     */
+    async append(input) {
+        const t = this.db.db;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", input.conversationId)
+            .forUpdate()
+            .executeTakeFirst();
+        const prev = await foldOf(t, input.conversationId);
+        const next = input.subagent === undefined
+            ? await this.rootContext(t, input)
+            : await this.childContext(t, input, input.subagent);
+        const change = runContextChange(prev, next);
+        if (change === null)
+            return null;
+        const written = await this.eventLog.appendIn(input.conversationId, [
+            {
+                type: "run_context",
+                runId: input.runId,
+                idemKey: runContextIdemKey(input.runId),
+                payload: change,
+            },
+        ]);
+        return Math.max(...written.map((e) => e.seq));
+    }
+    /** A root run: agent, org, and the date, zone and language of the run's person (§3.4). */
+    async rootContext(t, input) {
+        const org = await t
+            .selectFrom("orgs")
+            .select("name")
+            .where("id", "=", input.orgId)
+            .executeTakeFirst();
+        const settings = await readOrgSettings(t, input.orgId);
+        // the person whose message started the run: the latest message at or before the trigger (a
+        // wake run has no message of its own). New messages record the zone and language used at send
+        // time (IM-provided, account, browser, web language, org: message-context.ts); a message
+        // without them (older logs) falls back to the author's own settings, then the org's (§3.4).
+        const person = await t
+            .selectFrom("conversation_events")
+            .select([
+            sql `payload->>'timeZone'`.as("timeZone"),
+            sql `payload->>'locale'`.as("locale"),
+            sql `payload->>'authorAccountId'`.as("author"),
+        ])
+            .where("conversation_id", "=", input.conversationId)
+            .where("type", "=", "user_message")
+            .where("seq", "<=", String(input.triggerSeq))
+            .orderBy("seq", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        const author = person?.author ?? null;
+        let zone = person?.timeZone != null && isTimeZone(person.timeZone) ? person.timeZone : undefined;
+        if (zone === undefined && author !== null) {
+            const own = await t
+                .selectFrom("accounts")
+                .select("time_zone")
+                .where("id", "=", author)
+                .executeTakeFirst();
+            if (own?.time_zone != null && isTimeZone(own.time_zone))
+                zone = own.time_zone;
+        }
+        zone ??= settings.timeZone ?? "UTC";
+        let locale = person?.locale === "zh" || person?.locale === "en" ? person.locale : undefined;
+        if (locale === undefined && author !== null) {
+            locale = await latestWebLocale(t, input.orgId, author);
+        }
+        locale ??= settings.locale;
+        const description = snapshotDescription(input.agent.description);
+        return {
+            agent: { name: input.agent.name, ...(description !== undefined && { description }) },
+            ...(org !== undefined && org.name.trim() !== "" && { org: { name: cut(org.name, 200) } }),
+            date: dateIn(this.clock(), zone),
+            timeZone: zone,
+            locale,
+        };
+    }
+    /**
+     * A sub-agent run (spec §6): its roster name, who dispatched it (the parent agent's name and
+     * the person the parent works for), and the parent's date and zone; no org, no language.
+     */
+    async childContext(t, input, child) {
+        const parent = await foldOf(t, child.parentConversationId);
+        const parentAgent = parent.agent?.name ?? (await parentDefinitionName(t, child.parentRunId)) ?? "agent";
+        const person = parent.dispatchedBy?.person ??
+            (await latestSenderName(t, child.parentConversationId)) ??
+            (await triggerName(t, child.parentRunId)) ??
+            "a person";
+        const zone = parent.timeZone ?? (await readOrgSettings(t, input.orgId)).timeZone ?? "UTC";
+        return {
+            agent: { name: cut(child.name, 130) },
+            dispatchedBy: { agent: cut(parentAgent, 130), person },
+            date: dateIn(this.clock(), zone),
+            timeZone: zone,
+        };
+    }
+};
+__decorate([
+    Transactional()
+], RunContextService.prototype, "append", null);
+RunContextService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(TransactionHost)),
+    __param(3, Optional()),
+    __param(3, Inject(RUN_CONTEXT_CLOCK))
+], RunContextService);
+export { RunContextService };
+/**
+ * The time zone a conversation's run context holds now (the latest `run_context` with a
+ * `timeZone`, as the fold reads it), else the org default (§3.3), else UTC. The `CurrentTime`
+ * builtin's default zone.
+ */
+export async function conversationTimeZone(t, orgId, conversationId) {
+    const row = await t
+        .selectFrom("conversation_events")
+        .select(sql `payload->>'timeZone'`.as("timeZone"))
+        .where("conversation_id", "=", conversationId)
+        .where("type", "=", "run_context")
+        .where(sql `payload ? 'timeZone'`)
+        .orderBy("seq", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    if (row?.timeZone != null && isTimeZone(row.timeZone))
+        return row.timeZone;
+    const zone = (await readOrgSettings(t, orgId)).timeZone;
+    return zone !== undefined && isTimeZone(zone) ? zone : "UTC";
+}
+/** The fold of a conversation's `run_context` events (read inside the caller's transaction). */
+async function foldOf(t, conversationId) {
+    const rows = await t
+        .selectFrom("conversation_events")
+        .select(["seq", "payload"])
+        .where("conversation_id", "=", conversationId)
+        .where("type", "=", "run_context")
+        .orderBy("seq", "asc")
+        .execute();
+    return currentRunContext(rows.map((r) => ({ type: "run_context", seq: Number(r.seq), payload: r.payload })));
+}
+/** The name in the parent run's agent version (a parent logged before run contexts existed). */
+async function parentDefinitionName(t, runId) {
+    const row = await t
+        .selectFrom("runs")
+        .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+        .innerJoin("agent_versions as v", (j) => j
+        .onRef("v.agent_id", "=", "conversations.agent_id")
+        .onRef("v.version", "=", "runs.agent_version"))
+        .select(sql `v.definition->>'name'`.as("name"))
+        .where("runs.id", "=", runId)
+        .executeTakeFirst();
+    return row?.name ?? undefined;
+}
+/** The latest sender name in a conversation's log (the person the conversation works for). */
+async function latestSenderName(t, conversationId) {
+    const row = await t
+        .selectFrom("conversation_events")
+        .select(sql `payload->'sender'->>'name'`.as("name"))
+        .where("conversation_id", "=", conversationId)
+        .where("type", "=", "user_message")
+        .where(sql `payload ? 'sender'`)
+        .orderBy("seq", "desc")
+        .limit(1)
+        .executeTakeFirst();
+    const name = row?.name == null ? "" : sanitizeSenderName(row.name);
+    return name === "" ? undefined : name;
+}
+/** The display name of the account that triggered a run. */
+async function triggerName(t, runId) {
+    const row = await t
+        .selectFrom("runs")
+        .innerJoin("accounts", "accounts.id", "runs.trigger_account_id")
+        .select("accounts.display_name")
+        .where("runs.id", "=", runId)
+        .executeTakeFirst();
+    const name = row === undefined ? "" : sanitizeSenderName(row.display_name);
+    return name === "" ? undefined : name;
+}

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

@@ -13,9 +13,11 @@ export declare class RunControl {
     private readonly abort;
     private readonly events;
     private readonly log;
-    constructor(queue: Pick<RunQueue, "ensureRun" | "abortIfOrphaned">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren">, abort: Pick<RunAbort, "request">, events: KernelEvents, log: Pick<KernelLogger, "error">);
+    constructor(queue: Pick<RunQueue, "ensureRun" | "abortIfOrphaned" | "wakeHeldTree">, waits: Pick<Waits, "abortWaiting" | "childFinished" | "stopChildren" | "stopTree">, abort: Pick<RunAbort, "request">, events: KernelEvents, log: Pick<KernelLogger, "error">);
     /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
     ensureRun(conversationId: string): Promise<string | null>;
+    /** After a root's queue was unpaused: the wakes it held for its tree ({@link RunQueue.wakeHeldTree}). */
+    wakeHeldTree(rootId: string): Promise<void>;
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
@@ -28,6 +30,14 @@ export declare class RunControl {
      * changed: `run.wait-stopped` lets the channel outbound update them.
      */
     abortWaiting(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /**
+     * Stops a sub-agent with its descendants, or with `includeSelf: false` only the sub-agent
+     * conversations below `conversationId` (agent map spec §6; {@link Waits.stopTree}). Returns
+     * the number of runs asked to stop.
+     */
+    stopTree(conversationId: string, byAccountId: string | null, opts?: {
+        includeSelf?: boolean;
+    }): Promise<number>;
     /** 请求中止运行（广播到所有副本）。 */
     requestAbort(runId: string, byAccountId: string | null): Promise<void>;
 }

package/dist/runtime/run-control.js

@@ -34,6 +34,10 @@ let RunControl = class RunControl {
     ensureRun(conversationId) {
         return this.queue.ensureRun(conversationId);
     }
+    /** After a root's queue was unpaused: the wakes it held for its tree ({@link RunQueue.wakeHeldTree}). */
+    wakeHeldTree(rootId) {
+        return this.queue.wakeHeldTree(rootId);
+    }
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。A stopped sub-agent then reports to its parent at once, and a stopped parent
@@ -61,6 +65,14 @@ let RunControl = class RunControl {
         await this.events.emit("run.wait-stopped", { conversationId, runId });
         return r;
     }
+    /**
+     * Stops a sub-agent with its descendants, or with `includeSelf: false` only the sub-agent
+     * conversations below `conversationId` (agent map spec §6; {@link Waits.stopTree}). Returns
+     * the number of runs asked to stop.
+     */
+    stopTree(conversationId, byAccountId, opts = {}) {
+        return this.waits.stopTree(conversationId, byAccountId, opts);
+    }
     /** 请求中止运行（广播到所有副本）。 */
     requestAbort(runId, byAccountId) {
         return this.abort.request(runId, byAccountId);

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-finish.d.ts

@@ -19,7 +19,7 @@ export interface FinishRunArgs {
     floorToTrigger?: boolean;
     /**
      * Runs in the transaction once the run is known not to be terminal, before the terminal event:
-     * a parent's open `agent` calls get their results here (sub-agents spec §12, review m1).
+     * a parent's open `Agent` calls get their results here (sub-agents spec §12, review m1).
      */
     beforeTerminal?: () => Promise<void>;
 }

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 ??
@@ -82,14 +78,16 @@ RunJobs = __decorate([
     __param(3, Inject(KERNEL_LOGGER))
 ], RunJobs);
 export { RunJobs };
+/** The run queues' registration (re-exported: the admin health reads their counts). */
+const RUN_QUEUES_MODULE = QueueModule.registerQueue(RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME);
 /** The run queues' producer (the sub-agent dispatch, the run queue and the waits use it). */
 let RunJobsModule = class RunJobsModule {
 };
 RunJobsModule = __decorate([
     Module({
-        imports: [QueueModule.registerQueue(RUN_QUEUE_NAME, SUBAGENT_RUN_QUEUE_NAME)],
+        imports: [RUN_QUEUES_MODULE],
         providers: [RunJobs],
-        exports: [RunJobs],
+        exports: [RunJobs, RUN_QUEUES_MODULE],
     })
 ], RunJobsModule);
 export { RunJobsModule };