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

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

@@ -28,6 +28,16 @@ export declare const MAX_PENDING_SKILL_PACKAGES = 5;
  * `POST /skills` 开始处理时再顺延这么久，处理期间不会被清理。
  */
 export declare const SKILL_PACKAGE_TTL_HOURS = 1;
+/** The image types an agent avatar upload may have (cropped square in the browser). */
+export declare const AGENT_AVATAR_CONTENT_TYPES: readonly ["image/png", "image/jpeg", "image/webp"];
+/** The size limit of an agent avatar upload (bytes). */
+export declare const AGENT_AVATAR_MAX_BYTES: number;
+/** Unfinished avatar uploads one account may have in an org (counted apart from other uploads). */
+export declare const MAX_PENDING_AGENT_AVATARS = 10;
+/** An avatar upload not saved into a profile expires (and is cleaned up) after this many hours. */
+export declare const AGENT_AVATAR_TTL_HOURS = 24;
+/** Download redirect lifetime of an avatar (seconds); also its `Cache-Control` max-age. */
+export declare const AGENT_AVATAR_DOWNLOAD_TTL_SECONDS = 300;
 /**
  * 技能包解出的文件在 `kernel/<orgId>/` 下的前缀：按上传 id，同一上传重试写到同一批键（幂等），
  * 并发处理同一上传也不会互相覆盖出不同内容。版本行记下这个前缀（`skill_versions.object_prefix`）。
@@ -169,6 +179,26 @@ export declare class AttachmentsService {
      * 不是该账号的 ready 技能包（如已被并发的请求用掉）→ `attachment.not_found`。
      */
     consumeSkillPackage(orgId: string, accountId: string, id: string): Promise<void>;
+    /**
+     * Makes an agent avatar upload ready to be saved into a profile (outside any transaction: it may
+     * read the object store): only the uploader, only the `agent-avatar` purpose, an image type, not
+     * expired and not yet used by another agent, else `attachment.not_found`. An upload still
+     * `pending` is finalized first (size, type and the image signature are checked). The expiry is
+     * extended so the cleanup job cannot delete it before {@link consumeAgentAvatar} runs.
+     */
+    prepareAgentAvatar(orgId: string, accountId: string, id: string, agentId: string): Promise<void>;
+    /**
+     * In the caller's transaction, binds a ready avatar upload to `agentId` (row lock; the expiry is
+     * cleared, so the cleanup job keeps it while the profile uses it). An upload another agent
+     * already uses, or one that is not the account's ready avatar → `attachment.not_found`; saving
+     * the same upload to the same agent again is fine.
+     */
+    consumeAgentAvatar(orgId: string, accountId: string, id: string, agentId: string): Promise<void>;
+    /**
+     * A short-lived presigned GET (inline, with the checked image type) of the avatar upload bound
+     * to `agentId`; `null` when there is none or its object is gone or no longer the finalized one.
+     */
+    agentAvatarUrl(orgId: string, agentId: string, id: string): Promise<string | null>;
     /**
      * 删除过期（`expires_at < now()`）且从未绑定到会话的附件：先把行认领为 `deleting`（`FOR UPDATE SKIP LOCKED`，
      * 多副本并发时互不重复），再删对象、删行。删对象失败的行保持 `deleting`，下次运行重试。

package/dist/conversations/attachments.service.js

@@ -40,6 +40,16 @@ export const MAX_PENDING_SKILL_PACKAGES = 5;
  * `POST /skills` 开始处理时再顺延这么久，处理期间不会被清理。
  */
 export const SKILL_PACKAGE_TTL_HOURS = 1;
+/** The image types an agent avatar upload may have (cropped square in the browser). */
+export const AGENT_AVATAR_CONTENT_TYPES = ["image/png", "image/jpeg", "image/webp"];
+/** The size limit of an agent avatar upload (bytes). */
+export const AGENT_AVATAR_MAX_BYTES = 2 * 1024 * 1024;
+/** Unfinished avatar uploads one account may have in an org (counted apart from other uploads). */
+export const MAX_PENDING_AGENT_AVATARS = 10;
+/** An avatar upload not saved into a profile expires (and is cleaned up) after this many hours. */
+export const AGENT_AVATAR_TTL_HOURS = 24;
+/** Download redirect lifetime of an avatar (seconds); also its `Cache-Control` max-age. */
+export const AGENT_AVATAR_DOWNLOAD_TTL_SECONDS = 300;
 /**
  * 技能包解出的文件在 `kernel/<orgId>/` 下的前缀：按上传 id，同一上传重试写到同一批键（幂等），
  * 并发处理同一上传也不会互相覆盖出不同内容。版本行记下这个前缀（`skill_versions.object_prefix`）。
@@ -56,7 +66,11 @@ const notFound = () => new ApiError("attachment.not_found", "Attachment not foun
 export const normalizeContentType = (ct) => (ct.split(";")[0] ?? "").trim().toLowerCase();
 const isImage = (ct) => IMAGE_MEDIA_TYPES.includes(ct);
 /** 对象键：只用附件 id，用户的文件名不进键。技能包另放 `skill-packages/<id>`。 */
-const objectKey = (id, purpose = "chat") => purpose === "chat" ? `attachments/${id}` : `skill-packages/${id}`;
+const objectKey = (id, purpose = "chat") => purpose === "chat"
+    ? `attachments/${id}`
+    : purpose === "agent-avatar"
+        ? `agent-avatars/${id}`
+        : `skill-packages/${id}`;
 const startsWith = (b, sig, at = 0) => sig.every((x, i) => b[at + i] === x);
 const ascii = (s) => [...s].map((c) => c.charCodeAt(0));
 /** 文件开头是否与声明的类型相符（图片与 PDF 看签名，文本不能含 NUL）。 */
@@ -139,12 +153,19 @@ let AttachmentsService = class AttachmentsService {
         const cfg = this.config.get().attachments;
         const contentType = normalizeContentType(input.contentType);
         const skill = purpose === "skill-package";
+        const avatar = purpose === "agent-avatar";
         if (skill
             ? contentType !== SKILL_PACKAGE_CONTENT_TYPE
-            : !cfg.allowedTypes.includes(contentType)) {
+            : avatar
+                ? !AGENT_AVATAR_CONTENT_TYPES.includes(contentType)
+                : !cfg.allowedTypes.includes(contentType)) {
             throw new ApiError("attachment.type_not_allowed", `Attachment type ${JSON.stringify(contentType)} is not allowed`);
         }
-        const limit = skill ? SKILL_PACKAGE_UPLOAD_MAX_BYTES : this.limitFor(contentType);
+        const limit = skill
+            ? SKILL_PACKAGE_UPLOAD_MAX_BYTES
+            : avatar
+                ? AGENT_AVATAR_MAX_BYTES
+                : this.limitFor(contentType);
         if (input.size > limit) {
             throw new ApiError("attachment.too_large", `Attachment is ${input.size} bytes, over the limit of ${limit} bytes`);
         }
@@ -156,13 +177,21 @@ let AttachmentsService = class AttachmentsService {
             .where("status", "=", "pending")
             .where("purpose", "=", purpose)
             .executeTakeFirst();
-        const maxPending = skill ? MAX_PENDING_SKILL_PACKAGES : MAX_PENDING_ATTACHMENTS;
+        const maxPending = skill
+            ? MAX_PENDING_SKILL_PACKAGES
+            : avatar
+                ? MAX_PENDING_AGENT_AVATARS
+                : MAX_PENDING_ATTACHMENTS;
         if (Number(pending?.n ?? 0) >= maxPending) {
             throw new ApiError("attachment.too_many_pending", `Too many unfinished uploads (at most ${maxPending}); finish or wait for them first`);
         }
         const id = randomUUID();
         const key = objectKey(id, purpose);
-        const ttlHours = skill ? SKILL_PACKAGE_TTL_HOURS : cfg.unboundTtlHours;
+        const ttlHours = skill
+            ? SKILL_PACKAGE_TTL_HOURS
+            : avatar
+                ? AGENT_AVATAR_TTL_HOURS
+                : cfg.unboundTtlHours;
         const upload = await this.storage.kernel(orgId).presignPut(key, {
             contentType,
             maxSize: input.size,
@@ -541,6 +570,99 @@ let AttachmentsService = class AttachmentsService {
             .where("id", "=", id)
             .execute();
     }
+    /**
+     * Makes an agent avatar upload ready to be saved into a profile (outside any transaction: it may
+     * read the object store): only the uploader, only the `agent-avatar` purpose, an image type, not
+     * expired and not yet used by another agent, else `attachment.not_found`. An upload still
+     * `pending` is finalized first (size, type and the image signature are checked). The expiry is
+     * extended so the cleanup job cannot delete it before {@link consumeAgentAvatar} runs.
+     */
+    async prepareAgentAvatar(orgId, accountId, id, agentId) {
+        this.storage.assertAvailable();
+        const row = await this.db
+            .selectFrom("attachments")
+            .select([
+            "status",
+            "purpose",
+            "content_type",
+            "agent_id",
+            sql `expires_at is not null and expires_at <= now()`.as("expired"),
+        ])
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .executeTakeFirst();
+        if (row?.purpose !== "agent-avatar" ||
+            row.status === "deleting" ||
+            row.expired ||
+            (row.agent_id !== null && row.agent_id !== agentId) ||
+            !AGENT_AVATAR_CONTENT_TYPES.includes(row.content_type)) {
+            throw notFound();
+        }
+        if (row.status === "pending")
+            await this.finalize(orgId, accountId, id);
+        await this.db
+            .updateTable("attachments")
+            .set({ expires_at: sql `now() + make_interval(hours => ${AGENT_AVATAR_TTL_HOURS})` })
+            .where("id", "=", id)
+            .where("status", "=", "ready")
+            .where("agent_id", "is", null)
+            .where("expires_at", "is not", null)
+            .execute();
+    }
+    /**
+     * In the caller's transaction, binds a ready avatar upload to `agentId` (row lock; the expiry is
+     * cleared, so the cleanup job keeps it while the profile uses it). An upload another agent
+     * already uses, or one that is not the account's ready avatar → `attachment.not_found`; saving
+     * the same upload to the same agent again is fine.
+     */
+    async consumeAgentAvatar(orgId, accountId, id, agentId) {
+        const trx = this.db.db;
+        const row = await trx
+            .selectFrom("attachments")
+            .select(["status", "agent_id"])
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .where("purpose", "=", "agent-avatar")
+            .forUpdate()
+            .executeTakeFirst();
+        if (row?.status !== "ready" || (row.agent_id !== null && row.agent_id !== agentId)) {
+            throw notFound();
+        }
+        await trx
+            .updateTable("attachments")
+            .set({ agent_id: agentId, expires_at: null })
+            .where("id", "=", id)
+            .execute();
+    }
+    /**
+     * A short-lived presigned GET (inline, with the checked image type) of the avatar upload bound
+     * to `agentId`; `null` when there is none or its object is gone or no longer the finalized one.
+     */
+    async agentAvatarUrl(orgId, agentId, id) {
+        this.storage.assertAvailable();
+        const row = await this.db
+            .selectFrom("attachments")
+            .select(["content_type", "object_key", "etag"])
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .where("agent_id", "=", agentId)
+            .where("purpose", "=", "agent-avatar")
+            .where("status", "=", "ready")
+            .executeTakeFirst();
+        if (!row)
+            return null;
+        const store = this.storage.kernel(orgId);
+        const head = await store.head(row.object_key);
+        if (!head || !this.sameContent(row.etag, head.etag, { orgId, attachmentId: id }))
+            return null;
+        return store.presignGet(row.object_key, {
+            ttlSeconds: AGENT_AVATAR_DOWNLOAD_TTL_SECONDS,
+            disposition: "inline",
+            responseContentType: row.content_type,
+        });
+    }
     /**
      * 删除过期（`expires_at < now()`）且从未绑定到会话的附件：先把行认领为 `deleting`（`FOR UPDATE SKIP LOCKED`，
      * 多副本并发时互不重复），再删对象、删行。删对象失败的行保持 `deleting`，下次运行重试。
@@ -613,6 +735,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], AttachmentsService.prototype, "consumeSkillPackage", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AttachmentsService.prototype, "consumeAgentAvatar", null);
 AttachmentsService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),

package/dist/conversations/conversations.controller.d.ts

@@ -1,34 +1,32 @@
 import type { FastifyReply } from "fastify";
 import { z } from "zod";
+import type { DeviceView } from "../devices/devices.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ConversationToolInfo, type ToolInfo } from "../tools/info.js";
+import type { AgentTreeNode } from "./agent-tree.js";
 import { type ArtifactPreview, ConversationArtifacts } from "./artifacts.js";
+import { EventsQuery, FilesQuery, IdParams, ListQuery, PatchBody, SubagentsQuery } from "./conversations.schemas.js";
 import { type ConversationGroup, ConversationsService, type ConversationView, type SubagentView, type UsageTotals } from "./conversations.service.js";
+import { ConversationDeviceStatus } from "./device-status.js";
 import type { ConversationEvent } from "./events.js";
 import { ConversationFiles, type FileOutput } from "./files.js";
 import { ConversationOutputs, type OutputPage } from "./outputs-read.js";
 import type { QueueItem, QueuePauseReason } from "./queue.js";
 import { ConversationQueue } from "./queue.service.js";
-import { ConversationSandboxStatus, type SandboxStatusView } from "./sandbox-status.js";
-declare const ListQuery: z.ZodObject<{
-    after: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-    agentId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 declare const GroupsQuery: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodEnum<{
+        running: "running";
+        waiting: "waiting";
+    }>>;
+    archived: z.ZodOptional<z.ZodEnum<{
+        1: "1";
+    }>>;
     perGroup: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     after: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-declare const SubagentsQuery: z.ZodObject<{
-    after: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-}, z.core.$strip>;
-declare const EventsQuery: z.ZodObject<{
-    after: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-}, z.core.$strip>;
 /** `?keys=a,b`: 1–100 comma-separated tool keys of 1–200 characters each. */
 declare const ToolsQuery: z.ZodObject<{
     keys: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodArray<z.ZodString>>;
@@ -37,10 +35,6 @@ declare const OutputQuery: z.ZodObject<{
     offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
-declare const FilesQuery: z.ZodObject<{
-    after: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
-}, z.core.$strip>;
 declare const FileContentQuery: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
@@ -74,14 +68,22 @@ declare const MessageBody: z.ZodObject<{
     skill: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strict>>;
+    timeZone: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
 }, z.core.$strict>;
 /**
  * `POST /conversations`: `message` creates the conversation with its first message (create on
  * first send; `clientMessageId` is required and makes a retry return the same conversation).
  * Without it the conversation is created empty (API clients; the web never does).
+ * `deviceId` binds it to one of the caller's devices; without it the caller's default
+ * device (environments spec §4.1 item 1).
  */
 declare const CreateBody: z.ZodObject<{
     agentId: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodString>;
     message: z.ZodOptional<z.ZodObject<{
         text: z.ZodString;
         attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -103,13 +105,16 @@ declare const CreateBody: z.ZodObject<{
         skill: z.ZodOptional<z.ZodObject<{
             name: z.ZodString;
         }, z.core.$strict>>;
+        timeZone: z.ZodOptional<z.ZodString>;
+        locale: z.ZodOptional<z.ZodEnum<{
+            en: "en";
+            zh: "zh";
+        }>>;
         clientMessageId: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
- * `POST …/queue`: the message fields that can be queued (no retry). A model / effort pick is checked
- * now and applied when the message is sent (final review I1). A skill invocation is rendered now
- * and checked again when sent (phase D Task 9).
+ * `POST …/queue` (deprecated, behaves as `POST …/messages`): the message fields (no retry).
  */
 declare const QueueBody: z.ZodObject<{
     text: z.ZodString;
@@ -132,19 +137,17 @@ declare const QueueBody: z.ZodObject<{
     skill: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
     }, z.core.$strict>>;
+    timeZone: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
     clientMessageId: z.ZodString;
 }, z.core.$strict>;
 /** `PATCH …/queue/:itemId`: only the text changes (the text rule is checked against the item). */
 declare const QueueEditBody: z.ZodObject<{
     text: z.ZodString;
 }, z.core.$strict>;
-/**
- * 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.
- */
-declare const RenameBody: z.ZodObject<{
-    title: z.ZodString;
-}, z.core.$strict>;
 /**
  * 会话（`/api/v1/orgs/:orgId/conversations`）：`agents.use`（访客以上），只接受人类用户；
  * 服务令牌 → 403 `forbidden`。只有会话所有者可见，其他人一律 `conversation.not_found`。
@@ -153,20 +156,30 @@ export declare class ConversationsController {
     private readonly conversations;
     private readonly outputs;
     private readonly artifacts;
-    private readonly sandboxStatus;
+    private readonly deviceStatus;
     private readonly toolInfo;
     private readonly queue;
     private readonly files;
-    constructor(conversations: ConversationsService, outputs: ConversationOutputs, artifacts: ConversationArtifacts, sandboxStatus: ConversationSandboxStatus, toolInfo: ConversationToolInfo, queue: ConversationQueue, files: ConversationFiles);
-    /** 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. */
+    constructor(conversations: ConversationsService, outputs: ConversationOutputs, artifacts: ConversationArtifacts, deviceStatus: ConversationDeviceStatus, toolInfo: ConversationToolInfo, queue: ConversationQueue, files: ConversationFiles);
+    /**
+     * 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. With a
+     * message the answer has `event` (the `user_message`) and `events`: every event the first send
+     * wrote, in seq order from seq 1 (a `model_switched` first when it switched).
+     */
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>, reply: FastifyReply): Promise<{
         conversation: ConversationView;
         event?: ConversationEvent;
+        events?: ConversationEvent[];
     }>;
-    /** Rename (owner only): `titleSource` becomes `manual` and the title is never regenerated. */
-    rename(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof RenameBody>): Promise<{
+    /**
+     * Rename and / or archive (owner only). A rename makes `titleSource` `manual`, so the title is
+     * never regenerated; `archived` archives or unarchives. Returns the final view.
+     */
+    patch(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof PatchBody>): Promise<{
         conversation: ConversationView;
     }>;
+    /** Soft delete (owner only): stops an active run and hides the conversation everywhere. */
+    remove(principal: Principal, org: OrgContext, { id }: z.infer<typeof IdParams>): Promise<void>;
     /** 我的会话，最近更新的在前：`next` 为下一页游标（作为 `after` 传回），没有更多时为 null。 */
     list(principal: Principal, org: OrgContext, q: z.infer<typeof ListQuery>): Promise<{
         conversations: ConversationView[];
@@ -180,13 +193,19 @@ export declare class ConversationsController {
     groups(principal: Principal, org: OrgContext, q: z.infer<typeof GroupsQuery>): Promise<{
         groups: ConversationGroup[];
         next: string | null;
+        archivedCount: number;
     }>;
     get(principal: Principal, org: OrgContext, id: string): Promise<{
         conversation: ConversationView;
     }>;
-    /** `after` 之后的事件（seq 升序，最多 `limit` 条）；客户端以最后一条的 seq 作为下一次的 `after`。 */
+    /**
+     * Events in ascending seq. `after`: those after it (at most `limit`; the client passes the last
+     * seq back as the next `after`). `before` (a seq, or `end` for the log's last page): the
+     * turn-aligned page before it, `{ events, turnsBefore }` (history paging spec §2).
+     */
     events(principal: Principal, org: OrgContext, id: string, q: z.infer<typeof EventsQuery>): Promise<{
         events: ConversationEvent[];
+        turnsBefore?: number;
     }>;
     /**
      * The conversation's sub-agents, newest first (sub-agents spec §14.3): `{ subagents, next }`,
@@ -197,6 +216,14 @@ export declare class ConversationsController {
         subagents: SubagentView[];
         next: string | null;
     }>;
+    /**
+     * The agent tree of a root conversation (agent map spec §8, §9.2): `{ root }`, each node with its
+     * status, model, time, tokens, tool calls and children. Owner only; a sub-agent's id is
+     * `conversation.not_found`.
+     */
+    agentTree(principal: Principal, org: OrgContext, { id }: z.infer<typeof IdParams>): Promise<{
+        root: AgentTreeNode;
+    }>;
     /**
      * The conversation's token usage, its sub-agents' included (sub-agents spec §8.3):
      * `{ usage: { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens } }`. Owner only.
@@ -239,11 +266,13 @@ export declare class ConversationsController {
      */
     fileContent(principal: Principal, org: OrgContext, id: string, fileId: string, q: z.infer<typeof FileContentQuery>, reply: FastifyReply): Promise<void>;
     /**
-     * 对话沙箱的状态。响应体**不套外层键**，直接是 `{ status: "running" | "suspended", lastUsedAt }`
-     * （不同于 `{ preview }`、`{ conversation }` 等；网页 `getSandboxStatus` 按此解析）；
-     * 没有可用的沙箱（未创建、已销毁）→ 404 `sandbox.not_found`。可见性与会话流相同。
+     * The device the conversation works in (a sub-agent: its root's), as its owner sees it,
+     * with its instance state; `null` while unbound, or when the device was deleted. Same
+     * visibility as the event stream.
      */
-    sandbox(principal: Principal, org: OrgContext, id: string): Promise<SandboxStatusView>;
+    device(principal: Principal, org: OrgContext, id: string): Promise<{
+        device: DeviceView | null;
+    }>;
     /**
      * Display metadata (title, kind, key arguments, source) of the tools a conversation's calls name,
      * for the tool rows (UI refresh B). Same visibility as the event stream; never model-visible.
@@ -264,12 +293,12 @@ export declare class ConversationsController {
         pauseReason?: QueuePauseReason;
     }>;
     /**
-     * Queues a message (201). The same `clientMessageId` again: 200 with the queued item, or with
-     * `item: null` and the sent `event` once it went out. An idle conversation sends it at once.
+     * Deprecated: behaves as `POST …/messages` (202 `{ event }`): an interjection while a run is
+     * active, a new run otherwise; nothing is queued any more. Kept for older clients for one release;
+     * the leftover-item routes below keep working until the queue table is dropped (contract step).
      */
-    enqueue(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof QueueBody>, reply: FastifyReply): Promise<{
-        item: QueueItem | null;
-        event?: ConversationEvent;
+    enqueue(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof QueueBody>): Promise<{
+        event: ConversationEvent;
     }>;
     /** "Continue sending" after a pause (202). Declared before `:itemId` routes. */
     resumeQueue(principal: Principal, org: OrgContext, id: string): Promise<Record<string, never>>;
@@ -281,7 +310,13 @@ export declare class ConversationsController {
     sendQueued(principal: Principal, org: OrgContext, id: string, itemId: string): Promise<{
         event: ConversationEvent;
     }>;
-    /** 中止当前运行（会话所有者）：202 `{ runId }`；没有活跃运行 → 409 `run.not_active`。 */
+    /**
+     * Stops the current run (the conversation's owner): 202 `{ runId }`; nothing active → 409
+     * `run.not_active`. On a root conversation `runId` is the stopped run, and its background
+     * sub-agents keep working. On a sub-agent's conversation (the root's owner, at any depth) the
+     * sub-agent stops with every sub-agent below it, and `runId` is the sub-agent's latest run,
+     * which may already be finished when only its descendants were working (agent map spec §6).
+     */
     abort(principal: Principal, org: OrgContext, id: string): Promise<{
         runId: string;
     }>;