minimal-agent 0.12.0 → 0.14.0

package/src/llm/gatewayClient.ts

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import type { ConversationMode } from '../runtime/agentRuntimeContext.js';
+import { onlineToolCategory } from '../team/toolPolicy.js';
+import type {
+  GatewayProvider,
+  LlmStreamEvent,
+  Message,
+  Tool,
+} from '../types.js';
+import { prepareMessagesForProvider } from './messageProvenance.js';
+
+const IDLE_TIMEOUT_MS =
+  Number(process.env.MINIMAL_AGENT_GATEWAY_IDLE_TIMEOUT_MS) > 0
+    ? Number(process.env.MINIMAL_AGENT_GATEWAY_IDLE_TIMEOUT_MS)
+    : 120_000;
+const DEADLINE_MS =
+  Number(process.env.MINIMAL_AGENT_GATEWAY_DEADLINE_MS) > 0
+    ? Number(process.env.MINIMAL_AGENT_GATEWAY_DEADLINE_MS)
+    : 15 * 60_000;
+
+function gatewayTools(
+  tools: Tool[],
+  allowedCategories?: readonly string[],
+): Array<{
+  type: 'function';
+  category: NonNullable<ReturnType<typeof onlineToolCategory>>;
+  function: {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+  };
+}> {
+  const allowed = allowedCategories ? new Set(allowedCategories) : null;
+  return tools.flatMap((tool) => {
+    const category = onlineToolCategory(tool.name);
+    if (!category || (allowed && !allowed.has(category))) return [];
+    return [
+      {
+        type: 'function' as const,
+        category,
+        function: {
+          name: tool.name,
+          ...(typeof tool.description === 'string'
+            ? { description: tool.description }
+            : {}),
+          parameters: tool.parameters as Record<string, unknown>,
+        },
+      },
+    ];
+  });
+}
+
+function safeMessages(messages: Message[]): unknown[] {
+  return messages.map((message) => {
+    const {
+      id: _id,
+      timestamp: _timestamp,
+      attachments: _attachments,
+      browserReferences: _browserReferences,
+      provenance: _provenance,
+      display_metadata: _displayMetadata,
+      tool_result_policy: _toolResultPolicy,
+      _ephemeral,
+      ...safe
+    } = message as Message & Record<string, unknown>;
+    return safe;
+  });
+}
+
+type GatewayEvent = {
+  type?: string;
+  code?: string;
+  retryable?: boolean;
+  message?: string;
+};
+
+export class GatewayClientError extends Error {
+  constructor(
+    public readonly code: string,
+    public readonly retryable: boolean,
+    message: string,
+  ) {
+    // ⚠️ code 必须烘进 message 文本，不能只存在 .code 属性上：这个错误穿过
+    // loop.ts（只取 `.message`）→ 引擎 runner（转成纯字符串 blocker）→
+    // workflowController 的 isUsageLimitError 文本兜底，每一层都只剩字符串。
+    // 不烘进去，`isUsageLimitError` 的「同时认 code 与文本」这句注释就是一句空话——
+    // 之前正是这样：message 是纯人话（如「设备授权不存在或已过期」），从不包含
+    // DEVICE_REVOKED 之类的码，文本兜底恒为 false，usage_limited 在真实调用链上
+    // 从未被触发过。
+    super(`[${code}] ${message}`);
+    this.name = 'GatewayClientError';
+  }
+}
+
+/**
+ * 服务端「配额/授权不给了」的错误码 —— **唯一真值**。
+ *
+ * 与 Goal 的 `usage_limited` 状态一一对应，也正是它与 `budget_limited` 的分界：
+ *  · `budget_limited` = **用户自己设的** token 额度用完 → 加预算即可继续。
+ *  · `usage_limited`  = **服务端配额/授权**不给了 → 加预算没用，要去解决授权或等周期重置。
+ * 两者都可 resume，但恢复动作完全不同，所以不能合并成一个状态。
+ *
+ * 服务端侧的产出点：`minimal-server/src/core/gatewayInference.ts`。
+ */
+const USAGE_LIMIT_CODES = new Set([
+  'REQUEST_QUOTA_EXHAUSTED',
+  'TOKEN_QUOTA_EXHAUSTED',
+  'CONCURRENCY_EXCEEDED',
+  'GRANT_REVOKED',
+  'DEVICE_REVOKED',
+]);
+
+/**
+ * 判断一个错误是不是「服务端配额/授权不给了」。
+ *
+ * ⚠️ 同时认 `GatewayClientError.code` 与错误文本：错误穿过 loop → 引擎 → 工作流
+ * 这几层之后往往只剩一个字符串（`llm_error` 事件带的是 message），
+ * 只认 code 会在真实链路上恒为 false。
+ */
+export function isUsageLimitError(error: unknown): boolean {
+  if (error instanceof GatewayClientError)
+    return USAGE_LIMIT_CODES.has(error.code);
+  const text = error instanceof Error ? error.message : String(error ?? '');
+  return [...USAGE_LIMIT_CODES].some((code) => text.includes(code));
+}
+
+function combinedSignal(signal?: AbortSignal): AbortSignal {
+  const timeout = AbortSignal.timeout(DEADLINE_MS);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+async function readWithIdleTimeout<T>(
+  promise: Promise<T>,
+  signal: AbortSignal,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_, reject) => {
+        timer = setTimeout(
+          () =>
+            reject(
+              new GatewayClientError(
+                'PROVIDER_TIMEOUT',
+                true,
+                '在线模型流式响应超时',
+              ),
+            ),
+          IDLE_TIMEOUT_MS,
+        );
+        onAbort = () => reject(new DOMException('aborted', 'AbortError'));
+        signal.addEventListener('abort', onAbort, { once: true });
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (onAbort) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+/** Gateway transport only. The caller retains the existing Agent/tool loop. */
+export async function* chatGateway(args: {
+  provider: GatewayProvider;
+  messages: Message[];
+  tools: Tool[];
+  signal?: AbortSignal;
+  conversationMode?: ConversationMode;
+  responseFormat?: {
+    type: 'json_schema';
+    json_schema: {
+      name: string;
+      schema: Record<string, unknown>;
+      strict?: boolean;
+    };
+  };
+}): AsyncGenerator<LlmStreamEvent> {
+  const {
+    provider,
+    messages,
+    tools,
+    signal: parentSignal,
+    conversationMode,
+    responseFormat,
+  } = args;
+  if (!provider.gatewayUrl || !provider.gatewayToken || !provider.remoteModelId)
+    throw new GatewayClientError(
+      'DEVICE_REVOKED',
+      false,
+      '在线模型设备授权不存在或已过期',
+    );
+  const url = `${provider.gatewayUrl.replace(/\/$/, '')}/api/inference/chat/stream`;
+  const payload = JSON.stringify({
+    requestId: randomUUID(),
+    modelId: provider.remoteModelId,
+    // Keep the gateway payload limited to provider-facing protocol content.
+    // Session IDs, provenance metadata, display metadata, and local-only
+    // fields must never cross the remote inference boundary.
+    messages: safeMessages(
+      prepareMessagesForProvider(messages, conversationMode ?? 'private'),
+    ),
+    tools: gatewayTools(
+      tools,
+      provider.gatewayToolCategories ??
+        provider.gatewayDefaultToolCategories ??
+        provider.gatewayMaxToolCategories,
+    ),
+    toolCategories:
+      provider.gatewayToolCategories ?? provider.gatewayMaxToolCategories ?? [],
+    ...(responseFormat ? { responseFormat } : {}),
+  });
+  let activeReader: { cancel(): Promise<void> } | undefined;
+  const signal = combinedSignal(parentSignal);
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      signal,
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${provider.gatewayToken}`,
+      },
+      body: payload,
+    });
+    if (!response.ok) {
+      const body = (await response.json().catch(() => ({}))) as {
+        error?: string;
+        code?: string;
+        retryable?: boolean;
+      };
+      // ⚠️ 服务端**明确表态**优先，状态码只是它没表态时的推断。
+      // 曾经写成 `body.retryable === true || status === 429 || …`：服务端发
+      // `{code:'TOKEN_QUOTA_EXHAUSTED', retryable:false}` 配 HTTP 429 时，
+      // `retryable:false` 被 `|| 429` 直接覆盖 —— 于是「额度用完了，别重试」
+      // 被当成限流反复重试，既拖慢失败反馈，也把真正的原因埋掉。
+      // 配额耗尽与限流是两回事：前者要去加额度，后者等一会儿就好。
+      const retryable =
+        typeof body.retryable === 'boolean'
+          ? body.retryable
+          : response.status === 408 ||
+            response.status === 425 ||
+            response.status === 429 ||
+            response.status >= 500;
+      throw new GatewayClientError(
+        body.code ?? `HTTP_${response.status}`,
+        retryable,
+        body.error ?? `在线模型请求失败（${response.status}）`,
+      );
+    }
+    if (!response.body)
+      throw new GatewayClientError(
+        'PROVIDER_UNAVAILABLE',
+        true,
+        '在线模型未返回流式响应',
+      );
+    const reader = response.body.getReader();
+    activeReader = reader;
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const next = await readWithIdleTimeout(reader.read(), signal);
+      if (next.done) break;
+      buffer += decoder.decode(next.value, { stream: true });
+      const frames = buffer.split(/\n\n/);
+      buffer = frames.pop() ?? '';
+      for (const frame of frames) {
+        const line = frame
+          .split(/\r?\n/)
+          .find((item) => item.startsWith('data:'));
+        if (!line) continue;
+        let event: GatewayEvent;
+        try {
+          event = JSON.parse(line.slice(5).trim());
+        } catch {
+          continue;
+        }
+        if (event.type === 'error')
+          throw new GatewayClientError(
+            event.code ?? 'PROVIDER_UNAVAILABLE',
+            event.retryable === true,
+            event.message ?? '在线模型流式调用失败',
+          );
+        if (event.type === 'usage') {
+          yield event as LlmStreamEvent;
+          continue;
+        }
+        if (event.type === 'done') return;
+        yield event as LlmStreamEvent;
+      }
+    }
+    return;
+  } finally {
+    // Release the response body on both normal `done` and error/abort paths.
+    // Without this, a completed stream can keep an HTTP connection/socket
+    // alive until the runtime's garbage collector notices it.
+    await activeReader?.cancel().catch(() => {});
+    activeReader = undefined;
+  }
+}

package/src/llm/messageProvenance.js

@@ -0,0 +1,46 @@
+function provenanceLabel(provenance) {
+    if (provenance.mode === 'private') {
+        return '[历史来源：主人私聊，仅限内部使用；群聊中不得复述或公开]';
+    }
+    const fields = [
+        '历史来源：群聊公开消息',
+        provenance.groupId ? `群=${provenance.groupId}` : '',
+        provenance.senderName ? `发送者=${provenance.senderName}` : '',
+        provenance.senderId ? `发送者ID=${provenance.senderId}` : '',
+        provenance.taskId ? `父任务=${provenance.taskId}` : '',
+    ].filter(Boolean);
+    return `[${fields.join('；')}]`;
+}
+function decorateContent(content, provenance) {
+    if (!provenance || content === null)
+        return content;
+    const label = provenanceLabel(provenance);
+    if (typeof content === 'string')
+        return `${label}\n${content}`;
+    const firstText = content.findIndex((part) => part.type === 'text');
+    if (firstText < 0)
+        return [{ type: 'text', text: label }, ...content];
+    return content.map((part, index) => index === firstText && part.type === 'text'
+        ? { ...part, text: `${label}\n${part.text}` }
+        : part);
+}
+/** Clone messages for a provider request without leaking local UI/provenance fields. */
+export function prepareMessagesForProvider(messages, conversationMode = 'private') {
+    return messages
+        .filter((message) => !(message.role === 'system' && message._ephemeral === true))
+        .map((message) => {
+        const { id, timestamp, attachments, browserReferences, display_metadata, tool_result_policy, provenance, ...rest } = message;
+        if (rest.role === 'user' || rest.role === 'assistant') {
+            // 旧 Session 在引入 provenance 之前没有来源元数据。进入群聊时必须保守地
+            // 把这些历史当作主人私聊，而不是让模型误以为它们已经公开。
+            const effectiveProvenance = provenance ?? (conversationMode === 'group'
+                ? { mode: 'private', visibility: 'owner-private' }
+                : undefined);
+            return {
+                ...rest,
+                content: decorateContent(rest.content, effectiveProvenance),
+            };
+        }
+        return rest;
+    });
+}

package/src/llm/messageProvenance.ts

@@ -0,0 +1,58 @@
+import type { ChatContentPart, ConversationProvenance, Message } from '../types.js';
+
+function provenanceLabel(provenance: ConversationProvenance): string {
+  if (provenance.mode === 'private') {
+    return '[历史来源：主人私聊，仅限内部使用；群聊中不得复述或公开]';
+  }
+  const fields = [
+    '历史来源：群聊公开消息',
+    provenance.groupId ? `群=${provenance.groupId}` : '',
+    provenance.senderName ? `发送者=${provenance.senderName}` : '',
+    provenance.senderId ? `发送者ID=${provenance.senderId}` : '',
+    provenance.taskId ? `父任务=${provenance.taskId}` : '',
+  ].filter(Boolean);
+  return `[${fields.join('；')}]`;
+}
+
+function decorateContent(
+  content: string | ChatContentPart[] | null,
+  provenance: ConversationProvenance | undefined,
+): string | ChatContentPart[] | null {
+  if (!provenance || content === null) return content;
+  const label = provenanceLabel(provenance);
+  if (typeof content === 'string') return `${label}\n${content}`;
+  const firstText = content.findIndex((part) => part.type === 'text');
+  if (firstText < 0) return [{ type: 'text', text: label }, ...content];
+  return content.map((part, index) => index === firstText && part.type === 'text'
+    ? { ...part, text: `${label}\n${part.text}` }
+    : part);
+}
+
+/** Clone messages for a provider request without leaking local UI/provenance fields. */
+export function prepareMessagesForProvider(
+  messages: readonly Message[],
+  conversationMode: 'private' | 'group' = 'private',
+): Message[] {
+  return messages
+    .filter((message) => !(message.role === 'system' && message._ephemeral === true))
+    .map((message) => {
+      const {
+        id, timestamp, attachments, browserReferences, display_metadata, tool_result_policy, provenance, ...rest
+      } = message as Message & Record<string, unknown>;
+      if (rest.role === 'user' || rest.role === 'assistant') {
+        // 旧 Session 在引入 provenance 之前没有来源元数据。进入群聊时必须保守地
+        // 把这些历史当作主人私聊，而不是让模型误以为它们已经公开。
+        const effectiveProvenance = provenance ?? (conversationMode === 'group'
+          ? { mode: 'private' as const, visibility: 'owner-private' as const }
+          : undefined);
+        return {
+          ...rest,
+          content: decorateContent(
+            rest.content as string | ChatContentPart[] | null,
+            effectiveProvenance,
+          ),
+        } as Message;
+      }
+      return rest as Message;
+    });
+}

package/src/llm/modelProvider.js

@@ -0,0 +1 @@
+export {};

package/src/llm/modelProvider.ts

@@ -0,0 +1,22 @@
+import type { ConversationMode } from '../runtime/agentRuntimeContext.js';
+import type { CacheEditsState, LlmStreamEvent, Message, Provider, PromptCacheContext, Tool } from '../types.js';
+
+export interface NormalizedModelRequest {
+  provider: Provider;
+  messages: Message[];
+  tools: Tool[];
+  signal?: AbortSignal;
+  responseFormat?: { type: 'json_schema'; json_schema: { name: string; schema: Record<string, unknown>; strict?: boolean } };
+  promptCache?: PromptCacheContext;
+  conversationMode?: ConversationMode;
+  cacheEdits?: CacheEditsState;
+  /** Current-turn images must not be silently removed when they are required. */
+  visionPolicy?: 'required' | 'optional-history';
+}
+
+/** Both local and gateway transports consume the same normalized request. */
+export interface ModelProvider {
+  readonly source: 'local' | 'gateway';
+  readonly descriptor: Provider;
+  stream(request: NormalizedModelRequest): AsyncGenerator<LlmStreamEvent, void, void>;
+}

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')