@armadra/agent 0.0.0-stage → 0.3.0

package/dist/compaction/cut-point.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 档二切点（设计 §9「档二」）。[B2]
+ *
+ * 在投影条目上从新往旧累计估算 token，到 `keepRecentTokens` 为止，切在其后最近的合法切点：
+ * user / assistant / custom_message / branch_summary（**不切 toolResult**；切在带工具调用的
+ * assistant 上时，它的结果随之保留）。system 消息不参与（它们折进 system 检查点，永不被摘要掉）。
+ * 切点不是回合起点（user / custom / branch_summary）时为 split turn：被摘要段分成「历史」与
+ * 「本回合前缀」两部分，各写一份摘要再合并。
+ */
+import type { ContextItem } from "../session/projection.js";
+import type { AgentMessage } from "../session/types.js";
+export interface CutPointResult {
+    /** items 中保留区的起点。等于 startIndex 表示没有可摘要的内容。 */
+    firstKeptIndex: number;
+    /** split turn 时本回合起点；否则 -1。 */
+    turnStartIndex: number;
+    isSplitTurn: boolean;
+}
+export declare function isCutPoint(message: AgentMessage): boolean;
+export declare function isTurnStart(message: AgentMessage): boolean;
+/** 摘要区的起点：跳过开头的 system 检查点与上一份压缩摘要。 */
+export declare function summarizableStart(items: readonly ContextItem[]): number;
+export declare function findCutPoint(items: readonly ContextItem[], startIndex: number, keepRecentTokens: number): CutPointResult;

package/dist/compaction/cut-point.js

@@ -0,0 +1,70 @@
+/**
+ * 档二切点（设计 §9「档二」）。[B2]
+ *
+ * 在投影条目上从新往旧累计估算 token，到 `keepRecentTokens` 为止，切在其后最近的合法切点：
+ * user / assistant / custom_message / branch_summary（**不切 toolResult**；切在带工具调用的
+ * assistant 上时，它的结果随之保留）。system 消息不参与（它们折进 system 检查点，永不被摘要掉）。
+ * 切点不是回合起点（user / custom / branch_summary）时为 split turn：被摘要段分成「历史」与
+ * 「本回合前缀」两部分，各写一份摘要再合并。
+ */
+import { estimateMessageTokens } from "./estimate.js";
+export function isCutPoint(message) {
+    return (message.role === "user" ||
+        message.role === "assistant" ||
+        message.role === "custom" ||
+        message.role === "branchSummary");
+}
+export function isTurnStart(message) {
+    return message.role === "user" || message.role === "custom" || message.role === "branchSummary";
+}
+/** 摘要区的起点：跳过开头的 system 检查点与上一份压缩摘要。 */
+export function summarizableStart(items) {
+    let i = 0;
+    while (i < items.length) {
+        const role = items[i]?.message.role;
+        if (role !== "system" && role !== "compactionSummary")
+            break;
+        i++;
+    }
+    return i;
+}
+export function findCutPoint(items, startIndex, keepRecentTokens) {
+    const cutPoints = [];
+    for (let i = startIndex; i < items.length; i++) {
+        const message = items[i]?.message;
+        if (message !== undefined && isCutPoint(message))
+            cutPoints.push(i);
+    }
+    const none = {
+        firstKeptIndex: startIndex,
+        turnStartIndex: -1,
+        isSplitTurn: false,
+    };
+    if (cutPoints.length === 0)
+        return none;
+    let accumulated = 0;
+    let cutIndex = startIndex;
+    for (let i = items.length - 1; i >= startIndex; i--) {
+        const message = items[i]?.message;
+        if (message === undefined || message.role === "system")
+            continue;
+        accumulated += estimateMessageTokens(message);
+        if (accumulated >= keepRecentTokens) {
+            cutIndex = cutPoints.find((candidate) => candidate >= i) ?? cutPoints.at(-1);
+            break;
+        }
+    }
+    if (cutIndex <= startIndex)
+        return none;
+    const cutMessage = items[cutIndex]?.message;
+    if (cutMessage === undefined || isTurnStart(cutMessage)) {
+        return { firstKeptIndex: cutIndex, turnStartIndex: -1, isSplitTurn: false };
+    }
+    for (let i = cutIndex - 1; i >= startIndex; i--) {
+        const message = items[i]?.message;
+        if (message !== undefined && isTurnStart(message)) {
+            return { firstKeptIndex: cutIndex, turnStartIndex: i, isSplitTurn: true };
+        }
+    }
+    return { firstKeptIndex: cutIndex, turnStartIndex: -1, isSplitTurn: false };
+}

package/dist/compaction/estimate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 上下文 token 估算（设计 §9「估算」）。[B2]
+ *
+ * `contextTokens` = 最后一条非 error / aborted 助手消息的 `totalTokens`（缺则
+ * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（字符 / 4，图片 1 600）。
+ * 若该 usage 之后活动分支上出现过 `context_edit` 或 `compaction`，usage 不再可信，按投影全量重估。
+ */
+import type { Usage } from "../ai/types.js";
+import type { ContextItem } from "../session/projection.js";
+import type { AgentMessage, SessionEntry } from "../session/types.js";
+export declare const IMAGE_TOKENS = 1600;
+export declare function calculateContextTokens(usage: Usage): number;
+/** 单条消息的估算（字符 / 4 向上取整，图片每张 1 600）。 */
+export declare function estimateMessageTokens(message: AgentMessage): number;
+export declare function estimateMessagesTokens(messages: readonly AgentMessage[]): number;
+export interface ContextEstimate {
+    tokens: number;
+    /** 来自 usage 的部分（0 = 全量估算）。 */
+    usageTokens: number;
+    trailingTokens: number;
+    /** 被采信的 usage 所在消息下标。 */
+    lastUsageIndex: number | null;
+}
+/** 只看消息：最后一条可用 usage + 其后估算；无 usage 则全量估算。 */
+export declare function estimateContextTokens(messages: readonly AgentMessage[]): ContextEstimate;
+/**
+ * 投影感知的估算：usage 所在条目之后若有 context_edit / compaction，按投影全量重估。
+ * `items` 是 buildProjection(branch).items，`branch` 是同一活动分支。
+ */
+export declare function estimateProjectedTokens(items: readonly ContextItem[], branch: readonly SessionEntry[]): ContextEstimate;

package/dist/compaction/estimate.js

@@ -0,0 +1,114 @@
+/**
+ * 上下文 token 估算（设计 §9「估算」）。[B2]
+ *
+ * `contextTokens` = 最后一条非 error / aborted 助手消息的 `totalTokens`（缺则
+ * `input + output + cacheRead + cacheWrite`，**含 output**）+ 其后消息的估算（字符 / 4，图片 1 600）。
+ * 若该 usage 之后活动分支上出现过 `context_edit` 或 `compaction`，usage 不再可信，按投影全量重估。
+ */
+export const IMAGE_TOKENS = 1600;
+const CHARS_PER_TOKEN = 4;
+export function calculateContextTokens(usage) {
+    return usage.totalTokens > 0
+        ? usage.totalTokens
+        : usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+function contentChars(content) {
+    if (typeof content === "string")
+        return { chars: content.length, images: 0 };
+    let chars = 0;
+    let images = 0;
+    for (const block of content) {
+        if (block.type === "text")
+            chars += block.text.length;
+        else
+            images++;
+    }
+    return { chars, images };
+}
+/** 单条消息的估算（字符 / 4 向上取整，图片每张 1 600）。 */
+export function estimateMessageTokens(message) {
+    let chars = 0;
+    let images = 0;
+    switch (message.role) {
+        case "system":
+            for (const text of Object.values(message.sections))
+                chars += text?.length ?? 0;
+            if (message.toolsAdded !== undefined)
+                chars += JSON.stringify(message.toolsAdded).length;
+            break;
+        case "user":
+        case "toolResult":
+        case "custom": {
+            const counted = contentChars(message.content);
+            chars = counted.chars;
+            images = counted.images;
+            break;
+        }
+        case "assistant":
+            for (const block of message.content) {
+                if (block.type === "text")
+                    chars += block.text.length;
+                else if (block.type === "thinking")
+                    chars += block.thinking.length;
+                else
+                    chars += block.name.length + JSON.stringify(block.arguments).length;
+            }
+            break;
+        case "compactionSummary":
+        case "branchSummary":
+            chars = message.summary.length;
+            break;
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN) + images * IMAGE_TOKENS;
+}
+export function estimateMessagesTokens(messages) {
+    let total = 0;
+    for (const message of messages)
+        total += estimateMessageTokens(message);
+    return total;
+}
+function usableUsage(message) {
+    if (message.role !== "assistant")
+        return undefined;
+    if (message.stopReason === "error" || message.stopReason === "aborted")
+        return undefined;
+    return calculateContextTokens(message.usage) > 0 ? message.usage : undefined;
+}
+/** 只看消息：最后一条可用 usage + 其后估算；无 usage 则全量估算。 */
+export function estimateContextTokens(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        const usage = message === undefined ? undefined : usableUsage(message);
+        if (usage === undefined)
+            continue;
+        const usageTokens = calculateContextTokens(usage);
+        const trailingTokens = estimateMessagesTokens(messages.slice(i + 1));
+        return { tokens: usageTokens + trailingTokens, usageTokens, trailingTokens, lastUsageIndex: i };
+    }
+    const tokens = estimateMessagesTokens(messages);
+    return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };
+}
+/**
+ * 投影感知的估算：usage 所在条目之后若有 context_edit / compaction，按投影全量重估。
+ * `items` 是 buildProjection(branch).items，`branch` 是同一活动分支。
+ */
+export function estimateProjectedTokens(items, branch) {
+    const messages = items.map((item) => item.message);
+    const estimate = estimateContextTokens(messages);
+    if (estimate.lastUsageIndex !== null) {
+        const usageEntryId = items[estimate.lastUsageIndex]?.entry.id;
+        const usageAt = branch.findIndex((entry) => entry.id === usageEntryId);
+        let invalidatedAt = -1;
+        for (let i = branch.length - 1; i >= 0; i--) {
+            const type = branch[i]?.type;
+            if (type === "context_edit" || type === "compaction") {
+                invalidatedAt = i;
+                break;
+            }
+        }
+        if (usageAt > invalidatedAt)
+            return estimate;
+    }
+    const tokens = estimateMessagesTokens(messages);
+    return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };
+}

package/dist/compaction/prune-tier.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 档一裁剪（设计 §9「档一」）：无模型调用。[B2]
+ *
+ * 触发：`contextTokens > 0.7 × (contextWindow − reserveTokens)`。
+ * 范围：最近两个用户回合之前、内容 > 2 KiB 的 toolResult。
+ * 动作：返回 `context_edit{reason:"prune", replacement:"[已裁剪 …全文 path]"}` 计划；有 outputDir 时
+ * 把全文写到 `<outputDir>/<toolCallId>.txt`（已存在则不覆盖），模型可用 read 取回。
+ */
+import type { ContentBlock } from "../ai/types.js";
+import type { ContextItem } from "../session/projection.js";
+export declare const PRUNE_THRESHOLD_RATIO = 0.7;
+export declare const PRUNE_MIN_BYTES = 2048;
+export declare const PRUNE_KEEP_USER_TURNS = 2;
+export interface PrunePlanItem {
+    targetId: string;
+    replacement: string;
+    toolCallId: string;
+    originalBytes: number;
+    fullTextPath?: string;
+}
+export interface PruneOptions {
+    keepUserTurns?: number;
+    minBytes?: number;
+    /** 全文落盘目录；undefined 时不落盘（内存会话）。 */
+    outputDir?: string | undefined;
+}
+export declare function pruneThreshold(contextWindow: number, reserveTokens: number): number;
+export declare function shouldPrune(tokens: number, contextWindow: number, reserveTokens: number): boolean;
+export declare function contentToText(content: string | readonly ContentBlock[]): string;
+/** 计算裁剪计划（并按需落盘全文）；返回空数组表示无可裁剪项。 */
+export declare function planPrune(items: readonly ContextItem[], options?: PruneOptions): PrunePlanItem[];

package/dist/compaction/prune-tier.js

@@ -0,0 +1,83 @@
+/**
+ * 档一裁剪（设计 §9「档一」）：无模型调用。[B2]
+ *
+ * 触发：`contextTokens > 0.7 × (contextWindow − reserveTokens)`。
+ * 范围：最近两个用户回合之前、内容 > 2 KiB 的 toolResult。
+ * 动作：返回 `context_edit{reason:"prune", replacement:"[已裁剪 …全文 path]"}` 计划；有 outputDir 时
+ * 把全文写到 `<outputDir>/<toolCallId>.txt`（已存在则不覆盖），模型可用 read 取回。
+ */
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const PRUNE_THRESHOLD_RATIO = 0.7;
+export const PRUNE_MIN_BYTES = 2048;
+export const PRUNE_KEEP_USER_TURNS = 2;
+export function pruneThreshold(contextWindow, reserveTokens) {
+    return PRUNE_THRESHOLD_RATIO * Math.max(0, contextWindow - reserveTokens);
+}
+export function shouldPrune(tokens, contextWindow, reserveTokens) {
+    return tokens > pruneThreshold(contextWindow, reserveTokens);
+}
+export function contentToText(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .map((block) => (block.type === "text" ? block.text : `[image ${block.mimeType}]`))
+        .join("\n");
+}
+function safeFileStem(id) {
+    return id.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 120) || "tool";
+}
+/** 计算裁剪计划（并按需落盘全文）；返回空数组表示无可裁剪项。 */
+export function planPrune(items, options = {}) {
+    const keepTurns = options.keepUserTurns ?? PRUNE_KEEP_USER_TURNS;
+    const minBytes = options.minBytes ?? PRUNE_MIN_BYTES;
+    let boundary = items.length;
+    let seen = 0;
+    for (let i = items.length - 1; i >= 0; i--) {
+        if (items[i]?.message.role !== "user")
+            continue;
+        seen++;
+        if (seen >= keepTurns) {
+            boundary = i;
+            break;
+        }
+    }
+    if (seen < keepTurns)
+        return [];
+    const plan = [];
+    for (const item of items.slice(0, boundary)) {
+        const { message, entry } = item;
+        if (message.role !== "toolResult" || entry.type !== "message")
+            continue;
+        const text = contentToText(message.content);
+        const bytes = Buffer.byteLength(text, "utf8");
+        if (bytes <= minBytes)
+            continue;
+        let fullTextPath;
+        if (options.outputDir !== undefined) {
+            fullTextPath = join(options.outputDir, `${safeFileStem(message.toolCallId)}.txt`);
+            try {
+                if (!existsSync(fullTextPath)) {
+                    mkdirSync(options.outputDir, { recursive: true });
+                    writeFileSync(fullTextPath, text, "utf8");
+                }
+            }
+            catch {
+                fullTextPath = undefined;
+            }
+        }
+        const replacement = fullTextPath === undefined
+            ? `[已裁剪：${message.toolName} 的结果原有 ${bytes} 字节，全文不可用]`
+            : `[已裁剪：${message.toolName} 的结果原有 ${bytes} 字节，全文 ${fullTextPath}]`;
+        const planned = {
+            targetId: entry.id,
+            replacement,
+            toolCallId: message.toolCallId,
+            originalBytes: bytes,
+        };
+        if (fullTextPath !== undefined)
+            planned.fullTextPath = fullTextPath;
+        plan.push(planned);
+    }
+    return plan;
+}

package/dist/compaction/serialize.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 被摘要段的文本序列化（设计 §9「模板」）与文件操作累计。[B2]
+ *
+ * 形状：`[User]: … / [Assistant thinking]: … / [Assistant]: … / [Assistant tool calls]: read(path="…") /
+ * [Tool result]: …`——写成记录而非对话，避免摘要模型把它当成要续写的对话。工具结果截 2 000 字符。
+ */
+import type { FileOpsDetails } from "../session/types.js";
+import type { AgentMessage } from "../session/types.js";
+export declare const TOOL_RESULT_SERIALIZE_LIMIT = 2000;
+export declare function serializeMessage(message: AgentMessage): string;
+export declare function serializeConversation(messages: readonly AgentMessage[]): string;
+export interface FileOps {
+    read: Set<string>;
+    modified: Set<string>;
+}
+export declare function createFileOps(previous?: FileOpsDetails): FileOps;
+export declare function collectFileOps(messages: readonly AgentMessage[], ops: FileOps): FileOps;
+/** 只读过、没改过的进 readFiles；改过的进 modifiedFiles。 */
+export declare function fileOpsDetails(ops: FileOps): FileOpsDetails;
+export declare function formatFileOps(details: FileOpsDetails): string;

package/dist/compaction/serialize.js

@@ -0,0 +1,115 @@
+/**
+ * 被摘要段的文本序列化（设计 §9「模板」）与文件操作累计。[B2]
+ *
+ * 形状：`[User]: … / [Assistant thinking]: … / [Assistant]: … / [Assistant tool calls]: read(path="…") /
+ * [Tool result]: …`——写成记录而非对话，避免摘要模型把它当成要续写的对话。工具结果截 2 000 字符。
+ */
+import { contentToText } from "./prune-tier.js";
+export const TOOL_RESULT_SERIALIZE_LIMIT = 2000;
+function truncate(text, limit) {
+    if (text.length <= limit)
+        return text;
+    return `${text.slice(0, limit)}… [截断，原 ${text.length} 字符]`;
+}
+function formatArgs(args) {
+    return Object.entries(args)
+        .map(([key, value]) => {
+        const text = typeof value === "string" ? JSON.stringify(value) : (JSON.stringify(value) ?? "");
+        return `${key}=${truncate(text, 300)}`;
+    })
+        .join(", ");
+}
+export function serializeMessage(message) {
+    switch (message.role) {
+        case "system":
+            return "";
+        case "user":
+            return `[User]: ${contentToText(message.content)}`;
+        case "custom":
+            return `[Context ${message.customType}]: ${contentToText(message.content)}`;
+        case "compactionSummary":
+            return `[Earlier summary]: ${message.summary}`;
+        case "branchSummary":
+            return `[Branch summary]: ${message.summary}`;
+        case "toolResult":
+            return `[Tool result${message.isError ? " (error)" : ""} ${message.toolName}]: ${truncate(contentToText(message.content), TOOL_RESULT_SERIALIZE_LIMIT)}`;
+        case "assistant": {
+            const parts = [];
+            const thinking = message.content
+                .filter((block) => block.type === "thinking")
+                .map((block) => block.thinking)
+                .join("\n")
+                .trim();
+            if (thinking !== "")
+                parts.push(`[Assistant thinking]: ${thinking}`);
+            const text = message.content
+                .filter((block) => block.type === "text")
+                .map((block) => block.text)
+                .join("\n")
+                .trim();
+            if (text !== "")
+                parts.push(`[Assistant]: ${text}`);
+            const calls = message.content
+                .filter((block) => block.type === "toolCall")
+                .map((block) => `${block.name}(${formatArgs(block.arguments)})`);
+            if (calls.length > 0)
+                parts.push(`[Assistant tool calls]: ${calls.join("; ")}`);
+            if (message.stopReason === "error" && message.errorMessage !== undefined) {
+                parts.push(`[Assistant error]: ${message.errorMessage}`);
+            }
+            return parts.join("\n");
+        }
+    }
+}
+export function serializeConversation(messages) {
+    return messages
+        .map(serializeMessage)
+        .filter((text) => text !== "")
+        .join("\n\n");
+}
+// ---------------------------------------------------------------------------
+// 文件操作
+// ---------------------------------------------------------------------------
+const READ_TOOLS = new Set(["read"]);
+const WRITE_TOOLS = new Set(["write", "edit"]);
+export function createFileOps(previous) {
+    return {
+        read: new Set(previous?.readFiles ?? []),
+        modified: new Set(previous?.modifiedFiles ?? []),
+    };
+}
+export function collectFileOps(messages, ops) {
+    for (const message of messages) {
+        if (message.role !== "assistant")
+            continue;
+        for (const block of message.content) {
+            if (block.type !== "toolCall")
+                continue;
+            const path = block.arguments["path"];
+            if (typeof path !== "string" || path === "")
+                continue;
+            if (READ_TOOLS.has(block.name))
+                ops.read.add(path);
+            else if (WRITE_TOOLS.has(block.name))
+                ops.modified.add(path);
+        }
+    }
+    return ops;
+}
+/** 只读过、没改过的进 readFiles；改过的进 modifiedFiles。 */
+export function fileOpsDetails(ops) {
+    return {
+        readFiles: [...ops.read].filter((path) => !ops.modified.has(path)).sort(),
+        modifiedFiles: [...ops.modified].sort(),
+    };
+}
+export function formatFileOps(details) {
+    const parts = [];
+    if (details.readFiles.length > 0) {
+        parts.push(`<read-files>\n${details.readFiles.join("\n")}\n</read-files>`);
+    }
+    if (details.modifiedFiles.length > 0) {
+        parts.push(`<modified-files>\n${details.modifiedFiles.join("\n")}\n</modified-files>`);
+    }
+    return parts.join("\n\n");
+}

package/dist/compaction/summarize-tier.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 档二摘要（设计 §9「档二」「模板」）。[B2]
+ *
+ * `prepareCompaction()` 在投影上找切点，得到「要摘要的消息」与 `firstKeptEntryId`；
+ * `runCompaction()` 请模型按模板写摘要，split turn 时历史与回合前缀各一份再合并；
+ * `<read-files>` / `<modified-files>` 与上一份 compaction 的 details 累计。失败抛
+ * `AmaError{code:"compaction_failed"}`，abort 抛 `aborted`。
+ *
+ * [W3-C1b] 会话前缀续写（第三波 §1.8）：调用方给出 `continuation.prefix`（与上一次真实请求
+ * 逐字节同前缀的完整转录）时，请求 = 前缀 + 一条摘要指令（「只摘要第 1–N 条，第 N+1 条起
+ * 保留原文」+ 首行引文），`cacheRetention: "short"`、`purpose: "summary"`，按读价计费。
+ * **不发 `toolChoice`**：实测（docs/benchmarks/cache-2026-10-02.md E3）中转与 Kimi 在
+ * `tool_choice: "none"` 时渲染的提示不带工具定义，前缀在工具段断开、cacheRead 为 0；Anthropic
+ * 文档也写明改动 tool_choice 会让消息缓存失效。所以 system + tools + 消息前缀与上一次真实请求
+ * 逐字节相同，「不调用工具、只输出摘要」只写在末尾指令里；响应为空 / 被截断 / 含工具调用 / 请求出错 → 回落现行独立请求（序列化转录、
+ * `cacheRetention: "none"`）并经 `onFallback` 记 warning。
+ */
+import type { ApiImplementation, Model, StreamOptions, TranscriptContext, Usage } from "../ai/types.js";
+import type { Projection } from "../session/projection.js";
+import type { AgentMessage, FileOpsDetails } from "../session/types.js";
+import { type CutPointResult } from "./cut-point.js";
+export type StreamFn = ApiImplementation["stream"];
+export declare const SUMMARY_MAX_TOKENS = 4096;
+export declare const SUMMARIZATION_SYSTEM_PROMPT: string;
+export declare const SUMMARY_TEMPLATE = "Write the checkpoint summary using EXACTLY this format:\n\n## Goal\n[What the user is trying to accomplish; several items if the session covers several tasks.]\n\n## Constraints & Preferences\n- [Constraints, preferences, or requirements stated by the user, or \"(none)\"]\n\n## Progress\n### Done\n- [x] [Completed tasks and changes]\n\n### In Progress\n- [ ] [Current work]\n\n### Blocked\n- [Issues preventing progress, if any]\n\n## Key Decisions\n- **[Decision]**: [Short rationale]\n\n## Next Steps\n1. [Ordered list of what should happen next]\n\n## Critical Context\n- [Data, file paths, identifiers, error messages, or references needed to continue, or \"(none)\"]\n\nKeep every section concise. Preserve exact file paths, function names, and error messages.";
+/** 续写指令的首句（测试据此识别摘要请求）。 */
+export declare const SUMMARY_CONTINUATION_PREAMBLE = "Stop here: do not continue the conversation, do not answer questions from it and do not call any tools.";
+/** 续写指令的末句：工具仍在请求里（为了缓存前缀），只靠指令禁止调用。 */
+export declare const SUMMARY_CONTINUATION_TAIL = "Tools are still listed above, but you must not call any of them now. Reply with the summary text only.";
+export interface CompactionPlan {
+    /** 要摘要的消息（不含 system 与上一份摘要）。 */
+    toSummarize: AgentMessage[];
+    /** split turn 时：回合前缀（同时也在 toSummarize 的末尾之后，不重叠）。 */
+    turnPrefix: AgentMessage[];
+    firstKeptEntryId: string;
+    cut: CutPointResult;
+    previousSummary: string | undefined;
+    previousDetails: FileOpsDetails | undefined;
+    /**
+     * [W3-C1b] 续写用的位置：转录里（不计 system）历史段结束前、保留区开始前各有多少条
+     * 消息，以及紧随其后那条消息的首行引文。
+     */
+    anchors: {
+        historyEnd: number;
+        keptStart: number;
+        historyExcerpt: string;
+        keptExcerpt: string;
+    };
+}
+export interface CompactionDraft {
+    summary: string;
+    firstKeptEntryId: string;
+    usage: Usage | undefined;
+    details: FileOpsDetails;
+}
+export interface SummarizerOptions {
+    stream: StreamFn;
+    model: Model;
+    apiKey?: string | undefined;
+    signal: AbortSignal;
+    customInstructions?: string | undefined;
+    maxTokens?: number;
+    /** [W3-C1b] 会话前缀续写的前缀与流选项（缺省 / 回落时走独立请求）。 */
+    continuation?: SummaryContinuation | undefined;
+    /** 续写失败回落独立请求时调用（记 warning）。 */
+    onFallback?(reason: string): void;
+}
+export interface SummaryContinuation {
+    /** 与上一次真实请求逐字节同前缀的完整转录（system 补丁 + 全部消息）。 */
+    prefix: TranscriptContext;
+    /** 沿用上一次真实请求的选项（apiKey、sessionId、thinkingLevel 等）。 */
+    streamOptions?: Partial<Omit<StreamOptions, "signal">>;
+}
+export interface ContinuationInput {
+    /** 与上一次真实请求逐字节相同的转录（system 补丁 + 全部消息，直到最后一条真实请求为止）。 */
+    prefix: TranscriptContext;
+    /** 摘要到第 index 条为止（不计 system）；excerpt 是第 index + 1 条的首行引文。 */
+    keepFrom: {
+        index: number;
+        excerpt: string;
+    };
+    /** 只摘要第 from + 1 条起（split turn 的回合前缀、分支摘要）；缺省从头。 */
+    from?: number;
+    /** SUMMARY_TEMPLATE / 回合前缀提示 / 分支摘要模板。 */
+    instruction: string;
+}
+/** 转录里（不计 system）实际发给模型的消息数：失败 / 中断的助手消息连同其工具结果不回放。 */
+export declare function countLlmMessages(messages: readonly AgentMessage[]): number;
+/** 消息首行引文（≤ 80 字符）。 */
+export declare function excerptOf(message: AgentMessage | undefined): string;
+/** 无可摘要内容时返回 undefined。 */
+export declare function prepareCompaction(projection: Projection, keepRecentTokens: number): CompactionPlan | undefined;
+/** 一次无工具的文本补全；错误 / 取消 / 空输出抛错。 */
+export declare function completeText(options: SummarizerOptions, userText: string): Promise<{
+    text: string;
+    usage: Usage;
+}>;
+/**
+ * 会话前缀续写：前缀 + 一条摘要指令，不发 `toolChoice`（保住含工具段的缓存前缀）。空 / 截断 /
+ * 含工具调用 / 出错抛 `compaction_failed`（调用方回落），abort 抛 `aborted`。
+ */
+export declare function completeByContinuation(options: SummarizerOptions, input: ContinuationInput): Promise<{
+    text: string;
+    usage: Usage;
+}>;
+/** 先试续写，失败（非 abort）回落独立请求。 */
+export declare function summarizeWithFallback(options: SummarizerOptions, continuation: Omit<ContinuationInput, "prefix"> | undefined, independentPrompt: () => string): Promise<{
+    text: string;
+    usage: Usage;
+}>;
+export declare function runCompaction(plan: CompactionPlan, options: SummarizerOptions): Promise<CompactionDraft>;