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

package/dist/conversations/files.d.ts

@@ -0,0 +1,92 @@
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { StorageService } from "../storage/storage.service.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
+ * every request (no cache); `status` comes from the object store.
+ */
+/** Versions listed per file (newest first). */
+export declare const FILE_VERSIONS_MAX = 20;
+/** Largest `limit` of the files list. */
+export declare const FILES_PAGE_MAX = 100;
+/** Largest `limit` (bytes) of the text content route. */
+export declare const FILE_CONTENT_MAX_BYTES: number;
+export interface FileOutput {
+    /** artifactId of the latest version. */
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    sourcePath: string;
+    /** 1-based count of deliveries with the same sourcePath, in log order. */
+    version: number;
+    /** Newest first, at most {@link FILE_VERSIONS_MAX}. */
+    versions: {
+        id: string;
+        size: number;
+        createdAt: Date;
+    }[];
+    callId: string;
+    createdAt: Date;
+    /** `removed`: the latest version's object is gone from storage (decision 8). */
+    status: "available" | "removed";
+    previewable: "image" | "text" | null;
+}
+/** Text content of one file version, at most the requested bytes. */
+export interface FileContent {
+    body: Buffer;
+    /**
+     * Always `text/plain; charset=utf-8`: agent output is never served as a script, stylesheet or
+     * page on the app origin (review I2).
+     */
+    contentType: string;
+    /** The stored type without parameters (sent as `X-Content-Original-Type`). */
+    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 checkAccess;
+    /** Every delivery of the conversation in log order. */
+    private deliveries;
+    /**
+     * Files newest first by their **first** delivery, so a new version keeps the file's place and a
+     * cursor stays stable while files are re-delivered (review M2). `after` is a file id from the
+     * previous page (any version's id finds its file); a cursor that names no file gives an empty
+     * page. Storage HEADs run at most {@link HEAD_CONCURRENCY} at a time.
+     */
+    list(orgId: string, conversationId: string, viewer: string, opts: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        files: FileOutput[];
+        next: string | null;
+    }>;
+    /**
+     * One file version of the conversation (any version's id) with its object key, after checking
+     * the viewer can read the conversation. For the kernel only (previewers, embed grants): the key
+     * never leaves the kernel.
+     */
+    file(orgId: string, conversationId: string, viewer: string, fileId: string): Promise<{
+        id: string;
+        name: string;
+        contentType: string;
+        size: number;
+        objectKey: string;
+    }>;
+    /**
+     * The first `limit` bytes of a text file version (any version's id). Not text, or NUL bytes in
+     * what was read → `conversation.artifact_not_previewable`; the object is gone →
+     * `conversation.artifact_removed`. A cut never splits a UTF-8 character.
+     */
+    content(orgId: string, conversationId: string, viewer: string, fileId: string, limit: number): Promise<FileContent>;
+}

package/dist/conversations/files.js

@@ -0,0 +1,213 @@
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { UUID_RE } from "../ui/registry.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
+ * (`artifact_created`), grouped by `sourcePath` into versions, newest first. Read from the log on
+ * every request (no cache); `status` comes from the object store.
+ */
+/** Versions listed per file (newest first). */
+export const FILE_VERSIONS_MAX = 20;
+/** Largest `limit` of the files list. */
+export const FILES_PAGE_MAX = 100;
+/** Largest `limit` (bytes) of the text content route. */
+export const FILE_CONTENT_MAX_BYTES = 1024 * 1024;
+const conversationNotFound = () => new ApiError("conversation.not_found", "Conversation not found");
+const artifactNotFound = () => new ApiError("conversation.artifact_not_found", "Artifact not found");
+/** Drops an incomplete UTF-8 sequence at the end of a cut buffer. */
+function trimUtf8(b) {
+    let i = b.length - 1;
+    let cont = 0;
+    while (i >= 0 && cont < 3 && (b[i] & 0xc0) === 0x80) {
+        i--;
+        cont++;
+    }
+    if (i < 0)
+        return b;
+    const lead = b[i];
+    const need = lead >= 0xf0 ? 3 : lead >= 0xe0 ? 2 : lead >= 0xc0 ? 1 : 0;
+    return need > cont ? b.subarray(0, i) : b;
+}
+async function readPrefix(body, max) {
+    const reader = body.getReader();
+    const chunks = [];
+    let n = 0;
+    try {
+        while (n < max) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const take = value.subarray(0, Math.min(value.byteLength, max - n));
+            chunks.push(take);
+            n += take.byteLength;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return Buffer.concat(chunks, n);
+}
+/** Storage HEADs a files list sends at once (review M1). */
+export const HEAD_CONCURRENCY = 8;
+/** `Promise.all(xs.map(fn))` with at most `limit` calls in flight; results in input order. */
+async function mapLimit(xs, limit, fn) {
+    const out = new Array(xs.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= xs.length)
+                return;
+            out[i] = await fn(xs[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, xs.length) }, worker));
+    return out;
+}
+export class ConversationFiles {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async checkAccess(orgId, conversationId, viewer) {
+        if (!UUID_RE.test(conversationId))
+            throw conversationNotFound();
+        if (!(await this.d.isAccessible(orgId, conversationId, viewer)))
+            throw conversationNotFound();
+    }
+    /** Every delivery of the conversation in log order. */
+    async deliveries(conversationId) {
+        const rows = await this.d.db
+            .selectFrom("conversation_events")
+            .select(["payload", "created_at"])
+            .where("conversation_id", "=", conversationId)
+            .where("type", "=", "artifact_created")
+            .orderBy("seq")
+            .execute();
+        return rows.map((r) => ({
+            ...r.payload,
+            createdAt: r.created_at,
+        }));
+    }
+    /**
+     * Files newest first by their **first** delivery, so a new version keeps the file's place and a
+     * cursor stays stable while files are re-delivered (review M2). `after` is a file id from the
+     * previous page (any version's id finds its file); a cursor that names no file gives an empty
+     * page. Storage HEADs run at most {@link HEAD_CONCURRENCY} at a time.
+     */
+    async list(orgId, conversationId, viewer, opts) {
+        await this.checkAccess(orgId, conversationId, viewer);
+        const groups = new Map();
+        for (const d of await this.deliveries(conversationId)) {
+            // insertion order = first delivery (oldest first)
+            const g = groups.get(d.sourcePath) ?? [];
+            g.push(d);
+            groups.set(d.sourcePath, g);
+        }
+        const ordered = [...groups.values()].reverse();
+        let start = 0;
+        if (opts.after !== undefined) {
+            const after = opts.after;
+            const at = ordered.findIndex((g) => g.some((d) => d.artifactId === after));
+            if (at < 0)
+                return { files: [], next: null };
+            start = at + 1;
+        }
+        const page = ordered.slice(start, start + opts.limit);
+        const store = this.d.storage.kernel(orgId);
+        const files = await mapLimit(page, HEAD_CONCURRENCY, async (g) => {
+            const latest = g.at(-1);
+            const head = await store.head(latest.objectKey);
+            return {
+                id: latest.artifactId,
+                name: latest.name,
+                contentType: latest.contentType,
+                size: latest.size,
+                sourcePath: latest.sourcePath,
+                version: g.length,
+                versions: g
+                    .slice(-FILE_VERSIONS_MAX)
+                    .reverse()
+                    .map((d) => ({ id: d.artifactId, size: d.size, createdAt: d.createdAt })),
+                callId: latest.callId,
+                createdAt: latest.createdAt,
+                status: head ? "available" : "removed",
+                previewable: isInlineArtifactType(latest.contentType)
+                    ? "image"
+                    : isTextArtifactType(latest.contentType)
+                        ? "text"
+                        : null,
+            };
+        });
+        const next = start + opts.limit < ordered.length ? (files.at(-1)?.id ?? null) : null;
+        return { files, next };
+    }
+    /**
+     * One file version of the conversation (any version's id) with its object key, after checking
+     * the viewer can read the conversation. For the kernel only (previewers, embed grants): the key
+     * never leaves the kernel.
+     */
+    async file(orgId, conversationId, viewer, fileId) {
+        await this.checkAccess(orgId, conversationId, viewer);
+        if (!UUID_RE.test(fileId))
+            throw artifactNotFound();
+        const row = await this.d.db
+            .selectFrom("conversation_events")
+            .select("payload")
+            .where("conversation_id", "=", conversationId)
+            .where("type", "=", "artifact_created")
+            .where(sql `payload->>'artifactId'`, "=", fileId)
+            .limit(1)
+            .executeTakeFirst();
+        if (!row)
+            throw artifactNotFound();
+        const a = row.payload;
+        return {
+            id: a.artifactId,
+            name: a.name,
+            contentType: a.contentType,
+            size: a.size,
+            objectKey: a.objectKey,
+        };
+    }
+    /**
+     * The first `limit` bytes of a text file version (any version's id). Not text, or NUL bytes in
+     * what was read → `conversation.artifact_not_previewable`; the object is gone →
+     * `conversation.artifact_removed`. A cut never splits a UTF-8 character.
+     */
+    async content(orgId, conversationId, viewer, fileId, limit) {
+        await this.checkAccess(orgId, conversationId, viewer);
+        if (!UUID_RE.test(fileId))
+            throw artifactNotFound();
+        const row = await this.d.db
+            .selectFrom("conversation_events")
+            .select("payload")
+            .where("conversation_id", "=", conversationId)
+            .where("type", "=", "artifact_created")
+            .where(sql `payload->>'artifactId'`, "=", fileId)
+            .limit(1)
+            .executeTakeFirst();
+        if (!row)
+            throw artifactNotFound();
+        const a = row.payload;
+        if (!isTextArtifactType(a.contentType)) {
+            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
+            .kernel(orgId)
+            .get(a.objectKey, { range: { start: 0, end: max - 1 } });
+        if (!got)
+            throw new ApiError("conversation.artifact_removed", "The file is no longer available");
+        let body = await readPrefix(got.body, max);
+        if (body.includes(0)) {
+            throw new ApiError("conversation.artifact_not_previewable", "This file contains binary data and has no text content");
+        }
+        const truncated = got.head.size > body.byteLength;
+        if (truncated)
+            body = trimUtf8(body);
+        const base = (a.contentType.split(";")[0] ?? "").trim().toLowerCase();
+        return { body, contentType: "text/plain; charset=utf-8", originalType: base, truncated };
+    }
+}

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

@@ -0,0 +1,34 @@
+/** 一次最多返回的字符数（也是默认值）：大存档按字符分页取。 */
+export declare const OUTPUT_PAGE_MAX_CHARS = 200000;
+export interface OutputPage {
+    id: string;
+    /** 本页正文：`[offset, offset + limit)` 个字符。 */
+    text: string;
+    offset: number;
+    /** 存档全文的字符数。 */
+    totalChars: number;
+    /** 下一页的 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);
+    read(orgId: string, conversationId: string, viewerAccountId: string, outputId: string, page: {
+        offset: number;
+        limit: number;
+    }): Promise<OutputPage>;
+}

package/dist/conversations/outputs-read.js

@@ -0,0 +1,37 @@
+import { ApiError } from "../errors.js";
+import { UUID_RE } from "../ui/registry.js";
+/** 一次最多返回的字符数（也是默认值）：大存档按字符分页取。 */
+export const OUTPUT_PAGE_MAX_CHARS = 200_000;
+const conversationNotFound = () => new ApiError("conversation.not_found", "Conversation not found");
+const outputNotFound = () => new ApiError("conversation.output_not_found", "Output not found or expired");
+/**
+ * 网页读工具输出存档（运行标签看全文）：先按会话流的规则判定会话可见（不可见 → `conversation.not_found`），
+ * 再只在这个会话的存档里找（别的会话 / 过期 → `conversation.output_not_found`）。
+ * 按字符分页（单行可能就很长，按行分页不能保证页大小）；id 不是 UUID 时直接 404，不打到数据库。
+ */
+export class ConversationOutputs {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async read(orgId, conversationId, viewerAccountId, outputId, page) {
+        if (!UUID_RE.test(conversationId))
+            throw conversationNotFound();
+        if (!(await this.d.isAccessible(orgId, conversationId, viewerAccountId)))
+            throw conversationNotFound();
+        if (!UUID_RE.test(outputId))
+            throw outputNotFound();
+        const content = await this.d.load({ orgId, conversationId }, outputId);
+        if (content === null)
+            throw outputNotFound();
+        const offset = Math.min(page.offset, content.length);
+        const end = Math.min(content.length, offset + page.limit);
+        return {
+            id: outputId,
+            text: content.slice(offset, end),
+            offset,
+            totalChars: content.length,
+            next: end < content.length ? end : null,
+        };
+    }
+}

package/dist/conversations/queue.d.ts

@@ -0,0 +1,169 @@
+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 AppendEvent, type EventLog } from "./event-log.js";
+import type { ConversationEvent } 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
+ * 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 declare const QUEUE_MAX_ITEMS = 20;
+/**
+ * Why a queue paused (0062): a run failed or was stopped, the head item's author can no longer use
+ * 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 message as the API returns it. */
+export interface QueueItem {
+    id: string;
+    text: string;
+    /** Uploaded files, bound to the conversation when queued. */
+    files: QueuedFile[];
+    /** `@` resources, read when queued (decision 15). */
+    attachments: {
+        connectorId: string;
+        name: string;
+        uri: string;
+    }[];
+    clientMessageId: string;
+    /** The model the message switches to when sent (null: no pick). */
+    model: ModelRef | null;
+    /** The effort the message switches to when sent (null: no pick). */
+    effort: string | null;
+    /**
+     * A skill invocation (phase D Task 9), rendered when queued; `text` is its arguments as typed.
+     * `name` is the name the person invoked.
+     */
+    skill?: {
+        name: string;
+        arguments: string;
+        mode: "inline" | "fork";
+    };
+    createdAt: Date;
+    /** Increasing in queue order (not dense: deleted items leave gaps). */
+    position: number;
+}
+export interface QueuedFile {
+    attachmentId: string;
+    name: string;
+    mediaType: string;
+}
+/** What `POST …/queue` takes (the message fields that can be queued). */
+export interface QueueInput {
+    text: string;
+    clientMessageId: string;
+    attachments?: AttachmentRef[];
+    files?: string[];
+    /** A model / effort pick, applied when the message is sent (as a direct send's). */
+    model?: ModelRef;
+    effort?: string;
+    /** Invoke this skill (phase D): rendered now, `text` is the arguments. */
+    skill?: {
+        name: string;
+    };
+}
+interface QueueRow {
+    id: string;
+    conversation_id: string;
+    account_id: string;
+    position: string;
+    text: string;
+    content: unknown;
+    attachments: unknown;
+    files: unknown;
+    client_message_id: string;
+    model: unknown;
+    effort: string | null;
+    skill: unknown;
+    created_at: Date;
+}
+/** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
+export declare function queuedUserMessage(r: QueueRow): AppendEvent;
+/**
+ * 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 declare function appendQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "append">, conversationId: string, r: QueueRow): Promise<{
+    event: ConversationEvent;
+    switched: boolean;
+}>;
+/** Pauses the queue with `reason` (inside `t`, holding the conversation row lock). */
+export declare function pauseQueueWith(t: KernelTrx, conversationId: string, reason: QueuePauseReason): Promise<void>;
+/**
+ * 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 declare function dispatchQueuedIn(t: KernelTrx, eventLog: Pick<EventLog, "append">, conversationId: string): Promise<{
+    event: ConversationEvent;
+    switched: boolean;
+} | {
+    paused: QueuePauseReason;
+} | null>;
+/**
+ * Pauses the queue of a conversation whose run just failed or was stopped, when it holds items
+ * (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 {};