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

package/dist/runtime/checkpointer.js

@@ -0,0 +1,243 @@
+import { BaseCheckpointSaver, compareWritesSortKeys, copyCheckpoint, getCheckpointId, maxChannelVersion, TASKS, WRITES_IDX_MAP, writesSortKey, } from "@langchain/langgraph-checkpoint";
+import { sql } from "kysely";
+const CHECKPOINT_COLUMNS = [
+    "thread_id",
+    "checkpoint_ns",
+    "checkpoint_id",
+    "parent_checkpoint_id",
+    "checkpoint_type",
+    "checkpoint",
+    "metadata_type",
+    "metadata",
+];
+/** checkpoint_id（uuid6）按字节序比较，不受数据库排序规则影响。 */
+const idC = sql `checkpoint_id collate "C"`;
+/**
+ * LangGraph checkpoint saver，存在内核 schema 的 `lg_checkpoints` / `lg_checkpoint_writes` 里（0007_checkpoints.sql）。
+ *
+ * - 每个 checkpoint 存整份（含全部 channel_values），不按 channel 增量存，所以 {@link pruneToLatest}
+ *   之后最新一份仍能独立还原。不要配合实验性的 `DeltaChannel` 使用：它依赖父链上的 writes 还原状态。
+ * - thread_id 约定为 runId。
+ * - 所有状态都在 PG 里，不持有进程内状态，任意副本都能续跑。
+ */
+export class KyselyCheckpointSaver extends BaseCheckpointSaver {
+    db;
+    constructor(db) {
+        super();
+        this.db = db;
+    }
+    async getTuple(config) {
+        const threadId = config.configurable?.thread_id;
+        if (threadId === undefined)
+            return undefined;
+        const ns = config.configurable?.checkpoint_ns ?? "";
+        const checkpointId = getCheckpointId(config);
+        let q = this.db
+            .selectFrom("lg_checkpoints")
+            .select(CHECKPOINT_COLUMNS)
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", ns);
+        q = checkpointId
+            ? q.where("checkpoint_id", "=", checkpointId)
+            : q.orderBy(sql `${idC} desc`).limit(1);
+        const row = await q.executeTakeFirst();
+        return row ? this.toTuple(row) : undefined;
+    }
+    async *list(config, options) {
+        const { before, filter } = options ?? {};
+        let { limit } = options ?? {};
+        const threadId = config.configurable?.thread_id;
+        const ns = config.configurable?.checkpoint_ns;
+        const checkpointId = config.configurable?.checkpoint_id;
+        const beforeId = before?.configurable?.checkpoint_id;
+        const filterEntries = Object.entries(filter ?? {});
+        let q = this.db.selectFrom("lg_checkpoints").select(CHECKPOINT_COLUMNS);
+        if (threadId !== undefined)
+            q = q.where("thread_id", "=", threadId);
+        if (ns !== undefined)
+            q = q.where("checkpoint_ns", "=", ns);
+        if (checkpointId)
+            q = q.where("checkpoint_id", "=", checkpointId);
+        if (beforeId)
+            q = q.where(idC, "<", beforeId);
+        q = q.orderBy(sql `${idC} desc`).orderBy("thread_id").orderBy("checkpoint_ns");
+        // metadata 是序列化字节，过滤只能在读出后做；没有过滤条件时 limit 下推到 SQL。
+        if (limit !== undefined && filterEntries.length === 0)
+            q = q.limit(Math.max(limit, 0));
+        const rows = await q.execute();
+        for (const row of rows) {
+            if (limit !== undefined && limit <= 0)
+                return;
+            const metadata = (await this.serde.loadsTyped(row.metadata_type, row.metadata));
+            if (!filterEntries.every(([k, v]) => metadata[k] === v))
+                continue;
+            if (limit !== undefined)
+                limit -= 1;
+            yield this.toTuple(row, metadata);
+        }
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        const threadId = config.configurable?.thread_id;
+        if (threadId === undefined) {
+            throw new Error('Failed to put checkpoint: config.configurable is missing the required "thread_id" field.');
+        }
+        const ns = config.configurable?.checkpoint_ns ?? "";
+        const parentId = config.configurable?.checkpoint_id ?? null;
+        const [[checkpointType, checkpointBytes], [metadataType, metadataBytes]] = await Promise.all([
+            this.serde.dumpsTyped(copyCheckpoint(checkpoint)),
+            this.serde.dumpsTyped(metadata),
+        ]);
+        const values = {
+            parent_checkpoint_id: parentId,
+            checkpoint_type: checkpointType,
+            checkpoint: Buffer.from(checkpointBytes),
+            metadata_type: metadataType,
+            metadata: Buffer.from(metadataBytes),
+        };
+        await this.db
+            .insertInto("lg_checkpoints")
+            .values({ thread_id: threadId, checkpoint_ns: ns, checkpoint_id: checkpoint.id, ...values })
+            .onConflict((oc) => oc.columns(["thread_id", "checkpoint_ns", "checkpoint_id"]).doUpdateSet(values))
+            .execute();
+        return {
+            configurable: { thread_id: threadId, checkpoint_ns: ns, checkpoint_id: checkpoint.id },
+        };
+    }
+    async putWrites(config, writes, taskId, taskPath) {
+        const threadId = config.configurable?.thread_id;
+        const checkpointId = config.configurable?.checkpoint_id;
+        if (threadId === undefined) {
+            throw new Error('Failed to put writes: config.configurable is missing the required "thread_id" field.');
+        }
+        if (checkpointId === undefined) {
+            throw new Error('Failed to put writes: config.configurable is missing the required "checkpoint_id" field.');
+        }
+        const ns = config.configurable?.checkpoint_ns ?? "";
+        const rows = await Promise.all(writes.map(async ([channel, value], i) => {
+            const [valueType, bytes] = await this.serde.dumpsTyped(value);
+            return {
+                thread_id: threadId,
+                checkpoint_ns: ns,
+                checkpoint_id: checkpointId,
+                task_id: taskId,
+                idx: WRITES_IDX_MAP[channel] ?? i,
+                channel,
+                value_type: valueType,
+                value: Buffer.from(bytes),
+                task_path: taskPath ?? "",
+            };
+        }));
+        // 特殊 channel（错误、中断等，idx < 0）以最后一次为准；普通 write 已存在则保留先写入的。
+        const special = rows.filter((r) => r.idx < 0);
+        const regular = rows.filter((r) => r.idx >= 0);
+        const key = ["thread_id", "checkpoint_ns", "checkpoint_id", "task_id", "idx"];
+        await this.db.transaction().execute(async (trx) => {
+            if (regular.length > 0) {
+                await trx
+                    .insertInto("lg_checkpoint_writes")
+                    .values(regular)
+                    .onConflict((oc) => oc.columns(key).doNothing())
+                    .execute();
+            }
+            if (special.length > 0) {
+                await trx
+                    .insertInto("lg_checkpoint_writes")
+                    .values(special)
+                    .onConflict((oc) => oc.columns(key).doUpdateSet((eb) => ({
+                    channel: eb.ref("excluded.channel"),
+                    value_type: eb.ref("excluded.value_type"),
+                    value: eb.ref("excluded.value"),
+                    task_path: eb.ref("excluded.task_path"),
+                })))
+                    .execute();
+            }
+        });
+    }
+    async deleteThread(threadId) {
+        await this.db.transaction().execute(async (trx) => {
+            await trx.deleteFrom("lg_checkpoint_writes").where("thread_id", "=", threadId).execute();
+            await trx.deleteFrom("lg_checkpoints").where("thread_id", "=", threadId).execute();
+        });
+    }
+    /**
+     * 一轮运行结束后调用：根命名空间（`checkpoint_ns = ''`）下只保留最新一个 checkpoint 及其 writes，
+     * 更早的 checkpoint 与它们的 writes 删除。只删 checkpoint_id **小于**最新的（按字节序）：
+     * 读出最新与删除之间并发写入的更新 checkpoint 不会被误删（R20）。返回删除的 checkpoint 条数。其他命名空间（子图）不动。
+     * 保留下来的 checkpoint 的 parent_checkpoint_id 原样保留（父 checkpoint 已不存在）。
+     */
+    async pruneToLatest(threadId) {
+        return this.db.transaction().execute(async (trx) => {
+            const latest = await trx
+                .selectFrom("lg_checkpoints")
+                .select("checkpoint_id")
+                .where("thread_id", "=", threadId)
+                .where("checkpoint_ns", "=", "")
+                .orderBy(sql `${idC} desc`)
+                .limit(1)
+                .executeTakeFirst();
+            if (!latest)
+                return 0;
+            await trx
+                .deleteFrom("lg_checkpoint_writes")
+                .where("thread_id", "=", threadId)
+                .where("checkpoint_ns", "=", "")
+                .where(idC, "<", latest.checkpoint_id)
+                .execute();
+            const res = await trx
+                .deleteFrom("lg_checkpoints")
+                .where("thread_id", "=", threadId)
+                .where("checkpoint_ns", "=", "")
+                .where(idC, "<", latest.checkpoint_id)
+                .executeTakeFirst();
+            return Number(res.numDeletedRows);
+        });
+    }
+    async toTuple(row, metadata) {
+        const { thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id } = row;
+        const checkpoint = (await this.serde.loadsTyped(row.checkpoint_type, row.checkpoint));
+        if (checkpoint.v < 4 && parent_checkpoint_id !== null) {
+            await this.migratePendingSends(checkpoint, thread_id, checkpoint_ns, parent_checkpoint_id);
+        }
+        const tuple = {
+            config: { configurable: { thread_id, checkpoint_ns, checkpoint_id } },
+            checkpoint,
+            metadata: metadata ??
+                (await this.serde.loadsTyped(row.metadata_type, row.metadata)),
+            pendingWrites: (await this.loadWrites(thread_id, checkpoint_ns, checkpoint_id)).map((w) => [w.taskId, w.channel, w.value]),
+        };
+        if (parent_checkpoint_id !== null) {
+            tuple.parentConfig = {
+                configurable: { thread_id, checkpoint_ns, checkpoint_id: parent_checkpoint_id },
+            };
+        }
+        return tuple;
+    }
+    /** 某个 checkpoint 的 writes，按 `writesSortKey`（task_path, task_id, idx）排序。 */
+    async loadWrites(threadId, ns, checkpointId) {
+        const rows = await this.db
+            .selectFrom("lg_checkpoint_writes")
+            .select(["task_id", "idx", "channel", "value_type", "value", "task_path"])
+            .where("thread_id", "=", threadId)
+            .where("checkpoint_ns", "=", ns)
+            .where("checkpoint_id", "=", checkpointId)
+            .execute();
+        rows.sort((a, b) => compareWritesSortKeys(writesSortKey(a.task_path, a.task_id, a.idx), writesSortKey(b.task_path, b.task_id, b.idx)));
+        return Promise.all(rows.map(async (r) => ({
+            taskId: r.task_id,
+            channel: r.channel,
+            value: await this.serde.loadsTyped(r.value_type, r.value),
+        })));
+    }
+    /** v < 4 的旧 checkpoint：把父 checkpoint 上的 TASKS writes 迁成本 checkpoint 的 TASKS channel（同 MemorySaver）。 */
+    async migratePendingSends(checkpoint, threadId, ns, parentId) {
+        const sends = (await this.loadWrites(threadId, ns, parentId))
+            .filter((w) => w.channel === TASKS)
+            .map((w) => w.value);
+        checkpoint.channel_values ??= {};
+        checkpoint.channel_values[TASKS] = sends;
+        checkpoint.channel_versions ??= {};
+        const versions = Object.values(checkpoint.channel_versions);
+        checkpoint.channel_versions[TASKS] =
+            versions.length > 0 ? maxChannelVersion(...versions) : this.getNextVersion(undefined);
+    }
+}

package/dist/runtime/context/build.d.ts

@@ -0,0 +1,254 @@
+import { type ContentBlock, type ModelInfo, type ModelRequest, type ParamValue } from "@capybara-hq/plugin-sdk";
+import type { AgentDefinition } from "../../agents/definition.js";
+import type { ConversationEvent, EventPayload } from "../../conversations/events.js";
+import type { ResolvedTool } from "../../tools/registry.js";
+/**
+ * 平台行为规范（模型可见，英文）。短而通用（spec 6 原则 5）；不放时间戳、会话 ID 等会变化的内容，
+ * 保证同一 agent 版本在所有会话中 system 前缀一致、可命中提示词缓存。改动它会让所有缓存失效。
+ */
+export declare const BEHAVIOR_RULES: string;
+/** 一次模型请求的来源（与 `model_call` 事件的 `request` 字段相同）：凭它可从日志还原请求。 */
+export interface ModelCallMeta {
+    /** 参与构建的事件 seq 下界（含）：有摘要时为 `coversUpToSeq + 1`。 */
+    fromSeq: number;
+    /** 参与构建的事件 seq 上界（含）。 */
+    toSeq: number;
+    /** 使用的 `compaction_summary` 事件 seq；没有摘要为 null。 */
+    summarySeq: number | null;
+    /** system 文本的 sha256（hex）。 */
+    systemHash: string;
+    /** 被放进请求的 `reminder` 事件 seq。 */
+    reminderSeqs: number[];
+    /** 构建时的 `absorbedUpToSeq`（见 {@link BuildModelRequestInput}）；未提供则没有该字段。 */
+    absorbedUpToSeq?: number;
+    /** 请求的模型参数（即 `ModelRequest.params`）。 */
+    params: Record<string, ParamValue>;
+    /**
+     * 请求带的工具（按发送顺序）及定义指纹；定义本身按指纹存在 `capybara.tool_specs`。
+     * 未启用 tool_search 时按 key 排序；启用时见 {@link BuildModelRequestInput.toolSearch}。
+     */
+    tools: {
+        key: string;
+        specHash: string;
+    }[];
+    /** 启用 tool_search 时 system 第二块目录里的工具（按 key 排序）及定义指纹；未启用没有该字段。 */
+    catalog?: {
+        key: string;
+        specHash: string;
+    }[];
+    /** 请求的 `toolChoice`（收尾调用为 `"none"`）；未设置则没有该字段。 */
+    toolChoice?: "auto" | "none";
+    /**
+     * 请求里每个附件的处理结果（按首次出现，同一附件一条）；发了字节的带 finalize 时的 etag。没有媒体则没有该字段。
+     */
+    media?: MediaOutcomeEntry[];
+    /** 请求里有媒体、且给了有限的预算时：所用的媒体字节预算（还原时重现同样的省略）。 */
+    mediaBudgetBytes?: number;
+}
+/** 构建请求用到的工具信息（`ResolvedTool` 的子集）。 */
+export type RequestTool = Pick<ResolvedTool, "key" | "spec" | "specHash">;
+export interface BuildModelRequestInput {
+    events: ConversationEvent[];
+    agent: AgentDefinition;
+    agentVersion: number;
+    model: ModelInfo;
+    step: number;
+    /**
+     * loop 已吸收到的 user_message seq（R31）。提供时：
+     * - seq 大于它的 user_message 不进请求（运行中途到达、尚未被吸收的插话，由后续步骤吸收或触发下一轮）；
+     * - 每条 user_message 放在**吸收它的那次模型调用**的位置：日志里第一个 `request.absorbedUpToSeq`
+     *   不小于它的 `model_call` 之前（没有该字段的旧 model_call 视为吸收了它之前的全部消息），
+     *   本次请求吸收的放在末尾。于是模型看到的历史只追加（插话不会插到已发送的回复之前），
+     *   且请求可由日志 + `model_call` 精确还原。
+     * 不提供时按 seq 原样回放全部 user_message。
+     */
+    absorbedUpToSeq?: number;
+    /**
+     * 本次请求的模型参数，原样放进 `ModelRequest.params`（不读 agent 定义里的参数）：
+     * 由 `runModelStep` 按所用模型的声明 sanitize 后传入，并记在 `model_call.request.params`；
+     * 还原时传入记录下的值。默认空。
+     */
+    params?: Record<string, ParamValue>;
+    /**
+     * 本步可用的工具（由 `ToolRegistry.forAgent` 在步骤开始时解析）。映射为 `ToolDefinition`
+     * （`name` 为模型可见的 key），按 key 排序以保证缓存前缀稳定；key 与指纹记在 `meta.tools`。默认空。
+     */
+    tools?: RequestTool[];
+    /**
+     * 启用 tool_search（spec 5.5，由 `ToolRegistry.forAgent` 判定）。启用且有工具时：
+     * - `tools` 只放内置工具（含 `tool_search`，按 key 排序）与**已加载**工具的完整定义；
+     *   已加载 = 日志中全部 `tool_result.loadedTools` 的并集（含摘要之前的；不在本步可用工具中的忽略），
+     *   按首次加载顺序追加在内置工具之后——新加载只在末尾追加，已发送的工具顺序不变；
+     * - 其余工具（不论是否已加载）以目录形式放进 system 第二个块（按 key 排序，打缓存断点），
+     *   目录只随可用工具集合变化，不随加载变化，保持 system 前缀稳定。
+     * 默认不启用（全部工具按 key 排序直接放完整定义）。
+     */
+    toolSearch?: boolean;
+    /** 本次请求的 `ModelRequest.toolChoice`；只在有工具时生效（没有工具时请求与 meta 都不带）。 */
+    toolChoice?: "auto" | "none";
+    /**
+     * 日志里媒体引用（`source.kind === "ref"`）对应的附件行（声明大小、PDF 页数）：附件 id → 信息；
+     * 缺省表示没有行（已删除）→「不再可用」占位。预算（{@link planMedia}）只按这里的声明大小计算，结果确定。
+     */
+    mediaInfo?: ReadonlyMap<string, MediaInfo>;
+    /**
+     * 引用的字节：附件 id → 字节；null 或缺省表示取不到（对象已不在、内容被替换）。调用方按 {@link planMedia}
+     * 的 `fetch` 取好再传入（本函数保持纯函数）。解析规则见 {@link resolveMedia}。
+     */
+    media?: ReadonlyMap<string, MediaBytes | null>;
+    /** 单次请求里媒体原始字节的预算（见 {@link planMedia}）；默认不限。 */
+    mediaBudgetBytes?: number;
+}
+/** 一个附件的字节。 */
+export interface MediaBytes {
+    mediaType: string;
+    data: Uint8Array;
+}
+/** 一个附件行的声明信息（finalize 时核对过）。 */
+export interface MediaInfo {
+    /** 字节数。 */
+    size: number;
+    /** PDF 的页数（finalize 时数出）；不是 PDF 或数不到为 null。 */
+    pages: number | null;
+    /** finalize 时记下的对象 etag（记进 `model_call` 的媒体结果，便于核对还原）；提供方不给为 null / 缺省。 */
+    etag?: string | null;
+}
+/** `text/*` 附件（内联文本与 base64 文档两种方式都一样）的最大字符数（UTF-16 码元，超出截断并注明）。 */
+export declare const TEXT_INLINE_MAX_CHARS = 50000;
+/**
+ * `text/*` 附件最多取的字节数：UTF-8 里一个 UTF-16 码元最多 3 字节，取这么多一定够凑满
+ * {@link TEXT_INLINE_MAX_CHARS}。更后面的字节不取（按范围读），预算也只按封顶后的大小计。
+ */
+export declare const TEXT_FETCH_MAX_BYTES: number;
+/** 单次请求最多的图片数（常见供应商的上限）：只保留最新的，更早的换成占位。 */
+export declare const MAX_IMAGES_PER_REQUEST = 20;
+/** PDF 的最大页数（常见供应商的上限）：页数（finalize 时数出）超过它的换成占位。 */
+export declare const MAX_PDF_PAGES = 100;
+/** 一张图片的估算 token 数（固定值，与尺寸无关）。 */
+export declare const IMAGE_TOKENS = 1600;
+/** PDF 每页的估算 token 数。 */
+export declare const PDF_PAGE_TOKENS = 1000;
+/** 数不到页数时，PDF 按每多少字节一页估算。 */
+export declare const PDF_BYTES_PER_PAGE_ESTIMATE: number;
+/** PDF 的估算 token 数：有页数按页数，没有按 `ceil(字节数 / 100 KB)`（最多 {@link MAX_PDF_PAGES} 页）。 */
+export declare function pdfTokens(size: number, pages: number | null): number;
+/** 日志里（按 zod 推导的形状）的内容块。 */
+type LogBlock = EventPayload<"user_message">["content"][number];
+/**
+ * 日志里 `media_excluded` 排除的附件（全部事件的并集，不看摘要边界）：此后的请求一律换成「被供应商拒绝」占位。
+ */
+export declare function excludedMedia(events: readonly ConversationEvent[]): Set<string>;
+/**
+ * 该模型需要的附件 id（去重、按出现顺序），调用方据此查行信息（{@link MediaInfo}）。
+ * 模型不支持的图片 / PDF、被 `media_excluded` 排除的不在其中——只发占位，行与字节都不取。
+ */
+export declare function mediaRefs(events: readonly ConversationEvent[], model: ModelInfo): string[];
+/** {@link planMedia} 的结果。 */
+export interface MediaPlan {
+    /** 要取字节的附件 id（从新到旧）。 */
+    fetch: string[];
+    /** 只取开头若干字节的附件（`text/*` 超过 {@link TEXT_FETCH_MAX_BYTES}）：id → 字节数。 */
+    caps: Map<string, number>;
+    /** 为控制请求大小而省略（预算）。 */
+    dropped: Set<string>;
+    /** 图片超过 {@link MAX_IMAGES_PER_REQUEST} 而省略。 */
+    tooManyImages: Set<string>;
+    /** PDF 页数超过 {@link MAX_PDF_PAGES}。 */
+    tooManyPages: Set<string>;
+    /** 日志里 `media_excluded` 排除的。 */
+    excluded: Set<string>;
+}
+/**
+ * 单次请求的媒体计划（Ruling M6 / M8），只取决于日志、模型能力与行信息，是确定的：
+ * - 被 `media_excluded` 排除的：不取、不计；
+ * - PDF 页数超过 {@link MAX_PDF_PAGES}：不取、不计；
+ * - 从最新的媒体往前：图片最多保留 {@link MAX_IMAGES_PER_REQUEST} 张，更早的图片省略（不影响其他媒体）；
+ * - 预算：按行里的**声明大小**（`text/*` 按封顶后的大小 `min(size, TEXT_FETCH_MAX_BYTES)`）累计，
+ *   第一次超出 `budgetBytes` 起，该附件及更早的全部省略；
+ * - 同一附件只算一次（按最后一次出现的位置算新旧）；没有行的不计（它们是「不再可用」）。
+ *
+ * 已知取舍（接受）：新的媒体把较早的媒体挤成占位时，请求里**较早位置**的内容随之改变，这一处之后的提示词缓存
+ * 失效（不是严格的只追加）。配置保证 `maxBytes ≤ requestMediaBytes`，所以最新的附件总能放进请求。
+ */
+export declare function planMedia(events: readonly ConversationEvent[], model: ModelInfo, info: ReadonlyMap<string, MediaInfo>, budgetBytes?: number): MediaPlan;
+/** 文字占位里的附件名：按 JSON 字符串转义（带引号），名字里的引号、括号不会打乱占位。 */
+export declare const quoted: (name: string) => string;
+/** 附件不可用时的占位（模型可见，英文）。 */
+export declare const mediaUnavailableText: (name: string) => string;
+/** 为控制单次请求大小而省略的附件（模型可见，英文）。 */
+export declare const mediaOmittedText: (name: string) => string;
+/** 单次请求图片太多而省略的附件（模型可见，英文）。 */
+export declare const mediaTooManyImagesText: (name: string) => string;
+/** PDF 页数超过上限（模型可见，英文）。 */
+export declare const mediaTooManyPagesText: (name: string) => string;
+/** 被供应商拒绝、此后不再发送的附件（模型可见，英文）。 */
+export declare const mediaRejectedText: (name: string) => string;
+/** {@link resolveMedia} 的输入：行信息、字节与本次请求的媒体计划。 */
+export interface MediaContext {
+    info: ReadonlyMap<string, MediaInfo> | undefined;
+    bytes: ReadonlyMap<string, MediaBytes | null> | undefined;
+    plan: MediaPlan;
+}
+/** `model_call.request.media` 的一项（形状取自事件 schema）。 */
+export type MediaOutcomeEntry = NonNullable<EventPayload<"model_call">["request"]["media"]>[number];
+/** 一个附件在本次请求里的处理结果。 */
+export type MediaOutcome = MediaOutcomeEntry["outcome"];
+/**
+ * 把日志里的媒体引用换成发给模型的内容（不改日志，结果只取决于日志、模型能力、行信息与字节）：
+ * - 模型不支持（图片看 `vision`，文档看 `documents`）：图片 / PDF 换成英文占位，**绝不带字节**；
+ * - 被 `media_excluded` 排除 →「被供应商拒绝」占位；没有行 →「不再可用」；PDF 页数过多 →「页数太多」；
+ *   图片太多或超出预算 →「省略」；取不到字节 →「不再可用」；字节超过 `MEDIA_LIMITS` →「太大」；
+ * - `text/*`：两种方式都封顶为 {@link TEXT_INLINE_MAX_CHARS} 个字符并注明截断——不支持 documents 时内联为文本，
+ *   支持时作为 base64 文档（截断时文档内容是截断后的文本加注明）；
+ * - 其余 → `base64` 块。
+ * 插件永远收不到 `ref`。返回块、发出的媒体块的估算 token 数（图片 {@link IMAGE_TOKENS}，PDF 见 {@link pdfTokens}，
+ * 文本文档按发出的字节数 ÷ 3）与每个块的处理结果。
+ */
+export declare function resolveMedia(content: readonly LogBlock[], model: ModelInfo, ctx: MediaContext): {
+    blocks: ContentBlock[];
+    tokens: number;
+    outcomes: {
+        attachmentId: string;
+        outcome: MediaOutcome;
+    }[];
+};
+type SummaryEvent = ConversationEvent & {
+    type: "compaction_summary";
+    payload: EventPayload<"compaction_summary">;
+};
+/** 最近一条 `compaction_summary` 事件（按 seq）；没有则 null。 */
+export declare function latestSummary(events: ConversationEvent[]): SummaryEvent | null;
+/** 摘要作为首条 user 消息时的文本。 */
+export declare function summaryText(summary: string): string;
+/**
+ * 由会话事件日志 + agent 定义构建模型请求（纯函数，不做 I/O）。
+ * - system：`BEHAVIOR_RULES + "\n\n" + agent.instructions` 一个块，打缓存断点（a sub-agent's log:
+ *   `BEHAVIOR_RULES`, its preamble and its instructions, all from its `subagent_started`）；日志里第一份 `skills_catalog`
+ *   快照在任何 `model_call` 之前时，技能目录接在这个块末尾（Ruling M17，见 ./skills.ts）；启用 tool_search 时
+ *   第二个块是工具目录（见 {@link BuildModelRequestInput.toolSearch}）；
+ * - 之后的 `skills_catalog` 在所在位置渲染为 system 变更提醒；被压缩摘要覆盖的，若摘要时生效的目录与 system 里的
+ *   不同，紧随摘要补一条完整的当前目录；
+ * - messages：最近一条摘要（若有）作为首条 user 消息，其后按 seq 回放 `coversUpToSeq` 之后的
+ *   `user_message` / `assistant_message`（content 原样，含 opaque；aborted 的也回放；媒体引用按
+ *   {@link resolveMedia} 换成 base64 或文字占位）/ `reminder`
+ *   （`role: "system"`，放在它所在的位置）；`tool_result` 事件还原为紧随其 assistant 消息之后的一条 user 消息
+ *   （同一步的多个结果合并，按该 assistant 消息里 tool_call 的顺序；找不到对应调用的结果不进请求）。
+ *   其他事件不进请求。提供 `absorbedUpToSeq` 时，
+ *   尚未被吸收的 user_message 不进请求，运行中途到达的插话放在吸收它的调用处（见 BuildModelRequestInput）。
+ * 只追加：新事件只会在 messages 末尾追加；唯一的前缀变化来自新的压缩摘要。
+ * `step` 与 `agentVersion` 不进请求内容（保证缓存前缀稳定），由调用方写入 `model_call` 事件。
+ */
+export declare function buildModelRequest(input: BuildModelRequestInput): {
+    request: ModelRequest;
+    meta: ModelCallMeta;
+    /** 请求里媒体块（base64 的图片 / 文档）的估算 token 数，传给 `estimateTokens`。 */
+    mediaTokens: number;
+};
+/**
+ * 日志里 `tool_search` 加载过的工具 key（全部 `tool_result.loadedTools` 的并集，按首次出现顺序）。
+ * 不看压缩摘要的边界：加载过的工具在摘要之后仍保持加载（模型可能凭摘要继续使用它们，且已发送的工具列表只追加）。
+ */
+export declare function loadedToolKeys(events: readonly ConversationEvent[]): string[];
+/** system 各块文本的 sha256（hex）；按 JSON 数组哈希，避免块边界歧义。 */
+export declare function hashSystem(system: ModelRequest["system"]): string;
+export {};