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

package/dist/runtime/retired-schedulers.js

@@ -0,0 +1,31 @@
+import { MARKETPLACES_REFRESH_SCHEDULER_ID, PLUGIN_STAGING_CLEANUP_SCHEDULER_ID, } from "../catalog/job-ids.js";
+import { GATEWAY_CHECK_SCHEDULER_ID } from "../channels/job-ids.js";
+import { ATTACHMENT_CLEANUP_SCHEDULER_ID } from "../conversations/job-ids.js";
+import { PLUGINS_RECONCILE_SCHEDULER_ID } from "../extensions/job-ids.js";
+import { DIRECTORY_SCAN_SCHEDULER_ID, OFFBOARD_SWEEP_SCHEDULER_ID } from "../orgs/job-ids.js";
+import { SANDBOX_DESTROY_SCHEDULER_ID, SANDBOX_SUSPEND_SCHEDULER_ID } from "../sandbox/job-ids.js";
+import { STORAGE_PURGE_SCHEDULER_ID } from "../storage/job-ids.js";
+import { DRIFT_SCHEDULER_ID, OUTPUT_CLEANUP_SCHEDULER_ID } from "../tools/job-ids.js";
+import { USAGE_SWEEP_SCHEDULER_ID, WAIT_SWEEP_SCHEDULER_ID } from "./job-ids.js";
+/**
+ * Job scheduler ids of the maintenance queue's fixed-period jobs before they became `@LockedCron` /
+ * `@LockedInterval` jobs: an upgraded deployment still has them in Redis, so a starting worker
+ * role removes them (else BullMQ keeps firing a job no handler knows). Each id
+ * comes from its domain's leaf `job-ids.ts`, so this module imports no domain code.
+ */
+export const RETIRED_SCHEDULER_IDS = [
+    STORAGE_PURGE_SCHEDULER_ID,
+    DIRECTORY_SCAN_SCHEDULER_ID,
+    OFFBOARD_SWEEP_SCHEDULER_ID,
+    PLUGINS_RECONCILE_SCHEDULER_ID,
+    MARKETPLACES_REFRESH_SCHEDULER_ID,
+    PLUGIN_STAGING_CLEANUP_SCHEDULER_ID,
+    DRIFT_SCHEDULER_ID,
+    OUTPUT_CLEANUP_SCHEDULER_ID,
+    ATTACHMENT_CLEANUP_SCHEDULER_ID,
+    WAIT_SWEEP_SCHEDULER_ID,
+    USAGE_SWEEP_SCHEDULER_ID,
+    GATEWAY_CHECK_SCHEDULER_ID,
+    SANDBOX_SUSPEND_SCHEDULER_ID,
+    SANDBOX_DESTROY_SCHEDULER_ID,
+];

package/dist/runtime/run-context.service.d.ts

@@ -0,0 +1,65 @@
+import type { AgentDefinition } from "../agents/definition.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";
+/**
+ * Optional provider: the clock run start reads the date from and the `CurrentTime` builtin reads
+ * the time from (default `Date.now`; tests).
+ */
+export declare const RUN_CONTEXT_CLOCK: unique symbol;
+/** The idem key of a run's `run_context` (one per run at most). */
+export declare const runContextIdemKey: (runId: string) => string;
+/** What a run start tells {@link RunContextService.record}. */
+export interface RunContextInput {
+    orgId: string;
+    conversationId: string;
+    runId: string;
+    /** The run's boundary: its trigger message (or the finish / delivery that woke it). */
+    triggerSeq: number;
+    /** The run's effective definition (a root run's agent version; a sub-agent's frozen one). */
+    agent: AgentDefinition;
+    /** A sub-agent run: the parent call that dispatched it and the child's roster name. */
+    subagent?: {
+        parentConversationId: string;
+        parentRunId: string;
+        /** The roster name (`subagent_started.agentType`), or the forked skill's name. */
+        name: string;
+    };
+}
+/**
+ * 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.
+ */
+export declare class RunContextService {
+    private readonly db;
+    private readonly eventLog;
+    readonly txHost: TransactionHost;
+    private readonly now;
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify">, txHost: TransactionHost, now?: () => number);
+    private clock;
+    /** Records the run's context (see the class) and notifies after the commit. */
+    record(input: RunContextInput): Promise<void>;
+    /**
+     * 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.
+     */
+    private append;
+    /** A root run: agent, org, and the date, zone and language of the run's person (§3.4). */
+    private rootContext;
+    /**
+     * 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.
+     */
+    private childContext;
+}
+/**
+ * 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 declare function conversationTimeZone(t: KernelSchemaDb, orgId: string, conversationId: string): Promise<string>;

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

@@ -0,0 +1,43 @@
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import type { KernelLogger } from "../log.js";
+import { RunAbort } from "./abort.js";
+import { RunQueue } from "./run-queue.js";
+import { Waits } from "./waits.js";
+/**
+ * Starting and stopping runs from outside the run worker: the conversations API (a message, a
+ * stop), the conversation queue and offboarding (a departed member's runs, `by: null`).
+ */
+export declare class RunControl {
+    private readonly queue;
+    private readonly waits;
+    private readonly abort;
+    private readonly events;
+    private readonly log;
+    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
+     * stops its children (sub-agents spec §12).
+     */
+    abortIfOrphaned(conversationId: string, runId: string, byAccountId: string | null): Promise<boolean>;
+    /**
+     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
+     * 运行已不是 waiting（例如刚被续跑）→ false. Either way its approval / question cards may have
+     * 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

@@ -0,0 +1,89 @@
+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 { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { RunAbort } from "./abort.js";
+import { RunQueue } from "./run-queue.js";
+import { Waits } from "./waits.js";
+/**
+ * Starting and stopping runs from outside the run worker: the conversations API (a message, a
+ * stop), the conversation queue and offboarding (a departed member's runs, `by: null`).
+ */
+let RunControl = class RunControl {
+    queue;
+    waits;
+    abort;
+    events;
+    log;
+    constructor(queue, waits, abort, events, log) {
+        this.queue = queue;
+        this.waits = waits;
+        this.abort = abort;
+        this.events = events;
+        this.log = log;
+    }
+    /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
+    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
+     * stops its children (sub-agents spec §12).
+     */
+    async abortIfOrphaned(conversationId, runId, byAccountId) {
+        const r = await this.queue.abortIfOrphaned(conversationId, runId, byAccountId);
+        if (r) {
+            await this.waits
+                .childFinished(runId)
+                .catch((err) => this.log.error("cannot report finished sub-agent run to its parent", { runId, err }));
+            await this.waits
+                .stopChildren(runId, null)
+                .catch((err) => this.log.error("cannot stop the sub-agents of a run", { runId, err }));
+        }
+        return r;
+    }
+    /**
+     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
+     * 运行已不是 waiting（例如刚被续跑）→ false. Either way its approval / question cards may have
+     * changed: `run.wait-stopped` lets the channel outbound update them.
+     */
+    async abortWaiting(conversationId, runId, byAccountId) {
+        const r = await this.waits.abortWaiting(conversationId, runId, byAccountId);
+        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);
+    }
+};
+RunControl = __decorate([
+    Injectable(),
+    __param(0, Inject(RunQueue)),
+    __param(1, Inject(Waits)),
+    __param(2, Inject(RunAbort)),
+    __param(3, Inject(KernelEvents)),
+    __param(4, Inject(KERNEL_LOGGER))
+], RunControl);
+export { RunControl };

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;