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

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

@@ -12,11 +12,27 @@ 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<{
+    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>;
 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>;
@@ -142,9 +158,13 @@ declare const QueueEditBody: z.ZodObject<{
  * 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;
+declare const PatchBody: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    archived: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+declare const IdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
 /**
  * 会话（`/api/v1/orgs/:orgId/conversations`）：`agents.use`（访客以上），只接受人类用户；
  * 服务令牌 → 403 `forbidden`。只有会话所有者可见，其他人一律 `conversation.not_found`。
@@ -158,15 +178,25 @@ export declare class ConversationsController {
     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. */
+    /**
+     * 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,6 +210,7 @@ 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;

package/dist/conversations/conversations.controller.js

@@ -12,7 +12,7 @@ import { z } from "zod";
 import { ModelRef } from "../agents/definition.js";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { CONTROL_OR_HIDDEN_RE } from "../text.js";
 import { MAX_ATTACHMENTS } from "../tools/connector-content.js";
@@ -23,17 +23,25 @@ import { ConversationFiles, FILE_CONTENT_MAX_BYTES, FILES_PAGE_MAX, } from "./fi
 import { ConversationOutputs, OUTPUT_PAGE_MAX_CHARS } from "./outputs-read.js";
 import { ConversationQueue } from "./queue.service.js";
 import { ConversationSandboxStatus } from "./sandbox-status.js";
+/** Shared by the list and groups queries: title search, run activity and the archived list. */
+const searchFields = {
+    q: z.string().min(1).max(100).optional(),
+    state: z.enum(["running", "waiting"]).optional(),
+    archived: z.enum(["1"]).optional(),
+};
 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,
 });
 const GroupsQuery = z.object({
     perGroup: z.coerce.number().int().min(1).max(20).default(5),
     limit: z.coerce.number().int().min(1).max(50).default(20),
     /** The last group's agent id from the previous page (`next`). */
     after: z.string().min(1).max(100).optional(),
+    ...searchFields,
 });
 const SubagentsQuery = z.object({
     /** The previous page's last sub-agent id (`next`). */
@@ -143,7 +151,7 @@ const QueueEditBody = z.object({ text: z.string().max(100_000) }).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.
  */
-const RenameBody = z
+const PatchBody = z
     .object({
     title: z
         .string()
@@ -151,12 +159,19 @@ const RenameBody = z
         .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"),
+        .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();
+    .strict()
+    .refine((b) => b.title !== undefined || b.archived !== undefined, "title or archived is required");
+const IdParams = z.object({ id: z.string().min(1).max(100) });
 class ConversationCreateBodyDto extends createZodDto(CreateBody, "ConversationCreateBody") {
 }
-class ConversationRenameBodyDto extends createZodDto(RenameBody, "ConversationRenameBody") {
+class ConversationPatchBodyDto extends createZodDto(PatchBody, "ConversationPatchBody") {
+}
+class ConversationIdParamsDto extends createZodDto(IdParams, "ConversationIdParams") {
 }
 class ConversationListQueryDto extends createZodDto(ListQuery, "ConversationListQuery") {
 }
@@ -203,7 +218,11 @@ let ConversationsController = class ConversationsController {
         this.queue = queue;
         this.files = files;
     }
-    /** 201 when created; 200 when `message.clientMessageId` repeats an earlier first send. */
+    /**
+     * 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).
+     */
     async create(principal, org, body, reply) {
         const p = requireUser(principal);
         if (body.message === undefined) {
@@ -222,15 +241,32 @@ let ConversationsController = class ConversationsController {
             ...(m.skill !== undefined && { skill: m.skill }),
         });
         reply.status(out.created ? 201 : 200);
-        return { conversation: out.conversation, event: out.event };
+        return { conversation: out.conversation, event: out.event, events: out.events };
     }
-    /** Rename (owner only): `titleSource` becomes `manual` and the title is never regenerated. */
-    async rename(principal, org, id, body) {
+    /**
+     * 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.
+     */
+    async patch(principal, org, id, body) {
         const p = requireUser(principal);
+        const renamed = body.title === undefined
+            ? undefined
+            : await this.conversations.rename(org.orgId, id, p.account.id, body.title);
+        if (body.archived === undefined) {
+            // The refine guarantees a title when there is no `archived`
+            return {
+                conversation: renamed ?? (await this.conversations.get(org.orgId, id, p.account.id)),
+            };
+        }
         return {
-            conversation: await this.conversations.rename(org.orgId, id, p.account.id, body.title),
+            conversation: await this.conversations.setArchived(org.orgId, id, p.account.id, body.archived),
         };
     }
+    /** Soft delete (owner only): stops an active run and hides the conversation everywhere. */
+    async remove(principal, org, { id }) {
+        const p = requireUser(principal);
+        await this.conversations.remove(org.orgId, id, p.account.id);
+    }
     /** 我的会话，最近更新的在前：`next` 为下一页游标（作为 `after` 传回），没有更多时为 null。 */
     async list(principal, org, q) {
         const p = requireUser(principal);
@@ -238,6 +274,9 @@ let ConversationsController = class ConversationsController {
             limit: q.limit + 1,
             ...(q.after !== undefined && { after: q.after }),
             ...(q.agentId !== undefined && { agentId: q.agentId }),
+            ...(q.q !== undefined && { q: q.q }),
+            ...(q.state !== undefined && { state: q.state }),
+            ...(q.archived !== undefined && { archived: true }),
         });
         const conversations = rows.slice(0, q.limit);
         const next = rows.length > q.limit ? (conversations.at(-1)?.id ?? null) : null;
@@ -254,6 +293,9 @@ let ConversationsController = class ConversationsController {
             perGroup: q.perGroup,
             limit: q.limit,
             ...(q.after !== undefined && { after: q.after }),
+            ...(q.q !== undefined && { q: q.q }),
+            ...(q.state !== undefined && { state: q.state }),
+            ...(q.archived !== undefined && { archived: true }),
         });
     }
     async get(principal, org, id) {
@@ -443,8 +485,16 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, ZBody(ConversationRenameBodyDto))
-], ConversationsController.prototype, "rename", null);
+    __param(3, ZBody(ConversationPatchBodyDto))
+], ConversationsController.prototype, "patch", null);
+__decorate([
+    Delete(":id"),
+    HttpCode(204),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ConversationIdParamsDto))
+], ConversationsController.prototype, "remove", null);
 __decorate([
     Get(),
     OrgAction("agents.use"),

package/dist/conversations/conversations.module.js

@@ -6,6 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Module } from "@nestjs/common";
 import { AgentLookupModule } from "../agents/agent-lookup.js";
+import { BackgroundModule } from "../background/background.module.js";
 import { ProvidersModule } from "../runtime/providers.js";
 import { RuntimeModule } from "../runtime/runtime.module.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
@@ -44,6 +45,8 @@ ConversationsModule = __decorate([
             ProvidersModule,
             // the sandbox status
             SandboxModule,
+            // the stop of a deleted conversation's background tasks
+            BackgroundModule,
         ],
         providers: [
             ConversationsService,

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

@@ -1,5 +1,6 @@
 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 { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -31,7 +32,16 @@ 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;
+    /**
+     * 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: {
@@ -150,6 +160,8 @@ 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;
     readonly txHost: TransactionHost;
     constructor(db: KernelDb, eventLog: EventLog, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, 
     /** Starts and stops the conversation's runs. */
@@ -161,7 +173,9 @@ 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">, txHost: TransactionHost);
     /**
      * 不阻塞地调用一次 `ensureRun`（打开 SSE、读事件时）：它幂等，并顺带清理孤儿运行，
      * 会话不会因为某次运行结束后的投递失败而永远停在「运行中」。失败只记日志。
@@ -175,12 +189,15 @@ export declare class ConversationsService {
      * 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<{
         conversation: ConversationView;
         event: ConversationEvent;
+        events: ConversationEvent[];
         created: boolean;
     }>;
     /** The conversation row and its first message (undefined: a concurrent retry committed first). */
@@ -197,6 +214,23 @@ 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, then 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`). 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 (enterprise 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 +250,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 +265,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
@@ -292,7 +333,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;
     /**