@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/config/sources.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 部署级插件配置某个字段的来源（D8 / C10）：启动配置文件、Nacos，或环境变量（优先级最高）。
+ * 这些来源里有的字段在后台只读；PG 里的值（`db`）与 schema 默认值优先级更低。
+ */
+export type ConfigSourceKind = "file" | "nacos" | "env";
+/**
+ * 启动配置里各插件部署配置的来源：`raw` 是配置来源（文件 / Nacos，`kind`）读出的原始对象，`env` 里
+ * `CAPYBARA_EXTENSION_CONFIG*` 推导出的覆盖（逐字段或整段 JSON）记为 `env`（优先级最高，覆盖同一路径的文件来源）。
+ * 返回插件名 → 叶子点路径 → 来源。只看路径，不含值。
+ */
+export declare function extensionConfigSources(raw: unknown, env: NodeJS.ProcessEnv, kind: "file" | "nacos"): Record<string, Record<string, ConfigSourceKind>>;
+/** `CAPYBARA_CONFIG_SOURCE` 对应的来源种类（默认 file）。 */
+export declare function configSourceKind(env: NodeJS.ProcessEnv): "file" | "nacos";
+/**
+ * 某个配置字段（点路径）是否出现在来源里：来源路径等于它、在它下面（字段是 record / 数组等整体叶子），
+ * 或是它的祖先（来源在上层给了非对象值）。环境变量优先。返回来源种类，没有返回 undefined。
+ */
+export declare function fieldSource(sources: Record<string, ConfigSourceKind> | undefined, field: string): ConfigSourceKind | undefined;

package/dist/config/sources.js

@@ -0,0 +1,59 @@
+import { envOverrides } from "./env.js";
+const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** 把一份插件配置展开成叶子点路径（对象递归；数组、null 与标量是叶子；空对象没有叶子）。 */
+function leafPaths(value, prefix, out) {
+    if (isPlainObject(value)) {
+        for (const [k, v] of Object.entries(value))
+            leafPaths(v, prefix ? `${prefix}.${k}` : k, out);
+        return;
+    }
+    if (prefix !== "")
+        out.push(prefix);
+}
+function mark(out, extensionConfig, kind) {
+    if (!isPlainObject(extensionConfig))
+        return;
+    for (const [plugin, value] of Object.entries(extensionConfig)) {
+        const paths = [];
+        leafPaths(value, "", paths);
+        if (paths.length === 0)
+            continue;
+        const target = out[plugin] ?? {};
+        out[plugin] = target;
+        for (const p of paths)
+            target[p] = kind;
+    }
+}
+/**
+ * 启动配置里各插件部署配置的来源：`raw` 是配置来源（文件 / Nacos，`kind`）读出的原始对象，`env` 里
+ * `CAPYBARA_EXTENSION_CONFIG*` 推导出的覆盖（逐字段或整段 JSON）记为 `env`（优先级最高，覆盖同一路径的文件来源）。
+ * 返回插件名 → 叶子点路径 → 来源。只看路径，不含值。
+ */
+export function extensionConfigSources(raw, env, kind) {
+    const out = {};
+    if (isPlainObject(raw))
+        mark(out, raw.extensionConfig, kind);
+    mark(out, envOverrides(env).extensionConfig, "env");
+    return out;
+}
+/** `CAPYBARA_CONFIG_SOURCE` 对应的来源种类（默认 file）。 */
+export function configSourceKind(env) {
+    return env.CAPYBARA_CONFIG_SOURCE === "nacos" ? "nacos" : "file";
+}
+/**
+ * 某个配置字段（点路径）是否出现在来源里：来源路径等于它、在它下面（字段是 record / 数组等整体叶子），
+ * 或是它的祖先（来源在上层给了非对象值）。环境变量优先。返回来源种类，没有返回 undefined。
+ */
+export function fieldSource(sources, field) {
+    if (!sources)
+        return undefined;
+    let found;
+    for (const [p, kind] of Object.entries(sources)) {
+        if (p === field || p.startsWith(`${field}.`) || field.startsWith(`${p}.`)) {
+            if (kind === "env")
+                return "env";
+            found = kind;
+        }
+    }
+    return found;
+}

package/dist/config/types.d.ts

@@ -0,0 +1,9 @@
+/** 配置来源：`load` 取原始配置，`watch` 可选地订阅变更并返回取消函数；`onError` 接收监听过程中的（已脱敏）错误。 */
+export interface ConfigSource {
+    load(): Promise<unknown>;
+    watch?(onChange: (raw: unknown) => void, onError?: (err: Error) => void): () => void;
+}
+/** 配置加载或校验失败。 */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}

package/dist/config/types.js

@@ -0,0 +1,7 @@
+/** 配置加载或校验失败。 */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}

package/dist/conversations/artifacts.d.ts

@@ -0,0 +1,52 @@
+import type { KernelDb } from "../db/kernel-schema.js";
+import type { StorageService } from "../storage/storage.service.js";
+/** 产物下载跳转的预签名有效期（秒）。 */
+export declare const ARTIFACT_DOWNLOAD_TTL_SECONDS = 300;
+/** 下载 302 的 `Cache-Control: private, max-age=…`（秒），不长于预签名有效期。 */
+export declare const ARTIFACT_DOWNLOAD_CACHE_SECONDS = 60;
+/** 文本预览最多读取的字节数（从对象开头按 Range 读）。 */
+export declare const ARTIFACT_PREVIEW_MAX_BYTES = 8192;
+/** 文本预览最多的行数。 */
+export declare const ARTIFACT_PREVIEW_MAX_LINES = 40;
+/** 产物能否以 `inline` 在页面里显示（只有位图）。 */
+export declare const isInlineArtifactType: (ct: string) => boolean;
+/** 产物能否给文本预览（`text/*` 与常见的文本格式；SVG 不算）。 */
+export declare function isTextArtifactType(ct: string): boolean;
+/** 文本预览：开头若干行（纯文本，网页按纯文本显示，从不当 HTML 渲染）。 */
+export interface ArtifactPreview {
+    text: string;
+    /** 只截取了开头（文件更长）。 */
+    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` 交付的文件。先按会话流的规则判定会话可见
+ * （不可见 → `conversation.not_found`），再只在这个会话的日志里找 `artifact_created`
+ * （没有 → `conversation.artifact_not_found`）。
+ *
+ * - 下载：302 到预签名地址，默认 `attachment`（带交付时的文件名与类型）；`inline` 只对位图生效
+ *   （网页的缩略图），其余类型即使要求 inline 也仍是 `attachment`。
+ * - 文本预览：`text/*` 等文本类，按 Range 读开头 {@link ARTIFACT_PREVIEW_MAX_BYTES} 字节、
+ *   至多 {@link ARTIFACT_PREVIEW_MAX_LINES} 行，以 JSON 字符串返回（网页按纯文本显示）；
+ *   其他类型、或读到的开头里有 NUL 字节（其实是二进制）→ `conversation.artifact_not_previewable`。
+ *
+ * 查找走 `conversation_events` 的主键 `(conversation_id, seq)` 前缀，在 SQL 里按 `type` 与
+ * `payload->>'artifactId'` 过滤、`LIMIT 1`（只扫这一个会话的事件，不在 JS 里扫日志；不加迁移）。
+ */
+export declare class ConversationArtifacts {
+    private readonly d;
+    constructor(d: ConversationArtifactsDeps);
+    private find;
+    downloadUrl(orgId: string, conversationId: string, viewerAccountId: string, artifactId: string, opts?: {
+        inline?: boolean;
+    }): Promise<{
+        url: string;
+        name: string;
+    }>;
+    preview(orgId: string, conversationId: string, viewerAccountId: string, artifactId: string): Promise<ArtifactPreview>;
+}

package/dist/conversations/artifacts.js

@@ -0,0 +1,137 @@
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { UUID_RE } from "../ui/registry.js";
+/** 产物下载跳转的预签名有效期（秒）。 */
+export const ARTIFACT_DOWNLOAD_TTL_SECONDS = 300;
+/** 下载 302 的 `Cache-Control: private, max-age=…`（秒），不长于预签名有效期。 */
+export const ARTIFACT_DOWNLOAD_CACHE_SECONDS = 60;
+/** 文本预览最多读取的字节数（从对象开头按 Range 读）。 */
+export const ARTIFACT_PREVIEW_MAX_BYTES = 8192;
+/** 文本预览最多的行数。 */
+export const ARTIFACT_PREVIEW_MAX_LINES = 40;
+/** 可以 `inline` 打开的类型：只有位图（SVG 能执行脚本，HTML 更不行，一律下载）。 */
+const INLINE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+/** `text/*` 之外也给文本预览的类型。 */
+const TEXT_TYPES = new Set([
+    "application/json",
+    "application/xml",
+    "application/yaml",
+    "application/sql",
+]);
+const baseType = (ct) => (ct.split(";")[0] ?? "").trim().toLowerCase();
+/** 产物能否以 `inline` 在页面里显示（只有位图）。 */
+export const isInlineArtifactType = (ct) => INLINE_TYPES.has(baseType(ct));
+/** 产物能否给文本预览（`text/*` 与常见的文本格式；SVG 不算）。 */
+export function isTextArtifactType(ct) {
+    const t = baseType(ct);
+    return t.startsWith("text/") || TEXT_TYPES.has(t);
+}
+const conversationNotFound = () => new ApiError("conversation.not_found", "Conversation not found");
+const artifactNotFound = () => new ApiError("conversation.artifact_not_found", "Artifact not found");
+/** 从流里读最多 `max` 字节（存储忽略 Range 时 body 可能是整个对象，读够就取消）。 */
+async function readPrefix(body, max) {
+    const reader = body.getReader();
+    const out = new Uint8Array(max);
+    let n = 0;
+    try {
+        while (n < max) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const take = Math.min(value.byteLength, max - n);
+            out.set(value.subarray(0, take), n);
+            n += take;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    return out.subarray(0, n);
+}
+/**
+ * 产物（M5 T8 / T11）：agent 经 `sandbox_deliver` 交付的文件。先按会话流的规则判定会话可见
+ * （不可见 → `conversation.not_found`），再只在这个会话的日志里找 `artifact_created`
+ * （没有 → `conversation.artifact_not_found`）。
+ *
+ * - 下载：302 到预签名地址，默认 `attachment`（带交付时的文件名与类型）；`inline` 只对位图生效
+ *   （网页的缩略图），其余类型即使要求 inline 也仍是 `attachment`。
+ * - 文本预览：`text/*` 等文本类，按 Range 读开头 {@link ARTIFACT_PREVIEW_MAX_BYTES} 字节、
+ *   至多 {@link ARTIFACT_PREVIEW_MAX_LINES} 行，以 JSON 字符串返回（网页按纯文本显示）；
+ *   其他类型、或读到的开头里有 NUL 字节（其实是二进制）→ `conversation.artifact_not_previewable`。
+ *
+ * 查找走 `conversation_events` 的主键 `(conversation_id, seq)` 前缀，在 SQL 里按 `type` 与
+ * `payload->>'artifactId'` 过滤、`LIMIT 1`（只扫这一个会话的事件，不在 JS 里扫日志；不加迁移）。
+ */
+export class ConversationArtifacts {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    async find(orgId, conversationId, viewerAccountId, artifactId) {
+        if (!UUID_RE.test(conversationId))
+            throw conversationNotFound();
+        if (!(await this.d.isAccessible(orgId, conversationId, viewerAccountId))) {
+            throw conversationNotFound();
+        }
+        if (!UUID_RE.test(artifactId))
+            throw artifactNotFound();
+        const row = await this.d.db
+            .selectFrom("conversation_events")
+            .select("payload")
+            .where("conversation_id", "=", conversationId)
+            .where("type", "=", "artifact_created")
+            .where(sql `payload->>'artifactId'`, "=", artifactId)
+            .limit(1)
+            .executeTakeFirst();
+        if (!row)
+            throw artifactNotFound();
+        return row.payload;
+    }
+    async downloadUrl(orgId, conversationId, viewerAccountId, artifactId, opts = {}) {
+        const a = await this.find(orgId, conversationId, viewerAccountId, artifactId);
+        const store = this.d.storage.kernel(orgId);
+        if (!(await store.head(a.objectKey)))
+            throw artifactNotFound();
+        const inline = opts.inline === true && isInlineArtifactType(a.contentType);
+        const url = await store.presignGet(a.objectKey, {
+            ttlSeconds: ARTIFACT_DOWNLOAD_TTL_SECONDS,
+            downloadName: a.name,
+            disposition: inline ? "inline" : "attachment",
+            responseContentType: a.contentType,
+        });
+        return { url, name: a.name };
+    }
+    async preview(orgId, conversationId, viewerAccountId, artifactId) {
+        const a = await this.find(orgId, conversationId, viewerAccountId, artifactId);
+        if (!isTextArtifactType(a.contentType)) {
+            throw new ApiError("conversation.artifact_not_previewable", "Only text artifacts have a preview");
+        }
+        const got = await this.d.storage
+            .kernel(orgId)
+            .get(a.objectKey, { range: { start: 0, end: ARTIFACT_PREVIEW_MAX_BYTES - 1 } });
+        if (!got)
+            throw artifactNotFound();
+        const bytes = await readPrefix(got.body, ARTIFACT_PREVIEW_MAX_BYTES);
+        // 类型说是文本、内容却是二进制（有 NUL）：不给预览，界面显示「不能预览」
+        if (bytes.includes(0)) {
+            throw new ApiError("conversation.artifact_not_previewable", "This artifact contains binary data and has no text preview");
+        }
+        // stream: true 丢掉被截断在末尾的半个多字节字符
+        let text = new TextDecoder("utf-8").decode(bytes, { stream: true });
+        let truncated = got.head.size > bytes.byteLength;
+        if (truncated) {
+            // 只读了开头：去掉最后不完整的一行
+            const nl = text.lastIndexOf("\n");
+            if (nl >= 0)
+                text = text.slice(0, nl);
+        }
+        const lines = text.split("\n");
+        if (text.endsWith("\n"))
+            lines.pop();
+        if (lines.length > ARTIFACT_PREVIEW_MAX_LINES) {
+            text = lines.slice(0, ARTIFACT_PREVIEW_MAX_LINES).join("\n");
+            truncated = true;
+        }
+        return { text, truncated };
+    }
+}

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

@@ -0,0 +1,28 @@
+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";
+declare const CreateBody: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * 对话附件（`/api/v1/orgs/:orgId/attachments`，`agents.use`，只接受人类用户）：
+ * 1. `POST /` 登记并取预签名上传（`upload.method` 为 `POST` 时按 multipart 表单：先放 `fields`，最后放 `file`）；
+ * 2. 浏览器直传对象存储；
+ * 3. `POST /:id/finalize` 核对大小与类型；
+ * 4. 发消息时在 `files` 里引用 id。
+ * 下载 `GET /:id/download` 302 到预签名地址（`Cache-Control: private, max-age=60`）。上限 `GET /limits`（类型、单个大小、
+ * 每条条数、单次请求的媒体预算、存储是否可用，供网页预检；不需要对象存储）。没有对象存储时其余接口 503 `storage.unavailable`。
+ */
+export declare class AttachmentsController {
+    private readonly attachments;
+    constructor(attachments: AttachmentsService);
+    limits(principal: Principal): AttachmentLimits;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<CreatedAttachment>;
+    finalize(principal: Principal, org: OrgContext, id: string): Promise<AttachmentView>;
+    download(principal: Principal, org: OrgContext, id: string, reply: FastifyReply): Promise<void>;
+}
+export {};

package/dist/conversations/attachments.controller.js

@@ -0,0 +1,96 @@
+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 { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
+import { Body, 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 { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ATTACHMENT_DOWNLOAD_CACHE_SECONDS, } from "./attachments.service.js";
+const CreateBody = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(MEDIA_NAME_MAX_CHARS)
+        .refine((s) => !hasControlChars(s), "name must not contain control characters"),
+    contentType: z.string().min(1).max(200),
+    size: z.number().int().min(1).max(Number.MAX_SAFE_INTEGER),
+})
+    .strict();
+/**
+ * 对话附件（`/api/v1/orgs/:orgId/attachments`，`agents.use`，只接受人类用户）：
+ * 1. `POST /` 登记并取预签名上传（`upload.method` 为 `POST` 时按 multipart 表单：先放 `fields`，最后放 `file`）；
+ * 2. 浏览器直传对象存储；
+ * 3. `POST /:id/finalize` 核对大小与类型；
+ * 4. 发消息时在 `files` 里引用 id。
+ * 下载 `GET /:id/download` 302 到预签名地址（`Cache-Control: private, max-age=60`）。上限 `GET /limits`（类型、单个大小、
+ * 每条条数、单次请求的媒体预算、存储是否可用，供网页预检；不需要对象存储）。没有对象存储时其余接口 503 `storage.unavailable`。
+ */
+let AttachmentsController = class AttachmentsController {
+    attachments;
+    constructor(attachments) {
+        this.attachments = attachments;
+    }
+    limits(principal) {
+        requireUser(principal);
+        return this.attachments.limits();
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return this.attachments.create(org.orgId, p.account.id, body);
+    }
+    async finalize(principal, org, id) {
+        const p = requireUser(principal);
+        return this.attachments.finalize(org.orgId, p.account.id, id);
+    }
+    async download(principal, org, id, reply) {
+        const p = requireUser(principal);
+        const location = await this.attachments.downloadUrl(org.orgId, p.account.id, id);
+        // 浏览器可在短时间内复用跳转（同一页面的缩略图）；预签名有效期不短于这段时间
+        await reply
+            .header("cache-control", `private, max-age=${ATTACHMENT_DOWNLOAD_CACHE_SECONDS}`)
+            .redirect(location, 302);
+    }
+};
+__decorate([
+    Get("limits"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal())
+], AttachmentsController.prototype, "limits", null);
+__decorate([
+    Post(),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(CreateBody)))
+], AttachmentsController.prototype, "create", null);
+__decorate([
+    Post(":id/finalize"),
+    HttpCode(200),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], AttachmentsController.prototype, "finalize", null);
+__decorate([
+    Get(":id/download"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Res())
+], AttachmentsController.prototype, "download", null);
+AttachmentsController = __decorate([
+    Controller("api/v1/orgs/:orgId/attachments"),
+    __param(0, Inject(ATTACHMENTS))
+], AttachmentsController);
+export { AttachmentsController };

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

@@ -0,0 +1,180 @@
+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 { MediaBytes, MediaInfo } from "../runtime/context/build.js";
+import type { StorageService } from "../storage/storage.service.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}（浏览器缓存的跳转仍可用）。 */
+export declare const ATTACHMENT_DOWNLOAD_TTL_SECONDS = 300;
+/** 下载 302 的 `Cache-Control: private, max-age=…`（秒）：同一页面里缩略图可复用跳转地址。 */
+export declare const ATTACHMENT_DOWNLOAD_CACHE_SECONDS = 60;
+/** 同一账号在一个组织里最多的未 finalize 附件数（超过 → 429 `attachment.too_many_pending`）。 */
+export declare const MAX_PENDING_ATTACHMENTS = 50;
+/** 技能包 zip 的内容类型（上传时一律按它签名，finalize 时核对 zip 文件头）。 */
+export declare const SKILL_PACKAGE_CONTENT_TYPE = "application/zip";
+/** 技能包 zip 的大小上限（字节）。 */
+export declare const SKILL_PACKAGE_UPLOAD_MAX_BYTES: number;
+/** 同一账号在一个组织里最多的未 finalize 技能包上传数（与对话附件分开计数）。 */
+export declare const MAX_PENDING_SKILL_PACKAGES = 5;
+/**
+ * 技能包上传的过期时间（小时）：没被 `POST /skills` 用掉的由清理任务删除（不跟对话附件的 `unboundTtlHours`）；
+ * `POST /skills` 开始处理时再顺延这么久，处理期间不会被清理。
+ */
+export declare const SKILL_PACKAGE_TTL_HOURS = 1;
+/**
+ * 技能包解出的文件在 `kernel/<orgId>/` 下的前缀：按上传 id，同一上传重试写到同一批键（幂等），
+ * 并发处理同一上传也不会互相覆盖出不同内容。版本行记下这个前缀（`skill_versions.object_prefix`）。
+ */
+export declare const skillFilesPrefix: (uploadId: string) => string;
+/** 维护任务：清理过期未绑定的附件（任务名与 scheduler id 不含 `:`）。 */
+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;
+    name: string;
+    contentType: string;
+    size: number;
+}
+/** 附件上限（`GET /attachments/limits`）：网页据此在上传前预检。 */
+export interface AttachmentLimits {
+    /** 允许的内容类型。 */
+    types: string[];
+    /** 非图片的单个上限（字节）。 */
+    maxBytes: number;
+    /** 图片的单个上限（字节，另受 `MEDIA_LIMITS.imageBytes` 限制）。 */
+    imageMaxBytes: number;
+    /** 单条消息最多附件数。 */
+    maxPerMessage: number;
+    /** 单次模型请求里媒体原始字节的预算（网页据此在发送前提醒总大小）。 */
+    requestMediaBytes: number;
+    /** 部署是否配置了对象存储；为 false 时上传不可用。 */
+    available: boolean;
+}
+/** {@link AttachmentsService.openForConversation} 的结果。 */
+export interface OpenedAttachment {
+    name: string;
+    contentType: string;
+    size: number;
+    body: ReadableStream<Uint8Array>;
+}
+/** `POST /attachments` 的返回：浏览器按 `upload` 直传存储，然后调 finalize。 */
+export interface CreatedAttachment {
+    id: string;
+    upload: PresignedUpload;
+    /** 预签名上传的过期时间（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）。 */
+export declare function sniffMatches(contentType: string, head: Uint8Array): boolean;
+/**
+ * PDF 的页数：数未压缩的页对象（`/Type /Page`，不含 `/Pages`）。页对象放在压缩的对象流里时数不到，返回 0。
+ */
+export declare function countPdfPages(bytes: Uint8Array): number;
+/**
+ * 对话附件（M5 T3）：登记 → 浏览器按预签名直传对象存储 → finalize 核对 → 发消息时绑定到会话。
+ * 字节只在对象存储（`kernel/<orgId>/attachments/<id>`），日志里只有引用；构建模型请求时经 {@link fetchMedia} 取字节。
+ * 无进程内状态，可多副本共用。
+ */
+export declare class AttachmentsService {
+    private readonly d;
+    constructor(d: AttachmentsDeps);
+    /** 单个附件的大小上限：配置的 `maxBytes`，图片再受 `MEDIA_LIMITS.imageBytes` 限制。 */
+    private limitFor;
+    /** 当前配置下的上限（不需要对象存储）。 */
+    limits(): AttachmentLimits;
+    /**
+     * 登记一个附件（`pending`）并返回预签名上传：存储端按声明的大小与类型限制上传。
+     * 类型不在 `attachments.allowedTypes` → `attachment.type_not_allowed`；超过上限 → `attachment.too_large`；
+     * 该账号在组织里已有 {@link MAX_PENDING_ATTACHMENTS} 个未 finalize 的附件 → `attachment.too_many_pending`
+     * （软上限：并发登记可能略超）；没有对象存储 → `storage.unavailable`。
+     */
+    create(orgId: string, accountId: string, input: {
+        name: string;
+        contentType: string;
+        size: number;
+    }, purpose?: AttachmentPurpose): Promise<CreatedAttachment>;
+    /**
+     * 上传完成后核对并标记为 `ready`（只有上传者能做；已 ready 时直接返回）：
+     * - 对象还不存在 → `attachment.not_ready`；
+     * - 大小与声明不符 → 删除已传的对象，大了 `attachment.too_large`、小了 `attachment.not_ready`（可重传）；
+     * - 存储记录的类型或文件开头的签名与声明不符 → 删除对象，`attachment.type_not_allowed`。
+     */
+    finalize(orgId: string, accountId: string, id: string): Promise<AttachmentView>;
+    /**
+     * 下载地址（预签名，{@link ATTACHMENT_DOWNLOAD_TTL_SECONDS} 秒）：已绑定的附件要求能访问其会话，
+     * 未绑定的只有上传者；否则 `attachment.not_found`。只有图片与 PDF 以 `inline` 打开，其余一律 `attachment`
+     * （即使存储里的类型被改成 text/html 也不会在页面里渲染）；响应类型按 finalize 核对过的类型返回。
+     */
+    downloadUrl(orgId: string, accountId: string, id: string): Promise<string>;
+    /**
+     * 绑定在该会话、已 ready 的附件（id 与原始文件名），按上传时间、id 排序（沙箱同步按这个顺序分配文件名）。
+     */
+    listForConversation(orgId: string, conversationId: string): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    /**
+     * 读取一个绑定在该会话、已 ready 的附件（沙箱同步等内核内部用途）：没有行、未绑定到该会话、对象已不在、
+     * 大小或 etag 与 finalize 时不符 → null。其余错误（存储不可用等）照常抛出。调用方负责读完或取消 `body`。
+     */
+    openForConversation(orgId: string, conversationId: string, attachmentId: string): Promise<OpenedAttachment | null>;
+    /**
+     * 发消息时在调用方事务里绑定附件（行锁），返回写进 user_message 的媒体块（`ref`，按 ids 顺序）：
+     * - 超过 `attachments.maxPerMessage`、或同一个 id 出现多次 → `validation_failed`；
+     * - 不存在、不是发送者上传的、已绑定到别的会话、未绑定且已过期 → `attachment.not_found`；
+     * - 还没 finalize → `attachment.not_ready`。
+     * 后两种的 details 为 `[{ path: "files", message, attachmentId }]`，网页据此标出对应条目。
+     * 已绑定到本会话的（重试）照常返回块。
+     */
+    bindForMessage(trx: Trx, orgId: string, conversationId: string, accountId: string, ids: readonly string[]): Promise<LogContentBlock[]>;
+    /** 下载 / 取字节时核对 etag：finalize 记下的与当前对象的不一致 → 内容被替换（记 warn）。没有记录时不核对。 */
+    private sameContent;
+    /**
+     * 构建模型请求时查附件行的声明信息（只含绑定在该会话、已 ready 的）：大小与 PDF 页数。
+     * 没有行的不在结果里；查询失败照常抛出。
+     */
+    mediaInfo(orgId: string, conversationId: string, ids: readonly string[]): Promise<Map<string, MediaInfo>>;
+    /**
+     * 构建模型请求时取附件字节：只取绑定在该会话、已 ready 的附件。只有「确定不存在」才为 null：没有行、对象已不在、
+     * 大小或 etag 与 finalize 时不符（内容被替换，记 warn）。其余错误（存储不可用、网络错误）一律抛出（Ruling M4），
+     * 由调用方按可重试处理，不会变成占位。`caps` 里的附件只按范围读开头若干字节（`text/*` 封顶，更后面的不取）。
+     */
+    fetchMedia(orgId: string, conversationId: string, ids: readonly string[], caps?: ReadonlyMap<string, number>): Promise<Map<string, MediaBytes | null>>;
+    /**
+     * 取一个技能包上传的字节，供 `POST /skills` 解包（只有上传者、只认 `skill-package` 用途）：
+     * 还没 finalize 的先 finalize（核对大小与 zip 文件头）；过期时间顺延 {@link SKILL_PACKAGE_TTL_HOURS} 小时，
+     * 处理期间不会被清理任务删掉。不存在、不是技能包、已用掉或已过期 → `attachment.not_found`；
+     * 对象已不在或内容与 finalize 时不符 → `attachment.not_found`。
+     */
+    readSkillPackage(orgId: string, accountId: string, id: string): Promise<Uint8Array>;
+    /**
+     * 在调用方事务里把技能包上传标记为已用掉（行锁；之后由清理任务删 zip，解出的文件因被版本引用而保留）。
+     * 不是该账号的 ready 技能包（如已被并发的请求用掉）→ `attachment.not_found`。
+     */
+    consumeSkillPackage(trx: Trx, orgId: string, accountId: string, id: string): Promise<void>;
+    /**
+     * 删除过期（`expires_at < now()`）且从未绑定到会话的附件：先把行认领为 `deleting`（`FOR UPDATE SKIP LOCKED`，
+     * 多副本并发时互不重复），再删对象、删行。删对象失败的行保持 `deleting`，下次运行重试。
+     * 技能包上传（过期未用掉的，或已被 `POST /skills` 用掉、`expires_at` 置为当时的）同样由这里删 zip；
+     * 解出的文件 `skills/<id>/` 只在没有任何技能版本引用时一并删除。
+     * 没有对象存储时什么也不做。返回删除的附件数。
+     */
+    deleteExpired(): Promise<number>;
+}
+export {};