Execution-world image paths in model requests
在模型请求中提供执行环境图片路径
An uploaded image becomes an opaque durable `ImageAttachmentRef`. Image-capable models receive its request preview, but the prior descriptor gives them no filesystem location for later image operations. Agents consequently search the workspace and temporary directories or ask the user where the file is. The request preview and stored normalized attachment may both differ from the upload, so their dimensions, format,
English
Problem
An uploaded image becomes an opaque durable ImageAttachmentRef. Image-capable models receive its request preview, but the prior descriptor gives them no filesystem location for later image operations. Agents consequently search the workspace and temporary directories or ask the user where the file is. The request preview and stored normalized attachment may both differ from the upload, so their dimensions, format, and byte size cannot establish the upload's original properties.
Decision
ImageAttachmentRef remains portable session data and contains no host path. AttachmentStore.imageHostPath(ref) exposes only the attachment provider's optional host object location. The local provider derives that absolute path from the resolved DSH_HOME, attachment storage version, and validated digest; it does not inspect the model-tool execution world.
Each LLM provider plugin supplies the bridge at request assembly. It combines the attachment store with the current ctx.fs.processPathFromHostPath(hostPath) mapping and passes the resulting ImageAttachmentAccess independently into retained-image serialization and offload placeholders. The filesystem service is authoritative for this question because the mounted filesystem and subprocess providers share one execution world. A separate subprocess-presence check would not prove path reachability. Host-backed filesystems return a process path; E2B and other remote backends without a shared mount return no mapping.
RequestImageAttachment remains a deterministic version selected by the attachment and route policy. It contains variantId, encoded bytes, dimensions, and encoding metadata, but no access path. Execution-world access may change with the host or mounted providers and does not participate in variantId.
The shared LLM image descriptor names the display name or full attachment id, the exact request-preview dimensions, and the execution-world path when the bridge resolves one. Local access text includes normalized dimensions and media type, identifies the object as read-only, directs the model to copy it to a writable path with the matching extension before editing, and states that normalization or request projection may have resized or re-encoded the upload. DeepSeek Files and pi-ai inline requests use the same descriptor.
Request-size offload requires a per-image placeholder function; the previous shared placeholder constant and its byte-bound wrapper had no remaining production caller and are removed. DeepSeek and pi-ai replace each omitted occurrence with its own attachment identity and access resolved for that request without reading or transforming the omitted object. Offload selection, byte accounting, and quantized prefix behavior remain unchanged.
Descriptor identity comes from each occurrence's own durable reference, not from the prepared request version: versions are deduplicated per attachment id, so two uploads of the same content under different names share one version while each occurrence keeps its own display name. Host-location resolution validates the logged attachment id; a malformed reference in durable history fails the request at assembly, the earliest point that resolves it.
Absolute paths stay out of session events and request-image versions. Model-visible path text is reconstructed from the logged attachment reference, the current attachment provider, and the filesystem mounted for the current execution world. Restoring the same session with a different DSH_HOME produces the path valid on that host; restoring it with a remote execution world that has no shared mount produces no path. Published attachment objects use owner-read-only mode, including deduplicated objects, and model instructions require a writable copy for modifications.
Alternatives considered
Persist the absolute path in ImageAttachmentRef. A durable host path becomes stale after moving a session, changing DSH_HOME, or mounting another provider. Resolving it at request time preserves portable history.
Teach each LLM adapter the ~/.dsh layout. Explicit dshHome and $DSH_HOME can select another root, and non-local providers may expose no path. The attachment provider owns the object location; the shared LLM helper owns the composition with an execution-world mapper.
Let the attachment provider inspect ctx.fs. The attachment provider knows where its object lives but does not own the model tools' execution environment. Combining both services in the LLM consumer also avoids a package reference cycle between attachment, filesystem, and LLM definitions.
Store ImageAttachmentAccess in RequestImageAttachment. Request versions are deterministic cache and upload values. A path that changes with the host or execution environment must not affect their identity or appear to be part of their reproducible data.
Infer path sharing from the filesystem provider's package or class name. Provider identity does not establish that a host file is mounted into its execution world. The filesystem provider instead answers the exact mapping question and can support an explicit shared mount without changing the attachment provider.
Add a dedicated crop or recovery tool. Standard filesystem and image tools can operate after copying the normalized object. A new tool adds a model schema and access-policy surface without being necessary for path discovery.
Verification
Package tests cover provider host-location defaults, host-backed path mapping, absence without a mapped filesystem, digest-to-path resolution, owner-read-only publication and deduplication, access passed independently from request versions, retained-image descriptions, per-image nested offload placeholders, source-property warnings, and matching extensions. A keyless assembled ACP snapshot checks the exact local object path in both a retained DeepSeek Files image handle and an offloaded image placeholder.
Consequences
When the execution world maps the attachment object, the selected model provider receives its path. This disclosure lets the model operate on the stored image and is limited to normalized attachment objects already in that request's authorized history. Descriptor text adds tokens for every retained or offloaded image. Paths can change while deterministic image bytes, variantId, and session references remain unchanged; the changed historical text can prevent KV-cache reuse from the first affected image even when no image is offloaded. Remote execution worlds without a shared mount receive the existing no-path recovery text. A missing local object still fails when a model tool attempts to read it.
中文
问题
上传图片会变成不透明的持久 ImageAttachmentRef。支持图片的模型可以收到请求预览，但原有描述没有给出供后续图片操作使用的文件系统位置。因此 agent 会搜索工作区和临时目录，或询问用户文件在哪里。请求预览和存储的规范化附件都可能与上传图片不同，所以它们的尺寸、格式和字节数不能证明上传图片原本的属性。
决策
ImageAttachmentRef 继续作为可移植的会话数据，不包含宿主路径。AttachmentStore.imageHostPath(ref) 只公开附件提供方可选的宿主对象位置。本地提供方根据已解析的 DSH_HOME、附件存储版本和经过校验的摘要派生该绝对路径，不检查模型工具的执行环境。
每个 LLM 提供方插件在组装请求时提供桥接逻辑。它把附件存储与当前 ctx.fs.processPathFromHostPath(hostPath) 映射组合起来，再将得到的 ImageAttachmentAccess 单独传给保留图片序列化和 offload 占位内容。当前文件系统服务可以回答这个问题，因为挂载的文件系统和子进程提供方共享同一执行环境。另行检查子进程服务是否存在并不能证明路径可达。宿主文件系统返回进程路径；E2B 和其他没有共享挂载的远程后端不返回映射。
RequestImageAttachment 仍是由附件和路由策略确定的请求版本。它包含 variantId、编码字节、尺寸和编码元数据，不包含访问路径。执行环境访问方式可能随宿主或挂载的提供方变化，不参与 variantId。
共用 LLM 图片描述会写明显示名称或完整附件 ID、确切请求预览尺寸，以及桥接逻辑能够解析出的执行环境路径。本地访问文本还包含规范化尺寸和媒体类型，说明对象只供读取，要求模型在编辑前按匹配扩展名复制到可写路径，并指出规范化或请求投影可能缩小或重新编码上传图片。DeepSeek Files 与 pi-ai 内联请求使用同一描述。
请求大小 offload 要求提供逐图占位文本函数；原先共享的占位常量及其字节上限包装函数已没有生产调用方，因此删除。DeepSeek 和 pi-ai 会把每个省略位置替换为该图片自己的附件身份和本次请求解析出的访问方式，无需读取或转换省略对象。Offload 的选择、字节计量和按固定步长变化的前缀行为保持不变。
描述文本的身份来自每个出现位置自己的持久引用，而不是准备好的请求版本：请求版本按附件 ID 去重，同一内容以不同文件名上传两次会共享一个版本，但每个出现位置保留自己的显示名称。宿主位置解析会校验已记录的附件 ID；持久历史中的畸形引用会在请求组装时失败，这是能解析它的最早时点。
绝对路径不会进入会话事件或请求图片版本。模型可见路径根据已记录附件引用、当前附件提供方和当前执行环境挂载的文件系统重建。同一会话在不同 DSH_HOME 下恢复时会得到该宿主上的有效路径；在没有共享挂载的远程执行环境中恢复时不会得到路径。发布的附件对象采用仅所有者可读的权限，去重对象也执行该权限。模型指令要求先复制到可写位置再修改。
考虑过的替代方案
把绝对路径持久保存到 ImageAttachmentRef。 移动会话、更改 DSH_HOME 或挂载其他提供方后，持久宿主路径会失效。请求时解析可以保持历史可移植。
让每个 LLM 适配器了解 ~/.dsh 布局。 显式 dshHome 和 $DSH_HOME 可以选择其他根目录，非本地提供方也可能没有路径。附件提供方拥有对象位置，共用 LLM 帮助函数负责与执行环境映射组合。
让附件提供方检查 ctx.fs。 附件提供方知道对象在哪里，但不拥有模型工具的执行环境。在 LLM 消费方组合两个服务，也避免了附件、文件系统和 LLM 定义包之间的项目引用循环。
把 ImageAttachmentAccess 放进 RequestImageAttachment。 请求版本是确定性的缓存和上传值。随宿主或执行环境变化的路径不能影响其身份，也不能表现为可重复生成的数据。
根据文件系统提供方的包名或类名判断是否共享路径。 提供方身份不能证明宿主文件已挂载到其执行世界。文件系统提供方直接回答具体路径能否映射，也允许未来的显式共享挂载在不修改附件提供方的情况下返回映射。
增加专用裁剪或恢复工具。 把规范化对象复制出来后，标准文件系统与图片工具已经可以处理它。新增工具会增加模型 schema 和访问策略范围，但路径发现不需要它。
验证
包测试覆盖提供方宿主位置默认值、宿主后端路径映射、没有文件系统映射时省略路径、本地摘要到路径的解析、仅所有者可读的发布与去重、独立于请求版本传入访问方式、保留图片描述、逐图嵌套 offload 占位文本、源属性提醒和匹配扩展名。Keyless ACP 组装快照会检查保留的 DeepSeek Files 图片句柄和被 offload 图片占位文本中的确切本地对象路径。
后果
执行环境能够映射附件对象时，所选模型提供方会收到该路径。模型可借此操作存储图片，路径只指向该请求已授权历史中的规范化附件对象。每张保留或被 offload 的图片都会增加描述文本 token。路径变化时，确定性图片字节、variantId 和会话引用可以保持不变；即使没有图片被 offload，变化后的历史文本也可能使 KV 缓存从首张受影响图片起无法复用。没有共享挂载的远程执行环境会收到原有的无路径恢复文本。本地对象缺失时，模型工具读取它仍会失败。