@migor/agentia 0.0.1

package/README.md

@@ -0,0 +1,171 @@
+# Agentia
+
+声明式 agent 服务开发框架：TS 装饰器 + DI，主 agent 调度 `@Tool` / `@Skill` / `@SubAgent` / `@Prompt` 单元执行任务，产出结构化结果与调用树（trace）。
+
+## 环境准备
+
+```bash
+export ANTHROPIC_API_KEY=sk-...        # 或 ANTHROPIC_AUTH_TOKEN
+# 可选：ANTHROPIC_BASE_URL（兼容端点）、AGENTIA_MODEL（缺省 claude-opus-5）
+```
+
+## 快速开始（CLI）
+
+```bash
+npm i -g @migor/cli                 # 安装 CLI（提供 agentia 命令）
+agentia create my-app                  # 脚手架新项目（依赖 @migor/agentia）
+cd my-app && npm install
+agentia g tool weather                 # 生成 units/weather/index.ts 并登记 units.ts
+agentia g subagent doc-reviewer        # 生成 units/doc-reviewer/{index.ts,system.md}
+agentia g skill note-writer            # 生成 units/note-writer/index.ts
+agentia g prompt style-guide           # 生成 units/style-guide/{index.ts,asset.md}
+npm run dev                            # 运行 src/main.ts
+```
+
+**目录约定**：`units/<name>/` 一单元一文件夹，`index.ts` default export 一个 provider 类，DI token 缺省 = 文件夹名；长文本放文件夹内 `.md`，代码里用 `asset(import.meta.url, './system.md')` 读取。
+
+**装配两条路（可混用）**：
+
+```ts
+// 1) 目录扫描：启动期扫描 units/*/ 自动装配（返回 Promise）
+const app = await createApp({ name: 'my-app', discover: 'units', system });
+
+// 2) 显式注册表：units.ts 由 CLI 自动维护
+import { providers } from './units.js';
+const app = createApp({ name: 'my-app', providers, system });
+```
+
+## 手写单元
+
+```ts
+import { Tool, SubAgent, createApp, SystemPrompt, RunContext } from '@migor/agentia';
+
+class WeatherTools {
+  // 工具名缺省取方法名（建议 snake_case）；入参 = 模型按 schema 解析的结构化 input
+  @Tool({
+    description: '查询城市天气',
+    schema: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+      additionalProperties: false,
+    },
+    strict: true,
+  })
+  get_weather(input: { city: string }): string {
+    // 方法体内随时可读本次 run 的上下文（blackboard）
+    const token = RunContext.current()?.get<string>('authToken');
+    return `city=${input.city};token=${token ?? 'none'}`;
+  }
+}
+
+class Pipeline {
+  // 子 agent：独立循环 + 裁剪上下文，只有最终报告回流主上下文（方法体不执行）
+  @SubAgent({
+    name: 'reviewer',
+    description: '审查给定文档并输出书面评审意见',
+    schema: { type: 'object', properties: { doc: { type: 'string' } }, required: ['doc'], additionalProperties: false },
+    system: '你是评审 agent。结论必须以“审查通过/不通过”开头。',
+    tools: ['weather'], // 子 agent 自己的工具菜单（provider token）
+  })
+  reviewer(_input: { doc: string }): void {}
+}
+
+const app = createApp({
+  name: 'weather-app',
+  providers: [
+    { provide: 'weather', useClass: WeatherTools },
+    { provide: 'pipeline', useClass: Pipeline },
+  ],
+  system: new SystemPrompt().add('role', '你是天气助手。', true),
+});
+
+const { run, result } = await app.run(
+  [{ role: 'user', content: '上海天气如何?' }],
+  { blackboard: { authToken: 'sk-...' } }, // 预置本次 run 的上下文
+);
+console.log(result.finalText); // 最终文本
+console.log(result.trace);     // 调用树 + 每步 token/成本（traceId == runId）
+```
+
+另外两类单元：
+
+```ts
+// @Skill：代码控制的流程，模型调用只发生在显式 ctx.llm()
+class Notes {
+  @Skill({ description: '按主题整理要点' })
+  async note_writer(input: { topic: string }, ctx: SkillContext): Promise<string> {
+    const r = await ctx.llm({ prompt: `就「${input.topic}」给出三个要点` });
+    return r.text; // 返回值即产物，以 tool_result 交回主 agent
+  }
+}
+
+// @Prompt：纯文本资产，模型判定需要时拉取进上下文
+class Assets {
+  @Prompt({ description: '品牌基调文案规范' })
+  style_guide(): string {
+    return asset(import.meta.url, './asset.md'); // 从单元文件夹读 .md
+  }
+}
+```
+
+## 触发方式
+
+同一份应用，三种触发任选：
+
+```ts
+// 同步 RPC
+const { run, result } = await app.run(messages);
+
+// 异步任务（幂等键去重，失败可重提，可落盘续跑）
+const runner = new AsyncRunner(app, { store: new FileTaskStore('./tasks.jsonl'), concurrency: 4 });
+const task = runner.submit('总结一下今天的新闻', { idempotencyKey: 'daily-2026-09-10' });
+await runner.awaitTask(task.taskId);
+
+// 定时
+const scheduler = new Scheduler(runner);
+scheduler.every(60_000, '巡检一次', { idempotencyKey: 'patrol' });
+```
+
+## 长上下文预算
+
+```ts
+import { createBudgetPolicy } from '@migor/agentia';
+
+const app = createApp({
+  // ...
+  contextPolicy: createBudgetPolicy({
+    budgetTokens: 60_000,   // 超预算先丢旧工具对，仍超且有 summarize 才压缩
+    summarize: (text) => mySummarizer(text), // 可选，框架不替你调模型
+  }),
+});
+```
+
+## 常用 API
+
+| 导出 | 用途 |
+|---|---|
+| `createApp` / `discoverProviders` | 装配应用 / 扫描单元目录 |
+| `Tool` / `Skill` / `SubAgent` / `Prompt` | 四类单元装饰器 |
+| `asset` | 读单元文件夹内的文本资产 |
+| `SystemPrompt` | 拼装系统提示（自动打缓存 breakpoint） |
+| `RunContext.current()` | 取本次 run 的 blackboard / runId |
+| `AsyncRunner` / `Scheduler` / `runSync` | 异步任务 / 定时 / 同步触发 |
+| `FileTaskStore` / `InMemoryTaskStore` | 任务记录存储（重启续跑用 File） |
+| `createBudgetPolicy` | 长上下文预算护栏 |
+| `runAgent` / `executeRun` | 裸引擎入口（不走装配） |
+
+完整导出见 [`src/index.ts`](src/index.ts)，设计规格见 [`docs/spec.md`](docs/spec.md)。
+
+## 本仓库脚本
+
+```bash
+npm install
+npm run build        # 编译框架（dist/）
+npm run typecheck    # 类型检查
+npm run smoke:turn7  # 端到端：CLI 脚手架 → 目录发现/注册表装配 → mock run
+npm run live         # 真机：runAgent + 工具往返（需 API key）
+npm run live:skill   # 真机：@Skill ctx.llm()（需 API key）
+```
+
+> 注：`npm run dev`（tsx）前需先 `npm approve-scripts` 批准 esbuild/tsx 的 postinstall。

package/dist/container/container.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Agentia —— 最小显式 DI 容器（spec §4/§10：标准装饰器 + 显式 DI，不用
+ * experimentalDecorators/emitDecoratorMetadata/reflect-metadata）。
+ *
+ * NestJS 风格 provider 三态：useValue / useClass / useFactory(+deps)。
+ * 依赖以字符串 token 显式声明，靠工厂解析期惰性求值；无构造器参数反射。
+ * 容器按 app 粒度单例缓存；run 作用域的黑板/上下文不经过 DI，而由
+ * RunContext(AsyncLocalStorage) 在 executeRun 内注入（见 run/context.ts）。
+ */
+export type Token = string;
+export interface ValueProvider<T = unknown> {
+    provide: Token;
+    useValue: T;
+}
+export interface ClassProvider<T = unknown> {
+    provide: Token;
+    useClass: new (...args: never[]) => T;
+    /** 构造器参数对应的依赖 token（按序注入）；无依赖可省略 */
+    deps?: Token[];
+}
+export interface FactoryProvider<T = unknown> {
+    provide: Token;
+    useFactory: (...deps: unknown[]) => T;
+    /** 与 useFactory 形参一一对应的依赖 token */
+    deps?: Token[];
+}
+export type Provider<T = unknown> = ValueProvider<T> | ClassProvider<T> | FactoryProvider<T>;
+export declare function isProvider(p: unknown): p is Provider;
+export declare class Container {
+    private readonly bindings;
+    private readonly cache;
+    /** 正在解析的 token 链，用于循环依赖检测 */
+    private resolving;
+    /** 覆盖式注册（后注册覆盖先注册；同一 app 内同 token 重复注册视为升级） */
+    register(...providers: Provider[]): this;
+    has(token: Token): boolean;
+    resolve<T = unknown>(token: Token): T;
+    /** 调试辅助 */
+    registered(): Token[];
+}

package/dist/container/container.js

@@ -0,0 +1,66 @@
+export function isProvider(p) {
+    return (typeof p === 'object' &&
+        p !== null &&
+        typeof p.provide === 'string' &&
+        ('useValue' in p ||
+            'useClass' in p ||
+            'useFactory' in p));
+}
+export class Container {
+    bindings = new Map();
+    cache = new Map();
+    /** 正在解析的 token 链，用于循环依赖检测 */
+    resolving = [];
+    /** 覆盖式注册（后注册覆盖先注册；同一 app 内同 token 重复注册视为升级） */
+    register(...providers) {
+        for (const p of providers) {
+            if (!isProvider(p)) {
+                throw new Error(`非法 provider: ${JSON.stringify(p)}`);
+            }
+            this.bindings.set(p.provide, p);
+        }
+        return this;
+    }
+    has(token) {
+        return this.bindings.has(token);
+    }
+    resolve(token) {
+        // 用 has 判定命中：provider 值可以是 undefined，get 返回 undefined 不等于未缓存
+        if (this.cache.has(token))
+            return this.cache.get(token);
+        const cycleAt = this.resolving.indexOf(token);
+        if (cycleAt !== -1) {
+            const chain = [...this.resolving.slice(cycleAt), token].join(' -> ');
+            throw new Error(`循环依赖（DI）: ${chain}`);
+        }
+        const binding = this.bindings.get(token);
+        if (!binding) {
+            throw new Error(`未注册的 provider: "${token}"`);
+        }
+        this.resolving.push(token);
+        let value;
+        try {
+            if ('useValue' in binding) {
+                value = binding.useValue;
+            }
+            else if ('useClass' in binding) {
+                const deps = (binding.deps ?? []).map((d) => this.resolve(d));
+                value = new binding.useClass(...deps);
+            }
+            else {
+                const deps = (binding.deps ?? []).map((d) => this.resolve(d));
+                value = binding.useFactory(...deps);
+            }
+        }
+        finally {
+            this.resolving.pop();
+        }
+        this.cache.set(token, value);
+        return value;
+    }
+    /** 调试辅助 */
+    registered() {
+        return [...this.bindings.keys()];
+    }
+}
+//# sourceMappingURL=container.js.map

package/dist/container/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../../src/container/container.ts"],"names":[],"mappings":"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"}

package/dist/core/schema.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from './tool.js';
+/**
+ * Agentia —— 最小 JSON Schema 校验子集（spec：v1 裸 JSON Schema，不接 zod）。
+ *
+ * 用途：engine 在执行 tool.run 前校验模型给出的结构化 input；校验失败直接回
+ * is_error 的 tool_result（错误信息含路径，模型可自我修正），不进方法体。
+ *
+ * 覆盖子集：type（object/array/string/number/integer/boolean/null）、
+ * properties、required、additionalProperties:false、enum、items。
+ * 未覆盖的关键字（format/minimum/oneOf 等）一律放行 —— 护栏不是完整校验器。
+ *
+ * @returns 人类可读的错误描述（含路径）；合法返回 null。
+ */
+export declare function validateJsonSchema(schema: JsonSchema, input: unknown): string | null;

package/dist/core/schema.js

@@ -0,0 +1,116 @@
+/**
+ * Agentia —— 最小 JSON Schema 校验子集（spec：v1 裸 JSON Schema，不接 zod）。
+ *
+ * 用途：engine 在执行 tool.run 前校验模型给出的结构化 input；校验失败直接回
+ * is_error 的 tool_result（错误信息含路径，模型可自我修正），不进方法体。
+ *
+ * 覆盖子集：type（object/array/string/number/integer/boolean/null）、
+ * properties、required、additionalProperties:false、enum、items。
+ * 未覆盖的关键字（format/minimum/oneOf 等）一律放行 —— 护栏不是完整校验器。
+ *
+ * @returns 人类可读的错误描述（含路径）；合法返回 null。
+ */
+export function validateJsonSchema(schema, input) {
+    return check(schema, input, '$');
+}
+function check(schema, value, path) {
+    const en = schema.enum;
+    if (Array.isArray(en) && !en.some((v) => deepEqual(v, value))) {
+        return `${path}: 值不在 enum 允许范围内（得到 ${preview(value)}）`;
+    }
+    switch (schema.type) {
+        case 'object':
+            return checkObject(schema, value, path);
+        case 'array':
+            return checkArray(schema, value, path);
+        case 'string':
+            return typeof value === 'string' ? null : `${path}: 期望 string，得到 ${typeOf(value)}`;
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value)
+                ? null
+                : `${path}: 期望 number，得到 ${typeOf(value)}`;
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value)
+                ? null
+                : `${path}: 期望 integer，得到 ${typeOf(value)}`;
+        case 'boolean':
+            return typeof value === 'boolean' ? null : `${path}: 期望 boolean，得到 ${typeOf(value)}`;
+        case 'null':
+            return value === null ? null : `${path}: 期望 null，得到 ${typeOf(value)}`;
+        default:
+            return null; // 未声明/未覆盖的 type 放行
+    }
+}
+function checkObject(schema, value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return `${path}: 期望 object，得到 ${typeOf(value)}`;
+    }
+    const obj = value;
+    for (const key of schema.required ?? []) {
+        if (!(key in obj))
+            return `${path}: 缺少必需属性 "${key}"`;
+    }
+    const properties = schema.properties ?? {};
+    for (const [key, sub] of Object.entries(properties)) {
+        if (key in obj) {
+            const err = check(sub, obj[key], `${path}.${key}`);
+            if (err)
+                return err;
+        }
+    }
+    if (schema.additionalProperties === false) {
+        const extra = Object.keys(obj).filter((k) => !(k in properties));
+        if (extra.length > 0) {
+            return `${path}: 存在 schema 未声明的属性 ${extra.map((k) => `"${k}"`).join(', ')}`;
+        }
+    }
+    return null;
+}
+function checkArray(schema, value, path) {
+    if (!Array.isArray(value))
+        return `${path}: 期望 array，得到 ${typeOf(value)}`;
+    const items = schema.items;
+    if (items && typeof items === 'object' && !Array.isArray(items)) {
+        for (let i = 0; i < value.length; i++) {
+            const err = check(items, value[i], `${path}[${i}]`);
+            if (err)
+                return err;
+        }
+    }
+    return null;
+}
+function typeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function preview(value) {
+    const s = stringifySafe(value);
+    return s.length > 80 ? `${s.slice(0, 80)}…` : s;
+}
+function stringifySafe(x) {
+    try {
+        return JSON.stringify(x) ?? String(x);
+    }
+    catch {
+        return String(x);
+    }
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    return (ka.length === kb.length &&
+        ka.every((k) => deepEqual(a[k], b[k])));
+}
+//# sourceMappingURL=schema.js.map

package/dist/core/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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"}

package/dist/core/tool.d.ts

@@ -0,0 +1,60 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { SpanError, SpanId, SpanKind, SpanStatus, Trace, Usage } from './trace.js';
+/**
+ * Agentia —— 工具定义。
+ * Turn 0：v1 用裸 JSON Schema，不引 zod；装饰器 → schema 在 Turn 2 接入。
+ * Turn 3：run 执行体可接收第二参 ctx（ToolRunContext），供子 agent/嵌套单元把
+ * 自己的 llm.turn 递归挂进当前 trace（unit span 的父由 engine 给定）。
+ */
+/** JSON Schema 对象子集，供工具的 input_schema */
+export interface JsonSchema {
+    type: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * engine 的 TraceRecorder 面向子单元的最小结构面（core 不依赖 engine）。
+ * 需要开嵌套 span 的单元（如 @SubAgent）通过 ctx.recorder 记账，
+ * 其余工具可完全忽略它。
+ */
+export interface RecorderBackend {
+    readonly traceId: string;
+    begin(kind: SpanKind, name: string, parentSpanId: SpanId | null): SpanId;
+    end(id: SpanId, patch?: {
+        status?: SpanStatus;
+        error?: SpanError;
+        usage?: Usage;
+    }): void;
+    event(id: SpanId, name: string, body: unknown): void;
+    setAttribute(id: SpanId, key: string, value: string | number | boolean): void;
+    snapshot(status: SpanStatus): Trace;
+}
+/**
+ * engine 在调用每个工具时注入的执行上下文（spec §9.2：当前 span 句柄随调用传播，
+ * 不用全局单例，保证并行工具调用父子关系准确）。
+ * - recorder：整条 run 共享的 recorder（新子单元/子 agent 的 span 写它下面）；
+ * - parentSpanId：发起本次调用的上层 span —— 子单元 span 应挂它下面；
+ * - client：与主循环同一注入（子 agent 独立循环复用它）。
+ */
+export interface ToolRunContext {
+    client: Anthropic;
+    recorder: RecorderBackend;
+    parentSpanId: SpanId;
+}
+export interface AgentTool<I = unknown, O = unknown> {
+    /** 模型可见的唯一名（建议 snake_case） */
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    /** 开启严格参数校验（schema 需 additionalProperties:false + required） */
+    strict?: boolean;
+    /**
+     * 执行体。入参 = 模型按 schema 解析的结构化 input；
+     * ctx 由 engine 注入（含 recorder/父 span），需要开嵌套 span 的单元（子 agent）用，
+     * 普通工具可忽略。抛错会被包成 is_error 的 tool_result 回给模型，不中断 run。
+     */
+    run: (input: I, ctx?: ToolRunContext) => Promise<O> | O;
+}

package/dist/core/tool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/core/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/core/tool.ts"],"names":[],"mappings":""}

package/dist/core/trace.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Agentia —— Trace / 调用树 类型草稿。
+ * 设计见 docs/spec.md §9。一次 run == 一条 trace（v1 中 traceId == runId）。
+ */
+export type TraceId = string;
+export type SpanId = string;
+/** span 层级：run=整次运行；unit=对单个单元(tool/skill/prompt/subagent)的调用；llm.turn=unit 内每次模型往返 */
+export type SpanKind = 'run' | 'unit' | 'llm.turn' | 'internal';
+export type UnitType = 'tool' | 'skill' | 'prompt' | 'subagent';
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** 估算成本(美元)，由 token × 单价算出，随模型表更新 */
+    costEstimate?: number;
+}
+export type SpanStatus = 'ok' | 'error';
+export interface SpanError {
+    type: string;
+    message: string;
+    /** 是否可安全重试（429/5xx/网络 vs 400/400类） */
+    retryable: boolean;
+}
+/** 结构化事件（日志）。工具入参/出参默认截断 + 脱敏，完整内容 opt-in */
+export interface SpanEvent {
+    time: number;
+    name: string;
+    body: unknown;
+}
+export interface Span {
+    spanId: SpanId;
+    traceId: TraceId;
+    parentSpanId: SpanId | null;
+    kind: SpanKind;
+    name: string;
+    startedAt: number;
+    endedAt?: number;
+    status: SpanStatus;
+    error?: SpanError;
+    /** unit / llm.turn 的聚合用量 */
+    usage?: Usage;
+    attributes: Record<string, string | number | boolean>;
+    events: SpanEvent[];
+}
+export interface Trace {
+    traceId: TraceId;
+    rootSpanId: SpanId;
+    spans: Span[];
+    status: SpanStatus;
+    totalUsage: Usage;
+}

package/dist/core/trace.js

@@ -0,0 +1,6 @@
+/**
+ * Agentia —— Trace / 调用树 类型草稿。
+ * 设计见 docs/spec.md §9。一次 run == 一条 trace（v1 中 traceId == runId）。
+ */
+export {};
+//# sourceMappingURL=trace.js.map

package/dist/core/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/engine/context.d.ts

@@ -0,0 +1,47 @@
+import type Anthropic from '@anthropic-ai/sdk';
+/**
+ * Agentia —— 长上下文策略的纯函数层（spec §5/§6：compaction / context editing 分清）。
+ *
+ * 三策略不混：
+ * - **context editing**（`trimToolPairs`）：清旧 tool_use→tool_result 对，不掉内容、不额外调模型；
+ * - **compaction**（`compactMessages`）：把旧消息前缀做**服务端摘要**（摘要器由上层注入，可走模型），
+ *   只保留最近 N 条 + 一段摘要 —— 新的消息数组仍保证角色交替合法；
+ * - **客户端剪裁** = Turn 3 子 agent（另件）。
+ *
+ * 不在此自研 token 计数黑名单：`estimateMessages` 只是预算策略的默认启发式
+ * （CJK 感知估算，明确标注为估算），上层可注入真实 count_tokens 结果。
+ */
+/**
+ * 默认估算（仅预算决策用，非精确记账）：CJK 字符按 ~1.5 字/token，
+ * 其余（ASCII/拉丁）按 ~4 字符/token。纯字符/4 对中文系统性高估，
+ * 会让预算护栏过早触发压缩。
+ */
+export declare function defaultEstimateTokens(text: string): number;
+export declare function isToolResultMessage(msg: Anthropic.MessageParam): boolean;
+/** 整组消息的估算 token（含每条 role 开销）。 */
+export declare function estimateMessages(messages: Anthropic.MessageParam[], estimate?: (text: string) => number): number;
+/** 把消息渲染成可喂给摘要器的纯文本（role: content）。 */
+export declare function renderMessages(messages: Anthropic.MessageParam[]): string;
+export interface TrimOptions {
+    /** 保留最近几对 tool exchange；缺省 1 */
+    keepRecent?: number;
+}
+/**
+ * context editing：丢弃旧的 tool_use→tool_result 对（超出 keepRecent 的），
+ * 保留最近 N 对以及所有非工具消息。逐对整体移除，保角色交替合法。
+ * 返回原数组引用（若无需裁剪）或新数组。
+ */
+export declare function trimToolPairs(messages: Anthropic.MessageParam[], opts?: TrimOptions): Anthropic.MessageParam[];
+export interface CompactOptions {
+    /** 保留的最近消息条数；缺省 20 */
+    keepRecent?: number;
+    /** 摘要器：输入被弃旧前缀的渲染文本，返回摘要 */
+    summarize: (historyText: string) => string | Promise<string>;
+}
+/**
+ * compaction：把 messages 里“除最近 keepRecent 条”的旧前缀做摘要，替换成一段
+ * 摘要消息，尾部保留。产出保证：
+ * - 不拆散 (assistant tool_use → user tool_result) 对 —— cut 落到对中间时整体后移；
+ * - 角色交替合法 —— 尾段首条是普通 user 时摘要并入之；否则摘要以 user 角色放最前。
+ */
+export declare function compactMessages(messages: Anthropic.MessageParam[], opts: CompactOptions): Promise<Anthropic.MessageParam[]>;