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

package/dist/config/schema.js

@@ -179,6 +179,14 @@ export const KernelConfigSchema = z.object({
             .positive()
             .default(5000)
             .meta(meta({ description: "PostgreSQL connect timeout in milliseconds" })),
+        idleTimeoutMs: z
+            .number()
+            .int()
+            .positive()
+            .default(60_000)
+            .meta(meta({
+            description: "How long an idle PostgreSQL connection stays in the pool, in milliseconds",
+        })),
     })
         .prefault({}),
     redis: z
@@ -568,6 +576,12 @@ export const KernelConfigSchema = z.object({
             .positive()
             .default(50)
             .meta(meta({ description: "Maximum model steps per agent run before the final wrap-up" })),
+        wakeOnBackgroundTask: z
+            .boolean()
+            .default(true)
+            .meta(meta({
+            description: "Whether the finish of a background Bash task starts a run on an idle conversation (the person who started the task's run is the trigger); an organization can override it in its settings. When false the event is only logged and shown, and the next message picks it up",
+        })),
         maxRunSeconds: z
             .number()
             .int()
@@ -656,6 +670,7 @@ export const KernelConfigSchema = z.object({
     })
         .default({
         maxSteps: 50,
+        wakeOnBackgroundTask: true,
         maxRunSeconds: DEFAULT_MAX_RUN_SECONDS,
         streamIdleMs: 60000,
         maxOutputTokens: 16000,
@@ -751,7 +766,7 @@ export const KernelConfigSchema = z.object({
             .int()
             .positive()
             .default(20000)
-            .meta(meta({ description: "Maximum characters returned by one read_tool_output call" })),
+            .meta(meta({ description: "Maximum characters returned by one ReadToolOutput call" })),
         oauthAllowInsecureLoopback: z
             .boolean()
             .default(false)
@@ -946,6 +961,64 @@ export const KernelConfigSchema = z.object({
         })),
     })
         .prefault({}),
+    web: z
+        .object({
+        search: z
+            .object({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .default(10)
+                .meta(meta({
+                hot: true,
+                description: "Maximum number of results one WebSearch call returns to the model, however many the search provider returns",
+            })),
+        })
+            .prefault({}),
+        fetch: z
+            .object({
+            maxPageChars: z
+                .number()
+                .int()
+                .positive()
+                .default(400_000)
+                .meta(meta({
+                hot: true,
+                description: "Maximum characters of a fetched page kept for answering a WebFetch prompt; longer pages are truncated",
+            })),
+            maxAnswerTokens: z
+                .number()
+                .int()
+                .positive()
+                .default(4000)
+                .meta(meta({
+                hot: true,
+                description: "Maximum output tokens of the model call that answers a WebFetch prompt from the page",
+            })),
+            cacheSeconds: z
+                .number()
+                .int()
+                .min(0)
+                .default(900)
+                .meta(meta({
+                hot: true,
+                description: "Seconds a fetched page is cached per organization and URL; 0 turns the cache off",
+            })),
+            timeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .default(180_000)
+                .meta(meta({
+                hot: true,
+                description: "Time limit of one WebFetch call in milliseconds, the provider's fetch and the answering model call together; replaces tools.timeoutMs for WebFetch",
+            })),
+        })
+            .prefault({}),
+    })
+        .prefault({}),
     sandbox: z
         .object({
         image: z
@@ -978,8 +1051,37 @@ export const KernelConfigSchema = z.object({
             .positive()
             .default(104_857_600)
             .meta(meta({
-            description: "Largest file in bytes an agent may deliver from its sandbox to the user as an artifact (sandbox_deliver)",
+            description: "Largest file in bytes an agent may deliver from its sandbox to the user as an artifact (Deliver)",
         })),
+        background: z
+            .object({
+            maxTasks: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(4)
+                .meta(meta({
+                description: "Most background Bash tasks (run_in_background) that may run at once in one conversation's sandbox, sub-agents included; a launch beyond it is refused",
+            })),
+            maxSeconds: z
+                .number()
+                .int()
+                .positive()
+                .default(7200)
+                .meta(meta({
+                description: "Longest a background Bash task may run, in seconds; the task is killed at its deadline and ends as timed_out. Clamped to sandbox.limits.maxCommandSeconds; not limited by runtime.maxRunSeconds",
+            })),
+            pollSeconds: z
+                .number()
+                .int()
+                .min(1)
+                .default(10)
+                .meta(meta({
+                description: "How often the worker checks the running background Bash tasks of every sandbox for a finish, in seconds; read when the worker starts",
+            })),
+        })
+            .prefault({}),
         limits: z
             .object({
             cpu: z

package/dist/conversations/access.js

@@ -27,6 +27,7 @@ export const parentReachable = (viewerAccountId) => (eb) => eb.or([
         .whereRef("p.org_id", "=", "conversations.org_id")
         .where("p.account_id", "=", viewerAccountId)
         .where("p.kind", "=", "chat")
+        .where("p.deleted_at", "is", null)
         .where("agents.deleted_at", "is", null)
         .where(visibleTo(viewerAccountId))),
 ]);
@@ -53,6 +54,7 @@ let ConversationAccess = class ConversationAccess {
             .where("conversations.id", "=", conversationId)
             .where("conversations.org_id", "=", orgId)
             .where("conversations.account_id", "=", viewerAccountId)
+            .where("conversations.deleted_at", "is", null)
             .where("conversations.kind", "in", ["chat", "subagent"])
             .where(parentReachable(viewerAccountId))
             .where((eb) => eb.and([

package/dist/conversations/artifacts.d.ts

@@ -20,7 +20,7 @@ export interface ArtifactPreview {
     truncated: boolean;
 }
 /**
- * 产物（M5 T8 / T11）：agent 经 `sandbox_deliver` 交付的文件。先按会话流的规则判定会话可见
+ * 产物（M5 T8 / T11）：agent 经 `Deliver` 交付的文件。先按会话流的规则判定会话可见
  * （不可见 → `conversation.not_found`），再只在这个会话的日志里找 `artifact_created`
  * （没有 → `conversation.artifact_not_found`）。
  *

package/dist/conversations/artifacts.js

@@ -62,7 +62,7 @@ async function readPrefix(body, max) {
     return out.subarray(0, n);
 }
 /**
- * 产物（M5 T8 / T11）：agent 经 `sandbox_deliver` 交付的文件。先按会话流的规则判定会话可见
+ * 产物（M5 T8 / T11）：agent 经 `Deliver` 交付的文件。先按会话流的规则判定会话可见
  * （不可见 → `conversation.not_found`），再只在这个会话的日志里找 `artifact_created`
  * （没有 → `conversation.artifact_not_found`）。
  *

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

@@ -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,