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

package/dist/conversations/queue.js

@@ -1,10 +1,9 @@
-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 { recordedSkillBlocked, } from "../skills/invoke.js";
 import { payloadJson } from "./event-log.js";
+import { userMessageIdemKey } from "./idem-keys.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
@@ -15,7 +14,7 @@ import { planSelection, readSelection } from "./selection.js";
  */
 /** The most messages a conversation can hold in its queue. */
 export const QUEUE_MAX_ITEMS = 20;
-const COLUMNS = [
+export const COLUMNS = [
     "id",
     "conversation_id",
     "account_id",
@@ -34,9 +33,9 @@ const COLUMNS = [
  * 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) {
+export const noNul = (text) => text.replaceAll("\0", "\uFFFD");
+export const itemNotFound = () => new ApiError("conversation.queue_item_not_found", "Queued message not found");
+export function toItem(r) {
     const skill = r.skill;
     return {
         id: r.id,
@@ -62,7 +61,7 @@ function toItem(r) {
  * 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) {
+export function checkText(text, files, attachments, skill) {
     if (text.length > 0 || skill || (files > 0 && attachments === 0))
         return;
     throw new ApiError("validation_failed", "Request validation failed", [
@@ -73,7 +72,7 @@ function checkText(text, files, attachments, skill) {
     ]);
 }
 /** The stored form of a rendered invocation and its first content block. */
-function storedSkill(invokedAs, invoked) {
+export function storedSkill(invokedAs, invoked) {
     const skill = { invokedAs, record: invoked.skill };
     return { skill: payloadJson(skill), first: { type: "text", text: invoked.text } };
 }
@@ -122,7 +121,7 @@ export async function appendQueuedIn(t, eventLog, conversationId, r) {
         });
     }
     events.push(queuedUserMessage(r));
-    const written = await eventLog.append(conversationId, events, t);
+    const written = await eventLog.appendIn(conversationId, events);
     if (next !== null) {
         await t
             .updateTable("conversations")
@@ -156,7 +155,7 @@ async function currentAgent(t, conversationId) {
  * 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) {
+export async function queuedSkillBlocked(t, conversationId, r) {
     const skill = r.skill;
     if (skill === null)
         return null;
@@ -178,7 +177,7 @@ export async function pauseQueueWith(t, conversationId, reason) {
         .execute();
 }
 /** Whether a user_message with this client id is already in the log (inside `t`). */
-async function alreadySent(t, conversationId, clientMessageId) {
+export async function alreadySent(t, conversationId, clientMessageId) {
     const row = await t
         .selectFrom("conversation_events")
         .select("seq")
@@ -188,7 +187,7 @@ async function alreadySent(t, conversationId, clientMessageId) {
     return row !== undefined;
 }
 /** Clears the pause once the queue is empty (inside `t`, holding the conversation row lock). */
-async function unpauseIfEmpty(t, conversationId) {
+export async function unpauseIfEmpty(t, conversationId) {
     await t
         .updateTable("conversations")
         .set({ queue_paused: false, queue_pause_reason: null })
@@ -200,7 +199,7 @@ async function unpauseIfEmpty(t, conversationId) {
         .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`);
+export 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
@@ -250,278 +249,3 @@ export async function pauseQueueIn(t, conversationId) {
         .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/queue.service.d.ts

@@ -0,0 +1,60 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { ConversationsService, type RunControl } from "./conversations.service.js";
+import { EventLog } from "./event-log.js";
+import type { ConversationEvent } from "./events.js";
+import { type QueueInput, type QueueItem, type QueuePauseReason } from "./queue.js";
+/**
+ * The queue API (owner only, as the conversation): list, add, edit the text, delete, send now and
+ * resume. Every change publishes `changed: queue`.
+ */
+export declare class ConversationQueue {
+    private readonly db;
+    private readonly eventLog;
+    private readonly conversations;
+    /** Starts the conversation's next run (`ensureRun`). */
+    private readonly runs;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill">, 
+    /** Starts the conversation's next run (`ensureRun`). */
+    runs: Pick<RunControl, "ensureRun">, txHost: TransactionHost);
+    list(orgId: string, conversationId: string, accountId: string): Promise<{
+        items: QueueItem[];
+        paused: boolean;
+        pauseReason?: QueuePauseReason;
+    }>;
+    private listIn;
+    /**
+     * 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.
+     */
+    add(orgId: string, conversationId: string, accountId: string, input: QueueInput): Promise<{
+        item: QueueItem | null;
+        event?: ConversationEvent;
+        created: boolean;
+    }>;
+    private addIn;
+    /**
+     * 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.
+     */
+    edit(orgId: string, conversationId: string, accountId: string, itemId: string, text: string): Promise<QueueItem>;
+    private editIn;
+    remove(orgId: string, conversationId: string, accountId: string, itemId: string): Promise<void>;
+    private removeIn;
+    /**
+     * 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).
+     */
+    sendNow(orgId: string, conversationId: string, accountId: string, itemId: string): Promise<ConversationEvent>;
+    private sendNowIn;
+    /** "Continue sending": clears the pause and lets `ensureRun` send the head item. */
+    resume(orgId: string, conversationId: string, accountId: string): Promise<void>;
+    /** A queued item or a sent message for this client id (outside any transaction). */
+    private prior;
+    private lockConversation;
+}