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

package/dist/conversations/agent-tree.d.ts

@@ -0,0 +1,46 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * One agent of a conversation tree as the agent map shows it (agent map spec §8, §9.2): the root
+ * conversation or a sub-agent at any depth.
+ */
+export interface AgentTreeNode {
+    /** The conversation's id (a sub-agent's is its child conversation's). */
+    id: string;
+    /** A sub-agent's dispatched description; the root's title ("" before it has one). */
+    description: string;
+    /**
+     * The sub-agent type (`conversations.subagent_type`, set at the first dispatch); null for the
+     * root, and for a sub-agent row that has none (the column is nullable; no sentinel is invented).
+     */
+    agentType: string | null;
+    /**
+     * The latest run's status; `idle` when no run is active and the latest run completed (or the
+     * conversation has no run yet).
+     */
+    status: "queued" | "running" | "waiting" | "completed" | "failed" | "aborted" | "idle";
+    /** The model of the latest run (a queued sub-agent's: the dispatched one); null when unknown. */
+    model: {
+        provider: string;
+        model: string;
+    } | null;
+    /** The first run's start; null until a run started. */
+    startedAt: string | null;
+    /** The latest run's end; null while a run is active or before any run ended. */
+    finishedAt: string | null;
+    /** The wall time of the conversation's own runs, summed (a running run up to now). */
+    durationMs: number;
+    /** The tokens of the conversation's own runs (`usage` events with a run; never descendants'). */
+    tokens: number;
+    /** The tool calls of the conversation's own runs (its `tool_result` events). */
+    toolCalls: number;
+    /** The sub-agents it dispatched, oldest first. */
+    children: AgentTreeNode[];
+}
+/**
+ * The agent tree of the root conversation `rootId` of org `orgId`: null when it is not a root
+ * chat conversation of that org. The tree's ids come from {@link conversationTree} (one recursive
+ * query); one more query reads every node's numbers. A deleted conversation, and a sub-agent
+ * conversation without a dispatch row, is left out with its subtree. Call only after an access
+ * check of the root.
+ */
+export declare function readAgentTree(db: KernelSchemaDb, orgId: string, rootId: string): Promise<AgentTreeNode | null>;

package/dist/conversations/agent-tree.js

@@ -0,0 +1,92 @@
+import { sql } from "kysely";
+import { conversationTree } from "./tree.js";
+const ACTIVE = new Set(["queued", "running", "waiting"]);
+/**
+ * The agent tree of the root conversation `rootId` of org `orgId`: null when it is not a root
+ * chat conversation of that org. The tree's ids come from {@link conversationTree} (one recursive
+ * query); one more query reads every node's numbers. A deleted conversation, and a sub-agent
+ * conversation without a dispatch row, is left out with its subtree. Call only after an access
+ * check of the root.
+ */
+export async function readAgentTree(db, orgId, rootId) {
+    const ids = (await conversationTree(db, rootId)).map((t) => t.id);
+    if (ids.length === 0)
+        return null;
+    const { rows } = await sql `
+    SELECT c.id, c.parent_conversation_id, c.subagent_type, c.title,
+      (SELECT e.payload->>'description' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.parent_conversation_id AND e.type = 'subagent_dispatched'
+          AND e.payload->>'subagentId' = c.id
+        ORDER BY e.seq DESC LIMIT 1) AS description,
+      (SELECT e.payload->'model' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.parent_conversation_id AND e.type = 'subagent_dispatched'
+          AND e.payload->>'subagentId' = c.id
+        ORDER BY e.seq DESC LIMIT 1) AS dispatched_model,
+      (SELECT e.payload->'model' FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.id AND e.type = 'run_started'
+        ORDER BY e.seq DESC LIMIT 1) AS run_model,
+      latest.status AS last_status, latest.finished_at AS last_finished_at,
+      runs.started_at, runs.duration_ms,
+      (SELECT count(*) FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.id AND e.type = 'tool_result') AS tool_calls,
+      (SELECT coalesce(sum(
+          coalesce((e.payload->>'inputTokens')::bigint, 0)
+          + coalesce((e.payload->>'outputTokens')::bigint, 0)
+          + coalesce((e.payload->>'cacheReadTokens')::bigint, 0)
+          + coalesce((e.payload->>'cacheWriteTokens')::bigint, 0)
+        ), 0)
+        FROM capybara.conversation_events e
+        WHERE e.conversation_id = c.id AND e.type = 'usage' AND e.run_id IS NOT NULL) AS tokens
+    FROM capybara.conversations c
+    LEFT JOIN LATERAL (
+      SELECT r.status, r.finished_at FROM capybara.runs r
+      WHERE r.conversation_id = c.id
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT 1
+    ) latest ON true
+    CROSS JOIN LATERAL (
+      SELECT min(r.started_at) AS started_at,
+        coalesce(sum(floor(extract(epoch FROM coalesce(r.finished_at, now()) - r.started_at) * 1000))
+          FILTER (WHERE r.started_at IS NOT NULL), 0)::bigint AS duration_ms
+      FROM capybara.runs r WHERE r.conversation_id = c.id
+    ) runs
+    WHERE c.id IN (${sql.join(ids)}) AND c.org_id = ${orgId} AND c.deleted_at IS NULL
+      AND (
+        (c.id = ${rootId} AND c.kind = 'chat' AND c.parent_conversation_id IS NULL)
+        OR (c.id <> ${rootId} AND c.kind = 'subagent' AND EXISTS (
+          SELECT 1 FROM capybara.subagent_dispatches sd WHERE sd.child_conversation_id = c.id
+        ))
+      )
+    ORDER BY c.created_at, c.id
+  `.execute(db);
+    const nodes = new Map();
+    for (const r of rows)
+        nodes.set(r.id, toNode(r, r.id === rootId));
+    for (const r of rows) {
+        if (r.id === rootId || r.parent_conversation_id === null)
+            continue;
+        const node = nodes.get(r.id);
+        const parent = nodes.get(r.parent_conversation_id);
+        if (node && parent)
+            parent.children.push(node);
+    }
+    return nodes.get(rootId) ?? null;
+}
+function toNode(r, isRoot) {
+    const active = r.last_status !== null && ACTIVE.has(r.last_status);
+    const status = r.last_status === null || r.last_status === "completed" ? "idle" : r.last_status;
+    return {
+        id: r.id,
+        description: (isRoot ? r.title : (r.description ?? r.title)) ?? "",
+        agentType: isRoot ? null : r.subagent_type,
+        status,
+        model: modelOf(r.run_model ?? r.dispatched_model),
+        startedAt: r.started_at?.toISOString() ?? null,
+        finishedAt: active ? null : (r.last_finished_at?.toISOString() ?? null),
+        durationMs: Number(r.duration_ms),
+        tokens: Number(r.tokens),
+        toolCalls: Number(r.tool_calls),
+        children: [],
+    };
+}
+const modelOf = (m) => m ? { provider: m.provider, model: m.model } : null;

package/dist/conversations/artifacts.d.ts

@@ -1,5 +1,6 @@
-import type { KernelDb } from "../db/kernel-schema.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { StorageService } from "../storage/storage.service.js";
+import { ConversationAccess } from "./access.js";
 /** 产物下载跳转的预签名有效期（秒）。 */
 export declare const ARTIFACT_DOWNLOAD_TTL_SECONDS = 300;
 /** 下载 302 的 `Cache-Control: private, max-age=…`（秒），不长于预签名有效期。 */
@@ -18,14 +19,8 @@ export interface ArtifactPreview {
     /** 只截取了开头（文件更长）。 */
     truncated: boolean;
 }
-export interface ConversationArtifactsDeps {
-    db: KernelDb;
-    storage: Pick<StorageService, "kernel">;
-    /** 会话可见性（与会话 SSE 流同一判定：`ConversationsService.isAccessible`）。 */
-    isAccessible(orgId: string, conversationId: string, viewerAccountId: string): Promise<boolean>;
-}
 /**
- * 产物（M5 T8 / T11）：agent 经 `sandbox_deliver` 交付的文件。先按会话流的规则判定会话可见
+ * 产物（M5 T8 / T11）：agent 经 `Deliver` 交付的文件。先按会话流的规则判定会话可见
  * （不可见 → `conversation.not_found`），再只在这个会话的日志里找 `artifact_created`
  * （没有 → `conversation.artifact_not_found`）。
  *
@@ -39,8 +34,13 @@ export interface ConversationArtifactsDeps {
  * `payload->>'artifactId'` 过滤、`LIMIT 1`（只扫这一个会话的事件，不在 JS 里扫日志；不加迁移）。
  */
 export declare class ConversationArtifacts {
-    private readonly d;
-    constructor(d: ConversationArtifactsDeps);
+    private readonly db;
+    private readonly storage;
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    private readonly access;
+    constructor(db: KernelDb, storage: Pick<StorageService, "kernel">, 
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    access: Pick<ConversationAccess, "isAccessible">);
     private find;
     downloadUrl(orgId: string, conversationId: string, viewerAccountId: string, artifactId: string, opts?: {
         inline?: boolean;

package/dist/conversations/artifacts.js

@@ -1,6 +1,19 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { StorageService } from "../storage/storage.service.js";
 import { UUID_RE } from "../ui/registry.js";
+import { ConversationAccess } from "./access.js";
 /** 产物下载跳转的预签名有效期（秒）。 */
 export const ARTIFACT_DOWNLOAD_TTL_SECONDS = 300;
 /** 下载 302 的 `Cache-Control: private, max-age=…`（秒），不长于预签名有效期。 */
@@ -49,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`）。
  *
@@ -62,20 +75,26 @@ async function readPrefix(body, max) {
  * 查找走 `conversation_events` 的主键 `(conversation_id, seq)` 前缀，在 SQL 里按 `type` 与
  * `payload->>'artifactId'` 过滤、`LIMIT 1`（只扫这一个会话的事件，不在 JS 里扫日志；不加迁移）。
  */
-export class ConversationArtifacts {
-    d;
-    constructor(d) {
-        this.d = d;
+let ConversationArtifacts = class ConversationArtifacts {
+    db;
+    storage;
+    access;
+    constructor(db, storage, 
+    /** 会话可见性（与会话 SSE 流同一判定）。 */
+    access) {
+        this.db = db;
+        this.storage = storage;
+        this.access = access;
     }
     async find(orgId, conversationId, viewerAccountId, artifactId) {
         if (!UUID_RE.test(conversationId))
             throw conversationNotFound();
-        if (!(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+        if (!(await this.access.isAccessible(orgId, conversationId, viewerAccountId))) {
             throw conversationNotFound();
         }
         if (!UUID_RE.test(artifactId))
             throw artifactNotFound();
-        const row = await this.d.db
+        const row = await this.db
             .selectFrom("conversation_events")
             .select("payload")
             .where("conversation_id", "=", conversationId)
@@ -89,7 +108,7 @@ export class ConversationArtifacts {
     }
     async downloadUrl(orgId, conversationId, viewerAccountId, artifactId, opts = {}) {
         const a = await this.find(orgId, conversationId, viewerAccountId, artifactId);
-        const store = this.d.storage.kernel(orgId);
+        const store = this.storage.kernel(orgId);
         if (!(await store.head(a.objectKey)))
             throw artifactNotFound();
         const inline = opts.inline === true && isInlineArtifactType(a.contentType);
@@ -106,7 +125,7 @@ export class ConversationArtifacts {
         if (!isTextArtifactType(a.contentType)) {
             throw new ApiError("conversation.artifact_not_previewable", "Only text artifacts have a preview");
         }
-        const got = await this.d.storage
+        const got = await this.storage
             .kernel(orgId)
             .get(a.objectKey, { range: { start: 0, end: ARTIFACT_PREVIEW_MAX_BYTES - 1 } });
         if (!got)
@@ -134,4 +153,11 @@ export class ConversationArtifacts {
         }
         return { text, truncated };
     }
-}
+};
+ConversationArtifacts = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(ConversationAccess))
+], ConversationArtifacts);
+export { ConversationArtifacts };

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

@@ -2,7 +2,7 @@ import type { FastifyReply } from "fastify";
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import { type AttachmentLimits, type AttachmentsService, type AttachmentView, type CreatedAttachment } from "./attachments.service.js";
+import { type AttachmentLimits, AttachmentsService, type AttachmentView, type CreatedAttachment } from "./attachments.service.js";
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
     contentType: z.ZodString;

package/dist/conversations/attachments.controller.js

@@ -8,13 +8,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
-import { Body, Controller, Get, HttpCode, Inject, Param, Post, Res } from "@nestjs/common";
+import { Controller, Get, HttpCode, Inject, Param, Post, Res } from "@nestjs/common";
 import { z } from "zod";
-import { ATTACHMENTS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-import { ATTACHMENT_DOWNLOAD_CACHE_SECONDS, } from "./attachments.service.js";
+import { ATTACHMENT_DOWNLOAD_CACHE_SECONDS, AttachmentsService, } from "./attachments.service.js";
 const CreateBody = z
     .object({
     name: z
@@ -26,6 +26,8 @@ const CreateBody = z
     size: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
 })
     .strict();
+class AttachmentCreateBodyDto extends createZodDto(CreateBody, "AttachmentCreateBody") {
+}
 /**
  * 对话附件（`/api/v1/orgs/:orgId/attachments`，`agents.use`，只接受人类用户）：
  * 1. `POST /` 登记并取预签名上传（`upload.method` 为 `POST` 时按 multipart 表单：先放 `fields`，最后放 `file`）；
@@ -71,7 +73,7 @@ __decorate([
     OrgAction("agents.use"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(CreateBody)))
+    __param(2, ZBody(AttachmentCreateBodyDto))
 ], AttachmentsController.prototype, "create", null);
 __decorate([
     Post(":id/finalize"),
@@ -91,6 +93,6 @@ __decorate([
 ], AttachmentsController.prototype, "download", null);
 AttachmentsController = __decorate([
     Controller("api/v1/orgs/:orgId/attachments"),
-    __param(0, Inject(ATTACHMENTS))
+    __param(0, Inject(AttachmentsService))
 ], AttachmentsController);
 export { AttachmentsController };

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

@@ -0,0 +1,7 @@
+/**
+ * Conversation attachments and skill package uploads (the hourly cleanup of expired unbound ones,
+ * `AttachmentCleanupJob`, is the worker role's: `WorkerModule`). Its own module (no conversations dependency) so the
+ * skills and the builtin tools can use it.
+ */
+export declare class AttachmentsModule {
+}

package/dist/conversations/attachments.module.js

@@ -0,0 +1,25 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { StorageModule } from "../storage/storage.module.js";
+import { ConversationAccessModule } from "./access.js";
+import { AttachmentsService } from "./attachments.service.js";
+/**
+ * Conversation attachments and skill package uploads (the hourly cleanup of expired unbound ones,
+ * `AttachmentCleanupJob`, is the worker role's: `WorkerModule`). Its own module (no conversations dependency) so the
+ * skills and the builtin tools can use it.
+ */
+let AttachmentsModule = class AttachmentsModule {
+};
+AttachmentsModule = __decorate([
+    Module({
+        imports: [StorageModule, ConversationAccessModule],
+        providers: [AttachmentsService],
+        exports: [AttachmentsService],
+    })
+], AttachmentsModule);
+export { AttachmentsModule };

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

@@ -1,11 +1,14 @@
-import { type Logger, type PresignedUpload } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
-import type { KernelConfig } from "../config/schema.js";
-import type { AttachmentPurpose, KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import { type PresignedUpload } from "@capybara-hq/plugin-sdk";
+import type { AttachmentPurpose } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
 import type { MediaBytes, MediaInfo } from "../runtime/context/build.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { StorageService } from "../storage/storage.service.js";
+import { ConversationAccess } from "./access.js";
 import type { LogContentBlock } from "./events.js";
-type Trx = Transaction<KernelDatabase>;
 /** 预签名上传的有效期（秒）。尽量短：表单在有效期内可被再次使用（内容替换由 etag 核对兜底）。 */
 export declare const ATTACHMENT_UPLOAD_TTL_SECONDS = 300;
 /** 下载跳转的预签名有效期（秒）；不短于 {@link ATTACHMENT_DOWNLOAD_CACHE_SECONDS}（浏览器缓存的跳转仍可用）。 */
@@ -25,15 +28,23 @@ 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`）。
  */
 export declare const skillFilesPrefix: (uploadId: string) => string;
-/** 维护任务：清理过期未绑定的附件（任务名与 scheduler id 不含 `:`）。 */
+/** 周期任务：每小时清理过期未绑定的附件（`@LockedCron`）。 */
 export declare const ATTACHMENT_CLEANUP_JOB = "attachment-cleanup";
-export declare const ATTACHMENT_CLEANUP_SCHEDULER_ID = "attachment-cleanup-hourly";
-export declare const ATTACHMENT_CLEANUP_EVERY_MS = 3600000;
 /** 附件元数据（finalize 的返回）。 */
 export interface AttachmentView {
     id: string;
@@ -70,14 +81,6 @@ export interface CreatedAttachment {
     /** 预签名上传的过期时间（ISO 8601）。 */
     expiresAt: string;
 }
-export interface AttachmentsDeps {
-    db: KernelDb;
-    storage: StorageService;
-    config: () => KernelConfig;
-    /** viewer 能否访问该会话（与会话流相同的规则）。 */
-    canAccessConversation: (orgId: string, conversationId: string, viewerAccountId: string) => Promise<boolean>;
-    log: Pick<Logger, "info" | "warn">;
-}
 /** 去掉参数、转小写：`Text/Plain; charset=utf-8` → `text/plain`。 */
 export declare const normalizeContentType: (ct: string) => string;
 /** 文件开头是否与声明的类型相符（图片与 PDF 看签名，文本不能含 NUL）。 */
@@ -92,8 +95,16 @@ export declare function countPdfPages(bytes: Uint8Array): number;
  * 无进程内状态，可多副本共用。
  */
 export declare class AttachmentsService {
-    private readonly d;
-    constructor(d: AttachmentsDeps);
+    private readonly db;
+    private readonly storage;
+    private readonly config;
+    /** viewer 能否访问该会话（与会话流相同的规则）。 */
+    private readonly access;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, storage: Pick<StorageService, "available" | "assertAvailable" | "kernel">, config: Pick<KernelConfigService, "get">, 
+    /** viewer 能否访问该会话（与会话流相同的规则）。 */
+    access: Pick<ConversationAccess, "isAccessible">, log: Pick<KernelLogger, "info" | "warn">, txHost: TransactionHost);
     /** 单个附件的大小上限：配置的 `maxBytes`，图片再受 `MEDIA_LIMITS.imageBytes` 限制。 */
     private limitFor;
     /** 当前配置下的上限（不需要对象存储）。 */
@@ -142,7 +153,7 @@ export declare class AttachmentsService {
      * 后两种的 details 为 `[{ path: "files", message, attachmentId }]`，网页据此标出对应条目。
      * 已绑定到本会话的（重试）照常返回块。
      */
-    bindForMessage(trx: Trx, orgId: string, conversationId: string, accountId: string, ids: readonly string[]): Promise<LogContentBlock[]>;
+    bindForMessage(orgId: string, conversationId: string, accountId: string, ids: readonly string[]): Promise<LogContentBlock[]>;
     /** 下载 / 取字节时核对 etag：finalize 记下的与当前对象的不一致 → 内容被替换（记 warn）。没有记录时不核对。 */
     private sameContent;
     /**
@@ -167,7 +178,27 @@ export declare class AttachmentsService {
      * 在调用方事务里把技能包上传标记为已用掉（行锁；之后由清理任务删 zip，解出的文件因被版本引用而保留）。
      * 不是该账号的 ready 技能包（如已被并发的请求用掉）→ `attachment.not_found`。
      */
-    consumeSkillPackage(trx: Trx, orgId: string, accountId: string, id: string): Promise<void>;
+    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`，下次运行重试。
@@ -177,4 +208,11 @@ export declare class AttachmentsService {
      */
     deleteExpired(): Promise<number>;
 }
-export {};
+/** The hourly cleanup of expired unbound attachments, once per tick across replicas. */
+export declare class AttachmentCleanupJob {
+    private readonly attachments;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(attachments: Pick<AttachmentsService, "deleteExpired">, lockService: LockService, log: KernelLogger);
+    run(): Promise<void>;
+}