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

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

@@ -1,16 +1,23 @@
 import { AgentLookup } from "../agents/agent-lookup.js";
 import type { ModelRef } from "../agents/definition.js";
+import type { AgentAvatar } from "../agents/profile.js";
+import { BackgroundTaskStopper } from "../background/stop.js";
 import type { TitleSource } from "../db/kernel-schema.js";
+import { ConversationDevices, type NewConversationDevice } from "../devices/conversation-devices.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 { ProviderRegistry } from "../runtime/providers.js";
 import { type RenderedInvocation, SkillInvoker } from "../skills/invoke.js";
 import { ConnectorContent } from "../tools/connector-content.js";
+import { type QuestionRecord, QuestionsService } from "../tools/questions.service.js";
 import { ConversationAccess } from "./access.js";
+import { type AgentTreeNode } from "./agent-tree.js";
 import { AttachmentsService } from "./attachments.service.js";
 import { EventLog } from "./event-log.js";
 import type { ConversationEvent, LogContentBlock } from "./events.js";
+import { type ImSenderContext } from "./message-context.js";
 import { type Selection } from "./selection.js";
 /** 对外的会话视图。 */
 export interface ConversationView {
@@ -31,12 +38,35 @@ export interface ConversationView {
     parentConversationId: string | null;
     /** A sub-agent's type as resolved at its first dispatch; null for any other conversation. */
     subagentType: string | null;
+    /** When the owner archived it; null = not archived (hidden from the default lists). */
+    archivedAt: Date | null;
+    /**
+     * The device it works in (environments spec §4.1 item 1); null while unbound (no sandbox
+     * provider when it was created, an anonymous IM sender's, or created before devices). A
+     * sub-agent's is null: it works in its root conversation's.
+     */
+    deviceId: string | null;
+    /**
+     * What the latest run is doing: `running` (queued or running), `waiting` (an approval or a
+     * question), else null. Only the list queries compute it; other responses carry null.
+     */
+    activity: "running" | "waiting" | null;
 }
+/** Escapes `\`, `%` and `_` so user text is matched literally by `LIKE … ESCAPE '\'`. */
+export declare function escapeLike(s: string): string;
 /** One agent's group in the sidebar list: the caller's newest conversations with that agent. */
 export interface ConversationGroup {
+    /**
+     * The agent's name and the avatar half of its profile, in the agents API's shape (the sidebar
+     * draws the group title from it without reading the agents list).
+     */
     agent: {
         id: string;
         name: string;
+        profile: {
+            avatar: AgentAvatar;
+            updatedAt: string;
+        };
     };
     /** max(updated_at) of the group's conversations. */
     latestAt: Date;
@@ -75,6 +105,8 @@ export interface SubagentView {
 export interface RunControl {
     /** 有未消费的消息且没有进行中的运行时投递一轮运行；返回 runId 或 null。 */
     ensureRun(conversationId: string): Promise<string | null>;
+    /** After a root's queue was unpaused: the wakes it held for its tree (agent map spec §5.3). */
+    wakeHeldTree(rootId: string): Promise<void>;
     /**
      * 运行是孤儿（会话锁空闲、任务已不存在，没有 worker 会收到中止广播）时直接把它写成 aborted，返回 true；
      * 否则返回 false。
@@ -87,6 +119,13 @@ export interface RunControl {
     abortWaiting(conversationId: string, runId: string, byAccountId: string): Promise<boolean>;
     /** 请求中止运行（广播到所有副本）。 */
     requestAbort(runId: string, byAccountId: string): Promise<void>;
+    /**
+     * Stops a sub-agent with its descendants (with `includeSelf: false` only the sub-agent
+     * conversations below); the number of runs asked to stop (agent map spec §6).
+     */
+    stopTree(conversationId: string, byAccountId: string, opts?: {
+        includeSelf?: boolean;
+    }): Promise<number>;
 }
 /** 消息附件引用（连接器 + 资源 URI）。 */
 export interface AttachmentRef {
@@ -110,6 +149,11 @@ export interface ResolvedExtra {
 export { userMessageIdemKey } from "./idem-keys.js";
 /** The longest conversation title (characters, after trimming). */
 export declare const CONVERSATION_TITLE_MAX_CHARS = 120;
+/**
+ * How far back a `before` page of events reaches past its `limit` for the start of a turn (history
+ * paging spec §2); a longer run starts mid-run.
+ */
+export declare const EVENTS_TURN_EXTEND = 2000;
 /** A user message as posted (`POST …/messages`, or the first message of `POST /conversations`). */
 export interface UserMessageInput {
     text: string;
@@ -129,6 +173,17 @@ export interface UserMessageInput {
     skill?: {
         name: string;
     };
+    /** The browser's IANA time zone and UI language (run context spec §3.4); IM sends none. */
+    timeZone?: string;
+    locale?: "zh" | "en";
+    /** An anonymous IM guest's IM profile name (run context spec §7); other senders: none. */
+    senderName?: string;
+    /**
+     * An IM message: the time zone and language the platform gave for the sender (channel@1
+     * `sender.timeZone` / `sender.locale`, checked and normalized by the inbound); they win over the
+     * account setting and the person's web language (run context spec §3.4).
+     */
+    im?: ImSenderContext;
 }
 /**
  * 会话：只有所有者可见；每次访问都实时复核 agent 对所有者仍可用（spec 3.6 R5），
@@ -150,6 +205,13 @@ export declare class ConversationsService {
     private readonly attachments;
     /** Renders a person's skill invocation (phase D). */
     private readonly invoker;
+    /** Stops a deleted conversation's background tasks. */
+    private readonly background;
+    /** The device a new conversation is bound to (environments spec §4.1 item 1). */
+    private readonly devices;
+    /** A starter's message skips the run's pending questions (reply-while-question spec §8.1). */
+    private readonly questions;
+    private readonly events;
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, eventLog: EventLog, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, 
     /** Starts and stops the conversation's runs. */
@@ -161,26 +223,40 @@ export declare class ConversationsService {
     /** Binds uploaded files to the conversation in the message's transaction. */
     attachments: Pick<AttachmentsService, "bindForMessage">, 
     /** Renders a person's skill invocation (phase D). */
-    invoker: Pick<SkillInvoker, "prepare">, txHost: TransactionHost);
+    invoker: Pick<SkillInvoker, "prepare">, 
+    /** Stops a deleted conversation's background tasks. */
+    background: Pick<BackgroundTaskStopper, "stopForDeletedConversation">, 
+    /** The device a new conversation is bound to (environments spec §4.1 item 1). */
+    devices: Pick<ConversationDevices, "forNew">, 
+    /** A starter's message skips the run's pending questions (reply-while-question spec §8.1). */
+    questions: Pick<QuestionsService, "skipPendingIn">, events: Pick<KernelEvents, "emit">, txHost: TransactionHost);
     /**
      * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
      * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
      */
     kickRun(conversationId: string): void;
-    /** 新建会话；agent 对该账号不可用 → `agent.not_found`。 */
-    create(orgId: string, accountId: string, agentId: string): Promise<ConversationView>;
+    /**
+     * Creates an empty conversation bound to its device (`pick`, see
+     * {@link ConversationDevices.forNew}); an agent the account cannot use →
+     * `agent.not_found`, a device it may not use → `device.not_found` /
+     * `device.unavailable`, and nothing is created.
+     */
+    create(orgId: string, accountId: string, agentId: string, pick?: NewConversationDevice): 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`.
+     * `events` are every event the create wrote, in seq order from seq 1 (a `model_switched` before
+     * the message when the send switched), so a client can seed the new conversation's log whole.
      */
     createWithMessage(orgId: string, accountId: string, agentId: string, input: UserMessageInput & {
         clientMessageId: string;
-    }): Promise<{
+    }, pick?: NewConversationDevice): Promise<{
         conversation: ConversationView;
         event: ConversationEvent;
+        events: ConversationEvent[];
         created: boolean;
     }>;
     /** The conversation row and its first message (undefined: a concurrent retry committed first). */
@@ -197,6 +273,24 @@ export declare class ConversationsService {
      * job never overwrites it. Publishes `changed: title`. `title` is already trimmed and checked.
      */
     rename(orgId: string, conversationId: string, accountId: string, title: string): Promise<ConversationView>;
+    /**
+     * Archives or unarchives a conversation (owner only, as {@link rename}). An archived
+     * conversation leaves the default lists but stays readable. Publishes `changed: archived`.
+     */
+    setArchived(orgId: string, conversationId: string, accountId: string, archived: boolean): Promise<ConversationView>;
+    /**
+     * Soft-deletes a conversation (owner only; a sub-agent's conversation is `conversation.read_only`):
+     * stops an active run, hides the conversation everywhere for its owner and drops its channel
+     * bindings, stops every running background task in its sandbox (its sub-agents' too; outside
+     * the delete's transaction, a task whose sandbox cannot be reached ends `lost` with
+     * `kill_pending`), then every active run of its sub-agent tree (agent map spec §10). The tasks
+     * are stopped after the conversation is marked deleted, so no finish
+     * (the stops' own, or one the poller writes meanwhile) can wake a run on it: `ensureRun` refuses a
+     * deleted conversation (the stops' finishes carry `stoppedBy: "deletion"` as well). The event
+     * log, runs and trajectory stay (super admins still see them).
+     */
+    remove(orgId: string, conversationId: string, accountId: string): Promise<void>;
+    private markDeleted;
     /** 读会话：非所有者、或 agent 已对所有者不可用 → `conversation.not_found`。 */
     get(orgId: string, conversationId: string, viewerAccountId: string): Promise<ConversationView>;
     /**
@@ -216,6 +310,9 @@ export declare class ConversationsService {
         after?: string;
         limit: number;
         agentId?: string;
+        archived?: boolean;
+        q?: string;
+        state?: "running" | "waiting";
     }): Promise<ConversationView[]>;
     /**
      * My chat conversations grouped by agent (the sidebar, UI refresh spec §5.9), in one statement.
@@ -228,9 +325,13 @@ export declare class ConversationsService {
         perGroup: number;
         limit: number;
         after?: string;
+        archived?: boolean;
+        q?: string;
+        state?: "running" | "waiting";
     }): Promise<{
         groups: ConversationGroup[];
         next: string | null;
+        archivedCount: number;
     }>;
     /**
      * The sub-agents of a conversation, newest first (sub-agents spec §14.3); owner only, as
@@ -248,17 +349,37 @@ export declare class ConversationsService {
         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}.
+     * The agent tree of a root conversation (agent map spec §8, §9.2): the root and every sub-agent
+     * below it with status, model, time, tokens and tool calls. Owner only, as {@link isAccessible};
+     * a sub-agent's id (not a root) is `conversation.not_found` too.
+     */
+    agentTree(orgId: string, conversationId: string, viewerAccountId: string): Promise<{
+        root: AgentTreeNode;
+    }>;
+    /**
+     * A conversation's token usage: its own `usage` events (compaction included) plus those of every
+     * sub-agent below it, at any depth (sub-agents spec §8.3, agent map spec §6: every descendant
+     * counts toward the root; `conversationTree`), 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.
+     * The conversation whose sandbox `conversationId` works in: a sub-agent's is its root
+     * conversation's at any depth (sub-agents spec §10.1, agent map spec §6), 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[]>;
+    /**
+     * The turn-aligned page of events before `beforeSeq` (`null`: the log's last page), with how
+     * many runs started before it ({@link EventLog.readTurnPageBefore}; history paging spec §2).
+     * Visibility as {@link get}; kicks a stalled run as {@link listEvents} does.
+     */
+    listEventsBefore(orgId: string, conversationId: string, viewerAccountId: string, beforeSeq: number | null, limit: number): Promise<{
+        events: ConversationEvent[];
+        turnsBefore: number;
+    }>;
     /**
      * 追加一条用户消息；带 `clientMessageId` 时重复提交返回同一事件。写入后调用 `ensureRun`：
      * 没有进行中的运行时投递一轮；运行中则由当前运行在步骤间隙吸收，或在它结束时再次 `ensureRun`。
@@ -273,15 +394,19 @@ export declare class ConversationsService {
      * `text` 为空时（只发附件，HTTP 层保证此时有 `files` 且没有 `@` 资源）不写文本块。
      */
     postUserMessage(orgId: string, conversationId: string, accountId: string, input: UserMessageInput): Promise<ConversationEvent>;
-    /** A message with files or a model switch: binds the files and writes it in one transaction. */
+    /**
+     * Writes a message in one transaction: binds its files, reads its sender context and appends it
+     * (after its `model_switched` when it switches).
+     */
     private postIn;
     /**
      * 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.
+     * (`validation_failed`). Resolving is the agent editor's check, for the org (its effective
+     * provider config, spec B §5.5) and its disabled lists: a model the platform or the org disabled,
+     * or a non-chat model, is refused (spec B §5.3), as the run worker's `fallBackIfUnavailable` falls
+     * back from it.
      */
     private planSwitch;
     /**
@@ -290,9 +415,27 @@ export declare class ConversationsService {
      * 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>;
+    /**
+     * Skips, in the caller's transaction (it wrote `accountId`'s message at `messageSeq` and holds the
+     * conversation row lock), the pending questions that message closes (reply-while-question spec
+     * §8.1). The queue's "send now" uses it as the direct send does; announce after the commit with
+     * {@link announceSkipped}.
+     */
+    skipQuestionsIn(conversationId: string, accountId: string, messageSeq: number): Promise<{
+        records: QuestionRecord[];
+        toSeq: number | null;
+    }>;
+    /**
+     * After the commit: announces each skipped question (`question.answered`, outcome `skipped`), so
+     * its run resumes (waits) and its IM card updates (channel jobs).
+     */
+    announceSkipped(records: readonly QuestionRecord[]): 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.
+     * `conversations.selection`; returns the events written, in seq order (the `user_message`
+     * last). A message this call newly wrote (not a retry's deduped one) then skips the pending
+     * questions its author may answer (reply-while-question spec §8.1): `skipped` and the highest
+     * seq their events took. The caller notifies and emits `question.answered` after commit.
      */
     private writeMessage;
     /**
@@ -318,6 +461,11 @@ export declare class ConversationsService {
      * 中止会话当前的运行（queued / running / waiting）：返回 runId；没有 → `run.not_active`。
      * 等人处理的运行没有 worker：直接取消等待并写终态。其余经 Redis 广播，运行所在的任意副本都会收到；
      * 运行已是孤儿（没有任何 worker 在执行）时直接写终态。
+     *
+     * A root conversation's stop stops only its own run: its background sub-agents keep working
+     * (agent map spec §6). A sub-agent's conversation (its owner, from the agent map) stops that
+     * sub-agent with every descendant (`RunControl.stopTree`); `run.not_active` when nothing in that
+     * subtree runs, else the sub-agent's latest run id.
      */
     abort(orgId: string, conversationId: string, accountId: string): Promise<string>;
 }