@fllf/agent-sdk 0.1.2 → 0.1.3

package/dist/executors/tool-calling-executor.js

@@ -1,121 +1,215 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolCallingExecutor = void 0;
+const llm_1 = require("../llm");
+const errors_1 = require("../errors");
 const messages_1 = require("../messages");
 const tools_1 = require("../tools");
+const chat_request_builder_1 = require("./chat-request-builder");
 class ToolCallingExecutor {
     maxIterations;
+    onMaxIterations;
     constructor(options = {}) {
         this.maxIterations = options.maxIterations ?? 5;
+        this.onMaxIterations = options.onMaxIterations ?? 'finalize';
     }
     async run(context) {
-        const userMessage = new messages_1.Message(context.input, 'user', context.options.metadata ? { metadata: context.options.metadata } : {});
-        const runMessages = [userMessage];
-        const toolExecutor = new tools_1.ToolExecutor(context.tools, {
-            runId: context.runId,
-            observer: context.observer,
-            agentName: context.agentName,
-            sessionId: context.sessionId,
-        });
-        const messages = await buildInitialMessages(context, userMessage);
-        let usage;
-        let raw;
+        const toolExecutor = createToolExecutor(context);
+        const state = await createRunState(context);
         for (let iteration = 0; iteration < this.maxIterations; iteration += 1) {
-            const response = await context.llm.chat(buildChatRequest(context, messages));
-            usage = mergeTokenUsage(usage, response.usage);
-            raw = response.raw;
+            const response = await context.llm.chat((0, chat_request_builder_1.buildChatRequest)(context, state.chatMessages, { includeTools: true }));
+            mergeResponseIntoState(state, response);
             if (response.toolCalls.length === 0) {
-                const assistantMessage = new messages_1.Message(response.content, 'assistant');
-                runMessages.push(assistantMessage);
-                await context.history.addMany(runMessages);
-                const result = {
-                    output: response.content,
-                    messages: await context.history.get(),
-                    raw,
-                };
-                if (usage !== undefined) {
-                    result.usage = usage;
-                }
-                return result;
+                return await finishRun(context, state, response.content);
+            }
+            appendAssistantToolCallMessage(state, response);
+            const outcomes = await toolExecutor.executeMany(response.toolCalls);
+            appendToolOutcomeMessages(state, outcomes);
+        }
+        return await this.handleMaxIterations(context, state);
+    }
+    async *stream(context) {
+        const toolExecutor = createToolExecutor(context);
+        const state = await createRunState(context);
+        for (let iteration = 0; iteration < this.maxIterations; iteration += 1) {
+            const response = yield* this.streamOneTurn(context, state, { includeTools: true });
+            mergeResponseIntoState(state, response);
+            if (response.toolCalls.length === 0) {
+                yield await this.createEndEvent(context, state, response.content);
+                return;
             }
-            const assistantMessage = new messages_1.Message(response.content, 'assistant', {
-                metadata: { toolCalls: response.toolCalls },
-            });
-            runMessages.push(assistantMessage);
-            messages.push(assistantMessage.toChatMessage());
+            appendAssistantToolCallMessage(state, response);
             for (const toolCall of response.toolCalls) {
-                const result = await toolExecutor.execute(toolCall);
-                const toolMessage = new messages_1.Message(result, 'tool', {
-                    metadata: {
-                        toolCallId: toolCall.id,
-                        toolName: toolCall.name,
-                    },
-                });
-                runMessages.push(toolMessage);
-                messages.push(toolMessage.toChatMessage());
+                yield {
+                    type: 'agent:tool_call',
+                    runId: context.runId,
+                    timestamp: new Date(),
+                    agentName: context.agentName,
+                    sessionId: context.sessionId,
+                    toolCall,
+                };
+            }
+            const outcomes = await toolExecutor.executeMany(response.toolCalls);
+            appendToolOutcomeMessages(state, outcomes);
+            for (const outcome of outcomes) {
+                yield {
+                    type: 'agent:tool_result',
+                    runId: context.runId,
+                    timestamp: new Date(),
+                    agentName: context.agentName,
+                    sessionId: context.sessionId,
+                    toolResult: outcome,
+                };
+            }
+        }
+        if (this.onMaxIterations === 'throw') {
+            await context.history.addMany(state.runMessages);
+            throw maxIterationsError(this.maxIterations);
+        }
+        const response = yield* this.streamOneTurn(context, state, { includeTools: false });
+        mergeResponseIntoState(state, response);
+        yield await this.createEndEvent(context, state, response.content);
+    }
+    /**
+     * 执行一轮模型请求。模型支持流式时边流边发 text_delta 事件，
+     * 否则退化为一次非流式请求并整体发出。两种情况都返回聚合后的完整响应。
+     */
+    async *streamOneTurn(context, state, options) {
+        const request = (0, chat_request_builder_1.buildChatRequest)(context, state.chatMessages, options);
+        if (!context.llm.stream) {
+            const response = await context.llm.chat(request);
+            if (response.content.length > 0) {
+                yield this.createTextDeltaEvent(context, response.content, response.raw);
+            }
+            return response;
+        }
+        const accumulator = new llm_1.ChatStreamAccumulator();
+        for await (const chunk of context.llm.stream(request)) {
+            accumulator.add(chunk);
+            if (chunk.contentDelta !== undefined && chunk.contentDelta.length > 0) {
+                yield this.createTextDeltaEvent(context, chunk.contentDelta, chunk.raw);
             }
         }
-        throw new Error(`Tool calling exceeded max iterations: ${this.maxIterations}`);
+        return accumulator.toResponse();
     }
-}
-exports.ToolCallingExecutor = ToolCallingExecutor;
-async function buildInitialMessages(context, userMessage) {
-    const systemPrompt = context.options.systemPrompt ?? context.systemPrompt;
-    const history = await context.history.get();
-    return [
-        ...(systemPrompt ? [new messages_1.Message(systemPrompt, 'system').toChatMessage()] : []),
-        ...history.map((message) => message.toChatMessage()),
-        userMessage.toChatMessage(),
-    ];
-}
-function buildChatRequest(context, messages) {
-    const request = {
-        messages,
-        trace: {
+    createTextDeltaEvent(context, delta, raw) {
+        const event = {
+            type: 'agent:text_delta',
             runId: context.runId,
-            observer: context.observer,
+            timestamp: new Date(),
             agentName: context.agentName,
             sessionId: context.sessionId,
-        },
-    };
-    const model = context.options.model ?? context.config.defaultModel;
-    if (model) {
-        request.model = model;
-    }
-    request.temperature = context.options.temperature ?? context.config.temperature;
-    const maxTokens = context.options.maxTokens ?? context.config.maxTokens;
-    if (maxTokens !== undefined) {
-        request.maxTokens = maxTokens;
-    }
-    const tools = context.tools.toOpenAISchemas();
-    if (tools.length > 0) {
-        request.tools = tools;
-        request.toolChoice = 'auto';
+            delta,
+        };
+        if (raw !== undefined) {
+            event.raw = raw;
+        }
+        return event;
+    }
+    async createEndEvent(context, state, output) {
+        const assistantMessage = new messages_1.Message(output, 'assistant');
+        state.runMessages.push(assistantMessage);
+        await context.history.addMany(state.runMessages);
+        const event = {
+            type: 'agent:end',
+            runId: context.runId,
+            timestamp: new Date(),
+            agentName: context.agentName,
+            sessionId: context.sessionId,
+            output,
+            message: assistantMessage,
+        };
+        if (state.usage !== undefined) {
+            event.usage = state.usage;
+        }
+        if (state.raw !== undefined) {
+            event.raw = state.raw;
+        }
+        return event;
     }
-    if (context.options.signal) {
-        request.signal = context.options.signal;
+    async handleMaxIterations(context, state) {
+        if (this.onMaxIterations === 'throw') {
+            // 即使失败也要保留轨迹，否则重试时模型看不到已经发生过什么。
+            await context.history.addMany(state.runMessages);
+            throw maxIterationsError(this.maxIterations);
+        }
+        const response = await context.llm.chat((0, chat_request_builder_1.buildChatRequest)(context, state.chatMessages, { includeTools: false }));
+        mergeResponseIntoState(state, response);
+        return await finishRun(context, state, response.content);
     }
-    applyRuntimeOptions(context, request);
-    return request;
 }
-function applyRuntimeOptions(context, request) {
-    // 单次 run 的 options 优先级高于 Agent 的默认 config。
-    const timeoutMs = context.options.timeoutMs ?? context.config.requestTimeoutMs;
-    if (timeoutMs !== undefined) {
-        request.timeoutMs = timeoutMs;
-    }
-    const maxRetries = context.options.maxRetries ?? context.config.maxRetries;
-    if (maxRetries !== undefined) {
-        request.maxRetries = maxRetries;
+exports.ToolCallingExecutor = ToolCallingExecutor;
+function createToolExecutor(context) {
+    const toolExecutorOptions = {};
+    if (context.options.metadata !== undefined) {
+        toolExecutorOptions.metadata = context.options.metadata;
+    }
+    if (context.options.signal !== undefined) {
+        toolExecutorOptions.signal = context.options.signal;
+    }
+    return new tools_1.ToolExecutor(context.tools, {
+        runId: context.runId,
+        observer: context.observer,
+        agentName: context.agentName,
+        sessionId: context.sessionId,
+    }, toolExecutorOptions);
+}
+async function createRunState(context) {
+    const userMessage = new messages_1.Message(context.input, 'user', context.options.metadata ? { metadata: context.options.metadata } : {});
+    const history = await context.history.get();
+    return {
+        runMessages: [userMessage],
+        chatMessages: await (0, chat_request_builder_1.buildChatMessages)(context, [...history, userMessage]),
+        usage: undefined,
+        raw: undefined,
+    };
+}
+function mergeResponseIntoState(state, response) {
+    state.usage = mergeTokenUsage(state.usage, response.usage);
+    if (response.raw !== undefined) {
+        state.raw = response.raw;
     }
-    const retryDelayMs = context.options.retryDelayMs ?? context.config.retryDelayMs;
-    if (retryDelayMs !== undefined) {
-        request.retryDelayMs = retryDelayMs;
+}
+function appendAssistantToolCallMessage(state, response) {
+    const assistantMessage = new messages_1.Message(response.content, 'assistant', {
+        metadata: { toolCalls: response.toolCalls },
+    });
+    state.runMessages.push(assistantMessage);
+    state.chatMessages.push(assistantMessage.toChatMessage());
+}
+function appendToolOutcomeMessages(state, outcomes) {
+    for (const outcome of outcomes) {
+        const toolMessage = new messages_1.Message(outcome.content, 'tool', {
+            metadata: {
+                toolCallId: outcome.toolCallId,
+                toolName: outcome.toolName,
+                isError: outcome.isError,
+            },
+        });
+        state.runMessages.push(toolMessage);
+        state.chatMessages.push(toolMessage.toChatMessage());
     }
-    const retryMaxDelayMs = context.options.retryMaxDelayMs ?? context.config.retryMaxDelayMs;
-    if (retryMaxDelayMs !== undefined) {
-        request.retryMaxDelayMs = retryMaxDelayMs;
+}
+async function finishRun(context, state, output) {
+    state.runMessages.push(new messages_1.Message(output, 'assistant'));
+    await context.history.addMany(state.runMessages);
+    const result = {
+        output,
+        messages: await context.history.get(),
+        raw: state.raw,
+    };
+    if (state.usage !== undefined) {
+        result.usage = state.usage;
     }
+    return result;
+}
+function maxIterationsError(maxIterations) {
+    return new errors_1.AgentExecutionError(`Tool calling exceeded max iterations: ${maxIterations}.`, {
+        code: 'tool_calling_max_iterations',
+        metadata: {
+            maxIterations,
+        },
+    });
 }
 function mergeTokenUsage(current, next) {
     if (next === undefined) {
@@ -128,6 +222,7 @@ function mergeTokenUsage(current, next) {
     const promptTokens = addOptionalNumbers(current.promptTokens, next.promptTokens);
     const completionTokens = addOptionalNumbers(current.completionTokens, next.completionTokens);
     const totalTokens = addOptionalNumbers(current.totalTokens, next.totalTokens);
+    const cachedPromptTokens = addOptionalNumbers(current.cachedPromptTokens, next.cachedPromptTokens);
     if (promptTokens !== undefined) {
         merged.promptTokens = promptTokens;
     }
@@ -137,6 +232,9 @@ function mergeTokenUsage(current, next) {
     if (totalTokens !== undefined) {
         merged.totalTokens = totalTokens;
     }
+    if (cachedPromptTokens !== undefined) {
+        merged.cachedPromptTokens = cachedPromptTokens;
+    }
     return merged;
 }
 function addOptionalNumbers(left, right) {

package/dist/executors/tool-calling-executor.js.map

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

package/dist/history/base.d.ts

@@ -1,10 +1,53 @@
 import type { Message } from '../messages';
 export declare const DEFAULT_SESSION_ID = "default";
+export interface MessageHistoryGetOptions {
+    /**
+     * Return at most this many most-recent messages after applying other filters.
+     */
+    limit?: number;
+    /**
+     * Exclusive upper timestamp bound. Accepts an ISO timestamp string or Date.
+     */
+    before?: string | Date;
+}
+export interface MessageHistoryAddOptions {
+    /**
+     * 乐观并发（CAS）：调用方此前读到的版本号。
+     * 与存储中的实际版本不一致时抛 HistoryVersionConflictError，且不写入任何消息。
+     * 只有实现了 getVersion 的存储才支持该选项；不支持版本的旧实现会忽略它。
+     */
+    expectedVersion?: number;
+}
+/**
+ * 并发契约（使用说明）：
+ *
+ * - 进程内：Agent 的 session queue（src/agent/Agent.ts）已把同一会话的运行
+ *   串行化，单实例部署无需额外保护。
+ * - 多实例共享同一持久化后端时，进程内队列不再有效，写入方应使用
+ *   getVersion + expectedVersion 做 CAS 重试：
+ *
+ *       const version = (await history.getVersion?.()) ?? 0;
+ *       // ...基于当前历史构造要追加的消息...
+ *       try {
+ *           await history.addMany(messages, { expectedVersion: version });
+ *       } catch (error) {
+ *           if (error instanceof HistoryVersionConflictError) {
+ *               // 版本已过期：重新 getVersion/get 之后重试
+ *           }
+ *       }
+ *
+ * getVersion 与 expectedVersion 都是可选能力：只实现两参数 addMany 的旧实现
+ * 依旧满足本接口（方法参数是双变的），行为退化为无并发保护。
+ */
 export interface MessageHistory {
     add(message: Message): Promise<void>;
-    addMany(messages: Message[]): Promise<void>;
-    get(): Promise<Message[]>;
+    addMany(messages: Message[], options?: MessageHistoryAddOptions): Promise<void>;
+    get(options?: MessageHistoryGetOptions): Promise<Message[]>;
     clear(): Promise<void>;
+    /**
+     * 可选能力：当前会话版本号。0 表示尚无成功写入；每次成功写入 +1。
+     */
+    getVersion?(): Promise<number>;
 }
 export interface MessageHistoryStore {
     get(sessionId: string): MessageHistory;
@@ -13,4 +56,14 @@ export interface MessageHistoryStore {
     clearAll?(): Promise<void>;
 }
 export declare function normalizeSessionId(sessionId: string | undefined): string;
+export declare function applyMessageHistoryWindow(messages: readonly Message[], options?: MessageHistoryGetOptions): Message[];
+/**
+ * 校验并解析 get({ before }) 游标。
+ * 导出给 SQL 侧实现窗口语义的持久化存储复用，保证报错行为与内存实现一致。
+ */
+export declare function parseMessageHistoryBefore(before: string | Date): Date;
+/**
+ * 校验 get({ limit }) 参数，非法值抛 invalid_history_window。
+ */
+export declare function assertValidMessageHistoryLimit(limit: number): void;
 //# sourceMappingURL=base.d.ts.map

package/dist/history/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/history/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC3B,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAChC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC;IACvC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,aAAa,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGxE"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/history/base.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAG3C,eAAO,MAAM,kBAAkB,YAAY,CAAC;AAE5C,MAAM,WAAW,wBAAwB;IACrC;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,cAAc;IAC3B,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,GAAG,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;OAEG;IACH,UAAU,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAChC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAAC;IACvC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,aAAa,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGxE;AAED,wBAAgB,yBAAyB,CACrC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,OAAO,GAAE,wBAA6B,GACvC,OAAO,EAAE,CAiBX;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAarE;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CASlE"}

package/dist/history/base.js

@@ -2,9 +2,58 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SESSION_ID = void 0;
 exports.normalizeSessionId = normalizeSessionId;
+exports.applyMessageHistoryWindow = applyMessageHistoryWindow;
+exports.parseMessageHistoryBefore = parseMessageHistoryBefore;
+exports.assertValidMessageHistoryLimit = assertValidMessageHistoryLimit;
+const errors_1 = require("../errors");
+const tool_pairing_1 = require("./tool-pairing");
 exports.DEFAULT_SESSION_ID = 'default';
 function normalizeSessionId(sessionId) {
     const trimmedSessionId = sessionId?.trim();
     return trimmedSessionId ? trimmedSessionId : exports.DEFAULT_SESSION_ID;
 }
+function applyMessageHistoryWindow(messages, options = {}) {
+    let result = [...messages];
+    if (options.before !== undefined) {
+        const beforeMs = parseMessageHistoryBefore(options.before).getTime();
+        result = result.filter((message) => message.timestamp.getTime() < beforeMs);
+    }
+    if (options.limit !== undefined) {
+        assertValidMessageHistoryLimit(options.limit);
+        result = options.limit === 0 ? [] : result.slice(-options.limit);
+        // 切片可能砍在 assistant(toolCalls)/tool 配对中间，
+        // 与 addMany 溢出截断保持同一不变量。
+        (0, tool_pairing_1.repairLeadingToolContext)(result);
+    }
+    return result;
+}
+/**
+ * 校验并解析 get({ before }) 游标。
+ * 导出给 SQL 侧实现窗口语义的持久化存储复用，保证报错行为与内存实现一致。
+ */
+function parseMessageHistoryBefore(before) {
+    const date = before instanceof Date ? before : new Date(before);
+    if (Number.isNaN(date.getTime())) {
+        throw new errors_1.HistoryError('Message history before cursor must be a valid timestamp.', {
+            code: 'invalid_history_window',
+            metadata: {
+                field: 'before',
+            },
+        });
+    }
+    return date;
+}
+/**
+ * 校验 get({ limit }) 参数，非法值抛 invalid_history_window。
+ */
+function assertValidMessageHistoryLimit(limit) {
+    if (!Number.isInteger(limit) || limit < 0) {
+        throw new errors_1.HistoryError('Message history limit must be a non-negative integer.', {
+            code: 'invalid_history_window',
+            metadata: {
+                field: 'limit',
+            },
+        });
+    }
+}
 //# sourceMappingURL=base.js.map

package/dist/history/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/history/base.ts"],"names":[],"mappings":";;;AAkBA,gDAGC;AAnBY,QAAA,kBAAkB,GAAG,SAAS,CAAC;AAgB5C,SAAgB,kBAAkB,CAAC,SAA6B;IAC5D,MAAM,gBAAgB,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAC3C,OAAO,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,0BAAkB,CAAC;AACpE,CAAC"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/history/base.ts"],"names":[],"mappings":";;;AAiEA,gDAGC;AAED,8DAoBC;AAMD,8DAaC;AAKD,wEASC;AA3HD,sCAAyC;AAEzC,iDAA0D;AAE7C,QAAA,kBAAkB,GAAG,SAAS,CAAC;AA6D5C,SAAgB,kBAAkB,CAAC,SAA6B;IAC5D,MAAM,gBAAgB,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAC3C,OAAO,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,0BAAkB,CAAC;AACpE,CAAC;AAED,SAAgB,yBAAyB,CACrC,QAA4B,EAC5B,UAAoC,EAAE;IAEtC,IAAI,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAE3B,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,yBAAyB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QACrE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,8BAA8B,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,GAAG,OAAO,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACjE,yCAAyC;QACzC,yBAAyB;QACzB,IAAA,uCAAwB,EAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,SAAgB,yBAAyB,CAAC,MAAqB;IAC3D,MAAM,IAAI,GAAG,MAAM,YAAY,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhE,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,qBAAY,CAAC,0DAA0D,EAAE;YAC/E,IAAI,EAAE,wBAAwB;YAC9B,QAAQ,EAAE;gBACN,KAAK,EAAE,QAAQ;aAClB;SACJ,CAAC,CAAC;IACP,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAgB,8BAA8B,CAAC,KAAa;IACxD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,qBAAY,CAAC,uDAAuD,EAAE;YAC5E,IAAI,EAAE,wBAAwB;YAC9B,QAAQ,EAAE;gBACN,KAAK,EAAE,OAAO;aACjB;SACJ,CAAC,CAAC;IACP,CAAC;AACL,CAAC"}

package/dist/history/compression.d.ts

@@ -0,0 +1,49 @@
+import type { ChatModel } from '../llm/types';
+import { Message } from '../messages';
+export interface ContextCompressorInput {
+    /**
+     * 因超出 token 预算而被截掉的旧消息（保持原始时间正序）。
+     */
+    dropped: Message[];
+    /**
+     * 截断后保留的消息，供压缩策略参考上下文；实现不应修改它。
+     */
+    kept: Message[];
+    /**
+     * 当前 Agent 的模型。压缩直接复用它，不引入额外的模型依赖。
+     */
+    llm: ChatModel;
+    signal?: AbortSignal | undefined;
+}
+/**
+ * 可插拔的历史压缩策略：超预算时把被截断的旧消息换成更省 token 的
+ * 前缀消息（通常是一条带 metadata.compressed 标记的摘要），而不是
+ * 直接丢弃。返回 [] 表示放弃压缩，等价于纯截断。
+ * 返回的前缀不得以 tool 消息开头（调用方拼接后还会跑一次配对修复兜底）。
+ */
+export interface ContextCompressor {
+    compress(input: ContextCompressorInput): Promise<Message[]>;
+}
+export interface SummarizingContextCompressorOptions {
+    /**
+     * 摘要请求的 maxTokens 上限。摘要本身也占用输入预算，
+     * 所以默认给一个明显小于常见 maxInputTokens 的值。
+     */
+    maxSummaryTokens?: number;
+    /**
+     * 摘要指令（system prompt）。不提供时使用内置中文指令。
+     */
+    prompt?: string;
+}
+/**
+ * 用 LLM 把被截断的旧消息摘要成一条 user 消息。
+ * 设计约束：压缩是"尽力而为"的优化，llm 调用失败时必须降级为
+ * 纯截断（返回 []）而不是让主请求失败。
+ */
+export declare class SummarizingContextCompressor implements ContextCompressor {
+    private readonly maxSummaryTokens;
+    private readonly prompt;
+    constructor(options?: SummarizingContextCompressorOptions);
+    compress(input: ContextCompressorInput): Promise<Message[]>;
+}
+//# sourceMappingURL=compression.d.ts.map

package/dist/history/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/history/compression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAEH,OAAO,EACV,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB;;OAEG;IACH,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB;;OAEG;IACH,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,mCAAmC;IAChD;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;;GAIG;AACH,qBAAa,4BAA6B,YAAW,iBAAiB;IAClE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,GAAE,mCAAwC;IAKvD,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAmCpE"}

package/dist/history/compression.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SummarizingContextCompressor = void 0;
+const messages_1 = require("../messages");
+const DEFAULT_SUMMARY_PROMPT = '你是对话历史压缩器。请把下面被截断的早期对话压缩成一段简洁摘要，'
+    + '保留关键事实、结论、用户偏好和未完成的任务，不要添加评论或建议，直接输出摘要正文。';
+/**
+ * 用 LLM 把被截断的旧消息摘要成一条 user 消息。
+ * 设计约束：压缩是"尽力而为"的优化，llm 调用失败时必须降级为
+ * 纯截断（返回 []）而不是让主请求失败。
+ */
+class SummarizingContextCompressor {
+    maxSummaryTokens;
+    prompt;
+    constructor(options = {}) {
+        this.maxSummaryTokens = options.maxSummaryTokens ?? 512;
+        this.prompt = options.prompt ?? DEFAULT_SUMMARY_PROMPT;
+    }
+    async compress(input) {
+        if (input.dropped.length === 0) {
+            return [];
+        }
+        // 摘要输入用纯文本视图并标注角色，避免把 tool 配对结构带进请求。
+        const transcript = input.dropped
+            .map((message) => `[${message.role}] ${(0, messages_1.contentToText)(message.content)}`)
+            .join('\n');
+        try {
+            const response = await input.llm.chat({
+                messages: [
+                    new messages_1.Message(this.prompt, 'system').toChatMessage(),
+                    new messages_1.Message(transcript, 'user').toChatMessage(),
+                ],
+                maxTokens: this.maxSummaryTokens,
+                ...(input.signal !== undefined ? { signal: input.signal } : {}),
+            });
+            const summary = response.content.trim();
+            if (summary.length === 0) {
+                return [];
+            }
+            return [
+                new messages_1.Message(summary, 'user', {
+                    metadata: { compressed: true },
+                }),
+            ];
+        }
+        catch {
+            // 压缩失败不应影响主请求：降级为纯截断。
+            return [];
+        }
+    }
+}
+exports.SummarizingContextCompressor = SummarizingContextCompressor;
+//# sourceMappingURL=compression.js.map

package/dist/history/compression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../src/history/compression.ts"],"names":[],"mappings":";;;AACA,0CAGqB;AAwCrB,MAAM,sBAAsB,GAAG,kCAAkC;MAC3D,2CAA2C,CAAC;AAElD;;;;GAIG;AACH,MAAa,4BAA4B;IACpB,gBAAgB,CAAS;IACzB,MAAM,CAAS;IAEhC,YAAY,UAA+C,EAAE;QACzD,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,GAAG,CAAC;QACxD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,sBAAsB,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,KAA6B;QACxC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,CAAC;QACd,CAAC;QAED,qCAAqC;QACrC,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO;aAC3B,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,IAAA,wBAAa,EAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;aACvE,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhB,IAAI,CAAC;YACD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;gBAClC,QAAQ,EAAE;oBACN,IAAI,kBAAO,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,aAAa,EAAE;oBAClD,IAAI,kBAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,aAAa,EAAE;iBAClD;gBACD,SAAS,EAAE,IAAI,CAAC,gBAAgB;gBAChC,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClE,CAAC,CAAC;YAEH,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO,EAAE,CAAC;YACd,CAAC;YAED,OAAO;gBACH,IAAI,kBAAO,CAAC,OAAO,EAAE,MAAM,EAAE;oBACzB,QAAQ,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE;iBACjC,CAAC;aACL,CAAC;QACN,CAAC;QAAC,MAAM,CAAC;YACL,sBAAsB;YACtB,OAAO,EAAE,CAAC;QACd,CAAC;IACL,CAAC;CACJ;AA5CD,oEA4CC"}