@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/conversations/queue.js

@@ -0,0 +1,527 @@
+import { randomUUID } from "node:crypto";
+import { sql } from "kysely";
+import { normalizeStoredDefinition } from "../agents/definition.js";
+import { ApiError } from "../errors.js";
+import { notInvocable, recordedSkillBlocked, } from "../skills/invoke.js";
+import { userMessageIdemKey, } from "./conversations.service.js";
+import { payloadJson } from "./event-log.js";
+import { planSelection, readSelection } from "./selection.js";
+/**
+ * Queued messages (UI refresh B, spec §5.7): messages a person queued while a run was going. They
+ * are conversation state in PG, not events: the model has not seen them, so they enter the log only
+ * when sent. `RunQueue.ensureRun` sends the head item, one per run, when the conversation is idle
+ * (no unconsumed message, no active run, not paused), under the conversation row lock, so exactly
+ * one replica sends each item. A run that fails or is stopped pauses the queue (`finishRunIn`).
+ */
+/** The most messages a conversation can hold in its queue. */
+export const QUEUE_MAX_ITEMS = 20;
+const COLUMNS = [
+    "id",
+    "conversation_id",
+    "account_id",
+    "position",
+    "text",
+    "content",
+    "attachments",
+    "files",
+    "client_message_id",
+    "model",
+    "effort",
+    "skill",
+    "created_at",
+];
+/**
+ * Queued text as the event log will store it: NUL becomes U+FFFD (PG rejects NUL in text and
+ * jsonb), the mapping `payloadJson` applies to a direct send (final review m1).
+ */
+const noNul = (text) => text.replaceAll("\0", "\uFFFD");
+const itemNotFound = () => new ApiError("conversation.queue_item_not_found", "Queued message not found");
+function toItem(r) {
+    const skill = r.skill;
+    return {
+        id: r.id,
+        text: r.text,
+        files: r.files,
+        attachments: r.attachments.map((a) => ({
+            connectorId: a.appId,
+            name: a.name,
+            uri: a.uri,
+        })),
+        clientMessageId: r.client_message_id,
+        model: r.model ?? null,
+        effort: r.effort,
+        ...(skill !== null && {
+            skill: { name: skill.invokedAs, arguments: skill.record.arguments, mode: skill.record.mode },
+        }),
+        createdAt: r.created_at,
+        position: Number(r.position),
+    };
+}
+/**
+ * The text rule of `POST …/messages`: text is required unless the message invokes a skill (its
+ * rendered text is `content[0]`) or carries files and no `@` resources (`content[0]` must be the
+ * text when resources follow it).
+ */
+function checkText(text, files, attachments, skill) {
+    if (text.length > 0 || skill || (files > 0 && attachments === 0))
+        return;
+    throw new ApiError("validation_failed", "Request validation failed", [
+        {
+            path: "text",
+            message: "Text is required unless the message invokes a skill or carries files (and no @ resources)",
+        },
+    ]);
+}
+/** The stored form of a rendered invocation and its first content block. */
+function storedSkill(invokedAs, invoked) {
+    const skill = { invokedAs, record: invoked.skill };
+    return { skill: payloadJson(skill), first: { type: "text", text: invoked.text } };
+}
+/** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
+export function queuedUserMessage(r) {
+    const attachments = r.attachments;
+    const skill = r.skill;
+    return {
+        type: "user_message",
+        idemKey: userMessageIdemKey(r.client_message_id),
+        payload: {
+            // a skill invocation's `content` starts with the text rendered when queued
+            content: [
+                ...(r.text === "" || skill !== null ? [] : [{ type: "text", text: r.text }]),
+                ...r.content,
+            ],
+            ...(attachments.length > 0 && { attachments }),
+            authorAccountId: r.account_id,
+            clientMessageId: r.client_message_id,
+            ...(skill !== null && { skill: skill.record }),
+        },
+    };
+}
+/**
+ * Appends a queued item inside `t` (the caller holds the conversation row lock): its pick, re-planned
+ * against the selection in effect now, becomes a `model_switched` before the `user_message`, as a
+ * direct send writes it (final review I1), and the cached selection follows the log. A model that
+ * stopped resolving since the item was queued is still written: the run worker's fallback
+ * (`model_switched { reason: "unavailable" }` before `run_started`) handles it, as it does for a
+ * direct switch whose model disappears. Returns the `user_message` and whether it switched.
+ */
+export async function appendQueuedIn(t, eventLog, conversationId, r) {
+    const events = [];
+    const pick = {
+        ...(r.model !== null && { model: r.model }),
+        ...(r.effort !== null && { effort: r.effort }),
+    };
+    const next = pick.model === undefined && pick.effort === undefined
+        ? null
+        : planSelection(await agentModel(t, conversationId), await readSelection(t, conversationId), pick);
+    if (next !== null) {
+        events.push({
+            type: "model_switched",
+            idemKey: `switch:${r.client_message_id}`,
+            payload: { ...next, byAccountId: r.account_id, reason: "user" },
+        });
+    }
+    events.push(queuedUserMessage(r));
+    const written = await eventLog.append(conversationId, events, t);
+    if (next !== null) {
+        await t
+            .updateTable("conversations")
+            .set({ selection: JSON.stringify(await readSelection(t, conversationId)) })
+            .where("id", "=", conversationId)
+            .execute();
+    }
+    return { event: written.at(-1), switched: next !== null };
+}
+/** The model of the conversation agent's current version (inside `t`). */
+async function agentModel(t, conversationId) {
+    return (await currentAgent(t, conversationId)).definition.model;
+}
+/** The conversation's org, agent and the agent's current definition (inside `t`). */
+async function currentAgent(t, conversationId) {
+    const row = await t
+        .selectFrom("conversations as c")
+        .innerJoin("agents as a", "a.id", "c.agent_id")
+        .innerJoin("agent_versions as v", (j) => j.onRef("v.agent_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
+        .select(["c.org_id", "c.agent_id", "v.definition"])
+        .where("c.id", "=", conversationId)
+        .executeTakeFirstOrThrow();
+    return {
+        orgId: row.org_id,
+        agentId: row.agent_id,
+        definition: normalizeStoredDefinition(row.definition),
+    };
+}
+/**
+ * Why a queued item's skill can no longer be invoked, or null (also null for a plain message).
+ * Checked at dispatch, inside `t` (phase D Task 9): the rendered text was frozen when queued, but
+ * the skill must still be one of the agent's skills a person can invoke.
+ */
+async function queuedSkillBlocked(t, conversationId, r) {
+    const skill = r.skill;
+    if (skill === null)
+        return null;
+    const a = await currentAgent(t, conversationId);
+    return recordedSkillBlocked(t, {
+        orgId: a.orgId,
+        agentId: a.agentId,
+        agent: a.definition,
+        conversationId,
+        skillId: skill.record.id,
+    });
+}
+/** Pauses the queue with `reason` (inside `t`, holding the conversation row lock). */
+export async function pauseQueueWith(t, conversationId, reason) {
+    await t
+        .updateTable("conversations")
+        .set({ queue_paused: true, queue_pause_reason: reason })
+        .where("id", "=", conversationId)
+        .execute();
+}
+/** Whether a user_message with this client id is already in the log (inside `t`). */
+async function alreadySent(t, conversationId, clientMessageId) {
+    const row = await t
+        .selectFrom("conversation_events")
+        .select("seq")
+        .where("conversation_id", "=", conversationId)
+        .where("idem_key", "=", userMessageIdemKey(clientMessageId))
+        .executeTakeFirst();
+    return row !== undefined;
+}
+/** Clears the pause once the queue is empty (inside `t`, holding the conversation row lock). */
+async function unpauseIfEmpty(t, conversationId) {
+    await t
+        .updateTable("conversations")
+        .set({ queue_paused: false, queue_pause_reason: null })
+        .where("id", "=", conversationId)
+        .where("queue_paused", "=", true)
+        .where((eb) => eb.not(eb.exists(eb
+        .selectFrom("conversation_queue")
+        .select(sql `1`.as("one"))
+        .where("conversation_queue.conversation_id", "=", conversationId))))
+        .execute();
+}
+const queueFull = () => new ApiError("conversation.queue_full", `A conversation can hold at most ${QUEUE_MAX_ITEMS} queued messages`);
+/**
+ * Sends the queue's head item as a `user_message` inside `t` (the caller holds the conversation
+ * row lock and has checked the conversation is idle and not paused); returns the event, or null
+ * when the queue is empty. An item whose message is already in the log (a retried enqueue after it
+ * was sent) is dropped and the next one is taken. A head item whose skill can no longer be invoked
+ * stays queued and the queue pauses (`skill_not_invocable`): `{ paused }`. The caller notifies
+ * after commit.
+ */
+export async function dispatchQueuedIn(t, eventLog, conversationId) {
+    for (;;) {
+        const head = await t
+            .selectFrom("conversation_queue")
+            .select(COLUMNS)
+            .where("conversation_id", "=", conversationId)
+            .orderBy("position")
+            .limit(1)
+            .executeTakeFirst();
+        if (!head)
+            return null;
+        const sent = await alreadySent(t, conversationId, head.client_message_id);
+        if (!sent && (await queuedSkillBlocked(t, conversationId, head)) !== null) {
+            await pauseQueueWith(t, conversationId, "skill_not_invocable");
+            return { paused: "skill_not_invocable" };
+        }
+        const row = await t
+            .deleteFrom("conversation_queue")
+            .where("id", "=", head.id)
+            .returning(COLUMNS)
+            .executeTakeFirst();
+        if (!row || sent)
+            continue;
+        return appendQueuedIn(t, eventLog, conversationId, row);
+    }
+}
+/**
+ * Pauses the queue of a conversation whose run just failed or was stopped, when it holds items
+ * (inside the terminal transaction, see `finishRunIn`).
+ */
+export async function pauseQueueIn(t, conversationId) {
+    await t
+        .updateTable("conversations")
+        .set({ queue_paused: true, queue_pause_reason: "run_ended" })
+        .where("id", "=", conversationId)
+        .where((eb) => eb.exists(eb
+        .selectFrom("conversation_queue")
+        .select(sql `1`.as("one"))
+        .where("conversation_queue.conversation_id", "=", conversationId)))
+        .execute();
+}
+/**
+ * The queue API (owner only, as the conversation): list, add, edit the text, delete, send now and
+ * resume. Every change publishes `changed: queue`.
+ */
+export class ConversationQueue {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async list(orgId, conversationId, accountId) {
+        await this.d.conversations.get(orgId, conversationId, accountId);
+        return this.d.db
+            .transaction()
+            .setIsolationLevel("repeatable read")
+            .execute(async (t) => {
+            const conv = await t
+                .selectFrom("conversations")
+                .select(["queue_paused", "queue_pause_reason"])
+                .where("id", "=", conversationId)
+                .executeTakeFirstOrThrow();
+            const rows = await t
+                .selectFrom("conversation_queue")
+                .select(COLUMNS)
+                .where("conversation_id", "=", conversationId)
+                .orderBy("position")
+                .execute();
+            const reason = conv.queue_paused ? conv.queue_pause_reason : null;
+            return {
+                items: rows.map(toItem),
+                paused: conv.queue_paused,
+                ...(reason !== null && { pauseReason: reason }),
+            };
+        });
+    }
+    /**
+     * Queues a message. `@` resources are read now with the caller's credentials and stored with the
+     * item, and uploaded files are bound to the conversation now, so sending later needs nobody's
+     * credentials. The same `clientMessageId` again returns the queued item (`created: false`), or,
+     * when it was already sent, the sent `user_message` with `item: null`. Then `ensureRun`: on an
+     * idle conversation the item goes out at once.
+     */
+    async add(orgId, conversationId, accountId, input) {
+        const conv = await this.d.conversations.writable(orgId, conversationId, accountId);
+        this.d.conversations.checkFilesSupported(input);
+        const files = input.files ?? [];
+        checkText(input.text, files.length, input.attachments?.length ?? 0, input.skill !== undefined);
+        const prior = await this.prior(conversationId, input.clientMessageId);
+        if (prior)
+            return prior;
+        // a cheap unlocked check first, so a full queue never reads `@` resources (slow, remote,
+        // credentialed); the locked check below stays authoritative
+        const { n: queued } = await this.d.db
+            .selectFrom("conversation_queue")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirstOrThrow();
+        if (Number(queued) >= QUEUE_MAX_ITEMS)
+            throw queueFull();
+        await this.d.conversations.checkPick(orgId, conv, accountId, input);
+        // a skill invocation is rendered now, like the `@` resources (spec §4.5)
+        const invoked = await this.d.conversations.prepareQueuedSkill(orgId, conv, accountId, input);
+        const extra = await this.d.conversations.resolveExtra(orgId, accountId, input);
+        const skill = invoked === undefined || input.skill === undefined
+            ? undefined
+            : storedSkill(input.skill.name, invoked);
+        const out = await this.d.db.transaction().execute(async (t) => {
+            await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", conversationId)
+                .forUpdate()
+                .executeTakeFirstOrThrow();
+            const existing = await t
+                .selectFrom("conversation_queue")
+                .select(COLUMNS)
+                .where("conversation_id", "=", conversationId)
+                .where("client_message_id", "=", input.clientMessageId)
+                .executeTakeFirst();
+            if (existing)
+                return { row: existing, created: false };
+            if (await alreadySent(t, conversationId, input.clientMessageId))
+                return null;
+            const { n, last } = await t
+                .selectFrom("conversation_queue")
+                .select((eb) => [
+                eb.fn.countAll().as("n"),
+                eb.fn.max("position").as("last"),
+            ])
+                .where("conversation_id", "=", conversationId)
+                .executeTakeFirstOrThrow();
+            if (Number(n) >= QUEUE_MAX_ITEMS)
+                throw queueFull();
+            const blocks = await this.d.conversations.bindIn(t, orgId, conversationId, accountId, files);
+            const fileMeta = blocks.flatMap((b) => (b.type === "image" || b.type === "document") && b.source.kind === "ref"
+                ? [{ attachmentId: b.source.attachmentId, name: b.name ?? "", mediaType: b.mediaType }]
+                : []);
+            const row = await t
+                .insertInto("conversation_queue")
+                .values({
+                id: randomUUID(),
+                conversation_id: conversationId,
+                account_id: accountId,
+                position: last === null ? 1 : Number(last) + 1,
+                text: noNul(input.text),
+                content: payloadJson([
+                    ...(skill === undefined ? [] : [skill.first]),
+                    ...extra.blocks,
+                    ...blocks,
+                ]),
+                attachments: payloadJson(extra.attachments),
+                files: JSON.stringify(fileMeta),
+                client_message_id: input.clientMessageId,
+                model: input.model === undefined ? null : JSON.stringify(input.model),
+                effort: input.effort ?? null,
+                skill: skill?.skill ?? null,
+            })
+                .returning(COLUMNS)
+                .executeTakeFirstOrThrow();
+            return { row, created: true };
+        });
+        if (out === null) {
+            return ((await this.prior(conversationId, input.clientMessageId)) ?? { item: null, created: false });
+        }
+        if (out.created) {
+            await this.d.eventLog.publishChanged(conversationId, "queue");
+            await this.d.runs?.ensureRun(conversationId);
+        }
+        return { item: toItem(out.row), created: out.created };
+    }
+    /**
+     * Changes a queued item's text (its resources and files stay as queued). A skill invocation's
+     * text is its arguments: the skill is rendered again with them now (phase D Task 9).
+     */
+    async edit(orgId, conversationId, accountId, itemId, text) {
+        const conv = await this.d.conversations.writable(orgId, conversationId, accountId);
+        const before = await this.d.db
+            .selectFrom("conversation_queue")
+            .select("skill")
+            .where("id", "=", itemId)
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst();
+        if (!before)
+            throw itemNotFound();
+        const was = before.skill;
+        const invoked = was === null
+            ? undefined
+            : await this.d.conversations.prepareQueuedSkill(orgId, conv, accountId, {
+                skill: { name: was.invokedAs },
+                text,
+            });
+        const row = await this.d.db.transaction().execute(async (t) => {
+            const cur = await t
+                .selectFrom("conversation_queue")
+                .select(["attachments", "files", "content", "skill"])
+                .where("id", "=", itemId)
+                .where("conversation_id", "=", conversationId)
+                .forUpdate()
+                .executeTakeFirst();
+            if (!cur)
+                throw itemNotFound();
+            const skill = cur.skill;
+            checkText(text, cur.files.length, cur.attachments.length, skill !== null);
+            // an invocation's first block is its rendered text: replace it and the record
+            const stored = skill === null || invoked === undefined ? undefined : storedSkill(skill.invokedAs, invoked);
+            return t
+                .updateTable("conversation_queue")
+                .set({
+                text: noNul(text),
+                updated_at: sql `now()`,
+                ...(stored !== undefined && {
+                    skill: stored.skill,
+                    content: payloadJson([stored.first, ...cur.content.slice(1)]),
+                }),
+            })
+                .where("id", "=", itemId)
+                .returning(COLUMNS)
+                .executeTakeFirstOrThrow();
+        });
+        await this.d.eventLog.publishChanged(conversationId, "queue");
+        return toItem(row);
+    }
+    async remove(orgId, conversationId, accountId, itemId) {
+        await this.d.conversations.writable(orgId, conversationId, accountId);
+        await this.d.db.transaction().execute(async (t) => {
+            await this.lockConversation(t, conversationId);
+            const gone = await t
+                .deleteFrom("conversation_queue")
+                .where("id", "=", itemId)
+                .where("conversation_id", "=", conversationId)
+                .returning("id")
+                .executeTakeFirst();
+            if (!gone)
+                throw itemNotFound();
+            await unpauseIfEmpty(t, conversationId);
+        });
+        await this.d.eventLog.publishChanged(conversationId, "queue");
+    }
+    /**
+     * Sends a queued item now: it leaves the queue and is posted as a user message in the same
+     * transaction (an interjection when a run is active; the items before it keep their place).
+     * Racing the dispatcher, exactly one of them takes the item; the loser sees it gone (404).
+     */
+    async sendNow(orgId, conversationId, accountId, itemId) {
+        await this.d.conversations.writable(orgId, conversationId, accountId);
+        const { event, fresh, switched } = await this.d.db.transaction().execute(async (t) => {
+            await this.lockConversation(t, conversationId);
+            const head = await t
+                .selectFrom("conversation_queue")
+                .select(["skill", "client_message_id"])
+                .where("id", "=", itemId)
+                .where("conversation_id", "=", conversationId)
+                .executeTakeFirst();
+            if (!head)
+                throw itemNotFound();
+            // the skill is checked again, as at dispatch; a refused item stays queued
+            if (!(await alreadySent(t, conversationId, head.client_message_id))) {
+                const blocked = await queuedSkillBlocked(t, conversationId, head);
+                if (blocked !== null) {
+                    throw notInvocable(blocked, head.skill.invokedAs);
+                }
+            }
+            const row = await t
+                .deleteFrom("conversation_queue")
+                .where("id", "=", itemId)
+                .where("conversation_id", "=", conversationId)
+                .returning(COLUMNS)
+                .executeTakeFirst();
+            if (!row)
+                throw itemNotFound();
+            const sent = await alreadySent(t, conversationId, row.client_message_id);
+            const out = await appendQueuedIn(t, this.d.eventLog, conversationId, row);
+            await unpauseIfEmpty(t, conversationId);
+            return { ...out, fresh: !sent };
+        });
+        if (fresh)
+            await this.d.eventLog.notify(conversationId, event.seq);
+        if (switched)
+            await this.d.eventLog.publishChanged(conversationId, "selection");
+        await this.d.eventLog.publishChanged(conversationId, "queue");
+        await this.d.runs?.ensureRun(conversationId);
+        return event;
+    }
+    /** "Continue sending": clears the pause and lets `ensureRun` send the head item. */
+    async resume(orgId, conversationId, accountId) {
+        await this.d.conversations.writable(orgId, conversationId, accountId);
+        await this.d.db
+            .updateTable("conversations")
+            .set({ queue_paused: false, queue_pause_reason: null })
+            .where("id", "=", conversationId)
+            .execute();
+        await this.d.eventLog.publishChanged(conversationId, "queue");
+        await this.d.runs?.ensureRun(conversationId);
+    }
+    /** A queued item or a sent message for this client id (outside any transaction). */
+    async prior(conversationId, clientMessageId) {
+        const row = await this.d.db
+            .selectFrom("conversation_queue")
+            .select(COLUMNS)
+            .where("conversation_id", "=", conversationId)
+            .where("client_message_id", "=", clientMessageId)
+            .executeTakeFirst();
+        if (row)
+            return { item: toItem(row), created: false };
+        const event = await this.d.eventLog.findByIdem(conversationId, userMessageIdemKey(clientMessageId));
+        return event ? { item: null, event, created: false } : null;
+    }
+    async lockConversation(t, conversationId) {
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .executeTakeFirstOrThrow();
+    }
+}

package/dist/conversations/sandbox-status.d.ts

@@ -0,0 +1,21 @@
+import type { SandboxService } from "../sandbox/sandbox.service.js";
+export interface SandboxStatusView {
+    status: "running" | "suspended";
+    lastUsedAt: string;
+}
+export interface ConversationSandboxStatusDeps {
+    sandbox: Pick<SandboxService, "status">;
+    /** 会话可见性（与会话 SSE 流同一判定：`ConversationsService.isAccessible`）。 */
+    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
+    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
+    sandboxConversationOf(orgId: string, conversationId: string): Promise<string>;
+}
+/**
+ * 对话沙箱的状态（网页上下文标签，M5 T11）：会话不可见 → `conversation.not_found`；
+ * 没有可用的沙箱（未创建、已销毁、正在创建）→ `sandbox.not_found`（界面显示「未创建」）。
+ */
+export declare class ConversationSandboxStatus {
+    private readonly d;
+    constructor(d: ConversationSandboxStatusDeps);
+    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<SandboxStatusView>;
+}

package/dist/conversations/sandbox-status.js

@@ -0,0 +1,24 @@
+import { ApiError } from "../errors.js";
+import { UUID_RE } from "../ui/registry.js";
+/**
+ * 对话沙箱的状态（网页上下文标签，M5 T11）：会话不可见 → `conversation.not_found`；
+ * 没有可用的沙箱（未创建、已销毁、正在创建）→ `sandbox.not_found`（界面显示「未创建」）。
+ */
+export class ConversationSandboxStatus {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async get(orgId, conversationId, viewerAccountId) {
+        if (!UUID_RE.test(conversationId) ||
+            !(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+            throw new ApiError("conversation.not_found", "Conversation not found");
+        }
+        // a sub-agent works in its parent conversation's sandbox (sub-agents spec §10.1)
+        const sandboxConv = await this.d.sandboxConversationOf(orgId, conversationId);
+        const s = await this.d.sandbox.status(orgId, sandboxConv);
+        if (!s)
+            throw new ApiError("sandbox.not_found", "This conversation has no sandbox");
+        return { status: s.status, lastUsedAt: s.lastUsedAt.toISOString() };
+    }
+}

package/dist/conversations/selection.d.ts

@@ -0,0 +1,46 @@
+import type { Kysely } from "kysely";
+import type { AgentDefinition, ModelRef } from "../agents/definition.js";
+import type { KernelDatabase } from "../db/kernel-schema.js";
+/**
+ * The model and effort a person chose for a conversation (UI refresh B, spec §5.2): `null` model =
+ * the agent's model, `null` effort = the agent's saved effort or the model's default. Recorded in
+ * the log as `model_switched` events (the source of truth) and cached in `conversations.selection`
+ * for the conversation view.
+ */
+export interface Selection {
+    model: ModelRef | null;
+    effort: string | null;
+}
+export declare const NO_SELECTION: Selection;
+export declare const sameModel: (a: ModelRef, b: ModelRef) => boolean;
+export declare const sameSelection: (a: Selection, b: Selection) => boolean;
+/**
+ * The selection a message's pick switches to, or null when it changes nothing (pure; the direct
+ * send and queue dispatch share it). A model equal to the agent's means "back to the agent's
+ * model" (null); a model change without `effort` resets the effort.
+ */
+export declare function planSelection(agentModel: ModelRef, current: Selection, pick: {
+    model?: ModelRef | undefined;
+    effort?: string | undefined;
+}): Selection | null;
+/**
+ * The selection in effect for a run that started at `seq` (its `run_started`): the latest
+ * `model_switched` before it. Runtime and replays read it the same way, so a replay honors the
+ * switch the original run used.
+ */
+export declare function selectionAt(events: readonly {
+    seq: number;
+    type: string;
+    payload: unknown;
+}[], seq: number): Selection;
+/**
+ * The definition a run uses under a selection: `model` replaced by the selected one, `modelParams`
+ * = the agent's own (only while the model is the agent's) plus the selected effort. Fallback model
+ * and params are untouched. No selection returns the definition itself (old logs stay identical).
+ */
+export declare function effectiveDefinition(def: AgentDefinition, sel: Selection): AgentDefinition;
+/**
+ * The selection from the log: the latest `model_switched` (before `beforeSeq` when given). Pass a
+ * transaction that holds the conversation row lock to read it consistently with an append.
+ */
+export declare function readSelection(db: Kysely<KernelDatabase>, conversationId: string, beforeSeq?: number): Promise<Selection>;