更新日志

​

破坏性变更

• Rollout 调用方与 server 必须一起升级。使用 RolloutClient 替换 HttpRolloutDriver 和 callback model；每个请求都需要唯一的 rollout_id，chat endpoint 需要认证时还需显式提供 llm_api_key。
• 自定义 backend 的 execute(request) 返回 ExecutionOutcome，并通过 await RolloutContext.set_status() 发布进度。本地 LLM bridge 的 import 从 osmosis_ai.rollout.controller 迁移到 osmosis_ai.eval.local。
• 本地 evaluation 的协议指纹现在是 0.4。使用旧协议记录的 run 需要更换 run name，或使用之前版本的 SDK 恢复。
• 移除 managed SkyPilot placement。请使用 EnvironmentType.DAYTONA 和 Daytona credentials；HARBOR_SKYPILOT_CONTEXT 不再被读取。省略 environment_config 时仍选择 Docker。

​

新增功能

• RolloutClient 负责 lease 续期、HTTP 429 admission 重试、取消，以及可选的 grade=False。await run_rollout_async() 返回可 await 的 RolloutHandle，提供实时状态与 milestone 等待方法。
• osmosis eval upload 和 osmosis eval run --upload 会上传 logs.txt，显示在 platform 的 Logs 标签页中。本地日志记录和上传会脱敏当前进程环境中已知的、长度至少八个字符的 provider 与 platform 凭证；脱敏无法识别所有可能的 secret，分享前请检查日志。

​

变更

• delete=True 的内置 Daytona 环境默认在 Daytona 观测到 60 分钟无活动后停止，并立即删除。对于较长时间无 provider 可见活动的阶段，请增大 auto_stop_interval_mins，或设为 0 禁用自动停止。参见 Daytona 生命周期默认值。
• 支持的依赖范围扩展为 Harbor >=0.20.0,<0.23 和 OpenAI Agents >=0.18.1,<0.21。升级 Harbor 时，请从 SDK workflow task 目录移除顶层 trajectory.json 输入，并在运行受限网络 trial 前检查 Docker host 的 nftables 支持。生成的 rollout trajectory artifact 仍受支持。

​

修复

• 轮询会保留已完成的 reward 和失败详情，限定 admission 与取消清理时长，并让没有记录终态结果的本地 evaluation 工作保持 pending 以便恢复。
• System keyring 不可用时，login 回退到仅文件所有者可读写的凭证文件。OSMOSIS_TOKEN_STORE=keyring 强制要求 keyring；file 显式选择文件存储。参见凭证存储。
• osmosis train info 可在 training run 仍运行时列出 checkpoints。

​

升级

​

变更内容

• RolloutClient.run_rollout_async() 现在返回可 await 的 RolloutHandle，而不是 asyncio.Task。该 handle 提供 status、latest_result、done()、cancel()，以及 milestone 等待方法 wait_for_running()、wait_for_grading() 和 wait_for_completion()。当阶段已经过去或 rollout 已终止时，milestone 等待也会结束。
• 结果 long polling 会在状态变更时返回，包括来自 Local 与 Harbor backend 的 grading milestone，无需等满整个轮询超时。
• 自定义 backend 通过 await 活跃的 RolloutContext.set_status() 方法发布中间进度。结果轮询不再从 ExecutionBackend.rollout_status() 读取进度。
• osmosis eval upload 和 osmosis eval run --upload 会包含合并后的 logs.txt，因此本地 evaluation 日志会显示在 platform 的 run Logs 标签页中。
• 本地 evaluation 会从日志中脱敏 process environment 中已知的、长度至少八个字符的 provider 与 platform 凭证，并在上传哈希计算前再次执行脱敏。

​

谁需要采取行动

• 更新将 run_rollout_async() 返回值当作 asyncio.Task 使用的调用方。请继续 await 该 handle 以获取终态结果，并使用其 done()、cancel() 和 milestone 方法替代 Task 专有 API。
• 更新通过 ExecutionBackend.rollout_status() 报告中间进度的自定义 backend，改为 await RolloutContext.set_status()。

​

变更内容

• Rollout 完成机制现在使用基于 lease 的 long polling，而不是 callback。新的 RolloutClient 会提交 rollout、自动续期由 server 签发的 polling lease、在 HTTP 429 时重试 admission、轮询终态结果，并支持显式取消。请求可以通过 grade=False 跳过 grading。
• 移除 HttpRolloutDriver 和 callback model。每个请求需要提供唯一的 rollout_id；当 chat endpoint 需要认证时，还需显式提供 llm_api_key。
• 自定义 backend 的 execute(request) 现在返回 ExecutionOutcome，而不是调用 result callback。本地 LLM bridge 的 import 从已移除的 osmosis_ai.rollout.controller 包迁移到 osmosis_ai.eval.local。
• 支持的 Harbor 版本扩展为 >=0.20.0,<0.23，OpenAI Agents 扩展为 >=0.18.1,<0.21。
• 轮询到的结果在取消和序列化错误时仍会保留已完成的 reward 与失败详情；lease 过期或 server 关闭时，workflow 和 sandbox 可以在有限时间内完成清理。
• Admission deadline 现在覆盖 HTTP 请求和重试等待。丢失的 admission response 会把未观测到的工作交给 lease 过期处理，而不是冒险取消另一个使用相同 ID 的 rollout。
• 本地 evaluation 会限定结果轮询时长、等待取消清理完成，并让没有记录终态结果的工作保持 pending 以便 resume，包括轮询遇到 403 和 404 错误的情况。

​

谁需要采取行动

• 调用方与 rollout server 必须一起升级。基于 lease 的 long-poll 协议无法与 0.3.2 的 callback 协议互通，请用 RolloutClient 替换 HttpRolloutDriver 和 callback model。
• 本地 evaluation 的协议指纹现在是 0.4。使用旧协议记录的 run 无法在本版本下 resume；请使用新的 run name，或用之前版本的 SDK 完成该 run。
• 升级 Harbor 时，请从 SDK workflow task 中移除顶层的 trajectory.json 输入，并在运行受限网络 trial 前确认 Docker host 能通过其 nftables 探测。

​

破坏性变更

• 移除 public 的 MessageResult、GraderInitRequest、GraderInitResponse、RolloutDriver 和 resolve_workspace_directory_from_cwd() API。请改用 OperationResult、HttpRolloutDriver 和 resolve_workspace_directory()；两个未被使用的 grader-init 类型没有替代项。
• SDK 不再声明 requests 为基础 dependency，也不再在 rubric extra 中声明 tqdm。如果您的代码直接 import 这些包，请自行声明。

​

新增功能

• osmosis eval run 可通过托管的 cloudflared tunnel 访问 Daytona、SkyPilot 等云端 sandbox；当解析出的 sandbox 无法访问 host loopback 时会自动启动该 tunnel，也可以使用 --advertise-url 指向您自行运行的 tunnel。
• 根级 --workspace <name> 可按名称选择 platform workspace。此时 benchmark、dataset、model、secret 与 run inspection 命令无需本地 repository 即可运行；当 config 所在的 Git repository 与所选 workspace 匹配时，eval submit 和 train submit 也接受绝对 config 路径。
• osmosis eval upload <run-name> 会在 .osmosis/evals/ 下解析已完成的 run；显式 run directory 仍然可用。
• 新增 eval 安装 extra 的文档，并支持 Python 3.14。

​

变更

• 本地 osmosis eval run --dataset-file ... 在未请求 --upload 时不再加载 platform credentials。
• 新脚手架生成的 rollout 依赖稳定的 osmosis-ai[server]>=0.3.0,<0.4 版本线。
• 本地 evaluation 的 output、retry、resume 与 upload 路径会相对命令调用目录显示。

​

修复

• 本地 evaluation 会在打开 tunnel 前校验 model 和 rollout server，保持较慢的 non-streaming tunnel response 存活，在 host 无法探测 tunnel URL 时接受已注册的 Cloudflare connection，并在 loopback endpoint 不可达时快速失败而不是挂起。
• 当 CLI 与 rollout environment 使用不同的 osmosis-ai 版本时，本地 evaluation 会给出警告。
• harbor extra 会安装 Harbor 的 Daytona dependencies，因此 Daytona environment 无需单独配置依赖即可使用。
• --secrets-file 中的值仅在本地 evaluation run 期间覆盖 process environment，并在所有退出路径上恢复；orphan cleanup 也会拒绝 symlink 的 run directory。

​

升级

​

破坏性变更

• RolloutDriver.run 现在只接受单个 RolloutRunRequest 参数。请更新自定义 driver 及其调用方，改为传入该 request 对象。
• ExecutionBackend.max_concurrency 和 import 时的 osmosis_ai.platform.auth.PLATFORM_URL 已移除。请从 rollout server 的 /health 响应读取并发容量，并使用 get_platform_url() 获取当前 platform URL。
• 公共 record 类型中未使用的 server-owned 字段已移除。请不要再读取 UploadInfo.s3_key 和 .upload_id、DatasetFile.df_stats 和 .organization_id、TrainingRunMetrics.training_run_id、EvalRunMetrics.eval_run_id、RolloutInfo.last_synced_at 以及 TrainingRunCheckpoints.training_run_id。

​

新增功能

• osmosis eval run 通过新的 eval 安装 extra，使用与 managed run 相同的 TOML 在本地执行 crash-safe evaluation。它支持 dataset 切片、可恢复的输出、uv 管理的 rollout environment、LocalBackend 和 Harbor 的 Docker environment、可读的自动生成 run 名称、OpenAI Responses 路由、有界 admission，以及 orphan rollout server 清理。
• osmosis eval upload <run-dir> 和 eval run --upload 可将已完成的本地 run 导入平台。两者都以服务端为准且 idempotent，并且都不会启动 managed evaluation。

​

变更

• CLI machine contract 已标准化。--json 和 --plain 绝不会发出提示，JSON error 在 stderr 上使用稳定的 {code, message, details} envelope，机器可读的 warning 使用 JSON Lines，non-finite 值也不再可能产生无效 JSON。
• 登录凭证按 platform 划分 scope，并持久化在操作系统 keyring 中，可跨目录和环境复用。它们在 HTTP 401 响应后仍会保留；针对非生产环境的 OSMOSIS_TOKEN 会在任何网络访问之前与 OSMOSIS_TOKEN_PLATFORM_URL 校验。

​

修复

• Mini SWE-agent benchmark 的凭据校验与 Platform 保持一致，同时保留 Cursor CLI harness key 的要求。
• osmosis dev server up 会打印 Platform 返回的一次性 API key，因此新建的 server 可以立即使用。

​

升级

​

破坏性变更

• 每个 rollout 现在都会通过 rollout-scoped URL 生成且仅生成一个 RolloutSample 和 reward。请将自定义 context、grader、integration、callback 与 backend adapter 更新为 single-sample contract。
• Runtime integration 使用显式的 server、strands、openai-agents、harbor、rubric 和 parquet extra，并从 feature-specific module import。AgentWorkflow.run() 返回一个 message history，原有 loader、validator 和 multi-trajectory helper 已移除。
• HarborBackend 现在是此前名为 HarborBackendV2 的 container-native 实现；legacy backend、对应 constructor argument、OsmosisInstalledAgent 和 HarborAgentWorkflowContext 均已移除。
• Prompt 与 metadata dataset 各自在所有 row 中使用统一 schema，benchmark detail output 则以 requires_judge_api_key 替代 required_secret_names。

​

新增功能

• osmosis benchmark 现在支持 catalog discovery、submission、run inspection、logs、cancellation 和 output download。
• Container-native Harbor backend 新增 installable workflow bundle、native agent、template 与 dataset mode、prewarming、diagnostics、artifact、admission control、status polling 和 cancellation。
• Training、evaluation 与 benchmark submission 可以从 dotenv file、standard input、process environment 或 hidden terminal prompt 解析 per-run secret，无需将其保存到 Platform secret store。
• osmosis quickstart 会引导用户完成 authentication、workspace repository setup、clone、billing check，并生成可直接粘贴的 agent prompt；OsmosisClient 也提供对应的 onboarding API。

​

可靠性与安全性

• Rollout bundle 使用 content-addressed atomic cache，支持 flat、src/ 和 PEP 420 layout，拒绝不安全的 symlink 与 cache layout，并通过 Harbor extra 安装兼容的 uv builder。
• Local execution 会执行 controller deadline、校验 reward、清理 optional callback telemetry，并保持一致的 terminal callback outcome。
• Harbor 会保留 sample、diagnostics 与 ATIF trajectory，同时防止 task-source symlink 和 rollout credential 进入 archived trial data；secrets-file error 也不会再回显可能包含 secret 的输入。

​

升级

​

变更内容

• osmosis quickstart 现在会完成登录、选择 workspace、等待 repository 连接、clone 或复用 workspace directory、检查 billing，并为 training、evaluation 或 benchmark 生成可直接粘贴的 agent prompt。
• OsmosisClient 新增 list_workspaces()、get_quickstart_status() 和 complete_quickstart()，用于 workspace-scoped onboarding integration。
• RolloutSample.reward 现在会在构造与赋值时拒绝 NaN、无穷大和非数值。若 grader 传入此类值，会抛出 pydantic.ValidationError，而不再静默地以“无 reward”方式抵达控制器。NumPy 风格的数值标量会被规范化为 float。
• LocalBackend 将并发限流器的排队时间计入控制器下发的 agent_timeout_sec，并对 grading 应用独立的 grader_timeout_sec。吞掉 CancelledError 或阻塞事件循环超过截止时间的代码，现在会被报告为超时，而不是返回一个迟到的成功。
• osmosis eval submit、osmosis train submit 和 osmosis benchmark submit 的 --secrets-file 现在接受 export NAME=value 与 NAME="quoted value" 形式。格式错误的行仅按来源与行号报告，不会把行内容回显到 CI 日志。名称若无法通过 Python 的标识符检查会被直接拒绝。
• Rollout bundle 的构建改为按项目内容、解释器 ABI 与平台进行内容寻址，且每次构建在隔离的目录中运行，必须恰好产出一个 wheel。除 flat layout 之外，现在也支持 src/ layout（如 uv init --lib 生成的）与 PEP 420 namespace package，Harbor extra 也会安装兼容的 uv builder。
• Harbor 会在 task materialization 前拒绝 symlink，并在 retained trial file 被归档前清除 rollout controller credential。

​

谁需要采取行动

• 使用 osmosis quickstart 或依赖这些 rollout 加固修复前，请升级到 osmosis-ai>=0.3.0rc4。
• 更新任何可能向 ctx.set_reward 传入 float("nan")、float("inf") 或非数值的 grader —— Osmosis 现在会拒绝这些值。请返回预期的数值 reward，或者不调用 set_reward 以表示“未评分”。
• 更新此前依赖旧解析器把引号当作值一部分或把 export 前缀当作名称一部分的 --secrets-file 数据源。旧行为会静默提交错误字符串；新解析器会将两种形式都解析为预期的值。

​

变更内容

• Prompt dataset 需要 user_prompt 加 ground_truth 或其 label alias；system_prompt 仍为 optional。
• Metadata dataset 的每一行都需要 non-empty metadata object。Validation 现在会检查每一行 JSONL 和 CSV，以及每个 Parquet metadata value。
• osmosis train submit、osmosis eval submit 和 osmosis benchmark submit 接受 --secrets-file；value 也可以来自 process environment 或 interactive prompt。
• Benchmark detail 中的 required_secret_names 替换为 requires_judge_api_key。

​

谁需要采取行动

​

变更内容

• 使用 server、strands、openai-agents、harbor、rubric 或 parquet extra 安装 optional feature；full 会安装全部功能。
• 从各自的 public submodule import server、Harbor、Strands、OpenAI Agents 和 rubric 功能，而不是从 rollout 或 package root import。
• AgentWorkflow.run() 通过 AgentWorkflowOutput、bare message list 或 None 返回一个 message history；None 使用 active sample-source fallback。Output metrics 必须是有限值。
• 原 HarborBackendV2 现更名为 HarborBackend；legacy backend 和 HarborAgentWorkflowContext 已移除。
• CLI 新增 benchmark catalog、submission、status、logs、cancellation 和 output download workflow。

​

谁需要采取行动

​

变更内容

• GraderContext.samples 改为 GraderContext.sample，set_sample_reward(sample_id, reward) 改为 set_reward(reward)。
• 自定义 integration 通过 set_sample_source() 注册一个 source，并通过 get_sample() 读取它。
• 移除了 RolloutSample.id 和 MultiTurnMode。执行身份现在由 rollout URL 提供。
• 模型和 callback 请求使用 rollout-scoped URL。Integration 不再为每次调用附加 sample 或 rollout routing headers。
• Backend 交换 sample.json 和只包含单个值的 reward.json（{"reward": <float>}）。
• Strands 和 OpenAI Agents integration 强制每次 workflow 执行只能注册一个 agent 或 session。

​

谁需要采取行动