From 86fea5561e850fef4e903a4e43430f74b0e622f3 Mon Sep 17 00:00:00 2001 From: Yixiang Tu Date: Thu, 24 Sep 2026 13:13:07 +0800 Subject: [PATCH] fix(llm-pi-ai): anchor all-deferred Anthropic tool updates with a placeholder pi-ai sends Anthropic tool changes natively only when the initial tool list has an active declaration. When every projected declaration is deferred, prepend a non-deferred DeferredToolPlaceholder instead of failing the request. Document the placeholder, the catalog-owned update capabilities, and the image role limit as separate README entries. --- packages/llm/llm-pi-ai/README.i18n.yaml | 8 ++--- packages/llm/llm-pi-ai/README.md | 5 ++-- packages/llm/llm-pi-ai/README.zh.md | 5 ++-- packages/llm/llm-pi-ai/src/adapter.ts | 30 ++++++++++++------- .../tests/conversation-updates.spec.ts | 23 +++++++++----- 5 files changed, 45 insertions(+), 26 deletions(-) diff --git a/packages/llm/llm-pi-ai/README.i18n.yaml b/packages/llm/llm-pi-ai/README.i18n.yaml index b85a09e7de..1059df3ec2 100644 --- a/packages/llm/llm-pi-ai/README.i18n.yaml +++ b/packages/llm/llm-pi-ai/README.i18n.yaml @@ -66,8 +66,8 @@ en: e7348db3f7115960 zh: 5fd5fb09d7d09982 /deepseek-ai-dsh-llm-pi-ai/model-experience/provider-request-through-pi-ai/what-the-model-sees: - en: 606a6b300cbceb9d - zh: 9cb19014601212c4 + en: 128636721d92809e + zh: 99d345b5600af417 /deepseek-ai-dsh-llm-pi-ai/model-experience/provider-request-through-pi-ai/token-effect: en: 820221e8ae37aa61 zh: 7e6ff4db10067fc0 @@ -87,8 +87,8 @@ en: b6bd570c0159ba08 zh: 7d2d91eea6a8d830 /deepseek-ai-dsh-llm-pi-ai/known-limitations-and-deferred-work: - en: d0113737352177dd - zh: b477d08034c8f161 + en: b95c8b8d08c0025c + zh: 4d9649ff2265cd03 /deepseek-ai-dsh-llm-pi-ai/known-limitations-and-deferred-work/dev-note: en: 3678dd0f6642c2a5 zh: 75cbdd064cc64282 diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md index f62bdf305f..4acc79ef94 100644 --- a/packages/llm/llm-pi-ai/README.md +++ b/packages/llm/llm-pi-ai/README.md @@ -185,7 +185,7 @@ Read these pages when the package-level contract is not enough. They move from t #### What the model sees -The selected catalog model receives complete system-prompt snapshots, conversation history, tools, and supported sampling fields. A model with mid-conversation system support retains full updated prompts after the user/tool-result turn and before the next assistant; other models receive the latest prompt at the beginning. One-shot `GenerateOptions.system` precedes the initial history prompt. Repeated prompt snapshots remain repeated. Tool-update capabilities select the shared historical declaration projection; pi-ai receives initially active tools and grouped developer updates carrying additions and supported removals. Replay preserves tool-call namespaces for dynamically loaded Responses tools. Each retained image is preceded by text naming its complete attachment id and actual request dimensions. When the current execution filesystem maps the attachment provider's host object, the text also carries a read-only normalized-object path and warns that normalization or request projection may have resized or re-encoded the upload. Each occurrence selected by a logged image-offload decision keeps its own identity and currently resolved access in replacement text, and its normalized attachment is not read or transformed. When the retained occurrences' exact base64 payload still exceeds the route's `maxRequestImageBytes`, the call fails with `IMAGE_OFFLOAD_REQUIRED` so `dsh-compaction-image-offload` records the selected occurrences in an `image/offload` event and retries the step. Provider-native replay metadata is restored only when the adapter validates it for the historical content. +The selected catalog model receives complete system-prompt snapshots, conversation history, tools, and supported sampling fields. A model with mid-conversation system support retains full updated prompts after the user/tool-result turn and before the next assistant; other models receive the latest prompt at the beginning. One-shot `GenerateOptions.system` precedes the initial history prompt. Repeated prompt snapshots remain repeated. Tool-update capabilities select the shared historical declaration projection; pi-ai receives initially active tools and grouped developer updates carrying additions and supported removals. When every projected declaration of an Anthropic request with tool updates is deferred, the initially active tools are one placeholder, `DeferredToolPlaceholder`, whose description tells the model never to call it; a call reaches the ordinary unknown-tool result. Replay preserves tool-call namespaces for dynamically loaded Responses tools. Each retained image is preceded by text naming its complete attachment id and actual request dimensions. When the current execution filesystem maps the attachment provider's host object, the text also carries a read-only normalized-object path and warns that normalization or request projection may have resized or re-encoded the upload. Each occurrence selected by a logged image-offload decision keeps its own identity and currently resolved access in replacement text, and its normalized attachment is not read or transformed. When the retained occurrences' exact base64 payload still exceeds the route's `maxRequestImageBytes`, the call fails with `IMAGE_OFFLOAD_REQUIRED` so `dsh-compaction-image-offload` records the selected occurrences in an `image/offload` event and retries the step. Provider-native replay metadata is restored only when the adapter validates it for the historical content. #### Token effect @@ -229,7 +229,8 @@ These limits define where the adapter stops and future work begins. They are cur - **A modality declaration is not verified** — a model declaring `image` its gateway does not serve is refused by the provider after prompt admission. The durable image remains in history and the same misdeclared model can fail again; switching to a text-only model remains possible because the shared LLM runtime projects image references into stable text for that request. - **An unauthenticated route depends on its protocol** — a route naming no credential resolves as configured-but-keyless, but pi-ai's OpenAI-compatible implementation still requires an API key or an `Authorization` header, so a keyless local server needs a placeholder credential referenced by `apiKeyEnv` or an `Authorization` entry in `headers`. - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers. -- **Anthropic updates need an initially active tool** — when every projected declaration is deferred, a request containing tool updates fails with `UNSUPPORTED_CONTENT` before network I/O instead of allowing pi-ai to move activation to the initial declarations. Images in system or assistant history fail with `UNSUPPORTED_CONTENT` on both conversion paths. +- **Conversation update support comes only from the installed pi-ai catalog** — a route receives in-history prompt and tool updates only when its catalog model declares the mid-conversation compat flags, and profiles cannot set them; hand-declared routes and unflagged models receive the latest prompt and the complete current tool list at the start of each request. +- **Images are accepted only in user and tool-result messages** — images in system, developer, or assistant history fail with `UNSUPPORTED_CONTENT` on both conversion paths. - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers. - **Retry policy is provider-owned, not an SDK retry** — pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt. - **Streamed tool-call arguments are parsed once, when the call ends** — the installed pi-ai carries [`patches/@earendil-works__pi-ai@1.0.2.patch`](../../../patches/@earendil-works__pi-ai@1.0.2.patch), which removes the per-delta re-parse of the whole accumulated argument JSON in every stream adapter (upstream [earendil-works/pi#9265](https://github.com/earendil-works/pi/issues/9265)); unpatched, a multi-megabyte argument stream costs O(n²) CPU on the event loop and stalls every session in the process. Until `toolcall_end`, a pi-ai partial's tool-call `arguments` stays `{}`; this adapter reads only the delta strings and the finalized arguments. Re-apply or retire the patch on every pi-ai upgrade. diff --git a/packages/llm/llm-pi-ai/README.zh.md b/packages/llm/llm-pi-ai/README.zh.md index fa05f29f51..ba17c93d05 100644 --- a/packages/llm/llm-pi-ai/README.zh.md +++ b/packages/llm/llm-pi-ai/README.zh.md @@ -185,7 +185,7 @@ Config 更新严格验证发生变化的 provider。初始加载将已存储的 #### 模型看到什么 -所选目录模型会收到完整的系统提示词快照、对话历史、工具以及支持的采样字段。支持对话中系统消息的模型会在用户或工具结果轮次之后、下一条助手消息之前保留完整的更新提示词;其他模型在开头收到最新提示词。单次调用的 `GenerateOptions.system` 放在初始历史提示词之前。重复的提示词快照仍会重复发送。工具更新能力选择共享的历史声明投影;pi-ai 接收初始可用工具,以及按开发者消息分组的新增和受支持的移除更新。回放会保留工具调用命名空间,以支持动态加载的 Responses 工具。每张保留图片前都会有文本,注明其完整附件 id 与实际请求尺寸。当前执行文件系统可以映射附件提供方的宿主对象时,该文本还会携带只读规范化对象路径,并警告规范化或请求投影可能缩放或重新编码上传内容。日志中的图片省略决策选中的每个出现位置都会在替换文本中保留自己的身份与当前已解析访问方式,其规范化附件不会读取或变换。当保留的出现位置按精确 base64 载荷仍超过路由的 `maxRequestImageBytes` 时,调用以 `IMAGE_OFFLOAD_REQUIRED` 失败,由 `dsh-compaction-image-offload` 用 `image/offload` 事件记录所选位置并重试步骤。提供方原生回放元数据只在适配器针对历史内容校验通过后恢复。 +所选目录模型会收到完整的系统提示词快照、对话历史、工具以及支持的采样字段。支持对话中系统消息的模型会在用户或工具结果轮次之后、下一条助手消息之前保留完整的更新提示词;其他模型在开头收到最新提示词。单次调用的 `GenerateOptions.system` 放在初始历史提示词之前。重复的提示词快照仍会重复发送。工具更新能力选择共享的历史声明投影;pi-ai 接收初始可用工具,以及按开发者消息分组的新增和受支持的移除更新。当包含工具更新的 Anthropic 请求中所有投影后的声明均为延迟加载时,初始可用工具为一个占位工具 `DeferredToolPlaceholder`,其描述要求模型永不调用它;若被调用,会得到普通的未知工具结果。回放会保留工具调用命名空间,以支持动态加载的 Responses 工具。每张保留图片前都会有文本,注明其完整附件 id 与实际请求尺寸。当前执行文件系统可以映射附件提供方的宿主对象时,该文本还会携带只读规范化对象路径,并警告规范化或请求投影可能缩放或重新编码上传内容。日志中的图片省略决策选中的每个出现位置都会在替换文本中保留自己的身份与当前已解析访问方式,其规范化附件不会读取或变换。当保留的出现位置按精确 base64 载荷仍超过路由的 `maxRequestImageBytes` 时,调用以 `IMAGE_OFFLOAD_REQUIRED` 失败,由 `dsh-compaction-image-offload` 用 `image/offload` 事件记录所选位置并重试步骤。提供方原生回放元数据只在适配器针对历史内容校验通过后恢复。 #### Token 影响 @@ -229,7 +229,8 @@ pi-ai 事件变成 harness 的推理、文本、工具调用、用量与 finish - **模态声明不受校验**——声明 `image` 而其网关不支持的模型会在提示词准入后被提供方拒绝。持久图片仍留在历史中,同一误声明模型可能再次失败;切换到纯文本模型仍然可行,因为共享 LLM 运行时会针对该请求把图片引用投影为稳定文本。 - **未认证路由取决于其协议**——不点名凭据的路由解析为已配置但无密钥,但 pi-ai 的 OpenAI 兼容实现仍要求 API 密钥或 `Authorization` 标头,因此无密钥本地服务器需要由 `apiKeyEnv` 引用或 `headers` 中的 `Authorization` 条目提供的占位凭据。 - **不支持 `GenerateOptions.stop`**——pi-ai 的通用流式选项无法跨提供方保证停止序列行为。 -- **Anthropic 更新需要至少一个初始可用工具**——当所有投影后的声明均为延迟加载时,包含工具更新的请求会在网络 I/O 之前以 `UNSUPPORTED_CONTENT` 失败,而不是允许 pi-ai 将激活时机移到初始声明。system 或 assistant 历史中的图片在两条转换路径上都会以 `UNSUPPORTED_CONTENT` 失败。 +- **对话更新支持只来自已安装的 pi-ai 目录**——只有当路由的目录模型声明了对话中 compat 标志时,该路由才会在历史中接收提示词与工具更新,且 profile 不能设置这些标志;手工声明的路由与未标记的模型会在每次请求开头接收最新提示词与完整的当前工具列表。 +- **图片只在 user 与工具结果消息中被接受**——system、developer 或 assistant 历史中的图片在两条转换路径上都会以 `UNSUPPORTED_CONTENT` 失败。 - **提供方 HTTP 状态不可用**——pi-ai 错误事件不跨提供方暴露稳定 HTTP 状态。 - **重试策略由提供方自有,而非 SDK 重试**——pi-ai SDK 重试保持禁用,因此持久 agent(智能体)步骤与 `llm/retry` 事件拥有每个可见尝试,直接 `ctx.llm.stream()` 调用仍是单次尝试。 - **流式工具调用参数只在调用结束时解析一次**——安装的 pi-ai 带有 [`patches/@earendil-works__pi-ai@1.0.2.patch`](../../../patches/@earendil-works__pi-ai@1.0.2.patch),它移除了每个流适配器中对整段累计参数 JSON 的逐 delta 重新解析(上游 [earendil-works/pi#9265](https://github.com/earendil-works/pi/issues/9265));未打补丁时,数 MB 的参数流会在事件循环上消耗 O(n²) CPU,并使进程内所有会话停滞。在 `toolcall_end` 之前,pi-ai partial 的工具调用 `arguments` 保持为 `{}`;本适配器只读取 delta 字符串与最终参数。每次升级 pi-ai 时都要重新应用或撤销该补丁。 diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts index fff90ad65f..1da01b6a8f 100644 --- a/packages/llm/llm-pi-ai/src/adapter.ts +++ b/packages/llm/llm-pi-ai/src/adapter.ts @@ -54,6 +54,7 @@ import type { ReasoningEffortId as ReasoningEffortIdType, ResolvedRetryPolicy, StreamChunk, + ToolSchema, } from '@deepseek-ai/dsh-llm' import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout' @@ -62,6 +63,16 @@ import { toPiContext } from './context.ts' import { conversationUpdates, createModels, getSupportedThinkingLevels } from './models.ts' import { toStreamChunks } from './stream.ts' +/** + * Initially active declaration added to an Anthropic request whose projected + * tools are all deferred, because Anthropic rejects a tool list without one. + */ +const ANTHROPIC_TOOL_UPDATE_PLACEHOLDER: ToolSchema = { + name: 'DeferredToolPlaceholder', + description: 'Reserved placeholder that keeps deferred tool loading active; never call this tool.', + parameters: { type: 'object', properties: {} }, +} + /** One resolution's frozen view: the profiles and the collection built from them. */ interface PiAiSnapshot { /** The resolved profiles this collection was built from, used as its identity. */ @@ -344,15 +355,14 @@ export class PiAiAdapter extends LlmAdapter { const model = this.modelOf(snapshot, options.provider, options.model) const updates = conversationUpdates(model) // pi-ai collapses Anthropic tool updates without an initially active declaration. - if (model.api === 'anthropic-messages' && updates.toolUpdate === 'in-history' - && !options.tools?.some(tool => !tool.deferLoading) + const tools = options.tools ?? [] + const needsPlaceholder = model.api === 'anthropic-messages' && updates.toolUpdate === 'in-history' + && tools.every(tool => tool.deferLoading === true) && options.messages.some(message => message.role === 'developer' - && message.content.some(block => block.type === 'tool-addition' || block.type === 'tool-removal'))) { - throw new LlmError( - 'pi-ai Anthropic tool updates require an initially active tool; this request would otherwise move tool activation out of history.', - 'UNSUPPORTED_CONTENT', - ) - } + && message.content.some(block => block.type === 'tool-addition' || block.type === 'tool-removal')) + const request = needsPlaceholder + ? { ...options, tools: [ANTHROPIC_TOOL_UPDATE_PLACEHOLDER, ...tools] } + : options const reasoning = resolveReasoningLevel( model, options.reasoningEffort ?? profile.reasoning, @@ -379,8 +389,8 @@ export class PiAiAdapter extends LlmAdapter { this.config.onReplayDegrade?.({ provider: options.provider, model: options.model, reason }) } const context = attachments === undefined - ? toPiContext(options, undefined, onReplayDegrade, updates.systemPromptUpdate) - : await toPiContext({ ...options, signal: watchdog.signal }, { + ? toPiContext(request, undefined, onReplayDegrade, updates.systemPromptUpdate) + : await toPiContext({ ...request, signal: watchdog.signal }, { attachments, resolveImageAccess: ref => this.config.resolveImageAccess?.(attachments, ref), maxRequestImageBytes: profile.maxRequestImageBytes, diff --git a/packages/llm/llm-pi-ai/tests/conversation-updates.spec.ts b/packages/llm/llm-pi-ai/tests/conversation-updates.spec.ts index b185ff7033..99af56302e 100644 --- a/packages/llm/llm-pi-ai/tests/conversation-updates.spec.ts +++ b/packages/llm/llm-pi-ai/tests/conversation-updates.spec.ts @@ -121,19 +121,26 @@ describe('serialized conversation updates', () => { }) }) - it('refuses an empty initial Anthropic tool set before provider I/O', async () => { + it('anchors Anthropic tool updates with a placeholder when every declaration is deferred', async () => { const update = addition() - const { result, requests } = await send('anthropic', 'claude-opus-4-8', { + const { requests } = await send('anthropic', 'claude-opus-4-8', { messages: [user('first'), update], tools: [added], toolHistory: { tools: [], updates: [{ messageId: update.id, additions: [added] }] }, }) - expect(requests).toEqual([]) - expect(result.finish).toMatchObject({ - kind: 'error', failure: { - code: 'UNSUPPORTED_CONTENT', - message: 'pi-ai Anthropic tool updates require an initially active tool; this request would otherwise move tool activation out of history.', - }, + expect(requests).toHaveLength(1) + expect(requests[0]).toMatchObject({ + messages: [ + { role: 'user', content: 'first' }, + { role: 'system', content: [ + { type: 'text', text: 'Instruction one.\nInstruction two.' }, + { type: 'tool_addition', tool: { type: 'tool_reference', name: 'search' } }, + ] }, + ], }) + const tools = (requests[0] as { tools: { name?: string; defer_loading?: boolean }[] }).tools + expect(tools.map(tool => [tool.name, tool.defer_loading])).toEqual([ + ['DeferredToolPlaceholder', undefined], ['__pi_deferred_placeholder__', true], ['search', true], + ]) }) it('sends only the latest prompt and current tools on unsupported routes', async () => {