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

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

@@ -1,6 +1,8 @@
 import { AgentLookup } from "../agents/agent-lookup.js";
 import type { ModelRef } from "../agents/definition.js";
+import { BackgroundTaskStopper } from "../background/stop.js";
 import type { TitleSource } from "../db/kernel-schema.js";
+import { ConversationEnvironments, type NewConversationEnvironment } from "../environments/conversation-environments.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
@@ -8,6 +10,7 @@ import { ProviderRegistry } from "../runtime/providers.js";
 import { type RenderedInvocation, SkillInvoker } from "../skills/invoke.js";
 import { ConnectorContent } from "../tools/connector-content.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";
@@ -31,7 +34,22 @@ 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 environment 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 environments). A
+     * sub-agent's is null: it works in its root conversation's.
+     */
+    environmentId: 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 {
     agent: {
@@ -75,6 +93,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 +107,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 +137,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;
@@ -150,6 +182,10 @@ 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 environment a new conversation is bound to (environments spec §4.1 item 1). */
+    private readonly environments;
     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 +197,38 @@ 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 environment a new conversation is bound to (environments spec §4.1 item 1). */
+    environments: Pick<ConversationEnvironments, "forNew">, 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 environment (`pick`, see
+     * {@link ConversationEnvironments.forNew}); an agent the account cannot use →
+     * `agent.not_found`, an environment it may not use → `environment.not_found` /
+     * `environment.unavailable`, and nothing is created.
+     */
+    create(orgId: string, accountId: string, agentId: string, pick?: NewConversationEnvironment): 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?: NewConversationEnvironment): Promise<{
         conversation: ConversationView;
         event: ConversationEvent;
+        events: ConversationEvent[];
         created: boolean;
     }>;
     /** The conversation row and its first message (undefined: a concurrent retry committed first). */
@@ -197,6 +245,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 +282,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 +297,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 +321,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`。
@@ -292,7 +385,8 @@ export declare class ConversationsService {
     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.
+     * `conversations.selection`; returns the events written, in seq order (the `user_message`
+     * last). The caller notifies after commit.
      */
     private writeMessage;
     /**
@@ -318,6 +412,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>;
 }