Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions contracts/agents-api/harness-onboarding.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,21 +227,26 @@ python services/core/tests/qualify_public_native.py \
| `none` | Initial-input creation/retry/conflict with one Turn, foreign history rejection, two native text Turns, history recall, SSE ordering, SDK/raw schema parity and nullable usage accounting | `none` |
| `pending-actions` | Query/reconnect pending calls, success/error results, cancellation, exact target rejection, retries and durable Items | Any declared placement with function tools |
| `functions` | SDK handlers, success/error, native file and Artifact bytes, continuation, pending cancellation and tenant isolation | Workspace |
| `tool-search` | Deferred function execution, saved configuration freeze and the function suite | Workspace with declared deferred discovery |
| `policies` | Saved/inline disabled controls, unsupported enablement rejection, Codex native-parameter rejection and verbosity | Claude Code or Codex workspace |
| `steering` | Active message delivery, same-Turn attribution, public retries/conflicts, foreign rejection and continuation | MiniMax Code workspace |
| `images` | Initial and active images, image results, retry/atomic rejection, native files/Artifacts, isolation and continuation | Workspace with declared image and function support |
| `structured` | Saved and inline schema, function-assisted native files, exact JSON/SSE, cancellation and text override | Workspace with declared structured output and function support |
| `structured` | Saved and inline schema, function-assisted native files, exact JSON/SSE, large integers, schema admission, cancellation and text override | Workspace with declared structured output and function support |
| `composition` | Frozen source snapshots, initial bytes, ordered setup, packages, Skills, stdio MCP, continuation and cancellation | `openai_hosted` |

For `composition`, settings must supply exactly `{"type":"openai_hosted"}` as `environment`; the suite creates its own Template, file and Skill sources. It checks initial binary bytes, ordered setup, npm and Python packages, uploaded, plugin and directory Skills, and three real stdio MCP tool identities, Items and results. After changing or deleting source resources, it verifies frozen preparation through warm continuation and, when selected, the existing Compose-verified agent-host restart. Cancellation must stop the MCP descendant's file effects. The suite cleans up all resources it creates.

Private-owner and credential isolation remain `unverified`; positive canary evidence requires separate proof using operator-owned resources. The suite does not request `packages.system` or stdio MCP `env_vars`, which the current contracts reject.

The `tool-search` suite proves deferred callbacks through Core; the pinned public protocol has no required discovery event, so it does not claim a visible native ToolSearch call. `structured` distinguishes rejected lossy schema numbers from exact large-integer final text. `policies` records observed disabled-tool behavior, not network isolation or proof that a model honored verbosity; Codex low/high runs require native catalog support and an unsupported selection fails qualification. `steering` requires input while the original native Turn is active. Its public idempotency checks do not observe ACP duplicate receipts, and native acceptance does not guarantee model consumption. These limits remain in each suite’s evidence.

For `self_hosted`, choose a custom absolute `workspace_directory`. When the runner prints each new Session ID, connect a separate isolated machine or container using that Session's public installation command; the runner waits up to five minutes. Multiple Sessions must not share a workspace. The separate `official_environment_files_native.py` check accepts two already connected self-hosted Sessions and checks Files.list sorting, pagination and isolation through the Environment owner.

Warm continuation is the default and records cold recovery as `unverified`. To qualify cold continuation, additionally pass `--compose-directory` with the owned installation's absolute directory and `--compose-project` with its exact project name. The runner restarts only that project's `agent-host`, confirms its container start time changed, and then runs the unchanged history assertions. This does not qualify a Core restart or a sandbox checkpoint restore. The `pending-actions` suite reconnects the public client, not the agent-host process, and rejects those restart options. Select cold recovery only where the [declaration and coverage ledger](./index.md#known-gaps) support it; unsupported recovery remains a gap, never a successful skipped check. An API rejection fails the selected suite.
Warm continuation is the default and records cold recovery as `unverified`. To qualify cold continuation, additionally pass `--compose-directory` with the owned installation's absolute directory and `--compose-project` with its exact project name. The runner restarts only that project's `agent-host`, confirms its container start time changed, and then runs the unchanged history assertions. This does not qualify a Core restart or a sandbox checkpoint restore. The `pending-actions`, `policies` and `steering` suites do not qualify process restart and reject those options. Select cold recovery only where the [declaration and coverage ledger](./index.md#known-gaps) support it; unsupported recovery remains a gap, never a successful skipped check. An API rejection fails the selected suite.

The `none` suite validates required and nullable Session, Turn, Item and event fields against the pinned schema. When native Turns supply measured usage, it checks the terminal event against the stored Turn and sums the measurements into Session totals. Unknown usage remains `null` and each affected Turn is listed in the evidence’s `proof.unverified`; a passing suite does not claim native measurement support for those Turns.

Run `python -m unittest discover -s services/core/tests -p qualify_public_native_test.py` with the pinned SDK to check credential handling and the owned restart boundary without a model. Existing deterministic Core integration tests remain the authority for schema validation, atomic admission, durable receipts and rejection semantics. Real-model results qualify only the selected suite, protocol, Harness and placement. Provider lifecycle, native identity, credential isolation, deferred discovery and unselected suites need separate evidence; view-only results do not qualify the public path.
Run `python -m unittest discover -s services/core/tests -p qualify_public_native_test.py` with the pinned SDK to check credential handling and the owned restart boundary without a model. Existing deterministic Core integration tests remain the authority for schema validation, atomic admission, durable receipts and rejection semantics. Real-model results qualify only the selected suite, protocol, Harness and placement. Provider lifecycle, native identity, credential isolation and unselected suites need separate evidence; view-only results do not qualify the public path.

## Native version pins

Expand Down
13 changes: 9 additions & 4 deletions contracts/agents-api/zh/harness-onboarding.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "添加 Harness"
source: contracts/agents-api/harness-onboarding.md
source_hash: 84ebd7cebed1995c89a59f8c4c71542ca41ef6ccc890b4eba96340a970ae161c
source_hash: 56b2a40b814062de7d636af33ad2eb7671b8b3eb11781e32caacdf3d3985ae73
---

**Harness** 是一种运行模型和工具循环的原生代理引擎(Codex、Claude Code、MiniMax Code)。**Harness 适配器**将 Runtime 的 Executor 和 Turn 契约转换到该引擎的 SDK 或协议。本文档定义 Runtime–Harness 协议:适配器接口及其生命周期义务、注册、支持声明和验收。
Expand Down Expand Up @@ -229,21 +229,26 @@ python services/core/tests/qualify_public_native.py \
| `none` | 带初始输入的创建、重试和冲突保持单个 Turn,跨项目历史拒绝,两个原生文本 Turn,历史回忆,SSE 顺序,SDK/原始响应 schema 一致性与可空 usage 核算 | `none` |
| `pending-actions` | 查询和重连待处理调用、成功/错误结果、取消、精确目标拒绝、重试和持久化 Item | 声明支持函数工具的任意放置方式 |
| `functions` | SDK handler、成功/错误、原生文件和 Artifact 字节、继续执行、待处理调用取消和租户隔离 | 工作区 |
| `tool-search` | 延迟函数执行、已保存配置冻结及函数套件 | 声明支持延迟发现的工作区 |
| `policies` | 保存/内联禁用控制、不支持的启用拒绝、Codex 原生参数拒绝及 verbosity | Claude Code 或 Codex 工作区 |
| `steering` | 活跃消息投递、同一 Turn 归属、公共重试/冲突、跨租户拒绝及继续执行 | MiniMax Code 工作区 |
| `images` | 初始和活动图像、图像结果、重试/原子拒绝、原生文件/Artifact、隔离和继续执行 | 声明支持图像和函数的工作区 |
| `structured` | 保存和内联 schema、函数辅助原生文件、精确 JSON/SSE、取消和文本覆盖 | 声明支持结构化输出和函数的工作区 |
| `structured` | 保存和内联 schema、函数辅助原生文件、精确 JSON/SSE、大整数、schema 准入、取消和文本覆盖 | 声明支持结构化输出和函数的工作区 |
| `composition` | 冻结的源快照、初始字节、有序 setup、包、Skills、stdio MCP、继续执行和取消 | `openai_hosted` |

对于 `composition`,设置中的 `environment` 必须恰好为 `{"type":"openai_hosted"}`;套件创建自己的 Template、文件和 Skill 来源。它检查初始二进制字节、有序 setup、npm 和 Python 包、上传的 Skill、插件 Skill 和目录 Skill,以及三个真实 stdio MCP 工具的身份、Item 和结果。更改或删除源资源后,它通过热继续执行验证冻结的准备结果;选用重启时,还通过现有的 Compose 验证 agent-host 重启流程进行检查。取消必须使 MCP 后代进程停止产生文件副作用。套件清理其创建的全部资源。

私有所有者与凭据隔离仍为 `unverified`;肯定性的 canary 证据需要使用操作员拥有的资源独立验证。套件不请求当前契约拒绝的 `packages.system` 或 stdio MCP `env_vars`。

`tool-search` 套件证明延迟回调通过 Core 执行;锁定的公共协议没有必需的发现事件,因此它不声称观察到了原生 ToolSearch 调用。`structured` 区分有损 schema 数字的拒绝与精确保留的大整数最终文本。`policies` 记录观察到的工具禁用行为,不代表网络隔离,也不能证明模型遵循了 verbosity;Codex 的 low/high 执行需要原生 catalog 支持,不支持的选择会使验收失败。`steering` 要求输入提交时原始原生 Turn 仍活跃。其公共幂等性检查不观察 ACP 重复回执,原生接收也不保证模型采用输入。各套件的证据保留这些限制。

对于 `self_hosted`,选择自定义绝对 `workspace_directory`。运行器打印每个新 Session ID 后,使用该 Session 的公共安装命令连接独立的隔离机器或容器;运行器最多等待五分钟。多个 Session 不得共享工作区。独立的 `official_environment_files_native.py` 检查接受两个已连接的 self-hosted Session,通过 Environment owner 验证 Files.list 排序、分页和隔离。

默认验证热继续执行,并将冷恢复记录为 `unverified`。验证冷继续执行时,额外传入指向所拥有安装的绝对目录的 `--compose-directory`,以及指定其精确项目名称的 `--compose-project`。运行器仅重启该项目的 `agent-host`,确认容器启动时间已改变,然后执行相同的历史断言。这不能证明 Core 重启或 sandbox 检查点恢复。`pending-actions` 套件重连的是公共客户端,而非 agent-host 进程,因此拒绝这些重启选项。仅在[声明和覆盖台账](./index.md#known-gaps) 支持时选择冷恢复;不支持的恢复仍是缺口,不能把跳过的检查记为成功。API 拒绝会使所选套件失败。
默认验证热继续执行,并将冷恢复记录为 `unverified`。验证冷继续执行时,额外传入指向所拥有安装的绝对目录的 `--compose-directory`,以及指定其精确项目名称的 `--compose-project`。运行器仅重启该项目的 `agent-host`,确认容器启动时间已改变,然后执行相同的历史断言。这不能证明 Core 重启或 sandbox 检查点恢复。`pending-actions`、`policies` 和 `steering` 套件不验证进程重启,因此拒绝这些选项。仅在[声明和覆盖台账](./index.md#known-gaps) 支持时选择冷恢复;不支持的恢复仍是缺口,不能把跳过的检查记为成功。API 拒绝会使所选套件失败。

`none` 套件依据固定版本 schema 校验 Session、Turn、Item 和事件的必需字段及可空字段。原生 Turn 提供用量测量时,它会对比终止事件与已存储 Turn,并将测量值求和核对 Session 总量。未知用量保留为 `null`,每个受影响 Turn 都列入证据的 `proof.unverified`;套件通过不代表这些 Turn 已验证原生用量测量支持。

使用锁定的 SDK 运行 `python -m unittest discover -s services/core/tests -p qualify_public_native_test.py`,可在不调用模型的情况下检查凭据处理和所拥有的重启边界。现有确定性 Core 集成测试仍负责 schema 验证、原子准入、持久化回执和拒绝语义。真实模型结果仅证明所选套件、协议、Harness 和放置方式。Provider 生命周期、原生身份、凭据隔离、延迟发现和未选择的套件需要独立证据;仅通过 view 测试不能证明公共调用路径。
使用锁定的 SDK 运行 `python -m unittest discover -s services/core/tests -p qualify_public_native_test.py`,可在不调用模型的情况下检查凭据处理和所拥有的重启边界。现有确定性 Core 集成测试仍负责 schema 验证、原子准入、持久化回执和拒绝语义。真实模型结果仅证明所选套件、协议、Harness 和放置方式。Provider 生命周期、原生身份、凭据隔离和未选择的套件需要独立证据;仅通过 view 测试不能证明公共调用路径。

## 原生版本固定 {#native-version-pins}

Expand Down
Loading
Loading