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

package/dist/conversations/conversations.schemas.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** Shared by the list and groups queries: title search, run activity and the archived list. */
+export declare const searchFields: {
+    q: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodEnum<{
+        running: "running";
+        waiting: "waiting";
+    }>>;
+    archived: z.ZodOptional<z.ZodEnum<{
+        1: "1";
+    }>>;
+};
+export declare const ListQuery: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodEnum<{
+        running: "running";
+        waiting: "waiting";
+    }>>;
+    archived: z.ZodOptional<z.ZodEnum<{
+        1: "1";
+    }>>;
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    agentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const EventsQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    before: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"end">, z.ZodCoercedNumber<unknown>]>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/**
+ * A rename: 1–120 characters counted in code points after trimming, with no control or format
+ * (bidi, zero-width) characters, the same rule generated and tool titles follow.
+ */
+export declare const PatchBody: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const IdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const SubagentsQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const FilesQuery: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+/** The conversation routes a Platform operation mirrors (spec §14, conversations). */
+export declare const CONVERSATION_ROUTES: readonly RouteSchemas[];

package/dist/conversations/conversations.schemas.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { CONTROL_OR_HIDDEN_RE } from "../text.js";
+import { CONVERSATION_TITLE_MAX_CHARS } from "./conversations.service.js";
+import { FILES_PAGE_MAX } from "./files.js";
+/** Shared by the list and groups queries: title search, run activity and the archived list. */
+export const searchFields = {
+    q: z.string().min(1).max(100).optional(),
+    state: z.enum(["running", "waiting"]).optional(),
+    archived: z.enum(["1"]).optional(),
+};
+export const ListQuery = z.object({
+    after: z.string().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(200).default(50),
+    /** Only this agent's conversations (the sidebar's per-group "More"). */
+    agentId: z.string().min(1).max(100).optional(),
+    ...searchFields,
+});
+export const EventsQuery = z
+    .object({
+    after: z.coerce.number().int().min(0).optional(),
+    /** The page before this seq, or the log's last page (`end`); exclusive with `after`. */
+    before: z.union([z.literal("end"), z.coerce.number().int().min(1)]).optional(),
+    limit: z.coerce.number().int().min(1).max(500).default(500),
+})
+    .refine((q) => q.after === undefined || q.before === undefined, {
+    message: "after and before are exclusive",
+    path: ["before"],
+});
+/**
+ * A rename: 1–120 characters counted in code points after trimming, with no control or format
+ * (bidi, zero-width) characters, the same rule generated and tool titles follow.
+ */
+export const PatchBody = z
+    .object({
+    title: z
+        .string()
+        .max(CONVERSATION_TITLE_MAX_CHARS * 2 + 100)
+        .trim()
+        .refine((t) => t.length > 0, "title must not be empty")
+        .refine((t) => Array.from(t).length <= CONVERSATION_TITLE_MAX_CHARS, `title must be at most ${CONVERSATION_TITLE_MAX_CHARS} characters`)
+        .refine((t) => !CONTROL_OR_HIDDEN_RE.test(t), "title must not contain control or format characters")
+        .optional(),
+    /** true archives (hidden from the default lists), false unarchives. */
+    archived: z.boolean().optional(),
+})
+    .strict()
+    .refine((b) => b.title !== undefined || b.archived !== undefined, "title or archived is required");
+export const IdParams = z.object({ id: z.string().min(1).max(100) });
+export const SubagentsQuery = z.object({
+    /** The previous page's last sub-agent id (`next`). */
+    after: z.string().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export const FilesQuery = z.object({
+    after: z.string().min(1).max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(FILES_PAGE_MAX).default(50),
+});
+/** The conversation routes a Platform operation mirrors (spec §14, conversations). */
+export const CONVERSATION_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/conversations", query: ListQuery },
+    { route: "GET /api/v1/orgs/:orgId/conversations/:id", params: IdParams },
+    {
+        route: "GET /api/v1/orgs/:orgId/conversations/:id/events",
+        params: IdParams,
+        query: EventsQuery,
+    },
+    { route: "PATCH /api/v1/orgs/:orgId/conversations/:id", params: IdParams, body: PatchBody },
+    { route: "DELETE /api/v1/orgs/:orgId/conversations/:id", params: IdParams },
+    {
+        route: "GET /api/v1/orgs/:orgId/conversations/:id/subagents",
+        params: IdParams,
+        query: SubagentsQuery,
+    },
+    { route: "GET /api/v1/orgs/:orgId/conversations/:id/agent-tree", params: IdParams },
+    { route: "GET /api/v1/orgs/:orgId/conversations/:id/usage", params: IdParams },
+    { route: "GET /api/v1/orgs/:orgId/conversations/:id/files", params: IdParams, query: FilesQuery },
+    { route: "GET /api/v1/orgs/:orgId/conversations/:id/environment", params: IdParams },
+    { route: "POST /api/v1/orgs/:orgId/conversations/:id/abort", params: IdParams },
+];

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

@@ -1,12 +1,20 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import { type AgentsService } from "../agents/agents.service.js";
+import { AgentLookup } from "../agents/agent-lookup.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 { 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";
+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";
+import { type ImSenderContext } from "./message-context.js";
 import { type Selection } from "./selection.js";
 /** 对外的会话视图。 */
 export interface ConversationView {
@@ -27,7 +35,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: {
@@ -71,6 +94,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。
@@ -83,14 +108,19 @@ 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 {
     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: {
@@ -105,18 +135,14 @@ export interface ResolvedExtra {
         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;
+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;
@@ -136,6 +162,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），
@@ -145,40 +182,69 @@ 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?;
+    private readonly access;
+    /** Starts and stops the conversation's runs. */
+    private readonly runs;
     /** 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, 
+    private readonly providers;
+    private readonly log;
+    /** Reads `@` resources with the sender's credentials. */
+    private readonly content;
+    /** Binds uploaded files to the conversation in the message's transaction. */
+    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. */
+    runs: RunControl, 
     /** 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);
+    providers: Pick<ProviderRegistry, "resolve">, log: Pick<KernelLogger, "warn">, 
+    /** Reads `@` resources with the sender's credentials. */
+    content: Pick<ConnectorContent, "resolveAttachments">, 
+    /** 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">, 
+    /** 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). */
+    private createIn;
     /**
      * 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
@@ -191,6 +257,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>;
     /**
@@ -200,11 +284,7 @@ export declare class ConversationsService {
     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 仍是成员」）。
-     */
+    /** The stream's visibility check ({@link ConversationAccess.isAccessible}). */
     isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
     /**
      * 我的会话，最近更新的在前；只含 agent 仍可用的会话。`after` 为上一页最后一个会话的 id，
@@ -214,6 +294,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.
@@ -226,9 +309,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
@@ -246,17 +333,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`。
@@ -271,13 +378,19 @@ export declare class ConversationsService {
      * `text` 为空时（只发附件，HTTP 层保证此时有 `files` 且没有 `@` 资源）不写文本块。
      */
     postUserMessage(orgId: string, conversationId: string, accountId: string, input: UserMessageInput): Promise<ConversationEvent>;
+    /**
+     * 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;
     /**
@@ -288,7 +401,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;
     /**
@@ -302,20 +416,23 @@ export declare class ConversationsService {
      * `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[]>;
+    bindIn(orgId: string, conversationId: string, accountId: string, files: readonly string[]): Promise<LogContentBlock[]>;
     private userMessage;
     /**
      * 中止会话当前的运行（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>;
 }