Web delivers explicit file snapshots
Web 显式交付文件快照
Workspace links read live paths, so edits or deletion can invalidate a final deliverable. Files created through shell commands also lack first-party editor mutation records. Delivery needs an explicit operation and saved bytes without expanding Session ZIP exports.
English
Problem
Workspace links read live paths, so edits or deletion can invalidate a final deliverable. Files created through shell commands also lack first-party editor mutation records. Delivery needs an explicit operation and saved bytes without expanding Session ZIP exports.
Decision
The present tool owns execution, immutable snapshots, delivery types, and the durable event. The deliverables plugin owns authenticated snapshot actions and browser rendering, with type-only imports from the tool’s ./types entry. The standard, ptc, and cordis presets mount the tool package; minimal retains its two-tool training configuration. The existing attachment service saves immutable bytes; successful final tools/result notifications append deliverables/presented to the calling Session. Native and nested calls use the same recorder. A later enclosing program failure does not undo a completed nested delivery. Blocked tool results publish none.
Download and native-open requests authorize a reference by the viewed Session, event sequence, and file index. The event stores no Session ID, so forked history uses the child's own log. The existing produced-file row keeps its names and behavior. Session ZIP retains delivery events but does not collect their attachment bytes.
Card and closing-mention gestures open a verified private copy with the existing native-command utility. A POST expresses the desktop side effect; GET remains a byte read. Each gesture receives a new copy so application edits cannot corrupt the immutable attachment or alter later opens. Successful copies survive until plugin disposal for applications that read lazily; failed copies are removed immediately, and disposal awaits cancelled work before cleanup.
Alternatives considered
A Host tool subpath in the UI package couples preset installation to browser packaging and requires extra published entries. An ordinary tool package preserves shared filesystem and tool error classes through the repository’s peer dependency rules.
Live workspace links cannot preserve a delivered version after edits or deletion. Opening the attachment store’s own path instead would expose immutable saved bytes to application writes.
Generic artifact fields throughout tools, dispatch, and Session would broaden unrelated APIs for one Web feature. A plugin-owned event uses existing extension points and avoids parent-result forwarding.
Tool text as the durable index is unreliable because post-processing and spill can replace ordinary or nested result text. Each plugin instance retains its own completed snapshots by execution identity and publishes them only on a successful final result. Same-name scoped replacements cannot create or duplicate another instance’s delivery records.
Descriptor-bound filesystem extensions would change multiple capability providers. This feature uses existing bounded reads with containment and before/after version checks. Those checks reject ordinary concurrent changes but do not guarantee atomic confinement against swap-and-restore; stronger filesystem guarantees belong to the filesystem provider.
Consequences
The implementation adds no artifact service or attachment format. Unreferenced snapshots can remain after partial failure; attachment retention remains service-owned. A downstream build must understand the new required event to read the log. The generated Session event inventory records that requirement without changing released format generations.
The delivery event is required-on-read because it is the authorization index for saved bytes, not only display metadata. Skipping it would allow an older reader to reconstruct or fork a Session without its completed deliveries. Unsupported readers refuse that loss instead of silently dropping the references.
Focused tests cover snapshot bytes, invalid inputs, blocked results, HTTP integrity, native-open copy isolation, retry and disposal, turn isolation, and fork-addressed actions. The recorded Web scenario covers nested completion followed by an enclosing failure, source deletion, reload, native-open gestures without browser downloads, and ZIP exclusion.
中文
问题
工作区链接读取当前路径，因此编辑或删除会使最终交付文件失效。通过 shell 命令创建的文件也没有第一方编辑器修改记录。交付需要显式操作和保存的字节，同时不扩大 Session ZIP 导出内容。
决策
present 工具拥有执行、不可变快照、交付类型和持久事件。交付插件拥有认证快照操作和浏览器渲染，仅从工具的 ./types 入口导入类型。standard、ptc 与 cordis preset 挂载工具包；minimal 保留双工具训练配置。现有 attachment 服务保存不可变字节；成功的最终 tools/result 通知将 deliverables/presented 追加到调用方 Session。原生与嵌套调用使用同一个记录器。外层程序随后失败不会撤销已完成的嵌套交付。被阻止的工具结果不发布交付。
下载与原生打开请求通过当前查看的 Session、事件序号与文件索引授权引用。事件不保存 Session ID，因此 fork 历史使用子 Session 自己的日志。现有产出文件行保留其名称和行为。Session ZIP 保留交付事件，但不收集其中引用的 attachment 字节。
卡片和收尾引用操作通过现有 native-command 工具，在默认应用中打开经过校验的私有副本。POST 表达桌面副作用；GET 仍仅读取字节。每次操作创建新副本，避免应用内编辑损坏不可变 attachment 或改变后续打开的内容。成功副本保留到插件释放，以支持延迟读取的应用；失败副本立即删除，释放时先等待取消的操作结束再清理。
已考虑的替代方案
在 UI 包中提供 Host 工具子路径会将 preset 安装与浏览器打包耦合，并要求额外发布入口。普通工具包通过仓库 peer dependency 规则保留共享的文件系统和工具错误类。
实时工作区链接无法在编辑或删除后保留已交付版本。直接打开 attachment 存储路径则会使不可变保存字节暴露于应用写入。
在工具、dispatch 和 Session 中增加通用 artifact 字段会为单个 Web 功能扩大无关 API。插件拥有的事件使用现有扩展点，并省去父调用结果转发。
将工具文本作为持久索引并不可靠，因为后处理与 spill 可以替换普通或嵌套结果文本。每个插件实例按执行对象保留自身已完成的快照，仅在最终结果成功时发布。同名作用域替代工具不能创建或重复其他实例的交付记录。
基于文件描述符的文件系统扩展会修改多个能力提供方。本功能使用现有有界读取，并检查路径包含关系及读取前后的版本。这些校验会拒绝普通并发变化，但不保证对替换后复原提供原子路径限制；更强的文件系统保证属于文件系统提供方。
影响
实现不增加 artifact 服务或 attachment 格式。部分失败后可能留下无引用快照；attachment 保留策略仍由服务拥有。下游构建必须理解新必需事件才能读取日志。生成的 Session 事件清单记录该要求，不修改已发布的格式代际。
交付事件要求读取端识别，因为它是保存字节的授权索引，不只是显示元数据。跳过事件会让旧读取端在重建或分叉 Session 时丢失已完成的交付。不支持该事件的读取端拒绝读取，避免静默丢弃引用。
定向测试覆盖快照字节、无效输入、被阻止的结果、HTTP 完整性、原生打开的副本隔离、重试与释放、turn 隔离及使用 fork 地址的操作。录制 Web 场景覆盖嵌套调用完成后外层失败、源文件删除、重新加载、不触发浏览器下载的原生打开操作和 ZIP 排除。