Python minimal-composition model-visible snapshot
Python 极简组合的模型可见快照
The Python lane needs an exact record of what the standalone minimal profile shows the model. Functional tool assertions prove execution but do not reveal an added system section, tool description, or user-role context message, while the advanced executable snapshot replaces each request header's assembled system prompt with a token and each tool schema with its name.
English
Problem
The Python lane needs an exact record of what the standalone minimal profile shows the model. Functional tool assertions prove execution but do not reveal an added system section, tool description, or user-role context message, while the advanced executable snapshot replaces each request header's assembled system prompt with a token and each tool schema with its name.
Decision
The sdk-minimal scenario in the packaged-runtime smoke boots the shipped profile and records scripts/snapshots/python-sdk-single-exe/minimal/model-visible.json: for every model request of the turn, the advertised tool schemas verbatim and the message list. System and user messages keep their full text with the scenario's temporary directory tokenized; assistant and tool messages keep only call identity, because their PTY and filesystem text differs across replay platforms. The profile omits dynamic runtime context, so every message it emits is compared.
The snapshot, rather than inline mock-model assertions, owns the minimal scenario's tools and system prompts and reports their complete diff. Snapshot comparison takes its directory and file set as arguments, so the minimal and advanced expected outputs use one implementation, and --update-snapshots accepts sdk-minimal.
Alternatives considered
Snapshot the minimal session log, like the advanced scenario. The minimal turn drives a real PTY and editor, so persisted tool results carry platform-dependent text. The expected output would go red for reasons unrelated to model-visible assembly, and normalizing that text away leaves the log carrying little the model-visible file does not.
Extend the mock model's inline assertions. Every new model-visible contribution would need another hand-written expectation, and a failure names one mismatch rather than the whole surface. Tool descriptions would also be duplicated from the composition into the script.
Rely on the TypeScript SDK snapshot. Its persistent-tools scenario pins a similar two-tool composition through replayed model responses and a source or lib runtime, in a different required job. It cannot show what the deployed executable's shipped profile assembles for a Python caller.
Consequences
A change to the minimal composition's model-visible surface — a system section, a tool, a tool description, or an added user message — now fails python-runtime with the exact diff, and landing it means rerunning --scenario sdk-minimal --update-snapshots and reviewing that diff. The minimal composition's tool descriptions become reviewed expected output.
Assistant and tool message text is not compared. The scenario's own assertions continue to own persistent-shell state, editor output, and the final response; the snapshot owns every model-visible message the profile emits.
AGENTS.md and the testing policy now name both SDKs as independent projections of the agent loop, session lifecycle, and SessionEventMap, so a change to any of those carries updating both expected outputs rather than only the one a contributor happens to run.
中文
问题
Python 通道需要精确记录独立极简 profile 实际展示给模型的内容。功能性工具断言可以证明执行，但无法发现新增系统分段、工具描述或 user 角色上下文消息；而进阶可执行文件快照会把每个请求头中已组装的系统提示词换成占位符，并把每个工具 schema 换成其名称。
决策
打包运行时冒烟测试的 sdk-minimal 场景会启动随附 profile，并录制 scripts/snapshots/python-sdk-single-exe/minimal/model-visible.json：对该回合的每个模型请求，逐字记录对外公布的工具 schema 与消息列表。system 与 user 消息保留全文，仅将场景的临时目录替换为占位符；assistant 与 tool 消息只保留调用标识，因为它们的 PTY 与文件系统文本在各回放平台上并不相同。该 profile 省略动态运行时上下文，因此它发出的每条消息都会参与比对。
极简场景的工具与系统提示词由快照拥有，而不是由 mock 模型内联断言；快照会给出其完整差异。快照比对以目录与文件集合为参数，因此 minimal 与 advanced 两份期望输出共用一套实现，且 --update-snapshots 接受 sdk-minimal。
曾考虑的替代方案
像进阶场景那样对极简会话日志做快照。 极简回合驱动真实 PTY 与编辑器，持久化的工具结果带有平台相关文本。期望输出会因与模型可见组装无关的原因变红；而把这些文本归一化掉之后，日志所承载的内容也就所剩无几。
扩展 mock 模型中的内联断言。 每新增一项模型可见贡献都要再手写一条期望，且失败只会指出一处不匹配而非整个面。工具描述还会从组合复制进脚本，形成重复。
依赖 TypeScript SDK 快照。 其 persistent-tools 场景通过重放模型响应与 source 或 lib 运行时固定一套相似的双工具组合，且位于另一个必需任务中。它无法体现已部署可执行文件的随附 profile 为 Python 调用方组装出什么。
后果
极简组合模型可见面的改动——系统分段、工具、工具描述或新增的 user 消息——现在会让 python-runtime 带着精确差异失败；要让它落地，就必须重新运行 --scenario sdk-minimal --update-snapshots 并审阅该差异。极简组合的工具描述由此成为经过审阅的期望输出。
assistant 与 tool 消息文本不参与比对。持久 shell 状态、编辑器输出与最终响应仍由该场景自身的断言拥有；快照负责该 profile 发出的每条模型可见消息。
AGENTS.md 与测试政策现已点明两个 SDK 都是 agent loop、会话生命周期与 SessionEventMap 的独立投影，因此改动其中任何一项都要连带更新两侧的期望输出，而不只是贡献者恰好会运行的那一侧。