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

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;
+}

package/dist/conversations/queue.service.js

@@ -0,0 +1,343 @@
+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 { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+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 { RunControl as RunControlService } from "../runtime/run-control.js";
+import { notInvocable } from "../skills/invoke.js";
+import { ConversationsService, } from "./conversations.service.js";
+import { EventLog, payloadJson } from "./event-log.js";
+import { userMessageIdemKey } from "./idem-keys.js";
+import { alreadySent, appendQueuedIn, COLUMNS, checkText, itemNotFound, noNul, QUEUE_MAX_ITEMS, queuedSkillBlocked, queueFull, storedSkill, toItem, unpauseIfEmpty, } 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`.
+ */
+let ConversationQueue = class ConversationQueue {
+    db;
+    eventLog;
+    conversations;
+    runs;
+    txHost;
+    constructor(db, eventLog, conversations, 
+    /** Starts the conversation's next run (`ensureRun`). */
+    runs, txHost) {
+        this.db = db;
+        this.eventLog = eventLog;
+        this.conversations = conversations;
+        this.runs = runs;
+        this.txHost = txHost;
+    }
+    async list(orgId, conversationId, accountId) {
+        await this.conversations.get(orgId, conversationId, accountId);
+        return this.listIn(conversationId);
+    }
+    async listIn(conversationId) {
+        const t = this.db.db;
+        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.conversations.writable(orgId, conversationId, accountId);
+        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.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.conversations.checkPick(orgId, conv, accountId, input);
+        // a skill invocation is rendered now, like the `@` resources (spec §4.5)
+        const invoked = await this.conversations.prepareQueuedSkill(orgId, conv, accountId, input);
+        const extra = await this.conversations.resolveExtra(orgId, accountId, input);
+        const skill = invoked === undefined || input.skill === undefined
+            ? undefined
+            : storedSkill(input.skill.name, invoked);
+        const out = await this.addIn(orgId, conversationId, accountId, input, files, skill, extra);
+        if (out === null) {
+            return ((await this.prior(conversationId, input.clientMessageId)) ?? { item: null, created: false });
+        }
+        if (out.created) {
+            await this.eventLog.publishChanged(conversationId, "queue");
+            await this.runs.ensureRun(conversationId);
+        }
+        return { item: toItem(out.row), created: out.created };
+    }
+    // its own transaction: the caller notifies and publishes after the commit
+    async addIn(orgId, conversationId, accountId, input, files, skill, extra) {
+        const t = this.db.db;
+        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.conversations.bindIn(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 };
+    }
+    /**
+     * 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.
+     */
+    async edit(orgId, conversationId, accountId, itemId, text) {
+        const conv = await this.conversations.writable(orgId, conversationId, accountId);
+        const before = await this.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.conversations.prepareQueuedSkill(orgId, conv, accountId, {
+                skill: { name: was.invokedAs },
+                text,
+            });
+        const row = await this.editIn(conversationId, itemId, text, invoked);
+        await this.eventLog.publishChanged(conversationId, "queue");
+        return toItem(row);
+    }
+    // its own transaction: the caller notifies and publishes after the commit
+    async editIn(conversationId, itemId, text, invoked) {
+        const t = this.db.db;
+        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();
+    }
+    async remove(orgId, conversationId, accountId, itemId) {
+        await this.conversations.writable(orgId, conversationId, accountId);
+        await this.removeIn(conversationId, itemId);
+        await this.eventLog.publishChanged(conversationId, "queue");
+    }
+    // its own transaction: the caller notifies and publishes after the commit
+    async removeIn(conversationId, itemId) {
+        const t = this.db.db;
+        await this.lockConversation(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);
+    }
+    /**
+     * 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.conversations.writable(orgId, conversationId, accountId);
+        const { event, fresh, switched } = await this.sendNowIn(conversationId, itemId);
+        if (fresh)
+            await this.eventLog.notify(conversationId, event.seq);
+        if (switched)
+            await this.eventLog.publishChanged(conversationId, "selection");
+        await this.eventLog.publishChanged(conversationId, "queue");
+        await this.runs.ensureRun(conversationId);
+        return event;
+    }
+    // its own transaction: the caller notifies and publishes after the commit
+    async sendNowIn(conversationId, itemId) {
+        const t = this.db.db;
+        await this.lockConversation(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.eventLog, conversationId, row);
+        await unpauseIfEmpty(t, conversationId);
+        return { ...out, fresh: !sent };
+    }
+    /** "Continue sending": clears the pause and lets `ensureRun` send the head item. */
+    async resume(orgId, conversationId, accountId) {
+        await this.conversations.writable(orgId, conversationId, accountId);
+        await this.db
+            .updateTable("conversations")
+            .set({ queue_paused: false, queue_pause_reason: null })
+            .where("id", "=", conversationId)
+            .execute();
+        await this.eventLog.publishChanged(conversationId, "queue");
+        await this.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.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.eventLog.findByIdem(conversationId, userMessageIdemKey(clientMessageId));
+        return event ? { item: null, event, created: false } : null;
+    }
+    async lockConversation(conversationId) {
+        await this.db
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", conversationId)
+            .forUpdate()
+            .executeTakeFirstOrThrow();
+    }
+};
+__decorate([
+    Transactional({ isolationLevel: "repeatable read" })
+], ConversationQueue.prototype, "listIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ConversationQueue.prototype, "addIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ConversationQueue.prototype, "editIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ConversationQueue.prototype, "removeIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], ConversationQueue.prototype, "sendNowIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ConversationQueue.prototype, "lockConversation", null);
+ConversationQueue = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(ConversationsService)),
+    __param(3, Inject(RunControlService)),
+    __param(4, Inject(TransactionHost))
+], ConversationQueue);
+export { ConversationQueue };

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

@@ -1,21 +1,24 @@
-import type { SandboxService } from "../sandbox/sandbox.service.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { ConversationAccess } from "./access.js";
+import { ConversationsService } from "./conversations.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);
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    private readonly access;
+    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
+    private readonly conversations;
+    private readonly sandbox;
+    constructor(
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    access: Pick<ConversationAccess, "isAccessible">, 
+    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
+    conversations: Pick<ConversationsService, "sandboxConversationOf">, sandbox: Pick<SandboxService, "status">);
     get(orgId: string, conversationId: string, viewerAccountId: string): Promise<SandboxStatusView>;
 }

package/dist/conversations/sandbox-status.js

@@ -1,24 +1,52 @@
+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 { ApiError } from "../errors.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
 import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
+import { ConversationsService } from "./conversations.service.js";
 /**
  * 对话沙箱的状态（网页上下文标签，M5 T11）：会话不可见 → `conversation.not_found`；
  * 没有可用的沙箱（未创建、已销毁、正在创建）→ `sandbox.not_found`（界面显示「未创建」）。
  */
-export class ConversationSandboxStatus {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationSandboxStatus = class ConversationSandboxStatus {
+    access;
+    conversations;
+    sandbox;
+    constructor(
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    access, 
+    /** The conversation whose sandbox it works in: a sub-agent's parent, else itself. */
+    conversations, sandbox) {
+        this.access = access;
+        this.conversations = conversations;
+        this.sandbox = sandbox;
     }
     async get(orgId, conversationId, viewerAccountId) {
         if (!UUID_RE.test(conversationId) ||
-            !(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+            !(await this.access.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);
+        const sandboxConv = await this.conversations.sandboxConversationOf(orgId, conversationId);
+        const s = await this.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() };
     }
-}
+};
+ConversationSandboxStatus = __decorate([
+    Injectable(),
+    __param(0, Inject(ConversationAccess)),
+    __param(1, Inject(ConversationsService)),
+    __param(2, Inject(SandboxService))
+], ConversationSandboxStatus);
+export { ConversationSandboxStatus };

package/dist/conversations/titles.d.ts

@@ -1,10 +1,13 @@
-import { type Logger } from "@capybara-hq/plugin-sdk";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import { type ModelPurposesService } from "../models/purposes.js";
-import { type HookRunner } from "../runtime/hook-calls.js";
-import type { UsageReporter } from "../runtime/usage-report.js";
-import type { EventLog } from "./event-log.js";
+import { type Logger, type ModelUsage } from "@capybara-hq/plugin-sdk";
+import type { Job, Queue, Worker } from "bullmq";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { ModelPurposesService } from "../models/purposes.js";
+import { type AuditEntry, type HookRunner } from "../runtime/hook-calls.js";
+import { UsageReporter } from "../runtime/usage-report.js";
+import { EventLog } from "./event-log.js";
+import { type ConversationEvent } from "./events.js";
 /**
  * Model-generated conversation titles (UI refresh B, spec §5.1 "Titles").
  *
@@ -43,8 +46,8 @@ export declare function titleExcerpt(firstUser: string, firstReply: string): str
  */
 export declare function cleanTitle(reply: string): string | null;
 export interface TitleDeps {
-    db: KernelDb;
-    eventLog: Pick<EventLog, "append" | "readAfter" | "latestOfType" | "notify" | "publishChanged">;
+    db: KernelSchemaDb;
+    eventLog: Pick<EventLog, "append" | "appendIn" | "readAfter" | "latestOfType" | "notify" | "publishChanged">;
     purposes: Pick<ModelPurposesService, "chat">;
     log: Pick<Logger, "warn">;
     /**
@@ -55,9 +58,11 @@ export interface TitleDeps {
     usageReport?: Pick<UsageReporter, "enqueue">;
     /** Aborts the call (worker shutdown). */
     signal?: AbortSignal;
+    /** The job's transactional writes ({@link TitleGenerator}). */
+    writes: Pick<TitleGenerator, "writeResult" | "auditDenied">;
 }
 /** The attempt number to enqueue for this conversation, or null when no title job is due. */
-export declare function titleAttemptDue(db: KernelDb, conversationId: string): Promise<number | null>;
+export declare function titleAttemptDue(db: KernelSchemaDb, conversationId: string): Promise<number | null>;
 /**
  * One title attempt. Claims the attempt (`title_attempts = attempt` → `attempt + 1`; a second
  * execution of the same attempt finds nothing to claim and returns), calls the model, writes the
@@ -65,29 +70,71 @@ export declare function titleAttemptDue(db: KernelDb, conversationId: string): P
  * no run, idempotent per attempt) in the same transaction. Errors are logged, not thrown.
  */
 export declare function runTitleJob(d: TitleDeps, conversationId: string, attempt: number): Promise<void>;
-export interface TitleQueueDeps extends Omit<TitleDeps, "signal"> {
-    redisUrl: string;
-    config: () => KernelConfig;
-    log: Logger;
+interface TitleJob {
+    conversationId: string;
+    attempt: number;
+}
+/**
+ * One title attempt's work ({@link runTitleJob}) over the injected services, with its writes in
+ * transactions of their own: the title with the call's usage event, and a policy denial's audit row.
+ */
+export declare class TitleGenerator {
+    private readonly kdb;
+    private readonly eventLog;
+    private readonly purposes;
+    /** The title call fires the plugin hooks (`model.request`, `model.response`). */
+    private readonly host;
+    private readonly usageReport;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, eventLog: TitleDeps["eventLog"], purposes: Pick<ModelPurposesService, "chat">, 
+    /** The title call fires the plugin hooks (`model.request`, `model.response`). */
+    host: {
+        readonly hooks?: HookRunner;
+    } | undefined, usageReport: Pick<UsageReporter, "enqueue"> | undefined, log: Pick<Logger, "warn">, txHost: TransactionHost);
+    /** One attempt ({@link runTitleJob}); `signal` aborts the call (the worker stopping). */
+    run(conversationId: string, attempt: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Appends the call's `usage` event and writes the title while `title_source IS NULL` (a rename
+     * wins), in one transaction.
+     */
+    writeResult(conversationId: string, attempt: number, out: {
+        provider: string;
+        model: string;
+        usage: ModelUsage;
+    }, title: string | null): Promise<{
+        written: boolean;
+        usage: ConversationEvent | undefined;
+    }>;
+    /** The `hook.denied` audit row of a denied title call. */
+    auditDenied(entry: AuditEntry): Promise<void>;
 }
 /**
  * The title queue: `maybeEnqueue` on any role (called by the run worker after a completed run),
- * the worker on the `worker` role. One attempt per job, no BullMQ retries: the next completed run
- * enqueues the next attempt.
+ * consumed on the `worker` role by its `@Processor`. One attempt per job, no BullMQ retries: the
+ * next completed run enqueues the next attempt.
  */
 export declare class TitleQueue {
-    private readonly d;
-    private queue;
-    private queueConn;
+    private readonly kdb;
+    private readonly queue;
+    private readonly generator;
+    private readonly log;
     private worker;
-    private workerConn;
     private closed;
     private readonly stopping;
-    constructor(d: TitleQueueDeps);
+    constructor(kdb: KernelDb, queue: Queue<TitleJob>, generator: Pick<TitleGenerator, "run">, log: Pick<Logger, "warn" | "error">);
     /** Enqueues the next title attempt when one is due. Never throws (logs instead). */
     maybeEnqueue(conversationId: string): Promise<void>;
-    startWorker(): void;
-    private process;
+    /** Starts consuming (worker role only): `worker` is the `@Processor` worker of {@link TITLE_QUEUE}. */
+    startWorker(worker: Worker<TitleJob>): void;
+    /** The worker's `error` event. */
+    onError(err: Error): void;
+    /** One title job (the `@Processor` calls it). */
+    process(j: Job<TitleJob>): Promise<void>;
+    /** Stops: no more enqueues, the call in flight is aborted, the worker closes. */
     stop(): Promise<void>;
-    private getQueue;
 }
+/** Conversation titles: the queue and the job (consumed on the worker role). */
+export declare class TitlesModule {
+}
+export {};