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

package/dist/conversations/conversations.service.d.ts

@@ -0,0 +1,321 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import { type AgentsService } from "../agents/agents.service.js";
+import type { ModelRef } from "../agents/definition.js";
+import type { KernelDatabase, KernelDb, TitleSource } from "../db/kernel-schema.js";
+import type { ProviderRegistry } from "../runtime/providers.js";
+import type { RenderedInvocation, SkillInvoker } from "../skills/invoke.js";
+import type { EventLog } from "./event-log.js";
+import type { ConversationEvent, LogContentBlock } from "./events.js";
+import { type Selection } from "./selection.js";
+/** 对外的会话视图。 */
+export interface ConversationView {
+    id: string;
+    orgId: string;
+    agentId: string;
+    accountId: string;
+    title: string | null;
+    /** Who wrote `title`: the title job, a rename, or nobody yet (UI refresh B). */
+    titleSource: TitleSource | null;
+    /** The model / effort the person switched to (UI refresh B); nulls = the agent's own. */
+    selection: Selection;
+    /** 已写入的最大事件 seq。 */
+    lastSeq: number;
+    createdAt: Date;
+    updatedAt: Date;
+    /** A sub-agent's parent conversation; null for any other conversation (sub-agents spec §14.3). */
+    parentConversationId: string | null;
+    /** A sub-agent's type as resolved at its first dispatch; null for any other conversation. */
+    subagentType: string | null;
+}
+/** One agent's group in the sidebar list: the caller's newest conversations with that agent. */
+export interface ConversationGroup {
+    agent: {
+        id: string;
+        name: string;
+    };
+    /** max(updated_at) of the group's conversations. */
+    latestAt: Date;
+    /** At most `perGroup`, updated_at DESC, id DESC. */
+    conversations: ConversationView[];
+    /** The group has more than `perGroup` conversations. */
+    more: boolean;
+}
+/** Token usage, the four fields of a `usage` event. */
+export interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/**
+ * One sub-agent of a conversation (sub-agents spec §14.3). `status`, `toolCalls`, `startedAt` and
+ * `finishedAt` describe its latest run (the newest dispatch, a follow-up included); `description` is
+ * that dispatch's; `usage` sums all of its runs; the pending ids are its open approvals and
+ * questions.
+ */
+export interface SubagentView {
+    /** The child conversation's id. */
+    id: string;
+    agentType: string;
+    description: string;
+    status: "queued" | "running" | "waiting" | "completed" | "failed" | "aborted";
+    toolCalls: number;
+    startedAt: string;
+    finishedAt: string | null;
+    usage: UsageTotals;
+    pendingApprovalIds: string[];
+    pendingQuestionIds: string[];
+}
+/** 会话服务用到的运行控制：投递运行（RunQueue）与跨副本中止（RunAbort）。 */
+export interface RunControl {
+    /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
+    ensureRun(conversationId: string): Promise<string | null>;
+    /**
+     * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
+     * 否则返回 false。
+     */
+    abortIfOrphaned(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
+    /**
+     * 运行在等人处理（waiting）时直接中止：取消等待、写 `run_aborted`、删除 checkpoint，返回 true；
+     * 运行已不是 waiting（例如刚被续跑）→ false。
+     */
+    abortWaiting(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
+    /** 请求中止运行（广播到所有副本）。 */
+    requestAbort(runId: string, byAccountId: string): Promise<void>;
+}
+/** 消息附件引用（连接器 + 资源 URI）。 */
+export interface AttachmentRef {
+    connectorId: string;
+    uri: string;
+}
+/** 附件解析：以发送者的凭据读取资源，返回追加在消息后的文本块与元数据（见 tools/connector-content.ts）。 */
+export type ResolveAttachments = (orgId: string, accountId: string, refs: AttachmentRef[]) => Promise<ResolvedExtra>;
+/** Resolved `@` resources: the blocks after the user text and their metadata. */
+export interface ResolvedExtra {
+    blocks: {
+        type: "text";
+        text: string;
+    }[];
+    /** 写进 user_message 的附件元数据：事件 payload 字段名仍为 `appId` / `appName`（C27）。 */
+    attachments: {
+        appId: string;
+        appName: string;
+        uri: string;
+        name: string;
+    }[];
+}
+/**
+ * 消息引用的上传附件（`files`）：在发消息的事务里校验并绑定到会话，返回写进 user_message 的媒体块
+ * （`source: {kind: "ref"}`，见 AttachmentsService.bindForMessage）。
+ */
+export type BindFiles = (trx: Transaction<KernelDatabase>, orgId: string, conversationId: string, accountId: string, ids: readonly string[]) => Promise<LogContentBlock[]>;
+/**
+ * 用户消息的幂等键：客户端的 `clientMessageId` 加前缀，与运行流水线自用的幂等键分开，
+ * 避免客户端恰好选中内部键而命中别的事件。
+ */
+export declare const userMessageIdemKey: (clientMessageId: string) => string;
+/** The longest conversation title (characters, after trimming). */
+export declare const CONVERSATION_TITLE_MAX_CHARS = 120;
+/** A user message as posted (`POST …/messages`, or the first message of `POST /conversations`). */
+export interface UserMessageInput {
+    text: string;
+    clientMessageId?: string;
+    attachments?: AttachmentRef[];
+    files?: string[];
+    /** Switch the conversation's model from the next run (the agent's own model = back to it). */
+    model?: ModelRef;
+    /** Switch the effort (one of the model's declared `effort` values). */
+    effort?: string;
+    /** A retry after a failed run: the seq of the repeated message (display only). */
+    retryOf?: number;
+    /**
+     * Invoke this skill of the agent (phase D, `/name args`): `text` is the arguments, and the
+     * rendered skill replaces it as `content[0]`.
+     */
+    skill?: {
+        name: string;
+    };
+}
+/**
+ * 会话：只有所有者可见；每次访问都实时复核 agent 对所有者仍可用（spec 3.6 R5），
+ * 不可用时会话也按不存在处理（`conversation.not_found`）。
+ */
+export declare class ConversationsService {
+    private readonly db;
+    private readonly eventLog;
+    private readonly agents;
+    private readonly runs?;
+    private readonly log?;
+    private readonly resolveAttachments?;
+    private readonly bindFiles?;
+    /** Resolves a switched-to model and its declared parameters (UI refresh B). */
+    private readonly models?;
+    /** Renders a person's skill invocation (phase D); without it `skill` is refused. */
+    private readonly invoker?;
+    constructor(db: KernelDb, eventLog: EventLog, agents: AgentsService, runs?: RunControl | undefined, log?: Pick<Logger, "warn"> | undefined, resolveAttachments?: ResolveAttachments | undefined, bindFiles?: BindFiles | undefined, 
+    /** Resolves a switched-to model and its declared parameters (UI refresh B). */
+    models?: Pick<ProviderRegistry, "resolve"> | undefined, 
+    /** Renders a person's skill invocation (phase D); without it `skill` is refused. */
+    invoker?: Pick<SkillInvoker, "prepare"> | undefined);
+    /**
+     * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
+     * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
+     */
+    kickRun(conversationId: string): void;
+    /** 新建会话；agent 对该账号不可用 → `agent.not_found`。 */
+    create(orgId: string, accountId: string, agentId: string): Promise<ConversationView>;
+    /**
+     * Creates a conversation together with its first message (UI refresh B, create on first send):
+     * the conversation row and the `user_message` are written in one transaction, keyed by the
+     * message's `clientMessageId` (`create_request_id`), so a retried send returns the same
+     * conversation and event with `created: false`. An agent the caller cannot use →
+     * `agent.not_found` and nothing is written. Queues a run afterwards, like `postUserMessage`.
+     */
+    createWithMessage(orgId: string, accountId: string, agentId: string, input: UserMessageInput & {
+        clientMessageId: string;
+    }): Promise<{
+        conversation: ConversationView;
+        event: ConversationEvent;
+        created: boolean;
+    }>;
+    /**
+     * The conversation (and its first event) an earlier first send with this id created. The id used
+     * for another agent's conversation → `conflict` (the caller only checked access to `agentId`, so
+     * the other conversation is never returned).
+     */
+    private findCreated;
+    private rowView;
+    /**
+     * Renames a conversation (owner only, as {@link get}): `title_source = 'manual'`, so the title
+     * job never overwrites it. Publishes `changed: title`. `title` is already trimmed and checked.
+     */
+    rename(orgId: string, conversationId: string, accountId: string, title: string): Promise<ConversationView>;
+    /** 读会话：非所有者、或 agent 已对所有者不可用 → `conversation.not_found`。 */
+    get(orgId: string, conversationId: string, viewerAccountId: string): Promise<ConversationView>;
+    /**
+     * {@link get} for a change made by a person (a message, rename, queue, model switch): a
+     * sub-agent's conversation is read-only (sub-agents spec §6.1) → `conversation.read_only`.
+     */
+    writable(orgId: string, conversationId: string, accountId: string): Promise<ConversationView>;
+    /** {@link get}'s row, with the conversation's kind. */
+    private readable;
+    /**
+     * 轻量的可见性判定（一条查询，不加载 agent 视图），供长连接（SSE）建立时与定期复核用：
+     * 会话属于该组织且归 viewer 所有、viewer 账号仍为 active、agent 未删除且对 viewer 仍可见
+     * （`visibleTo` 已含「组织未删除、viewer 仍是成员」）。
+     */
+    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
+    /**
+     * 我的会话，最近更新的在前；只含 agent 仍可用的会话。`after` 为上一页最后一个会话的 id，
+     * 从它当前的 (updated_at, id) 之后继续；游标会话已不存在时返回空页。
+     */
+    listMine(orgId: string, accountId: string, opts: {
+        after?: string;
+        limit: number;
+        agentId?: string;
+    }): Promise<ConversationView[]>;
+    /**
+     * My chat conversations grouped by agent (the sidebar, UI refresh spec §5.9), in one statement.
+     * Only agents that are not deleted and still visible to me (as {@link listMine}). Groups are
+     * ordered by (latestAt DESC, agent id DESC); each holds up to `perGroup` conversations and says
+     * whether it has more. `after` is the last group's agent id, re-evaluated against that group's
+     * current latestAt; a cursor agent that is no longer listed gives an empty page.
+     */
+    listGroups(orgId: string, accountId: string, opts: {
+        perGroup: number;
+        limit: number;
+        after?: string;
+    }): Promise<{
+        groups: ConversationGroup[];
+        next: string | null;
+    }>;
+    /**
+     * The sub-agents of a conversation, newest first (sub-agents spec §14.3); owner only, as
+     * {@link isAccessible} (else `conversation.not_found`). `after` is the previous page's last id,
+     * re-evaluated against its current position; a cursor that is not a sub-agent of this
+     * conversation gives an empty page. A row is listed even when its child is not accessible to the
+     * viewer (an org agent they can no longer see): its id is already in the parent's log, and opening
+     * the child still goes through {@link isAccessible}.
+     */
+    listSubagents(orgId: string, conversationId: string, viewerAccountId: string, opts: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        subagents: SubagentView[];
+        next: string | null;
+    }>;
+    /**
+     * A conversation's token usage: its own `usage` events (compaction included) plus those of its
+     * sub-agents (sub-agents spec §8.3), whose logs keep their own. Owner only, as {@link get}.
+     */
+    usage(orgId: string, conversationId: string, viewerAccountId: string): Promise<UsageTotals>;
+    /**
+     * The conversation whose sandbox `conversationId` works in: a sub-agent's is its parent's
+     * (sub-agents spec §10.1), any other its own. Call only after an access check.
+     */
+    sandboxConversationOf(orgId: string, conversationId: string): Promise<string>;
+    /** 读事件（先做 `get` 的可见性判定）；顺带不阻塞地 {@link kickRun}。 */
+    listEvents(orgId: string, conversationId: string, viewerAccountId: string, afterSeq: number, limit: number): Promise<ConversationEvent[]>;
+    /**
+     * 追加一条用户消息；带 `clientMessageId` 时重复提交返回同一事件。写入后调用 `ensureRun`：
+     * 没有进行中的运行时投递一轮；运行中则由当前运行在步骤间隙吸收，或在它结束时再次 `ensureRun`。
+     * 投递失败时抛错（消息已写入；客户端带同一 `clientMessageId` 重试会再次触发投递）。
+     *
+     * `attachments`（`@` 资源引用）：内核以发送者的凭据读取资源（打码、限长），作为用户文本之后的额外文本块写入同一条
+     * user_message，并在 `payload.attachments` 记录元数据（第 i 个附件对应 `content[i + 1]`）。读取失败整条不写。
+     * 带 `clientMessageId` 的重复提交直接返回已写入的事件，不再读取。
+     *
+     * `files`（上传的附件 id）：在写事件的同一事务里校验并绑定到本会话（见 {@link BindFiles}），作为 image /
+     * document 引用块追加在最后（`@` 资源块之后）；任一附件不可用则整条不写。日志里只有引用，没有字节。
+     * `text` 为空时（只发附件，HTTP 层保证此时有 `files` 且没有 `@` 资源）不写文本块。
+     */
+    postUserMessage(orgId: string, conversationId: string, accountId: string, input: UserMessageInput): Promise<ConversationEvent>;
+    /**
+     * The selection a message switches to, or null when it changes nothing. A model equal to the
+     * agent's means "back to the agent's model" (null); a model change without `effort` resets the
+     * effort. The target model must resolve (`agent.model_unavailable`) and declare the effort
+     * (`validation_failed`). Resolving is the agent editor's check: providers are deployment-scoped
+     * and serve chat models only. If per-org provider enablement is added, this check and the run
+     * worker's `fallBackIfUnavailable` must follow it.
+     */
+    private planSwitch;
+    /**
+     * Checks a queued message's model / effort pick by the direct send's rules (final review I1): the
+     * target model must resolve and declare the effort, against the selection in effect now. The
+     * queue re-plans it against the selection in effect at dispatch.
+     */
+    checkPick(orgId: string, conv: ConversationView, accountId: string, pick: Pick<UserMessageInput, "model" | "effort">): Promise<void>;
+    /**
+     * Writes the message (preceded by its `model_switched` when it switches) inside `t` and updates
+     * `conversations.selection`; returns the `user_message` event. The caller notifies after commit.
+     */
+    private writeMessage;
+    /**
+     * Renders the message's skill invocation (phase D), or undefined when it has none. Resolved
+     * against the agent's current version and, for an existing conversation, its trial drafts.
+     */
+    private prepareSkill;
+    /**
+     * Renders a queued message's skill invocation now (phase D Task 9), by the direct send's rules,
+     * against the agent's current version and the conversation's trial drafts; undefined without
+     * `skill`. The queue stores the result and sends it unchanged later.
+     */
+    prepareQueuedSkill(orgId: string, conv: ConversationView, accountId: string, input: Pick<UserMessageInput, "skill" | "text">): Promise<RenderedInvocation | undefined>;
+    /** `files` need the attachments service (shared with the queue). */
+    checkFilesSupported(input: Pick<UserMessageInput, "files">): void;
+    /**
+     * Reads the `@` resources with the sender's credentials (nothing when there are none). Shared
+     * with the queue, which reads them when a message is queued (decision 15).
+     */
+    resolveExtra(orgId: string, accountId: string, input: Pick<UserMessageInput, "attachments">): Promise<ResolvedExtra>;
+    /** Binds uploaded files inside the message's (or queue item's) transaction; none → no blocks. */
+    bindIn(t: Transaction<KernelDatabase>, orgId: string, conversationId: string, accountId: string, files: readonly string[]): Promise<LogContentBlock[]>;
+    private userMessage;
+    /**
+     * 中止会话当前的运行（queued / running / waiting）：返回 runId；没有 → `run.not_active`。
+     * 等人处理的运行没有 worker：直接取消等待并写终态。其余经 Redis 广播，运行所在的任意副本都会收到；
+     * 运行已是孤儿（没有任何 worker 在执行）时直接写终态。
+     */
+    abort(orgId: string, conversationId: string, accountId: string): Promise<string>;
+}