minimal-agent 0.13.0 → 0.15.0

package/src/llm/providers/anthropicFormat.js

@@ -134,9 +134,11 @@ export function buildAnthropicUrl(provider) {
     return url;
 }
 export function buildAnthropicRequest(args) {
-    const { provider, cleanedMessages, tools } = args;
+    const { provider, cleanedMessages, tools, cacheEdits } = args;
     const { system, messages } = toAnthropicMessages(cleanedMessages);
     const anthropicTools = toAnthropicTools(tools);
+    if (cacheEdits)
+        applyCacheEdits(messages, cacheEdits);
     const body = {
         model: provider.model,
         ...(system ? { system } : {}),
@@ -160,6 +162,101 @@ export function buildAnthropicRequest(args) {
         body: JSON.stringify(body),
     };
 }
+// ==================== cache_edits 式回收（对齐 kakadeai Cached MC） ====================
+/**
+ * 把 cache_edits 回收决策落到请求体上（原地修改翻译后的 messages）。
+ *
+ * 处理顺序（顺序即正确性，调整会破坏协议约束）：
+ *   1. 最后一条消息的最后一个 block 打 cache_control 标记——这是 Anthropic 公开的
+ *      prompt caching 前提：没有缓存前缀，"在缓存内删除"无从谈起。
+ *   2. pinned 批次原位重发：服务端无状态，删除指令必须随每个请求重申；且必须
+ *      重发在**原 userMessageIndex**——cache_edits block 自身也是前缀的一部分，
+ *      挪位 = 前缀变化 = 它本要保护的缓存被它自己破坏。
+ *   3. pendingNew 作为新批次插入当前最后一条 user message，然后 pin 住该下标。
+ *   4. 给「严格早于 cache_control 标记消息」的 tool_result 加 cache_reference
+ *      （协议要求 cache_reference 出现在最后 cache_control 之前；用严格早于规避
+ *      cache_edits 插入改变 content 数组长度带来的下标边界问题）。
+ *
+ * 下标稳定性依赖：history append-only + toAnthropicMessages 纯函数。compact 后
+ * 必须 resetCacheEdits（loop.ts 已挂钩），否则 pin 的下标指向错误消息。
+ *
+ * dedup：同一 tool_use_id 全请求只允许出现一次删除指令（跨 pinned 批次去重）。
+ */
+function applyCacheEdits(messages, edits) {
+    if (messages.length === 0)
+        return;
+    // 1. 基础 prompt caching：最后一条消息的最后一个 block 打标记
+    const lastMsg = messages[messages.length - 1];
+    if (lastMsg.content.length > 0) {
+        const lastBlock = lastMsg.content[lastMsg.content.length - 1];
+        lastBlock.cache_control = { type: 'ephemeral' };
+    }
+    // 跨批次去重集：同一 cache_reference 不重复删
+    const seenDeleteRefs = new Set();
+    // wire 形状：整个 {type:'cache_edits', edits:[...]} 作为 user message 里的一个
+    // content block 追加（对齐 kakadeai addCacheBreakpoints 的 insertBlockAfterToolResults）。
+    const appendEditsBlock = (msg, toolUseIds) => {
+        msg.content.push({
+            type: 'cache_edits',
+            edits: toolUseIds.map((id) => ({ type: 'delete', cache_reference: id })),
+        });
+    };
+    const dedupe = (ids) => {
+        const unique = [];
+        for (const id of ids) {
+            if (seenDeleteRefs.has(id))
+                continue;
+            seenDeleteRefs.add(id);
+            unique.push(id);
+        }
+        return unique;
+    };
+    // 2. pinned 批次原位重发
+    for (const pinned of edits.pinned) {
+        const msg = messages[pinned.userMessageIndex];
+        if (!msg || msg.role !== 'user')
+            continue; // 下标失位（compact 后未 reset）→ 跳过该批，fail-safe
+        const unique = dedupe(pinned.toolUseIds);
+        if (unique.length > 0)
+            appendEditsBlock(msg, unique);
+    }
+    // 3. pendingNew：插入当前最后一条 user message 并 pin
+    if (edits.pendingNew.length > 0) {
+        const unique = dedupe(edits.pendingNew);
+        if (unique.length > 0) {
+            for (let i = messages.length - 1; i >= 0; i--) {
+                if (messages[i].role !== 'user')
+                    continue;
+                appendEditsBlock(messages[i], unique);
+                edits.pinned.push({ userMessageIndex: i, toolUseIds: unique });
+                break;
+            }
+        }
+        edits.pendingNew.length = 0; // 已消费（无论是否成功插入，都清空防止下轮重复插入）
+    }
+    // 4. cache_reference 标注：找最后含 cache_control 的消息，给它**严格之前**的 tool_result 加引用
+    let lastCCMsgIndex = -1;
+    for (let i = 0; i < messages.length; i++) {
+        for (const block of messages[i].content) {
+            if (block && typeof block === 'object' && 'cache_control' in block) {
+                lastCCMsgIndex = i;
+                break;
+            }
+        }
+    }
+    if (lastCCMsgIndex < 0)
+        return;
+    for (let i = 0; i < lastCCMsgIndex; i++) {
+        const msg = messages[i];
+        if (msg.role !== 'user')
+            continue;
+        for (const block of msg.content) {
+            if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+                block.cache_reference = block.tool_use_id;
+            }
+        }
+    }
+}
 /**
  * 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。
  *
@@ -171,6 +268,7 @@ export function buildAnthropicRequest(args) {
 export function createAnthropicSSEParser() {
     let stopReason = 'unknown';
     let usagePromptTokens;
+    let usageOutputTokens;
     let usageCachedTokens;
     let usageCacheWriteTokens;
     let promptCacheUsage = { reported: false };
@@ -178,6 +276,7 @@ export function createAnthropicSSEParser() {
         type: 'done',
         stopReason,
         promptTokens: usagePromptTokens,
+        outputTokens: usageOutputTokens,
         ...(promptCacheUsage.reported
             ? {
                 ...(usageCachedTokens !== undefined ? { cachedPromptTokens: usageCachedTokens } : {}),
@@ -250,6 +349,14 @@ export function createAnthropicSSEParser() {
                     return [];
                 }
                 case 'message_delta': {
+                    // 输出侧计量：Anthropic 把 output_tokens 放在 message_delta 的**顶层 usage** 下
+                    // （不在 delta 里），且给的是**到目前为止的累计值** —— 直接覆盖即可，不要累加。
+                    // 与 input_tokens 不同：那个要把缓存三段相加（见 message_start 分支）。
+                    // ⚠️ 非有限值/负数一律当「没报」，绝不退化成 0（0 会让预算闸永不触发）。
+                    const out = data.usage?.output_tokens;
+                    if (typeof out === 'number' && Number.isFinite(out) && out >= 0) {
+                        usageOutputTokens = out;
+                    }
                     // ⚠️ stop_reason 嵌套在 delta.stop_reason 下，不是 message_delta 顶层。
                     const sr = data.delta?.stop_reason;
                     if (sr === 'end_turn' || sr === 'stop_sequence')

package/src/llm/providers/anthropicFormat.ts

@@ -19,7 +19,7 @@
  * ============================================================
  */
 
-import type { ChatContentPart, LlmStreamEvent, Message, PromptCacheUsage, Provider, Tool } from '../../types.js';
+import type { CacheEditsState, ChatContentPart, LlmStreamEvent, LocalProvider, Message, PromptCacheUsage, Tool } from '../../types.js';
 
 const ANTHROPIC_VERSION = '2023-06-01';
 
@@ -128,7 +128,7 @@ function looksLikeVersionedBase(url: string): boolean {
   }
 }
 
-export function buildAnthropicUrl(provider: Provider): string {
+export function buildAnthropicUrl(provider: LocalProvider): string {
   // baseURL 是完整端点 URL（以 /v1/messages 结尾）。
   // 向后兼容：旧格式 baseURL（根域名或版本化基础路径）自动补全 /v1/messages 后缀。
   const url = provider.baseURL.trim().replace(/\/+$/, '');
@@ -145,15 +145,21 @@ export function buildAnthropicUrl(provider: Provider): string {
 }
 
 export interface AnthropicRequestArgs {
-  provider: Provider;
+  provider: LocalProvider;
   cleanedMessages: readonly Message[];
   tools: Tool[];
+  /**
+   * cache_edits 回收状态（provider.cacheEdits 开启时由 loop 传入）。
+   * 传入即进入协议组装：pinned 重发 + pendingNew 发送并 pin + cache_reference 标注。
+   */
+  cacheEdits?: CacheEditsState;
 }
 
 export function buildAnthropicRequest(args: AnthropicRequestArgs): { url: string; headers: Record<string, string>; body: string } {
-  const { provider, cleanedMessages, tools } = args;
+  const { provider, cleanedMessages, tools, cacheEdits } = args;
   const { system, messages } = toAnthropicMessages(cleanedMessages);
   const anthropicTools = toAnthropicTools(tools);
+  if (cacheEdits) applyCacheEdits(messages, cacheEdits);
   const body: Record<string, unknown> = {
     model: provider.model,
     ...(system ? { system } : {}),
@@ -177,6 +183,101 @@ export function buildAnthropicRequest(args: AnthropicRequestArgs): { url: string
   };
 }
 
+// ==================== cache_edits 式回收（对齐 kakadeai Cached MC） ====================
+
+/**
+ * 把 cache_edits 回收决策落到请求体上（原地修改翻译后的 messages）。
+ *
+ * 处理顺序（顺序即正确性，调整会破坏协议约束）：
+ *   1. 最后一条消息的最后一个 block 打 cache_control 标记——这是 Anthropic 公开的
+ *      prompt caching 前提：没有缓存前缀，"在缓存内删除"无从谈起。
+ *   2. pinned 批次原位重发：服务端无状态，删除指令必须随每个请求重申；且必须
+ *      重发在**原 userMessageIndex**——cache_edits block 自身也是前缀的一部分，
+ *      挪位 = 前缀变化 = 它本要保护的缓存被它自己破坏。
+ *   3. pendingNew 作为新批次插入当前最后一条 user message，然后 pin 住该下标。
+ *   4. 给「严格早于 cache_control 标记消息」的 tool_result 加 cache_reference
+ *      （协议要求 cache_reference 出现在最后 cache_control 之前；用严格早于规避
+ *      cache_edits 插入改变 content 数组长度带来的下标边界问题）。
+ *
+ * 下标稳定性依赖：history append-only + toAnthropicMessages 纯函数。compact 后
+ * 必须 resetCacheEdits（loop.ts 已挂钩），否则 pin 的下标指向错误消息。
+ *
+ * dedup：同一 tool_use_id 全请求只允许出现一次删除指令（跨 pinned 批次去重）。
+ */
+function applyCacheEdits(messages: AnthropicMessage[], edits: CacheEditsState): void {
+  if (messages.length === 0) return;
+
+  // 1. 基础 prompt caching：最后一条消息的最后一个 block 打标记
+  const lastMsg = messages[messages.length - 1];
+  if (lastMsg.content.length > 0) {
+    const lastBlock = lastMsg.content[lastMsg.content.length - 1] as Record<string, unknown>;
+    lastBlock.cache_control = { type: 'ephemeral' };
+  }
+
+  // 跨批次去重集：同一 cache_reference 不重复删
+  const seenDeleteRefs = new Set<string>();
+  // wire 形状：整个 {type:'cache_edits', edits:[...]} 作为 user message 里的一个
+  // content block 追加（对齐 kakadeai addCacheBreakpoints 的 insertBlockAfterToolResults）。
+  const appendEditsBlock = (msg: AnthropicMessage, toolUseIds: string[]): void => {
+    msg.content.push({
+      type: 'cache_edits',
+      edits: toolUseIds.map((id) => ({ type: 'delete', cache_reference: id })),
+    });
+  };
+  const dedupe = (ids: string[]): string[] => {
+    const unique: string[] = [];
+    for (const id of ids) {
+      if (seenDeleteRefs.has(id)) continue;
+      seenDeleteRefs.add(id);
+      unique.push(id);
+    }
+    return unique;
+  };
+
+  // 2. pinned 批次原位重发
+  for (const pinned of edits.pinned) {
+    const msg = messages[pinned.userMessageIndex];
+    if (!msg || msg.role !== 'user') continue; // 下标失位（compact 后未 reset）→ 跳过该批，fail-safe
+    const unique = dedupe(pinned.toolUseIds);
+    if (unique.length > 0) appendEditsBlock(msg, unique);
+  }
+
+  // 3. pendingNew：插入当前最后一条 user message 并 pin
+  if (edits.pendingNew.length > 0) {
+    const unique = dedupe(edits.pendingNew);
+    if (unique.length > 0) {
+      for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role !== 'user') continue;
+        appendEditsBlock(messages[i], unique);
+        edits.pinned.push({ userMessageIndex: i, toolUseIds: unique });
+        break;
+      }
+    }
+    edits.pendingNew.length = 0; // 已消费（无论是否成功插入，都清空防止下轮重复插入）
+  }
+
+  // 4. cache_reference 标注：找最后含 cache_control 的消息，给它**严格之前**的 tool_result 加引用
+  let lastCCMsgIndex = -1;
+  for (let i = 0; i < messages.length; i++) {
+    for (const block of messages[i].content) {
+      if (block && typeof block === 'object' && 'cache_control' in block) {
+        lastCCMsgIndex = i;
+        break;
+      }
+    }
+  }
+  if (lastCCMsgIndex < 0) return;
+  for (let i = 0; i < lastCCMsgIndex; i++) {
+    const msg = messages[i];
+    if (msg.role !== 'user') continue;
+    for (const block of msg.content) {
+      if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+        block.cache_reference = block.tool_use_id;
+      }
+    }
+  }
+}
+
 /**
  * 每个请求一个新实例；把逐条 SSE `data:` 行的内容转换成 LlmStreamEvent（0..N 个）。
  *
@@ -192,6 +293,7 @@ export function createAnthropicSSEParser(): {
 } {
   let stopReason: 'stop' | 'tool_calls' | 'length' | 'unknown' = 'unknown';
   let usagePromptTokens: number | undefined;
+  let usageOutputTokens: number | undefined;
   let usageCachedTokens: number | undefined;
   let usageCacheWriteTokens: number | undefined;
   let promptCacheUsage: PromptCacheUsage = { reported: false };
@@ -199,6 +301,7 @@ export function createAnthropicSSEParser(): {
     type: 'done',
     stopReason,
     promptTokens: usagePromptTokens,
+    outputTokens: usageOutputTokens,
     ...(promptCacheUsage.reported
       ? {
           ...(usageCachedTokens !== undefined ? { cachedPromptTokens: usageCachedTokens } : {}),
@@ -267,6 +370,14 @@ export function createAnthropicSSEParser(): {
           return [];
         }
         case 'message_delta': {
+          // 输出侧计量：Anthropic 把 output_tokens 放在 message_delta 的**顶层 usage** 下
+          // （不在 delta 里），且给的是**到目前为止的累计值** —— 直接覆盖即可，不要累加。
+          // 与 input_tokens 不同：那个要把缓存三段相加（见 message_start 分支）。
+          // ⚠️ 非有限值/负数一律当「没报」，绝不退化成 0（0 会让预算闸永不触发）。
+          const out = data.usage?.output_tokens;
+          if (typeof out === 'number' && Number.isFinite(out) && out >= 0) {
+            usageOutputTokens = out;
+          }
           // ⚠️ stop_reason 嵌套在 delta.stop_reason 下，不是 message_delta 顶层。
           const sr = data.delta?.stop_reason;
           if (sr === 'end_turn' || sr === 'stop_sequence') stopReason = 'stop';

package/src/llm/providers/openaiFormat.js

@@ -280,6 +280,7 @@ export function extractCachedPromptTokens(usage) {
 export function createOpenAISSEParser() {
     let stopReason = 'unknown';
     let usagePromptTokens;
+    let usageOutputTokens;
     let usageCachedTokens;
     let usageCacheMissTokens;
     let promptCacheUsage = { reported: false };
@@ -289,6 +290,7 @@ export function createOpenAISSEParser() {
                 type: 'done',
                 stopReason,
                 promptTokens: usagePromptTokens,
+                outputTokens: usageOutputTokens,
                 cachedPromptTokens: usageCachedTokens,
                 cacheMissTokens: usageCacheMissTokens,
                 promptCacheUsage,
@@ -300,6 +302,7 @@ export function createOpenAISSEParser() {
                         type: 'done',
                         stopReason,
                         promptTokens: usagePromptTokens,
+                        outputTokens: usageOutputTokens,
                         cachedPromptTokens: usageCachedTokens,
                         cacheMissTokens: usageCacheMissTokens,
                         promptCacheUsage,
@@ -326,6 +329,12 @@ export function createOpenAISSEParser() {
                     usageCachedTokens = cacheUsage.cacheReadTokens;
                 if (cacheUsage.cacheMissTokens !== undefined)
                     usageCacheMissTokens = cacheUsage.cacheMissTokens;
+                // 输出侧计量。⚠️ 非有限值/负数一律当「没报」，不能退化成 0 ——
+                // 0 会被预算刻度读成「这轮没花钱」，预算闸从此永不触发。
+                const completion = chunk.usage.completion_tokens;
+                if (typeof completion === 'number' && Number.isFinite(completion) && completion >= 0) {
+                    usageOutputTokens = completion;
+                }
             }
             const delta = chunk.choices?.[0]?.delta;
             const finish = chunk.choices?.[0]?.finish_reason;

package/src/llm/providers/openaiFormat.ts

@@ -12,7 +12,7 @@ import type {
   Message,
   PromptCacheContext,
   PromptCacheUsage,
-  Provider,
+  LocalProvider,
   Tool,
 } from '../../types.js';
 
@@ -112,7 +112,7 @@ export function isPromptCacheKeyRejected(status: number, errText: string): boole
 }
 
 export interface OpenAIRequestArgs {
-  provider: Provider;
+  provider: LocalProvider;
   cleanedMessages: unknown[];
   tools: Tool[];
   withResponseFormat: boolean;
@@ -211,7 +211,7 @@ function looksLikeVersionedBase(url: string): boolean {
   }
 }
 
-export function buildOpenAIUrl(provider: Provider): string {
+export function buildOpenAIUrl(provider: LocalProvider): string {
   // baseURL 是完整端点 URL（以 /chat/completions 结尾）。
   // 向后兼容：旧格式 baseURL（版本化基础路径，如 /v1）自动补全后缀，并打 warning。
   const url = provider.baseURL.trim().replace(/\/+$/, '');
@@ -344,6 +344,7 @@ export function createOpenAISSEParser(): {
 } {
   let stopReason: 'stop' | 'tool_calls' | 'length' | 'unknown' = 'unknown';
   let usagePromptTokens: number | undefined;
+  let usageOutputTokens: number | undefined;
   let usageCachedTokens: number | undefined;
   let usageCacheMissTokens: number | undefined;
   let promptCacheUsage: PromptCacheUsage = { reported: false };
@@ -353,6 +354,7 @@ export function createOpenAISSEParser(): {
         type: 'done',
         stopReason,
         promptTokens: usagePromptTokens,
+        outputTokens: usageOutputTokens,
         cachedPromptTokens: usageCachedTokens,
         cacheMissTokens: usageCacheMissTokens,
         promptCacheUsage,
@@ -364,6 +366,7 @@ export function createOpenAISSEParser(): {
           type: 'done',
           stopReason,
           promptTokens: usagePromptTokens,
+          outputTokens: usageOutputTokens,
           cachedPromptTokens: usageCachedTokens,
           cacheMissTokens: usageCacheMissTokens,
           promptCacheUsage,
@@ -386,6 +389,12 @@ export function createOpenAISSEParser(): {
         if (cacheUsage.promptTokens !== undefined) usagePromptTokens = cacheUsage.promptTokens;
         if (cacheUsage.cacheReadTokens !== undefined) usageCachedTokens = cacheUsage.cacheReadTokens;
         if (cacheUsage.cacheMissTokens !== undefined) usageCacheMissTokens = cacheUsage.cacheMissTokens;
+        // 输出侧计量。⚠️ 非有限值/负数一律当「没报」，不能退化成 0 ——
+        // 0 会被预算刻度读成「这轮没花钱」，预算闸从此永不触发。
+        const completion = (chunk.usage as Record<string, unknown>).completion_tokens;
+        if (typeof completion === 'number' && Number.isFinite(completion) && completion >= 0) {
+          usageOutputTokens = completion;
+        }
       }
       const delta = chunk.choices?.[0]?.delta;
       const finish = chunk.choices?.[0]?.finish_reason;