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

package/dist/conversations/event-log.d.ts

@@ -1,8 +1,8 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import type { KernelLogger } from "../log.js";
 import { type ConversationEvent, type ConversationEventType } from "./events.js";
-type Trx = Transaction<KernelDatabase>;
 /** 事件日志依赖的总线：内核 bus（命名空间 `kernel`）。 */
 export interface EventBus {
     publish(topic: string, payload: unknown): Promise<void>;
@@ -70,28 +70,35 @@ export type ConversationChange = (typeof CONVERSATION_CHANGES)[number];
  * 会话事件日志：只追加，是 agent 运行的唯一事实来源。
  * seq 由 `conversations.last_seq` 在会话行锁内连续分配（多副本并发写同一会话时串行化）；
  * 幂等键的「先查后写」也在同一把行锁内完成。
+ *
+ * Every published advance (`notify`) is also announced in-process as `conversation.event-appended`
+ * on {@link KernelEvents} (the channel outbound delivery enqueues from it), on this replica, right
+ * after the bus publish, in append order.
  */
 export declare class EventLog {
     private readonly db;
     private readonly bus;
-    private readonly log?;
+    private readonly log;
+    private readonly events;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, bus: EventBus, log: Pick<KernelLogger, "warn">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost);
     /**
-     * 每次发布「日志已推进」之后调用（同步、不等待）：内核用它给有 IM 投递目标的会话排出站任务。
-     * 钩子自己负责吞掉错误。
+     * 追加事件，返回与输入一一对应的事件（幂等命中的为已有事件）。
+     * 自开一个独立事务（`requires_new`，与调用方的事务无关），提交后发布 `conv.<id>`。
+     * 要在调用方的事务里追加（与其他写入一起提交），用 {@link appendIn}。
      */
-    private readonly onNotify?;
-    constructor(db: KernelDb, bus: EventBus, log?: Pick<Logger, "warn"> | undefined, 
+    append(conversationId: string, events: AppendEvent[]): Promise<ConversationEvent[]>;
     /**
-     * 每次发布「日志已推进」之后调用（同步、不等待）：内核用它给有 IM 投递目标的会话排出站任务。
-     * 钩子自己负责吞掉错误。
+     * {@link append} inside the caller's transaction (it must hold one: `mandatory`): the events
+     * commit or roll back with the caller's writes, and the caller calls {@link notify} after the
+     * commit with the highest seq it wrote.
      */
-    onNotify?: ((conversationId: string, toSeq: number) => void) | undefined);
+    appendIn(conversationId: string, events: AppendEvent[]): Promise<ConversationEvent[]>;
+    private appendOwn;
     /**
-     * 追加事件，返回与输入一一对应的事件（幂等命中的为已有事件）。
-     * 不传 `trx` 时自开事务，提交后发布 `conv.<id>`；传入外部 `trx` 时由调用方在提交后调用 `notify`。
+     * 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。Then announces
+     * it in-process (`conversation.event-appended`); a failing subscriber is logged by KernelEvents.
      */
-    append(conversationId: string, events: AppendEvent[], trx?: Trx): Promise<ConversationEvent[]>;
-    /** 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。 */
     notify(conversationId: string, toSeq: number): Promise<void>;
     /**
      * Publishes a `changed` frame on the conversation topic (rename, generated title, selection, ...).
@@ -117,6 +124,9 @@ export declare class EventLog {
         type: T;
     }> | undefined>;
     private validate;
-    private appendIn;
+    /** The append itself, in the context's transaction (both callers open or join one). */
+    private write;
+}
+/** The one {@link EventLog} (infra dependencies only, so every domain can import it). */
+export declare class EventLogModule {
 }
-export {};

package/dist/conversations/event-log.js

@@ -1,5 +1,20 @@
+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, Module } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.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 { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { ConversationEventSchema, } from "./events.js";
 /**
  * The JSON stored for an event payload, with every NUL (U+0000) in a string or an object key
@@ -50,53 +65,61 @@ const EVENT_COLUMNS = [
  * 会话事件日志：只追加，是 agent 运行的唯一事实来源。
  * seq 由 `conversations.last_seq` 在会话行锁内连续分配（多副本并发写同一会话时串行化）；
  * 幂等键的「先查后写」也在同一把行锁内完成。
+ *
+ * Every published advance (`notify`) is also announced in-process as `conversation.event-appended`
+ * on {@link KernelEvents} (the channel outbound delivery enqueues from it), on this replica, right
+ * after the bus publish, in append order.
  */
-export class EventLog {
+let EventLog = class EventLog {
     db;
     bus;
     log;
-    onNotify;
-    constructor(db, bus, log, 
-    /**
-     * 每次发布「日志已推进」之后调用（同步、不等待）：内核用它给有 IM 投递目标的会话排出站任务。
-     * 钩子自己负责吞掉错误。
-     */
-    onNotify) {
+    events;
+    txHost;
+    constructor(db, bus, log, events, txHost) {
         this.db = db;
         this.bus = bus;
         this.log = log;
-        this.onNotify = onNotify;
+        this.events = events;
+        this.txHost = txHost;
     }
     /**
      * 追加事件，返回与输入一一对应的事件（幂等命中的为已有事件）。
-     * 不传 `trx` 时自开事务，提交后发布 `conv.<id>`；传入外部 `trx` 时由调用方在提交后调用 `notify`。
+     * 自开一个独立事务（`requires_new`，与调用方的事务无关），提交后发布 `conv.<id>`。
+     * 要在调用方的事务里追加（与其他写入一起提交），用 {@link appendIn}。
      */
-    async append(conversationId, events, trx) {
+    async append(conversationId, events) {
         const bodies = events.map((e) => this.validate(e));
-        if (trx)
-            return (await this.appendIn(trx, conversationId, events, bodies)).events;
-        const { events: out, toSeq } = await this.db
-            .transaction()
-            .execute((t) => this.appendIn(t, conversationId, events, bodies));
+        const { events: out, toSeq } = await this.appendOwn(conversationId, events, bodies);
         if (toSeq !== null)
             await this.notify(conversationId, toSeq);
         return out;
     }
-    /** 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。 */
+    /**
+     * {@link append} inside the caller's transaction (it must hold one: `mandatory`): the events
+     * commit or roll back with the caller's writes, and the caller calls {@link notify} after the
+     * commit with the highest seq it wrote.
+     */
+    async appendIn(conversationId, events) {
+        const bodies = events.map((e) => this.validate(e));
+        return (await this.write(conversationId, events, bodies)).events;
+    }
+    async appendOwn(conversationId, events, bodies) {
+        return this.write(conversationId, events, bodies);
+    }
+    /**
+     * 发布「日志已推进到 toSeq」；发布失败只记日志（事件已提交，订阅方可按 seq 补读）。Then announces
+     * it in-process (`conversation.event-appended`); a failing subscriber is logged by KernelEvents.
+     */
     async notify(conversationId, toSeq) {
         const msg = { kind: "events", toSeq };
         try {
             await this.bus.publish(conversationTopic(conversationId), msg);
         }
         catch (err) {
-            this.log?.warn("conversation event notify failed", { conversationId, toSeq, err });
-        }
-        try {
-            this.onNotify?.(conversationId, toSeq);
-        }
-        catch (err) {
-            this.log?.warn("conversation event notify hook failed", { conversationId, err });
+            this.log.warn("conversation event notify failed", { conversationId, toSeq, err });
         }
+        await this.events.emit("conversation.event-appended", { conversationId, toSeq });
     }
     /**
      * Publishes a `changed` frame on the conversation topic (rename, generated title, selection, ...).
@@ -108,7 +131,7 @@ export class EventLog {
             await this.bus.publish(conversationTopic(conversationId), msg);
         }
         catch (err) {
-            this.log?.warn("conversation change publish failed", { conversationId, what, err });
+            this.log.warn("conversation change publish failed", { conversationId, what, err });
         }
     }
     /** 读 `afterSeq` 之后的事件，按 seq 升序，最多 `limit` 条。 */
@@ -175,7 +198,9 @@ export class EventLog {
         }
         return r.data;
     }
-    async appendIn(t, conversationId, events, bodies) {
+    /** The append itself, in the context's transaction (both callers open or join one). */
+    async write(conversationId, events, bodies) {
+        const t = this.db;
         // 先锁会话行：之后的幂等查询与 seq 分配都在这把锁内，并发 append 依次执行。
         const conv = await t
             .selectFrom("conversations")
@@ -256,4 +281,26 @@ export class EventLog {
             toSeq,
         };
     }
-}
+};
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], EventLog.prototype, "appendIn", null);
+__decorate([
+    Transactional({ propagation: "requires_new" })
+], EventLog.prototype, "appendOwn", null);
+EventLog = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KERNEL_BUS)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(KernelEvents)),
+    __param(4, Inject(TransactionHost))
+], EventLog);
+export { EventLog };
+/** The one {@link EventLog} (infra dependencies only, so every domain can import it). */
+let EventLogModule = class EventLogModule {
+};
+EventLogModule = __decorate([
+    Module({ providers: [EventLog], exports: [EventLog] })
+], EventLogModule);
+export { EventLogModule };

package/dist/conversations/files.d.ts

@@ -1,5 +1,6 @@
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { StorageService } from "../storage/storage.service.js";
+import { ConversationAccess } from "./access.js";
 /**
  * A conversation's file outputs (UI refresh B, spec §5.8 / §5.9): the files the agent delivered
  * (`artifact_created`), grouped by `sourcePath` into versions, newest first. Read from the log on
@@ -44,17 +45,16 @@ export interface FileContent {
     originalType: string;
     truncated: boolean;
 }
-export interface ConversationFilesDeps {
-    db: KernelDb;
-    storage: Pick<StorageService, "kernel">;
-    /** Same visibility as the event stream (`ConversationsService.isAccessible`). */
-    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
-}
 /** Storage HEADs a files list sends at once (review M1). */
 export declare const HEAD_CONCURRENCY = 8;
 export declare class ConversationFiles {
-    private readonly d;
-    constructor(d: ConversationFilesDeps);
+    private readonly db;
+    private readonly storage;
+    /** Same visibility as the event stream. */
+    private readonly access;
+    constructor(db: KernelDb, storage: Pick<StorageService, "kernel">, 
+    /** Same visibility as the event stream. */
+    access: Pick<ConversationAccess, "isAccessible">);
     private checkAccess;
     /** Every delivery of the conversation in log order. */
     private deliveries;

package/dist/conversations/files.js

@@ -1,6 +1,19 @@
+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 { sql } from "kysely";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { StorageService } from "../storage/storage.service.js";
 import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
 import { isInlineArtifactType, isTextArtifactType } from "./artifacts.js";
 /**
  * A conversation's file outputs (UI refresh B, spec §5.8 / §5.9): the files the agent delivered
@@ -65,20 +78,26 @@ async function mapLimit(xs, limit, fn) {
     await Promise.all(Array.from({ length: Math.min(limit, xs.length) }, worker));
     return out;
 }
-export class ConversationFiles {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationFiles = class ConversationFiles {
+    db;
+    storage;
+    access;
+    constructor(db, storage, 
+    /** Same visibility as the event stream. */
+    access) {
+        this.db = db;
+        this.storage = storage;
+        this.access = access;
     }
     async checkAccess(orgId, conversationId, viewer) {
         if (!UUID_RE.test(conversationId))
             throw conversationNotFound();
-        if (!(await this.d.isAccessible(orgId, conversationId, viewer)))
+        if (!(await this.access.isAccessible(orgId, conversationId, viewer)))
             throw conversationNotFound();
     }
     /** Every delivery of the conversation in log order. */
     async deliveries(conversationId) {
-        const rows = await this.d.db
+        const rows = await this.db
             .selectFrom("conversation_events")
             .select(["payload", "created_at"])
             .where("conversation_id", "=", conversationId)
@@ -115,7 +134,7 @@ export class ConversationFiles {
             start = at + 1;
         }
         const page = ordered.slice(start, start + opts.limit);
-        const store = this.d.storage.kernel(orgId);
+        const store = this.storage.kernel(orgId);
         const files = await mapLimit(page, HEAD_CONCURRENCY, async (g) => {
             const latest = g.at(-1);
             const head = await store.head(latest.objectKey);
@@ -152,7 +171,7 @@ export class ConversationFiles {
         await this.checkAccess(orgId, conversationId, viewer);
         if (!UUID_RE.test(fileId))
             throw artifactNotFound();
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("conversation_events")
             .select("payload")
             .where("conversation_id", "=", conversationId)
@@ -180,7 +199,7 @@ export class ConversationFiles {
         await this.checkAccess(orgId, conversationId, viewer);
         if (!UUID_RE.test(fileId))
             throw artifactNotFound();
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("conversation_events")
             .select("payload")
             .where("conversation_id", "=", conversationId)
@@ -195,7 +214,7 @@ export class ConversationFiles {
             throw new ApiError("conversation.artifact_not_previewable", "Only text files have content");
         }
         const max = Math.min(limit, FILE_CONTENT_MAX_BYTES);
-        const got = await this.d.storage
+        const got = await this.storage
             .kernel(orgId)
             .get(a.objectKey, { range: { start: 0, end: max - 1 } });
         if (!got)
@@ -210,4 +229,11 @@ export class ConversationFiles {
         const base = (a.contentType.split(";")[0] ?? "").trim().toLowerCase();
         return { body, contentType: "text/plain; charset=utf-8", originalType: base, truncated };
     }
-}
+};
+ConversationFiles = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(ConversationAccess))
+], ConversationFiles);
+export { ConversationFiles };

package/dist/conversations/idem-keys.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 用户消息的幂等键：客户端的 `clientMessageId` 加前缀，与运行流水线自用的幂等键分开，
+ * 避免客户端恰好选中内部键而命中别的事件。
+ */
+export declare const userMessageIdemKey: (clientMessageId: string) => string;

package/dist/conversations/idem-keys.js

@@ -0,0 +1,5 @@
+/**
+ * 用户消息的幂等键：客户端的 `clientMessageId` 加前缀，与运行流水线自用的幂等键分开，
+ * 避免客户端恰好选中内部键而命中别的事件。
+ */
+export const userMessageIdemKey = (clientMessageId) => `msg:${clientMessageId}`;

package/dist/conversations/job-ids.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the attachment cleanup had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The retired BullMQ repeatable scheduler of the cleanup (removed from Redis at worker start). */
+export declare const ATTACHMENT_CLEANUP_SCHEDULER_ID = "attachment-cleanup-hourly";

package/dist/conversations/job-ids.js

@@ -0,0 +1,6 @@
+/**
+ * The maintenance job scheduler ids the attachment cleanup had before becoming `@LockedCron` /
+ * `@LockedInterval` jobs (retired at worker start, `RETIRED_SCHEDULER_IDS`). A leaf module.
+ */
+/** The retired BullMQ repeatable scheduler of the cleanup (removed from Redis at worker start). */
+export const ATTACHMENT_CLEANUP_SCHEDULER_ID = "attachment-cleanup-hourly";

package/dist/conversations/outputs-read.d.ts

@@ -1,3 +1,5 @@
+import { ToolOutputs } from "../tools/outputs.js";
+import { ConversationAccess } from "./access.js";
 /** 一次最多返回的字符数（也是默认值）：大存档按字符分页取。 */
 export declare const OUTPUT_PAGE_MAX_CHARS = 200000;
 export interface OutputPage {
@@ -10,23 +12,21 @@ export interface OutputPage {
     /** 下一页的 offset；已到末尾为 null。 */
     next: number | null;
 }
-export interface ConversationOutputsDeps {
-    /** 会话可见性（与会话 SSE 流同一判定：`ConversationsService.isAccessible`）。 */
-    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
-    /** 读本会话未过期的存档（`ToolOutputs.load`）：不存在 / 过期 / 属于别的会话 → null。 */
-    load(scope: {
-        orgId: string;
-        conversationId: string;
-    }, id: string): Promise<string | null>;
-}
 /**
  * 网页读工具输出存档（运行标签看全文）：先按会话流的规则判定会话可见（不可见 → `conversation.not_found`），
  * 再只在这个会话的存档里找（别的会话 / 过期 → `conversation.output_not_found`）。
  * 按字符分页（单行可能就很长，按行分页不能保证页大小）；id 不是 UUID 时直接 404，不打到数据库。
  */
 export declare class ConversationOutputs {
-    private readonly d;
-    constructor(d: ConversationOutputsDeps);
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    private readonly access;
+    /** 读本会话未过期的存档：不存在 / 过期 / 属于别的会话 → null。 */
+    private readonly outputs;
+    constructor(
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    access: Pick<ConversationAccess, "isAccessible">, 
+    /** 读本会话未过期的存档：不存在 / 过期 / 属于别的会话 → null。 */
+    outputs: Pick<ToolOutputs, "load">);
     read(orgId: string, conversationId: string, viewerAccountId: string, outputId: string, page: {
         offset: number;
         limit: number;

package/dist/conversations/outputs-read.js

@@ -1,5 +1,17 @@
+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 { ToolOutputs } from "../tools/outputs.js";
 import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
 /** 一次最多返回的字符数（也是默认值）：大存档按字符分页取。 */
 export const OUTPUT_PAGE_MAX_CHARS = 200_000;
 const conversationNotFound = () => new ApiError("conversation.not_found", "Conversation not found");
@@ -9,19 +21,25 @@ const outputNotFound = () => new ApiError("conversation.output_not_found", "Outp
  * 再只在这个会话的存档里找（别的会话 / 过期 → `conversation.output_not_found`）。
  * 按字符分页（单行可能就很长，按行分页不能保证页大小）；id 不是 UUID 时直接 404，不打到数据库。
  */
-export class ConversationOutputs {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationOutputs = class ConversationOutputs {
+    access;
+    outputs;
+    constructor(
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    access, 
+    /** 读本会话未过期的存档：不存在 / 过期 / 属于别的会话 → null。 */
+    outputs) {
+        this.access = access;
+        this.outputs = outputs;
     }
     async read(orgId, conversationId, viewerAccountId, outputId, page) {
         if (!UUID_RE.test(conversationId))
             throw conversationNotFound();
-        if (!(await this.d.isAccessible(orgId, conversationId, viewerAccountId)))
+        if (!(await this.access.isAccessible(orgId, conversationId, viewerAccountId)))
             throw conversationNotFound();
         if (!UUID_RE.test(outputId))
             throw outputNotFound();
-        const content = await this.d.load({ orgId, conversationId }, outputId);
+        const content = await this.outputs.load({ orgId, conversationId }, outputId);
         if (content === null)
             throw outputNotFound();
         const offset = Math.min(page.offset, content.length);
@@ -34,4 +52,10 @@ export class ConversationOutputs {
             next: end < content.length ? end : null,
         };
     }
-}
+};
+ConversationOutputs = __decorate([
+    Injectable(),
+    __param(0, Inject(ConversationAccess)),
+    __param(1, Inject(ToolOutputs))
+], ConversationOutputs);
+export { ConversationOutputs };

package/dist/conversations/queue.d.ts

@@ -1,9 +1,10 @@
-import { type Transaction } from "kysely";
 import { type ModelRef } from "../agents/definition.js";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
-import { type AttachmentRef, type ConversationsService, type RunControl } from "./conversations.service.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import { type InvocationRecord, type RenderedInvocation } from "../skills/invoke.js";
+import type { AttachmentRef } from "./conversations.service.js";
 import { type AppendEvent, type EventLog } from "./event-log.js";
-import type { ConversationEvent } from "./events.js";
+import type { ConversationEvent, LogContentBlock } from "./events.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
@@ -18,7 +19,16 @@ export declare const QUEUE_MAX_ITEMS = 20;
  * the conversation, or the head item's skill can no longer be invoked (phase D Task 9).
  */
 export type QueuePauseReason = "run_ended" | "author_cannot_send" | "skill_not_invocable";
-type KernelTrx = Transaction<KernelDatabase>;
+/**
+ * A queued skill invocation (phase D Task 9), stored in `conversation_queue.skill`: the name the
+ * person invoked (`<plugin>:<name>` or bare) and the `user_message.skill` record rendered with it.
+ */
+export interface QueuedSkill {
+    invokedAs: string;
+    record: InvocationRecord;
+}
+/** The caller's transaction handle (the module helpers below run inside it). */
+type KernelTrx = KernelSchemaDb;
 /** A queued message as the API returns it. */
 export interface QueueItem {
     id: string;
@@ -68,7 +78,7 @@ export interface QueueInput {
         name: string;
     };
 }
-interface QueueRow {
+export interface QueueRow {
     id: string;
     conversation_id: string;
     account_id: string;
@@ -83,6 +93,25 @@ interface QueueRow {
     skill: unknown;
     created_at: Date;
 }
+export declare const COLUMNS: readonly ["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).
+ */
+export declare const noNul: (text: string) => string;
+export declare const itemNotFound: () => ApiError;
+export declare function toItem(r: QueueRow): QueueItem;
+/**
+ * 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).
+ */
+export declare function checkText(text: string, files: number, attachments: number, skill: boolean): void;
+/** The stored form of a rendered invocation and its first content block. */
+export declare function storedSkill(invokedAs: string, invoked: RenderedInvocation): {
+    skill: string;
+    first: LogContentBlock;
+};
 /** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
 export declare function queuedUserMessage(r: QueueRow): AppendEvent;
 /**
@@ -93,12 +122,23 @@ export declare function queuedUserMessage(r: QueueRow): AppendEvent;
  * (`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 declare function appendQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "append">, conversationId: string, r: QueueRow): Promise<{
+export declare function appendQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "appendIn">, conversationId: string, r: QueueRow): Promise<{
     event: ConversationEvent;
     switched: boolean;
 }>;
+/**
+ * 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.
+ */
+export declare function queuedSkillBlocked(t: KernelTrx, conversationId: string, r: Pick<QueueRow, "skill">): Promise<import("../skills/invoke.js").NotInvocableReason | null>;
 /** Pauses the queue with `reason` (inside `t`, holding the conversation row lock). */
 export declare function pauseQueueWith(t: KernelTrx, conversationId: string, reason: QueuePauseReason): Promise<void>;
+/** Whether a user_message with this client id is already in the log (inside `t`). */
+export declare function alreadySent(t: KernelTrx, conversationId: string, clientMessageId: string): Promise<boolean>;
+/** Clears the pause once the queue is empty (inside `t`, holding the conversation row lock). */
+export declare function unpauseIfEmpty(t: KernelTrx, conversationId: string): Promise<void>;
+export declare const queueFull: () => ApiError;
 /**
  * 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
@@ -107,7 +147,7 @@ export declare function pauseQueueWith(t: KernelTrx, conversationId: string, rea
  * stays queued and the queue pauses (`skill_not_invocable`): `{ paused }`. The caller notifies
  * after commit.
  */
-export declare function dispatchQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "append">, conversationId: string): Promise<{
+export declare function dispatchQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "appendIn">, conversationId: string): Promise<{
     event: ConversationEvent;
     switched: boolean;
 } | {
@@ -118,52 +158,4 @@ export declare function dispatchQueuedIn(t: KernelTrx, eventLog: Pick<EventLog,
  * (inside the terminal transaction, see `finishRunIn`).
  */
 export declare function pauseQueueIn(t: KernelTrx, conversationId: string): Promise<void>;
-export interface ConversationQueueDeps {
-    db: KernelDb;
-    eventLog: Pick<EventLog, "append" | "notify" | "publishChanged" | "findByIdem">;
-    conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkFilesSupported" | "checkPick" | "prepareQueuedSkill">;
-    runs?: Pick<RunControl, "ensureRun">;
-}
-/**
- * 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 d;
-    constructor(d: ConversationQueueDeps);
-    list(orgId: string, conversationId: string, accountId: string): Promise<{
-        items: QueueItem[];
-        paused: boolean;
-        pauseReason?: QueuePauseReason;
-    }>;
-    /**
-     * 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;
-    }>;
-    /**
-     * 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).
-     */
-    edit(orgId: string, conversationId: string, accountId: string, itemId: string, text: string): Promise<QueueItem>;
-    remove(orgId: string, conversationId: string, accountId: string, itemId: string): Promise<void>;
-    /**
-     * 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>;
-    /** "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;
-}
 export {};