@yachiyo-5i/xlyra-agent 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1171 @@
+import { z } from 'zod';
+import { Hono } from 'hono';
+
+/**
+ * 内部规范模型 —— 协议无关的对话数据表达。
+ *
+ * 分层定位：llm/protocols/ 下的两个适配器（OpenAI Responses / Anthropic
+ * Messages）负责把各自 wire 格式翻译成这里的模型；agent 层（runner/压缩/
+ * 工具）永远只面对本文件定义的结构，不感知任何协议细节。
+ *
+ * 设计要点：
+ * - ToolCall 始终保留 raw_arguments 原文（字符串），parse 发生在使用方——
+ *   流式分片期间参数是不完整 JSON，只有归并完成后才可能解析成功；
+ * - ChatMessage 带 thinking / thinking_signature：Anthropic 多轮工具往返
+ *   要求带签名的 thinking block 原样回喂（评审定案透传），无签名的旧消息
+ *   回喂时整块省略（API 允许）；
+ * - tool 角色的 is_error：Anthropic tool_result block 需要显式标注失败。
+ */
+
+declare const toolCallSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    raw_arguments: z.ZodString;
+}, z.core.$strip>;
+type ToolCall = z.infer<typeof toolCallSchema>;
+declare const chatMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        system: "system";
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>;
+    content: z.ZodDefault<z.ZodString>;
+    tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        raw_arguments: z.ZodString;
+    }, z.core.$strip>>>;
+    tool_call_id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    is_error: z.ZodOptional<z.ZodBoolean>;
+    thinking: z.ZodOptional<z.ZodString>;
+    thinking_signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ChatMessage = z.infer<typeof chatMessageSchema>;
+/** 消息正文文本（当前为纯文本管线，直接返回 content；保留函数形态便于将来多模态扩展） */
+declare function messageText(message: ChatMessage): string;
+declare const tokenUsageSchema: z.ZodObject<{
+    prompt_tokens: z.ZodDefault<z.ZodNumber>;
+    completion_tokens: z.ZodDefault<z.ZodNumber>;
+    total_tokens: z.ZodDefault<z.ZodNumber>;
+    cache_read_tokens: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type TokenUsage = z.infer<typeof tokenUsageSchema>;
+declare function emptyUsage(): TokenUsage;
+declare function addUsage(total: TokenUsage, step: TokenUsage): TokenUsage;
+declare const modelSettingsSchema: z.ZodObject<{
+    temperature: z.ZodOptional<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    reasoning_effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$strip>;
+type ModelSettings = z.infer<typeof modelSettingsSchema>;
+/** 暴露给模型的工具声明（parameters 为 JSON Schema object） */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** 一次模型调用的定稿响应（done 事件的载荷） */
+interface ChatResponse {
+    content: string;
+    thinking: string | null;
+    thinking_signature: string | null;
+    tool_calls: ToolCall[];
+    usage: TokenUsage;
+    finish_reason: string | null;
+    model: string;
+    provider: string;
+}
+/** 定稿响应 → 入对话历史的 assistant 消息（思考链与签名随消息保存，供历史回喂） */
+declare function responseToMessage(response: ChatResponse): ChatMessage;
+
+/**
+ * 协议接口 —— llm 层对上游（agent 层）的唯一契约。
+ *
+ * 契约约束（两个适配器都必须满足）：
+ * 1. 错误以 error 事件收尾，不抛异常（网络错误、HTTP 非 2xx、流中断同约定）；
+ * 2. 每条流恰好一个终态（done 或 error），永不静默结束；
+ * 3. toolcall_start 在工具名称确定的第一刻发出；toolcall_end 时
+ *    raw_arguments 为累积全量；
+ * 4. done 携带完整 ChatResponse（content/thinking/tool_calls/usage/...）。
+ */
+
+interface ChatRequest {
+    /** 端点内的模型 id（路由解析后的值，不含端点前缀） */
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    settings: ModelSettings;
+    /** 外部取消信号：触发后适配器尽快终止流并静默结束（终态事件由编排层负责） */
+    signal?: AbortSignal;
+}
+type StreamEvent = {
+    type: "thinking_delta";
+    delta: string;
+} | {
+    type: "text_delta";
+    delta: string;
+}
+/** 名称已确定，参数开始生成（tool_call 仅含 id/name） */
+ | {
+    type: "toolcall_start";
+    tool_call: ToolCall;
+}
+/** 参数 JSON 逐片增量 */
+ | {
+    type: "toolcall_delta";
+    tool_call: ToolCall;
+    delta: string;
+}
+/** 参数已完整（raw_arguments 为全量） */
+ | {
+    type: "toolcall_end";
+    tool_call: ToolCall;
+} | {
+    type: "done";
+    response: ChatResponse;
+} | {
+    type: "error";
+    error: string;
+};
+interface LlmProtocol {
+    /** 协议标识："openai-responses" | "anthropic-messages" */
+    readonly name: string;
+    chatStream(req: ChatRequest): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * LLM 层错误：路由解析失败（没配端点/模型不存在）等**调用前**错误抛出；
+ * 调用中的流错误一律走 StreamEvent error 事件，不抛异常。
+ */
+declare class LlmError extends Error {
+    constructor(message: string);
+}
+
+interface EndpointConfig {
+    name: string;
+    protocol: "openai-responses" | "anthropic-messages";
+    base_url: string;
+    api_key: string;
+    /** 可用模型表：key 为模型 id；context_window 可选 */
+    models?: Record<string, {
+        context_window?: number;
+    }>;
+    default_model?: string;
+}
+interface ResolvedModel {
+    endpoint: EndpointConfig;
+    protocol: LlmProtocol;
+    /** 端点内的模型 id（已剥离端点前缀） */
+    modelId: string;
+    contextWindow: number | undefined;
+}
+declare function builtinContextWindow(modelId: string): number | undefined;
+declare class EndpointResolver {
+    private readonly endpoints;
+    private readonly protocols;
+    constructor(endpoints: EndpointConfig[]);
+    resolve(model: string): ResolvedModel;
+    private protocolFor;
+}
+
+/**
+ * 极简 SSE 解析器 —— 两套协议适配器共用。
+ *
+ * 覆盖 SSE 规范的常用子集：`event:` / 多行 `data:` 拼接 / `: comment`
+ * 心跳行 / \r\n 与 \n 换行 / OpenAI 的 `data: [DONE]` 哨兵。
+ * 不依赖任何第三方库；输入是 fetch 响应的 body 流。
+ */
+interface SseEvent {
+    /** event 字段值；缺省为空串（OpenAI 系协议通常不写 event，靠 data 里的 type） */
+    event: string;
+    /** 多行 data 已按规范以 \n 拼接 */
+    data: string;
+}
+declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent>;
+
+/**
+ * 流式 tool_call 归并器 —— 两个协议适配器共用。
+ *
+ * 两套协议的参数都是逐片增量（Responses 的 function_call_arguments.delta /
+ * Anthropic 的 input_json_delta），适配器以各自的归并键（item_id / block
+ * index）调用本类累积，end 时得到 raw_arguments 全量。
+ *
+ * 刻意不在增量阶段做 partial parse（避免 O(n²) 重复解析）；end 时的
+ * JSON.parse 失败也不报错——raw_arguments 保留原文，由 runner 的参数
+ * 校验阶段统一报错回喂模型。
+ */
+
+declare class ToolCallBuffer {
+    private readonly buffers;
+    /** 名称确定的第一刻登记；返回仅含 id/name 的 ToolCall（供 toolcall_start 事件） */
+    start(key: string, id: string, name: string): ToolCall;
+    /** 追加参数分片；返回当前快照（供 toolcall_delta 事件携带归属信息） */
+    append(key: string, delta: string): ToolCall | null;
+    /** 结束归并；fullRaw 提供时以全量为准（Responses 的 .done 事件自带全量串） */
+    finish(key: string, fullRaw?: string): ToolCall | null;
+    /** 流异常终止时丢弃全部未完成归并 */
+    clear(): void;
+    get pendingCount(): number;
+}
+
+/**
+ * 工具参数校验 —— 调用前对 raw_arguments 做 JSON Schema 校验。
+ *
+ * 覆盖我们工具声明用到的 JSON Schema 子集（object / properties / required /
+ * string / number / integer / boolean / array / enum / default），不引 ajv：
+ * 我们的 schema 全部来自自家工具的 Zod 定义，结构可控。将来支持外部工具
+ * 声明时，可在此替换为完整 JSON Schema 校验器，接口不变。
+ *
+ * 校验失败返回中文错误文本（喂回模型自行修正），不抛异常。
+ */
+
+interface ValidatedArgs {
+    args: Record<string, unknown> | null;
+    error: string | null;
+}
+declare function validateToolCall(definitions: ToolDefinition[], call: ToolCall): ValidatedArgs;
+
+/**
+ * OpenAI Responses API 适配器。
+ *
+ * 按官方文档实现（https://platform.openai.com/docs/api-reference/responses-streaming）：
+ * - 请求：POST {base_url}/responses，system → instructions，历史 → input items
+ *   （message / function_call / function_call_output），stream: true；
+ * - 流式：tool_call 以 output_item.added(function_call) 确定 id/name，
+ *   function_call_arguments.delta 逐片累积、.done 给全量；
+ *   response.completed / failed / incomplete 为终态。
+ *
+ * 终态怪癖处理（继承 MovieClaw 兼容层经验）：
+ * - response.incomplete：已累积出完整 tool_calls 时按 done 处理（让循环继续），
+ *   否则报 error；
+ * - 流中途断开（无终态事件）→ error，不静默。
+ */
+
+interface ResponsesEndpointOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** 展示与日志用的端点名 */
+    providerName?: string;
+    /** 测试注入用；默认全局 fetch */
+    fetchImpl?: typeof fetch;
+}
+declare class OpenAIResponsesProtocol implements LlmProtocol {
+    readonly name = "openai-responses";
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly provider;
+    private readonly fetchImpl;
+    constructor(opts: ResponsesEndpointOptions);
+    chatStream(req: ChatRequest): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * Anthropic Messages API 适配器。
+ *
+ * 按官方文档实现（https://docs.claude.com/en/api/messages-streaming）：
+ * - 请求：POST {base_url}/v1/messages，system 是顶层字段；assistant 的
+ *   tool_calls → tool_use content blocks；tool 结果并入 user 消息的
+ *   tool_result blocks；max_tokens 必填；
+ * - 流式：content_block 状态机按 block index 归并；input_json_delta
+ *   累积到 content_block_stop 才 parse（避免每片 partial parse 的 O(n²)）；
+ *   signature_delta 必须采集——评审定案 thinking 签名透传进历史，
+ *   多轮工具往返要求带签名的 thinking block 原样回喂。
+ *
+ * 实现纪律（来自公开 issue 的已知坑）：
+ * - delta 类型与当前 block 类型不符 → 按流损坏处理，error 事件收尾，不猜；
+ * - tool_result 必须与此前 assistant 的 tool_use 严格配对（runner 保证），
+ *   否则 API 400。
+ */
+
+interface MessagesEndpointOptions {
+    baseUrl: string;
+    apiKey: string;
+    providerName?: string;
+    /** anthropic-version 头；默认官方当前版本 */
+    apiVersion?: string;
+    /** 测试注入用；默认全局 fetch */
+    fetchImpl?: typeof fetch;
+}
+declare class AnthropicMessagesProtocol implements LlmProtocol {
+    readonly name = "anthropic-messages";
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly provider;
+    private readonly apiVersion;
+    private readonly fetchImpl;
+    constructor(opts: MessagesEndpointOptions);
+    chatStream(req: ChatRequest): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * Agent 执行过程的事件协议 —— 前后端之间的「执行进度语言」。
+ *
+ * 设计原则（移植自 MovieClaw，对齐 pi 的 agent 事件思路）：
+ * 1. 事件类型面向「渲染语义」而非模型协议：调用方拿到事件就知道往哪个区域
+ *    画什么，不需要理解底层 LLM 流的细节；
+ * 2. 增量事件（*_delta）负责打字机效果，结束事件（agent_done）带完整结果，
+ *    断线重连/中途加入也能靠终态恢复；
+ * 3. 工具调用三段式：名称确定即发 tool_call_start，参数逐片发 tool_call_delta，
+ *    参数完整后发 tool_call——调用方从名称确定的一刻起就能展示进度。
+ *
+ * 事件序列（每一步 = 一次模型调用）：
+ *   agent_start → [ (thinking_delta|text_delta)*
+ *                   → (tool_call_start → tool_call_delta* → tool_call)*
+ *                   → tool_result* ]×N
+ *               → agent_done | agent_error | agent_cancelled
+ *               （任意安全点可插 context_compacted）
+ */
+
+declare const agentStartParamsSchema: z.ZodObject<{
+    input: z.ZodString;
+    include_input: z.ZodDefault<z.ZodBoolean>;
+    history: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodDefault<z.ZodString>;
+        tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            raw_arguments: z.ZodString;
+        }, z.core.$strip>>>;
+        tool_call_id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        is_error: z.ZodOptional<z.ZodBoolean>;
+        thinking: z.ZodOptional<z.ZodString>;
+        thinking_signature: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    model: z.ZodDefault<z.ZodString>;
+    system_prompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    settings: z.ZodDefault<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        max_tokens: z.ZodOptional<z.ZodNumber>;
+        reasoning_effort: z.ZodOptional<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AgentStartParams = z.input<typeof agentStartParamsSchema>;
+declare const agentToolResultSchema: z.ZodObject<{
+    tool_call_id: z.ZodString;
+    name: z.ZodString;
+    output: z.ZodString;
+    is_error: z.ZodDefault<z.ZodBoolean>;
+    elapsed_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type AgentToolResult = z.infer<typeof agentToolResultSchema>;
+declare const agentCompactionSchema: z.ZodObject<{
+    summary: z.ZodString;
+    tokens_before: z.ZodNumber;
+    tokens_after: z.ZodNumber;
+}, z.core.$strip>;
+type AgentCompaction = z.infer<typeof agentCompactionSchema>;
+/** 提权请求（escalation_request 事件载荷）：工具访问越界路径时发起，
+ *  前端展示并等待用户确认；确认后服务端登记授权并重发消息续跑 */
+declare const agentEscalationSchema: z.ZodObject<{
+    escalation_id: z.ZodString;
+    requested_path: z.ZodString;
+    resolved_path: z.ZodString;
+    tool_name: z.ZodString;
+    resource_type: z.ZodDefault<z.ZodEnum<{
+        path: "path";
+        command: "command";
+    }>>;
+    requested_command: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    workdir: z.ZodString;
+}, z.core.$strip>;
+type AgentEscalation = z.infer<typeof agentEscalationSchema>;
+declare const agentDoneSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    thinking: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    finish_reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    usage: z.ZodDefault<z.ZodObject<{
+        prompt_tokens: z.ZodDefault<z.ZodNumber>;
+        completion_tokens: z.ZodDefault<z.ZodNumber>;
+        total_tokens: z.ZodDefault<z.ZodNumber>;
+        cache_read_tokens: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    steps: z.ZodDefault<z.ZodNumber>;
+    model: z.ZodDefault<z.ZodString>;
+    provider: z.ZodDefault<z.ZodString>;
+    elapsed_ms: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type AgentDone = z.infer<typeof agentDoneSchema>;
+/** Agent 事件：type 决定哪些字段有值；作为 SSE 载荷时 type 同时用作 SSE 的 event 名 */
+declare const agentEventSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        thinking_delta: "thinking_delta";
+        text_delta: "text_delta";
+        tool_result: "tool_result";
+        tool_call: "tool_call";
+        agent_start: "agent_start";
+        tool_call_start: "tool_call_start";
+        tool_call_delta: "tool_call_delta";
+        context_compacted: "context_compacted";
+        escalation_request: "escalation_request";
+        agent_done: "agent_done";
+        agent_error: "agent_error";
+        agent_cancelled: "agent_cancelled";
+    }>;
+    run_id: z.ZodString;
+    delta: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tool_call: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        raw_arguments: z.ZodString;
+    }, z.core.$strip>>>;
+    tool_call_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    tool_result: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        tool_call_id: z.ZodString;
+        name: z.ZodString;
+        output: z.ZodString;
+        is_error: z.ZodDefault<z.ZodBoolean>;
+        elapsed_ms: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    compaction: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        summary: z.ZodString;
+        tokens_before: z.ZodNumber;
+        tokens_after: z.ZodNumber;
+    }, z.core.$strip>>>;
+    escalation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        escalation_id: z.ZodString;
+        requested_path: z.ZodString;
+        resolved_path: z.ZodString;
+        tool_name: z.ZodString;
+        resource_type: z.ZodDefault<z.ZodEnum<{
+            path: "path";
+            command: "command";
+        }>>;
+        requested_command: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        workdir: z.ZodString;
+    }, z.core.$strip>>>;
+    provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    result: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        text: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        thinking: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        finish_reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        usage: z.ZodDefault<z.ZodObject<{
+            prompt_tokens: z.ZodDefault<z.ZodNumber>;
+            completion_tokens: z.ZodDefault<z.ZodNumber>;
+            total_tokens: z.ZodDefault<z.ZodNumber>;
+            cache_read_tokens: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
+        steps: z.ZodDefault<z.ZodNumber>;
+        model: z.ZodDefault<z.ZodString>;
+        provider: z.ZodDefault<z.ZodString>;
+        elapsed_ms: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    error: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type AgentEvent = z.infer<typeof agentEventSchema>;
+type AgentEventType = AgentEvent["type"];
+declare const TERMINAL_EVENT_TYPES: ReadonlySet<AgentEventType>;
+
+/**
+ * 上下文压缩 —— codex 本地压缩策略的移植（经 MovieClaw 验证的取舍）。
+ *
+ * 核心思路：
+ * 1. 触发以服务端上报的 usage 为准：每步响应带回真实 prompt_tokens，无需引入
+ *    tokenizer；仅在没有服务端数据的场合（续聊冷启动、尚未发送的工具结果）用
+ *    「UTF-8 字节数 ≈ 4 字节/token」的启发式补估；
+ * 2. 压缩就是一次普通模型调用：把交接摘要指令作为 user 消息追加到全量历史
+ *    末尾，不带任何工具定义——模型只能输出文本，天然保证这一轮只写摘要；
+ * 3. 重建历史「宽进严出」：生成摘要时模型看得到全部现场；压缩落地后只保留
+ *    「预算内最近的用户原话 + 摘要」，工具轨迹全部丢弃——用户原话永不经过
+ *    有损摘要，防多次压缩后忘记原始意图；
+ * 4. 失败一律降级：压缩失败只记日志、返回 null，绝不中断正在进行的运行。
+ */
+
+/** 自动压缩水位线：上下文占用 ≥ 窗口的 90% 时触发（codex 同款比例） */
+declare const COMPACT_TRIGGER_RATIO = 0.9;
+/** 重建历史时保留近期用户消息的 token 预算（codex 同款 20k） */
+declare const RETAINED_USER_TOKEN_BUDGET = 20000;
+/** 无 tokenizer 时的估算系数：约 4 字节（UTF-8）≈ 1 token。对中文同样适用——
+ *  一个汉字 3 字节 ≈ 0.75 token，与主流 tokenizer 的量级一致，偏保守即可 */
+declare const APPROX_BYTES_PER_TOKEN = 4;
+interface CompactionResult {
+    /** 交接摘要文本 */
+    summary: string;
+    /** 重建后的历史（不含 system，system 每次运行重拼） */
+    replacement_history: ChatMessage[];
+    /** 压缩前后的估算 token 数（bytes/4 启发式，展示与观测用，非精确值） */
+    tokens_before: number;
+    tokens_after: number;
+}
+declare function estimateTokens(target: ChatMessage[] | ChatMessage | string): number;
+/** 是否达到自动压缩水位线；模型未声明窗口时永不自动压缩（调用方负责日志） */
+declare function shouldCompact(contextTokens: number, contextWindow: number | undefined): boolean;
+/** 识别历史里由压缩产生的摘要消息（user 角色 + 固定前缀） */
+declare function isSummaryMessage(message: ChatMessage): boolean;
+/** 按 codex 策略重建历史：预算内逆序保留的用户原话 + 摘要收尾。
+ *  - 只保留真实 user 消息（排除 system / 旧压缩摘要），从最新往旧装入预算，
+ *    装不下的最旧一条中部截断；
+ *  - assistant / tool / 思考内容全部丢弃，信息由摘要承载；
+ *  - 摘要带固定前缀、作为最后一条 user 消息。 */
+declare function buildReplacementHistory(messages: ChatMessage[], summary: string): ChatMessage[];
+/**
+ * 执行一次压缩：全量历史 + 摘要指令 → 模型写交接摘要 → 重建历史。
+ *
+ * messages 是完整现场（含 system 与全部工具往返）；返回的
+ * replacement_history 不含 system。任何失败（流错误、异常、空摘要）都
+ * 返回 null，由调用方决定降级方式——本函数绝不抛异常。
+ */
+declare function compact(protocol: LlmProtocol, model: string, messages: ChatMessage[], settings: ModelSettings): Promise<CompactionResult | null>;
+
+/**
+ * Agent 系统提示词。
+ *
+ * 设计原则（移植自 MovieClaw，对齐 Claude Code 的提示词架构）：
+ * - 正文只写通用行为准则（运行方式 / 并行调用 / 工作循环 / 回复风格），
+ *   不含任何领域词汇——领域语义由各工具的 description 和运行时环境段承载；
+ * - 环境事实（日期等）随时会变，由 buildSystemPrompt 在每次运行时拼接，
+ *   绝不写死在正文里。
+ */
+/** 压缩摘要消息的固定前缀——重建历史时靠它识别「这条 user 消息是压缩摘要」，
+ *  再次压缩时旧摘要不会被当成用户原话保留（codex SUMMARY_PREFIX 同款机制） */
+declare const SUMMARY_PREFIX = "\u3010\u4E0A\u4E0B\u6587\u538B\u7F29\u6458\u8981\u3011\u6B64\u524D\u7684\u5BF9\u8BDD\u5DF2\u88AB\u538B\u7F29\uFF0C\u4EE5\u4E0B\u662F\u4EA4\u63A5\u6458\u8981\uFF1A";
+/** 交接摘要指令（codex SUMMARIZATION_PROMPT 的中文对齐版）。作为一条普通
+ *  user 消息追加到全量历史末尾发起压缩请求，不是系统提示词。 */
+declare const COMPACT_PROMPT = "\u4F60\u6B63\u5728\u6267\u884C\u4E00\u6B21\u4E0A\u4E0B\u6587\u538B\u7F29\u3002\u8BF7\u4E3A\u5C06\u8981\u63A5\u624B\u8FD9\u6BB5\u5BF9\u8BDD\u7684\u53E6\u4E00\u4E2A LLM \u5199\u4E00\u4EFD\u4EA4\u63A5\u6458\u8981\u3002\n\n\u6458\u8981\u5FC5\u987B\u5305\u542B\uFF1A\n- \u4EFB\u52A1\u76EE\u6807\u4E0E\u5F53\u524D\u8FDB\u5EA6\u3001\u5DF2\u505A\u51FA\u7684\u5173\u952E\u51B3\u5B9A\n- \u7528\u6237\u63D0\u51FA\u7684\u7EA6\u675F\u3001\u504F\u597D\u548C\u91CD\u8981\u80CC\u666F\n- \u5C1A\u672A\u5B8C\u6210\u7684\u4E8B\u9879\uFF08\u660E\u786E\u7684\u4E0B\u4E00\u6B65\uFF09\n- \u7EE7\u7EED\u5DE5\u4F5C\u5FC5\u987B\u4FDD\u7559\u7684\u5173\u952E\u6570\u636E\uFF08\u8DEF\u5F84\u3001ID\u3001\u7F16\u53F7\u3001\u67E5\u8BE2\u7ED3\u679C\u8981\u70B9\u7B49\uFF09\n\n\u4FDD\u6301\u7B80\u6D01\u3001\u7ED3\u6784\u5316\uFF0C\u4EE5\u5E2E\u52A9\u4E0B\u4E00\u4E2A LLM \u65E0\u7F1D\u63A5\u7EED\u5DE5\u4F5C\u4E3A\u552F\u4E00\u76EE\u6807\u3002\u53EA\u8F93\u51FA\u6458\u8981\u6B63\u6587\u3002\n";
+interface SystemPromptOptions {
+    /** 助理名称，默认 "xlyra 助理" */
+    agentName?: string;
+    /** 一句话人设（拼在首段），默认空 */
+    persona?: string;
+    /** 运行时环境段（每行一个事实，拼在「# 环境」下） */
+    extraEnvironment?: string;
+    /** 当前会话实际暴露给模型的工具；由 Runner 动态注入，避免静态提示漂移。 */
+    availableTools?: Array<Pick<ToolDefinition, "name" | "description">>;
+}
+declare function buildAvailableToolsPrompt(availableTools: Array<Pick<ToolDefinition, "name" | "description">>): string;
+declare function buildSystemPrompt(opts?: SystemPromptOptions): string;
+
+/** 文件格式版本；结构变化时 +1，读取端按版本做迁移
+ *  v3：新增 type="escalation" 的提权请求行（读端向后兼容 v1/v2） */
+declare const SESSION_FORMAT_VERSION = 3;
+/** 会话标题 / 最后提示预览的截断长度 */
+declare const PREVIEW_MAX_CHARS = 80;
+/** 默认数据根目录（~/.xlyra-agent），sessions 与 index.json 均在其下 */
+declare function defaultDataDir(): string;
+declare function defaultSessionsDir(): string;
+declare const sessionHeaderSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"session">>;
+    version: z.ZodDefault<z.ZodNumber>;
+    session_id: z.ZodString;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+type SessionHeader = z.infer<typeof sessionHeaderSchema>;
+declare const sessionMessageEntrySchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"message">>;
+    uuid: z.ZodString;
+    parent_uuid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timestamp: z.ZodString;
+    message: z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodDefault<z.ZodString>;
+        tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            raw_arguments: z.ZodString;
+        }, z.core.$strip>>>;
+        tool_call_id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        is_error: z.ZodOptional<z.ZodBoolean>;
+        thinking: z.ZodOptional<z.ZodString>;
+        thinking_signature: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    model: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    usage: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        prompt_tokens: z.ZodDefault<z.ZodNumber>;
+        completion_tokens: z.ZodDefault<z.ZodNumber>;
+        total_tokens: z.ZodDefault<z.ZodNumber>;
+        cache_read_tokens: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    finish_reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type SessionMessageEntry = z.infer<typeof sessionMessageEntrySchema>;
+declare const sessionCompactionEntrySchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"compaction">>;
+    uuid: z.ZodString;
+    parent_uuid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timestamp: z.ZodString;
+    summary: z.ZodString;
+    replacement_history: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodDefault<z.ZodString>;
+        tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            raw_arguments: z.ZodString;
+        }, z.core.$strip>>>;
+        tool_call_id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        is_error: z.ZodOptional<z.ZodBoolean>;
+        thinking: z.ZodOptional<z.ZodString>;
+        thinking_signature: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    tokens_before: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tokens_after: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+type SessionCompactionEntry = z.infer<typeof sessionCompactionEntrySchema>;
+/** 提权请求行：越界访问的协商记录（回放时前端据此渲染确认卡片）。
+ *  granted=null 待确认；true 已授权；false 已拒绝 */
+declare const sessionEscalationEntrySchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodLiteral<"escalation">>;
+    uuid: z.ZodString;
+    parent_uuid: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    timestamp: z.ZodString;
+    requested_path: z.ZodString;
+    resolved_path: z.ZodString;
+    tool_name: z.ZodString;
+    resource_type: z.ZodDefault<z.ZodEnum<{
+        path: "path";
+        command: "command";
+    }>>;
+    requested_command: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    granted: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodBoolean>>>;
+}, z.core.$strip>;
+type SessionEscalationEntry = z.infer<typeof sessionEscalationEntrySchema>;
+type SessionEntry = SessionMessageEntry | SessionCompactionEntry | SessionEscalationEntry;
+interface SessionSummary {
+    session_id: string;
+    created_at: string;
+    entry_count: number;
+    leaf_uuid: string | null;
+    /** 首条 user 消息的截断文本；作为无自定义标题时的会话标题 */
+    title: string | null;
+    /** 最后一条 user 消息的截断文本 */
+    last_prompt: string | null;
+    last_timestamp: string;
+}
+declare function isMessageEntry(e: SessionEntry): e is SessionMessageEntry;
+declare function isCompactionEntry(e: SessionEntry): e is SessionCompactionEntry;
+declare function isEscalationEntry(e: SessionEntry): e is SessionEscalationEntry;
+declare class AgentSessionStore {
+    private readonly root;
+    /** session_id → 最后一条 entry 的 uuid（避免每次 append 都重读文件） */
+    private readonly leafCache;
+    constructor(root?: string);
+    get rootDir(): string;
+    pathOf(sessionId: string): string;
+    exists(sessionId: string): boolean;
+    /** 新建会话文件并写入头行，返回头信息 */
+    create(sessionId?: string): SessionHeader;
+    /** 追加一条定稿消息，自动接到当前链尾，返回写入的 entry */
+    append(sessionId: string, message: ChatMessage, meta?: {
+        model?: string;
+        usage?: z.infer<typeof tokenUsageSchema>;
+        finish_reason?: string;
+    }): SessionMessageEntry;
+    /** 追加一条压缩行，与 append 同款接到当前链尾（parent 链线性穿过压缩行） */
+    appendCompaction(sessionId: string, result: CompactionResult): SessionCompactionEntry;
+    /** 追加一条提权请求行（granted=null 待确认） */
+    appendEscalation(sessionId: string, info: {
+        escalation_id: string;
+        requested_path: string;
+        resolved_path: string;
+        tool_name: string;
+        resource_type?: "path" | "command";
+        requested_command?: string[];
+    }): SessionEscalationEntry;
+    /** 标记提权请求的确认结果（granted=true 授权 / false 拒绝）。
+     *  这是 append-only 原则的第二个例外（另一个是 discardFromUserMessage）：
+     *  提权行的 granted 字段需要就地更新，否则确认状态无法在回放时保留。
+     *  实现上仍是整文件原子重写（tmp + rename），与 discard 同款安全保证。 */
+    resolveEscalation(sessionId: string, escalationId: string, granted: boolean): boolean;
+    /**
+     * 中断收尾：给没有结果的 tool_call 补写错误回执，返回补写条数。
+     *
+     * 保证文件里 assistant 的 tool_calls 与 tool 消息任何时刻都配对完整，
+     * resume 直接回喂 API 不需要修复逻辑（在写入侧一次做对）。
+     * 只检查最后一条压缩行之后的消息：更早的往返已被压缩挡在上下文之外，
+     * 给死上下文补回执毫无意义。
+     */
+    sealPendingToolCalls(sessionId: string): number;
+    /**
+     * 删除指定 user message 及其之后的全部 entry，返回删除条数。
+     *
+     * 这是本模块唯一改写历史行的方法，与「append-only」约定相悖，属于刻意的
+     * 例外：用户要的就是「这些记录不该再存在」。整文件重写，写临时文件后
+     * rename 原子换入：中途崩溃要么旧文件完好、要么新文件完整。
+     * 只允许从 user message 切：从 assistant/tool 中间切会留下没有回执的
+     * tool_call，重建出的上下文喂回模型直接 400。
+     */
+    discardFromUserMessage(sessionId: string, messageId: string): number;
+    /** 删除会话文件（幂等） */
+    delete(sessionId: string): void;
+    /** 读取整个会话（头 + 全部 entry，含压缩行），坏行静默跳过 */
+    read(sessionId: string): {
+        header: SessionHeader;
+        entries: SessionEntry[];
+        badLines: number;
+    };
+    /**
+     * 把会话重建成模型上下文消息列表（resume 喂回模型用）。
+     * 有压缩行时，从最后一条压缩行的替换历史起步、只追加其后的增量消息；
+     * system 提示词不入库（随代码版本演进），由 runner 每次运行时重新拼装。
+     */
+    buildHistory(sessionId: string): ChatMessage[];
+    /**
+     * 重建提权中断前的上下文：保留原始 user 输入，但丢弃被中断的
+     * assistant/tool 往返，授权后由 runner 从原输入继续推理。
+     */
+    buildHistoryBeforeEscalation(sessionId: string, escalationId: string): ChatMessage[];
+    /** 扫描单个会话文件生成索引摘要 */
+    summarize(sessionId: string): SessionSummary;
+    /** 遍历目录下全部会话文件生成摘要（索引整体重建用；单文件损坏只跳过） */
+    scanAll(): SessionSummary[];
+    private currentLeaf;
+    private appendLine;
+}
+
+/**
+ * 工具挂点：声明 + 执行器的绑定。
+ *
+ * 工具的「声明」（definition，暴露给模型）与「执行」（handler，真正干活）
+ * 在此绑成一个单元——改行为时提示词与实现不会漂移。handler 约定：
+ * - 入参是已通过 JSON Schema 校验的参数 dict；
+ * - 返回喂回模型的文本（紧凑、模型可读即可）；
+ * - 业务失败 throw new Error(中文说明)：runner 会把异常转成失败结果
+ *   回喂模型，不中断 loop。
+ */
+
+interface ToolAnnotations {
+    /** 不修改文件、进程或外部状态。 */
+    readOnly: boolean;
+    /** 可与同一模型响应中的其他只读工具并发执行。 */
+    parallelSafe: boolean;
+}
+interface ToolContext {
+    /** 当前 Agent 运行的取消信号；长任务必须主动监听。 */
+    signal?: AbortSignal;
+    /** 当前运行编号，供进程会话与诊断日志关联。 */
+    runId?: string;
+}
+interface ToolHandlerResult {
+    /** 回喂模型的紧凑文本。 */
+    content: string;
+    /** 工具可显式返回业务失败，而不必抛异常。 */
+    isError?: boolean;
+    /** 仅供宿主扩展使用；当前消息协议不会把它回喂模型。 */
+    metadata?: Record<string, unknown>;
+}
+interface AgentTool {
+    definition: ToolDefinition;
+    /** 省略时按“有副作用、不可并行”的保守策略处理。 */
+    annotations?: ToolAnnotations;
+    /** 字符串返回值继续兼容已有自定义工具。 */
+    handler: (args: Record<string, unknown>, context?: ToolContext) => Promise<string | ToolHandlerResult>;
+}
+
+interface AgentRunnerOptions {
+    /** 直接使用单个协议实例（库形态的典型用法） */
+    protocol?: LlmProtocol;
+    /** 或经端点路由按 params.model 解析（服务层用法）；两者必传其一 */
+    resolver?: EndpointResolver;
+    tools?: AgentTool[];
+    maxSteps?: number;
+    /** 定稿消息回调（会话持久化挂点）：中间步 assistant（含 tool_calls）、
+     *  每条 tool 结果、终答 assistant 各调用一次；流式 delta 不经过这里 */
+    onMessage?: (message: ChatMessage, response: ChatResponse | null) => Promise<void>;
+    /** 压缩定稿回调（转录落盘挂点）：每次上下文压缩成功后调用一次 */
+    onCompaction?: (result: CompactionResult) => Promise<void>;
+    /** 提权请求回调（转录落盘挂点）：回放时前端据此渲染确认卡片 */
+    onEscalation?: (info: {
+        escalation_id: string;
+        requested_path: string;
+        resolved_path: string;
+        tool_name: string;
+        resource_type: "path" | "command";
+        requested_command?: string[];
+    }) => Promise<void>;
+    /** 日志输出（默认 console）；测试可注入静默 logger */
+    logger?: Pick<Console, "info" | "warn" | "error">;
+    /** 提权事件里展示的工作区根（用户判断边界用）；服务装配层从工具配置传入 */
+    workdirHint?: string;
+}
+interface AgentRunOptions {
+    runId?: string;
+    signal?: AbortSignal;
+}
+declare class AgentRunner {
+    private readonly protocol?;
+    private readonly resolver?;
+    private readonly tools;
+    private readonly toolsByName;
+    private readonly maxSteps;
+    private readonly onMessage?;
+    private readonly onCompaction?;
+    private readonly onEscalation?;
+    private readonly logger;
+    /** 提权事件里展示的工作区根（用户判断边界用）；由构造方从工具配置传入 */
+    private readonly workdirHint;
+    constructor(opts: AgentRunnerOptions);
+    start(params: AgentStartParams, runOpts?: AgentRunOptions): AsyncGenerator<AgentEvent>;
+    /** 达到水位线时压缩上下文并原地替换 messages，返回压缩事件。
+     *  任何失败都降级为「本次不压缩」：记日志后照常返回 null，运行继续。 */
+    private maybeCompact;
+    private notifyCompaction;
+    private notifyEscalation;
+    private notify;
+    /** 执行单个工具调用：校验 → 执行；任何失败都转为回喂文本，不抛异常 */
+    private executeTool;
+}
+
+/**
+ * 会话级路径授权登记表（进程内）。
+ * key = sessionId，value = 已授权的路径前缀集合（realpath 后的绝对路径）。
+ */
+declare class EscalationGrants {
+    private readonly grants;
+    grant(sessionId: string, resolvedPath: string): void;
+    grantCapability(sessionId: string, capability: string): void;
+    /** 已授权路径或其子路径视为已放开 */
+    isGranted(sessionId: string, resolvedPath: string): boolean;
+    isCapabilityGranted(sessionId: string, capability: string): boolean;
+    /** 会话删除时清掉授权（授权随会话生命周期） */
+    drop(sessionId: string): void;
+}
+
+/**
+ * 工具工厂共享的沙箱参数形态（避免每个工具文件重复定义）。
+ */
+
+interface SandboxOptions {
+    allowOutsideWorkdir?: boolean;
+    /** 命令工具是否已由宿主预授权；否则首次调用走提权协商。 */
+    commandExecutionEnabled?: boolean;
+    grants?: EscalationGrants;
+    sessionId?: string;
+}
+
+declare function makeListTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+declare function makeReadTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+declare function makeCreateTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+declare function makeApplyPatchTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+declare function makeEditTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+declare function makeSearchTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+interface SpawnProcessOptions {
+    command: string[];
+    cwd: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+interface ProcessPollResult {
+    sessionId: string;
+    output: string;
+    running: boolean;
+    exitCode: number | null;
+    exitSignal: NodeJS.Signals | null;
+    error: string | null;
+}
+declare class ProcessManager {
+    private readonly sessions;
+    start(options: SpawnProcessOptions): string;
+    poll(sessionId: string, yieldTimeMs: number, maxOutputBytes: number): Promise<ProcessPollResult>;
+    write(sessionId: string, chars: string): void;
+    private require;
+    private terminate;
+    private finish;
+    private prune;
+}
+
+declare function makeExecCommandTool(workdir: string, manager: ProcessManager, sandbox?: SandboxOptions): AgentTool;
+declare function formatProcessResult(result: ProcessPollResult): {
+    content: string;
+    isError: boolean;
+};
+
+declare function makeWriteStdinTool(manager: ProcessManager, sandbox?: SandboxOptions): AgentTool;
+
+declare function makeWriteTool(workdir: string, sandbox?: SandboxOptions): AgentTool;
+
+/**
+ * 解析目标路径并做沙箱校验；返回可直接用于 fs 操作的绝对路径。
+ * 目标不存在时（create 场景）：取最深的已存在祖先做 realpath，再拼回剩余段。
+ */
+declare function resolveSandboxed(workdir: string, raw: string, opts?: {
+    allowOutsideWorkdir?: boolean;
+    /** 会话级授权清单（提供 sessionId 时生效） */
+    grants?: EscalationGrants;
+    sessionId?: string;
+}): string;
+
+interface BuiltinToolsOptions {
+    /** 工作目录：相对路径解析基准 + 沙箱边界 */
+    workdir: string;
+    /** 显式放开沙箱（默认 false：全部路径限制在 workdir 内） */
+    allowOutsideWorkdir?: boolean;
+    /** 会话级路径授权清单（与 sessionId 一起提供时生效） */
+    grants?: EscalationGrants;
+    /** 当前会话 id（授权清单的查询键） */
+    sessionId?: string;
+    /** 预授权本机命令执行；关闭时工具仍会声明，但首次调用触发提权协商。 */
+    enableCommandExecution?: boolean;
+}
+declare function builtinTools(opts: BuiltinToolsOptions): AgentTool[];
+
+declare const appConfigSchema: z.ZodObject<{
+    endpoints: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        protocol: z.ZodEnum<{
+            "anthropic-messages": "anthropic-messages";
+            "openai-responses": "openai-responses";
+        }>;
+        base_url: z.ZodString;
+        api_key: z.ZodString;
+        models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            context_window: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        default_model: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    server: z.ZodOptional<z.ZodObject<{
+        port: z.ZodOptional<z.ZodNumber>;
+        token: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    agent: z.ZodOptional<z.ZodObject<{
+        workdir: z.ZodOptional<z.ZodString>;
+        agent_name: z.ZodOptional<z.ZodString>;
+        persona: z.ZodOptional<z.ZodString>;
+        enable_command_execution: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AppConfig = z.infer<typeof appConfigSchema>;
+type ServerConfig = NonNullable<AppConfig["server"]>;
+type AgentServiceConfig = NonNullable<AppConfig["agent"]>;
+declare function defaultConfigPath(): string;
+/** 加载并校验配置；文件不存在/结构非法时抛出明确中文错误 */
+declare function loadConfig(configPath?: string): AppConfig;
+/** 保存配置（tmp + rename 原子写入）；config 须已通过 schema 校验 */
+declare function saveConfig(config: AppConfig, configPath?: string): void;
+/** 配置是否存在（config init 判重 / 首次运行引导用） */
+declare function configExists(configPath?: string): boolean;
+/** 新增或更新端点（按 name 匹配，同名覆盖）；返回写入后的完整配置 */
+declare function upsertEndpoint(endpoint: EndpointConfig, configPath?: string): AppConfig;
+/** 按 name 删除端点；不存在时返回 false。不允许删除最后一条（配置必须非空） */
+declare function removeEndpoint(name: string, configPath?: string): boolean;
+
+interface RunningState {
+    run_id: string;
+    /** 最近一次心跳的 epoch 毫秒 */
+    last_heartbeat: number;
+}
+interface SessionMeta {
+    session_id: string;
+    created_at: string;
+    title: string | null;
+    last_prompt: string | null;
+    entry_count: number;
+    leaf_uuid: string | null;
+    last_active: string;
+    running: RunningState | null;
+}
+declare class SessionIndex {
+    private readonly file;
+    private readonly metas;
+    constructor(indexFile: string);
+    /** 启动时加载；文件不存在/损坏则从空开始（rebuild 会补齐） */
+    private load;
+    /** 从事实源整体重建（启动自愈）：扫描结果单向覆盖索引 */
+    rebuild(summaries: SessionSummary[]): void;
+    create(sessionId: string): void;
+    get(sessionId: string): SessionMeta | undefined;
+    /** 每次追加 entry 后刷新链尾/计数/预览；title 仅在传入时更新（首条消息） */
+    touchAfterAppend(sessionId: string, update: {
+        leaf_uuid: string;
+        entry_count: number;
+        last_prompt?: string;
+        title?: string;
+    }): void;
+    rename(sessionId: string, title: string): boolean;
+    markRunning(sessionId: string, runId: string): void;
+    heartbeat(sessionId: string): void;
+    finishRun(sessionId: string): void;
+    /** 是否有正在进行的消息处理：运行标记存在且心跳未超时 */
+    isRunning(sessionId: string): boolean;
+    /** 按最后活跃时间倒序分页 */
+    list(limit: number, offset: number): SessionMeta[];
+    remove(sessionId: string): void;
+    private persist;
+}
+
+/**
+ * 会话记录器：把一次 Agent 运行的定稿消息接进 JSONL 存储与会话索引。
+ *
+ * 一次运行一个实例，由路由层创建并挂到两个钩子上：
+ * - AgentRunner(onMessage / onCompaction)——定稿消息与压缩行落盘并刷新
+ *   索引（先文件后索引，见 sessions.ts 的写入顺序约定）；
+ * - RunRegistry.start(onTerminal)——运行终态时收尾：停心跳、给未配对的
+ *   tool_call 补错误回执、清空运行标记（列表立即显示已结束）。
+ *
+ * 心跳独立于消息追加：长工具执行期间可能几十秒没有新消息，心跳任务保证
+ * last_heartbeat 持续刷新，调用方才能正确区分「还在跑」和「已崩溃」。
+ * 进程硬崩时心跳自然停止，超时窗过后状态自愈为已结束——这正是不持久化
+ * 静态 status 字段的原因。
+ */
+
+declare class AgentRunRecorder {
+    private readonly store;
+    private readonly index;
+    private readonly sessionId;
+    /** 运行开始时会话已有的 entry 数；之后每次落盘递增，避免反复重读文件 */
+    private entryCount;
+    private heartbeatTimer;
+    /** begin 与 onTerminal 分别由路由层和后台任务并发调用：用同一根 Promise
+     *  链串行化，防「极速结束的运行被误标为永远运行中」的竞态 */
+    private lifecycle;
+    private terminated;
+    constructor(store: AgentSessionStore, index: SessionIndex, sessionId: string, entryCount: number);
+    /** 运行启动：标记 running 并开启心跳。运行已先一步终态时跳过。 */
+    begin(runId: string): Promise<void>;
+    /** 落盘 user message，刷新标题（仅首条）与最后提示预览，返回 message id */
+    recordUserMessage(text: string): Promise<string>;
+    /** runner 定稿消息回调：assistant 带响应元数据，tool 结果不带 */
+    onMessage: (message: ChatMessage, response: ChatResponse | null) => Promise<void>;
+    /** runner 压缩定稿回调：压缩行落盘并刷新索引（与 onMessage 同一节奏） */
+    onCompaction: (result: CompactionResult) => Promise<void>;
+    /** runner 提权请求回调：提权行落盘并刷新索引（回放时前端渲染确认卡片） */
+    onEscalation: (info: {
+        escalation_id: string;
+        requested_path: string;
+        resolved_path: string;
+        tool_name: string;
+        resource_type?: "path" | "command";
+        requested_command?: string[];
+    }) => Promise<void>;
+    /** 运行终态收尾（done / error / cancelled 统一路径） */
+    onTerminal: (_event: AgentEvent) => Promise<void>;
+}
+
+interface StoredAgentEvent {
+    /** 运行内递增序号；直接用作 SSE 的 id */
+    sequence: number;
+    event: AgentEvent;
+}
+interface Run {
+    runId: string;
+    sessionId: string;
+    events: StoredAgentEvent[];
+    terminal: boolean;
+    completedAt: number | null;
+    controller: AbortController;
+    /** 等待新事件的唤醒回调（一次性，触发后移除） */
+    waiters: Set<() => void>;
+    /** 终态钩子：运行进入终态后调用一次（停心跳、补配对、清运行标记） */
+    onTerminal: ((event: AgentEvent) => Promise<void>) | null;
+}
+declare class RunRegistry {
+    private readonly retentionMs;
+    private readonly runs;
+    private readonly latestBySession;
+    private closing;
+    constructor(opts?: {
+        retentionMs?: number;
+    });
+    /** 分配运行编号并把 runner 放入后台执行，立即返回编号 */
+    start(runner: AgentRunner, params: AgentStartParams, opts: {
+        sessionId: string;
+        onTerminal?: (event: AgentEvent) => Promise<void>;
+    }): string;
+    /** 按公开会话编号读取当前（或最近一轮）事件 */
+    getSessionEvents(sessionId: string, afterSequence: number, timeoutSeconds: number): Promise<{
+        events: StoredAgentEvent[];
+        terminal: boolean;
+    }>;
+    /**
+     * 返回游标后的事件；暂无事件时等待通知，超时返回空列表供 SSE 发心跳。
+     * 调用方应先发送本批事件，再在 terminal=true 且批次已追平时关闭连接。
+     */
+    getEvents(runId: string, afterSequence: number, timeoutSeconds: number): Promise<{
+        events: StoredAgentEvent[];
+        terminal: boolean;
+    }>;
+    /**
+     * 幂等取消一次运行：**先落可回放的 agent_cancelled 终态事件，再 abort**。
+     * 顺序很重要：运行刚创建、事件循环尚未开始消费时，直接 abort 会让 runner
+     * 一次都不执行，订阅者会永久等待——先落终态事件保证任何情况下订阅者
+     * 都能看到收尾。
+     */
+    cancel(runId: string): Promise<void>;
+    cancelSession(sessionId: string): Promise<void>;
+    /** 应用关闭时取消全部活动运行 */
+    close(): Promise<void>;
+    /** 消费 runner 事件并写入日志，兜住所有退出路径补齐终态 */
+    private execute;
+    /** 原子追加事件并广播唤醒；终态之后的迟到事件直接忽略 */
+    private publish;
+    getRun(runId: string): Run;
+    private sessionRun;
+    /** 惰性清理超过保留期的终态运行；活动运行永不在这里删除 */
+    private pruneExpired;
+}
+/** 路由层可直接转成统一错误响应的异常 */
+declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+interface RoutesContext {
+    resolver: EndpointResolver;
+    store: AgentSessionStore;
+    index: SessionIndex;
+    registry: RunRegistry;
+    /** 会话级路径授权登记表（提权协商的确认落点） */
+    grants: EscalationGrants;
+    /** 工具工厂：按会话构建工具集（授权清单需要 sessionId 才能生效） */
+    makeTools: (sessionId: string) => AgentTool[];
+    /** 提权事件展示的工作区根 */
+    workdir: string;
+    agentName?: string;
+    persona?: string;
+    /** 可选静态 Bearer token；配置后全部端点要求鉴权 */
+    token?: string;
+}
+declare function createAgentRoutes(ctx: RoutesContext): Hono;
+
+interface AgentServer {
+    app: Hono;
+    registry: RunRegistry;
+    store: AgentSessionStore;
+    index: SessionIndex;
+}
+/** 以代码方式装配服务（嵌入用法） */
+declare function createAgentServer(config: AppConfig, opts?: {
+    configPath?: string;
+    dataDir?: string;
+}): AgentServer;
+/** 以配置文件启动 HTTP 服务（CLI serve 命令） */
+declare function serveFromConfig(opts: {
+    configPath?: string;
+    port?: number;
+}): void;
+
+export { APPROX_BYTES_PER_TOKEN, type AgentCompaction, type AgentDone, type AgentEscalation, type AgentEvent, type AgentEventType, type AgentRunOptions, AgentRunRecorder, AgentRunner, type AgentRunnerOptions, type AgentServiceConfig, AgentSessionStore, type AgentStartParams, type AgentTool, type AgentToolResult, AnthropicMessagesProtocol, type AppConfig, type BuiltinToolsOptions, COMPACT_PROMPT, COMPACT_TRIGGER_RATIO, type ChatMessage, type ChatRequest, type ChatResponse, type CompactionResult, type EndpointConfig, EndpointResolver, HttpError, LlmError, type LlmProtocol, type MessagesEndpointOptions, type ModelSettings, OpenAIResponsesProtocol, PREVIEW_MAX_CHARS, ProcessManager, RETAINED_USER_TOKEN_BUDGET, type ResolvedModel, type ResponsesEndpointOptions, RunRegistry, SESSION_FORMAT_VERSION, SUMMARY_PREFIX, type SandboxOptions, type ServerConfig, type SessionCompactionEntry, type SessionEntry, type SessionEscalationEntry, type SessionHeader, SessionIndex, type SessionMessageEntry, type SessionSummary, type SseEvent, type StoredAgentEvent, type StreamEvent, type SystemPromptOptions, TERMINAL_EVENT_TYPES, type TokenUsage, type ToolAnnotations, type ToolCall, ToolCallBuffer, type ToolContext, type ToolDefinition, type ToolHandlerResult, type ValidatedArgs, addUsage, agentCompactionSchema, agentDoneSchema, agentEscalationSchema, agentEventSchema, agentStartParamsSchema, agentToolResultSchema, buildAvailableToolsPrompt, buildReplacementHistory, buildSystemPrompt, builtinContextWindow, builtinTools, chatMessageSchema, compact, configExists, createAgentRoutes, createAgentServer, defaultConfigPath, defaultDataDir, defaultSessionsDir, emptyUsage, estimateTokens, formatProcessResult, isCompactionEntry, isEscalationEntry, isMessageEntry, isSummaryMessage, loadConfig, makeApplyPatchTool, makeCreateTool, makeEditTool, makeExecCommandTool, makeListTool, makeReadTool, makeSearchTool, makeWriteStdinTool, makeWriteTool, messageText, modelSettingsSchema, parseSse, removeEndpoint, resolveSandboxed, responseToMessage, saveConfig, serveFromConfig, shouldCompact, tokenUsageSchema, toolCallSchema, upsertEndpoint, validateToolCall };