From 336898ed16d899594c8975bc702346e8e68cb5e2 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Fri, 16 Oct 2026 16:40:23 +0800
Subject: [PATCH 01/74] Keep only the code review in post-merge CI (#741)
The post-merge Docs review doubled the review's runner time and model
tokens without gating anything. Return the workflow to the single
review that reads the PR's checks and sends the Feishu card itself, and
delete the scripts that only the split reviews used.
Native checks also archived the distribution on every run although only
manual packaging and releases upload it; archive only when uploading.
---
.github/workflows/ci-review.yml | 103 ++++++--------------
.github/workflows/native.yml | 1 +
docs/maintainers.md | 6 +-
docs/zh/maintainers.md | 8 +-
scripts/ci_review.py | 163 --------------------------------
scripts/ci_review_test.py | 132 --------------------------
6 files changed, 35 insertions(+), 378 deletions(-)
delete mode 100644 scripts/ci_review.py
delete mode 100644 scripts/ci_review_test.py
diff --git a/.github/workflows/ci-review.yml b/.github/workflows/ci-review.yml
index 2bc1069bd..0cd33e664 100644
--- a/.github/workflows/ci-review.yml
+++ b/.github/workflows/ci-review.yml
@@ -16,28 +16,12 @@ permissions:
jobs:
review:
- name: ${{ matrix.name }}
- strategy:
- fail-fast: false
- matrix:
- include:
- - kind: code
- name: Code review
- instructions: |
- 检查本次代码改动的正确性、仓库设计规则及已有 CI 结果。先读取 AGENTS.md 和 CONTRIBUTING.md，再查看相关实现和测试。
- 用 gh pr checks 查询这个 PR 已有的检查结果，必要时读取 Actions 日志。检查失败、缺失或尚未完成时如实报告，不把合并当作检查通过的证据。
- 报告包括实际行为变化（1–3 条）、代码审查结论和 CI 状态。全部正常时保持简短；有问题时给出文件与行号、证据和最小修改建议。
- - kind: docs
- name: Docs review
- instructions: |
- 每次都检查文档与本次代码变化是否一致，即使 PR 没改文档。读取相关实现、测试和完整文档，核对平台、命令、配置、路径、默认值、接口和操作流程，找出遗漏更新或已经过时的说明。
- 文档有修改（包括新增、删除和重命名）时，再检查文档内部及同主题文档间的矛盾、重复维护的事实、主题归属和中英文含义。按 AGENTS.md 和 CONTRIBUTING.md 的 Documentation ownership 表判断位置。必要的概述加链接、中英文对照和同一来源生成的文档不算重复。
- 分别报告“文档与代码一致性”和“文档矛盾、重复与归属”。未改文档时，第二项写“本次未修改文档”。只报告本次修改引入或使之过时的、有依据的问题，给出文件与行号、对应代码或文档依据，以及最小修改建议。测试或链接检查通过不代表语义一致。只报告影响读者理解或操作的具体问题，不把未穷举实现细节当作文档缺陷。
if: github.event.pull_request.merged == true
runs-on: ${{ vars.OAC_USE_GITHUB_RUNNERS == 'true' && 'ubuntu-24.04' || 'blacksmith-2vcpu-ubuntu-2404' }}
timeout-minutes: 30
env:
- # Keep GH_TOKEN available to read the PR and Actions logs.
+ # allowed_non_write_users turns on a subprocess secret scrub; opt out so Claude's
+ # commands can read GH_TOKEN and the Feishu webhook.
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: '0'
steps:
# The triggering revision is already on main, so its rules and code are trusted.
@@ -46,15 +30,14 @@ jobs:
ref: ${{ github.event.pull_request.merge_commit_sha }}
fetch-depth: 2
persist-credentials: false
- - name: Prepare the report schema
- id: schema
- run: python3 scripts/ci_review.py schema "${{ matrix.kind }}" >> "$GITHUB_OUTPUT"
- - name: Review with Claude Code
- id: llm
+ - name: Review and send Feishu card with Claude Code
+ # Notification is best effort: a failed review or delivery never fails the job.
continue-on-error: true
timeout-minutes: 25
uses: anthropics/claude-code-action@12dd8d74c712f5f3669365b2369b558c495b1104 # v1
env:
+ FEISHU_WEBHOOK_URL: ${{ secrets.FEISHU_WEBHOOK_URL }}
+ FEISHU_WEBHOOK_SECRET: ${{ secrets.FEISHU_WEBHOOK_SECRET }}
ANTHROPIC_BASE_URL: https://api.minimax.cn/anthropic
ANTHROPIC_AUTH_TOKEN: ${{ secrets.MINIMAX_API_KEY }}
CLAUDE_CODE_AUTO_COMPACT_WINDOW: '524288'
@@ -71,57 +54,29 @@ jobs:
allowed_bots: '*'
allowed_non_write_users: '*'
prompt: |
- 你负责本次 PR 的 ${{ matrix.name }}，在独立上下文中完成审查。
- 仓库：${{ github.repository }}；PR：#${{ github.event.pull_request.number }}。
- 合并提交：${{ github.event.pull_request.merge_commit_sha }}，已检出到当前目录。
- 先用 gh pr diff ${{ github.event.pull_request.number }} --repo ${{ github.repository }} 读取变更清单与完整差异，再检查相关文件。
+ 你是 CI 的负责人，负责审核 CI 结果并给出结论。
+ 仓库 ${{ github.repository }} 的 PR #${{ github.event.pull_request.number }} 已合入 main：
+ - PR：https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}
+ - 合并 commit：${{ github.event.pull_request.merge_commit_sha }}（已 checkout 到当前目录）
- ${{ matrix.instructions }}
+ 用 gh pr checks ${{ github.event.pull_request.number }} --repo ${{ github.repository }} 查询这个 PR 已有的检查结果，必要时读取对应 Actions 日志。不要触发新的 CI，也不要把合并本身当作检查通过的证据；管理员可能绕过门禁。检查失败、缺失或尚未完成时如实报告。
- 按 JSON schema 返回中文报告。status 为 ok（未发现问题）、issues（发现有证据的问题）或 incomplete（审查失败、范围未检查完整或检查结果尚未完成）。有问题且仍有未检查项时，用 issues 并在对应字段中说明缺项。按 schema 把各项结论分别填入字段，不要重复标题；changes 用 1–3 条 Markdown 列表，其他字段无问题时一句话，有问题时保留依据和建议，遵守各字段长度限制。
- 围绕本次 diff 和受影响的文档展开，证据充分后输出结果，避免重复核对同一结论。
- 只读审查，不修改仓库，不触发新的 CI，不发送消息。两份报告会由后续 job 合并发送。
- claude_args: >-
- --allowedTools Bash Read Glob Grep
- --json-schema '${{ steps.schema.outputs.schema }}'
- - name: Save the review result
- if: always()
- env:
- REVIEW_OUTCOME: ${{ steps.llm.outcome }}
- REVIEW_RESULT: ${{ steps.llm.outputs.structured_output }}
- run: python3 scripts/ci_review.py collect "${{ matrix.kind }}" "$RUNNER_TEMP/review-${{ matrix.kind }}.json"
- - uses: actions/upload-artifact@v6
- if: always()
- with:
- name: ci-review-${{ matrix.kind }}
- path: ${{ runner.temp }}/review-${{ matrix.kind }}.json
- if-no-files-found: error
- overwrite: true
- retention-days: 7
+ 任务：给飞书群发一张中文卡片（Card 2.0）总结这次 CI，尽量在 10 轮以内给出结论，工具调用尽可能的并行。
+ 环境里有 gh（已登录，GH_TOKEN）、git、node 和完整的仓库代码。
- notify:
- name: Combined Feishu notification
- needs: review
- if: always() && github.event.pull_request.merged == true
- runs-on: ${{ vars.OAC_USE_GITHUB_RUNNERS == 'true' && 'ubuntu-24.04' || 'blacksmith-2vcpu-ubuntu-2404' }}
- timeout-minutes: 5
- permissions:
- contents: read
- actions: read
- steps:
- - uses: actions/checkout@v7
- with:
- ref: ${{ github.event.pull_request.merge_commit_sha }}
- persist-credentials: false
- - uses: actions/download-artifact@v6
- continue-on-error: true
- with:
- pattern: ci-review-*
- merge-multiple: true
- path: ${{ runner.temp }}/reviews
- - name: Send one card with both results
- continue-on-error: true
- env:
- FEISHU_WEBHOOK_URL: ${{ secrets.FEISHU_WEBHOOK_URL }}
- FEISHU_WEBHOOK_SECRET: ${{ secrets.FEISHU_WEBHOOK_SECRET }}
- run: python3 scripts/ci_review.py notify "$RUNNER_TEMP/reviews"
+ 卡片要让手机上的读者快速看懂，如果一切正常，表达的尽可能简单，如果没有问题，尽量简洁：
+ 1. 哪个 PR（github id + PR 标题 + 链接）
+ - 如：`github id: jing332, PR 标题: 添加一个新功能, 链接: https://github.com/org/repo/pull/123`
+ 2. 改了什么（实际行为变化，1–3 条）
+ - 如：`添加了一个新功能、修改了 web 和 backend 的 CI`
+ 3. 是否符合仓库规则（AGENTS.md、CONTRIBUTING.md 及相关文档）：未发现明确违规 / 发现需修复问题 / 信息不足，无法确认
+ - 如：`符合仓库规则`
+ 4. CI 哪里失败、可能的原因（可以看日志），全部通过就直接说通过，不要给出细节。如果 CI 失败，则详细说明。
+ - 如：`CI 失败，具体是哪几个失败；全部通过 ✅`
+
+ 发送：webhook 地址在环境变量 FEISHU_WEBHOOK_URL。
+ 响应 code=0 才算成功，失败就排查并重试，直到发出去。最后用一句中文说明结果，如：`CI 结果已发送至飞书群`。
+ 不要在输出里打印 webhook 地址和密钥。
+ claude_args: >-
+ --allowedTools Bash Read Write Edit Glob Grep WebFetch WebSearch
+ --max-turns 30
diff --git a/.github/workflows/native.yml b/.github/workflows/native.yml
index 4047bdf3c..2511a7908 100644
--- a/.github/workflows/native.yml
+++ b/.github/workflows/native.yml
@@ -146,6 +146,7 @@ jobs:
fi
node scripts/native-harness-smoke.mjs --codex-binary "$RUNNER_TEMP/native-installer/components/codex/bin/codex${{ runner.os == 'Windows' && '.exe' || '' }}" --claude-runtime "$RUNNER_TEMP/native-installer/components/claude"
- name: Archive the native distribution
+ if: inputs.upload-artifacts
run: |
cd "$RUNNER_TEMP"
tar -C native-installer -czf "oac-native-installer-${{ runner.os }}-${{ runner.arch }}.tar.gz" .
diff --git a/docs/maintainers.md b/docs/maintainers.md
index 8ee15c1d4..9b35222b5 100644
--- a/docs/maintainers.md
+++ b/docs/maintainers.md
@@ -197,11 +197,9 @@ The final `check` runs even when planning or a dependency fails. It requires a s
Use **Actions → core-check → Run workflow** for a manual full check. For a transient failure, use GitHub's **Re-run failed jobs** so successful jobs remain completed. PR updates cancel the superseded run through Actions concurrency. Build and dependency caches speed execution; they do not stand in for successful tests. Native release installers are passed between jobs using Actions artifacts, within the same release workflow.
-The `CI review and Feishu notification` workflow runs after a PR merges into main. A matrix runs **Code review** and **Docs review** in independent LLM contexts with `fail-fast: false`. Both read the merged commit and PR diff. Code review checks implementation, repository rules and existing CI results; it does not start another test run. Docs review checks changed behavior against documentation even when no docs changed. When docs change, it also checks contradictions, duplicated facts, topic ownership under CONTRIBUTING, and English/Chinese agreement. Findings include file and line references, supporting evidence and a minimal correction. Reviews read the repository without editing it.
+The `CI review and Feishu notification` workflow runs once after a PR merges into main. It checks out the merged commit, reads that PR's existing checks and logs, and sends one Feishu card through `FEISHU_WEBHOOK_URL` that summarizes the change, its fit with the repository rules and the actual CI status. It does not trigger another test run, and a failed review or delivery never fails the job or blocks merges. Closing an unmerged PR does not invoke the review. The workflow uses `pull_request_target` only for the merged event and never checks out an unmerged PR head with notification credentials.
-Each review returns a structured result (`ok`, `issues` or `incomplete`) and Chinese sections, retained as an Actions artifact for seven days. **Combined Feishu notification** waits for both jobs and sends one Card 2.0 message containing both results through the existing `FEISHU_WEBHOOK_URL`; `FEISHU_WEBHOOK_SECRET` optionally signs it. The card uses fixed sections for PR details, behavior changes, code and repository rules, CI results, and documentation review, separated by dividers. Its header shows green for no findings, red for findings, and yellow for an incomplete review without findings. Only this notification job receives the webhook secrets. Failed, missing or invalid reports appear as incomplete, alongside any available result from the other review. The notification job runs even when a review fails. Delivery requires Feishu's `code=0` response; a failed or ambiguous request is not automatically retried, avoiding duplicate messages. Each review has a 25-minute execution timeout. Review and delivery failures do not block merges, and closing an unmerged PR does not trigger this workflow. The workflow checks out only the merged commit with notification credentials.
-
-Browser jobs own separate fixtures and servers; increasing workers against the shared mutable fixture is unsafe. Failed browser jobs retain reports/traces for seven days. Native failure phase summaries are retained for seven days and detailed output stays in the Actions logs; credentials and temporary installation trees are not uploaded. Successful native archives are uploaded only for explicit manual packaging or releases, without recompressing the compressed archive. Release distribution artifacts retain their existing recovery policy; failed publication can reuse the original build as described above.
+Browser jobs own separate fixtures and servers; increasing workers against the shared mutable fixture is unsafe. Failed browser jobs retain reports/traces for seven days. Native failure phase summaries are retained for seven days and detailed output stays in the Actions logs; credentials and temporary installation trees are not uploaded. Native archives are built and uploaded only for explicit manual packaging or releases, without recompressing the compressed archive. Release distribution artifacts retain their existing recovery policy; failed publication can reuse the original build as described above.
The local Node composite action installs the pinned pnpm and caches its package store by lockfile, OS, architecture, Node version and pnpm version. It caches downloaded packages, not `node_modules`; installs remain frozen. Go partitions retain the existing module/compiler caches described under [publication](#publish-a-version). Cache hits seed work and never replace tests. The three native platforms run independently; parallel execution reduces elapsed time without reducing total machine time.
diff --git a/docs/zh/maintainers.md b/docs/zh/maintainers.md
index 7597b1a9d..54f90d296 100644
--- a/docs/zh/maintainers.md
+++ b/docs/zh/maintainers.md
@@ -1,7 +1,7 @@
---
title: "构建并发布 OpenAgentCore"
source: docs/maintainers.md
-source_hash: 18bb1549e69536abfe758b043e8621e77899a848efa8613760f7aff728afd63e
+source_hash: 54f4b7ee078787c3882562193b896fb570b137ba473a6cb0d56f6a355ef3b17a
---
本指南面向负责构建和发布 OpenAgentCore 的维护者。要安装 Core 和 Web，请使用 [安装指南](getting-started/install.md)。安装器代码遵循的规则见 [部署](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/README.md) 和 [节点安装器](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md)；必需检查见 [CONTRIBUTING](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/CONTRIBUTING.md#required-checks)。
@@ -199,11 +199,9 @@ Go 模块和工作区输入会选择后端、API（包括容器）、原生和
要手动执行完整检查，请使用 **Actions → core-check → Run workflow**。遇到暂时性故障时，请使用 GitHub 的 **Re-run failed jobs**，这样已成功的作业可保持完成状态。PR 更新后，Actions 并发机制会取消已被取代的运行。构建和依赖项缓存可加快执行，但不能替代成功的测试。原生发布安装器通过 Actions 构建产物在同一发布工作流的不同作业之间传递。
-`CI review and Feishu notification` 工作流在 PR 合入 main 后运行。矩阵中的 **Code review** 和 **Docs review** 使用独立的 LLM 上下文，并设置 `fail-fast: false`。两者读取合并后的提交和 PR 差异。代码审查检查实现、仓库规则和已有 CI 结果，不触发新一轮测试。文档审查会核对行为变化与文档是否一致，即使没有修改文档；修改文档时，还会检查矛盾、重复维护的事实、CONTRIBUTING 规定的主题归属及中英文含义。每项问题包含文件和行号、依据及最小修改建议。审查只读取仓库，不修改文件。
+`CI review and Feishu notification` 工作流仅在 PR 合并到 main 后运行一次。它检出合并后的提交，读取该 PR 已有的检查和日志，通过 `FEISHU_WEBHOOK_URL` 发送一张飞书卡片，概述本次改动、是否符合仓库规则以及实际 CI 状态。它不会触发另一轮测试；审查或发送失败不会让作业失败，也不会阻止合并。关闭未合并 PR 不触发审查。该工作流只针对合并事件使用 `pull_request_target`，绝不在持有通知凭据时检出未合并 PR 的 head。
-每项审查返回结构化结果（`ok`、`issues` 或 `incomplete`）及分项中文结论，作为 Actions 构建产物保留七天。**Combined Feishu notification** 等待两项审查结束，通过已有的 `FEISHU_WEBHOOK_URL` 发送一张包含两份结果的 Card 2.0 卡片；可选的 `FEISHU_WEBHOOK_SECRET` 用于签名。卡片固定分为 PR 信息、行为变化、代码与仓库规则、CI 结果和文档审查，各区之间使用分隔线。未发现问题时标题为绿色，发现问题时为红色，审查未完成且尚未发现问题时为黄色。只有通知 job 能读取 webhook 密钥。审查失败、报告缺失或格式无效时标为未完成，另一项已有的结果照常展示。某项审查失败时，通知 job 仍会运行。只有飞书返回 `code=0` 才确认送达；请求失败或送达状态不明时不自动重试，以免重复发消息。每项审查的执行超时为 25 分钟。审查和发送失败不会阻止合并；关闭未合并的 PR 不触发此流程。持有通知凭据时，工作流只检出合并后的提交。
-
-浏览器作业各自拥有独立的固定数据和服务；对共享可变固定数据增加 worker 数不安全。失败的浏览器作业保留报告与 trace 七天。原生失败阶段摘要保留七天，详细输出留在 Actions 日志中；凭据和临时安装目录不上传。成功的原生归档仅用于显式手动打包或发布时上传，不重新压缩已压缩的归档。发布分发产物保留现有恢复策略；失败发布可以按前述方式复用原构建。
+浏览器作业各自拥有独立的固定数据和服务；对共享可变固定数据增加 worker 数不安全。失败的浏览器作业保留报告与 trace 七天。原生失败阶段摘要保留七天，详细输出留在 Actions 日志中；凭据和临时安装目录不上传。原生归档仅在显式手动打包或发布时构建并上传，不重新压缩已压缩的归档。发布分发产物保留现有恢复策略；失败发布可以按前述方式复用原构建。
本地 Node 复合操作会安装固定版本的 pnpm，并根据锁文件、OS、架构、Node 版本和 pnpm 版本缓存其软件包存储。它缓存下载的软件包，而不是 `node_modules`；安装仍保持冻结状态。Go 分区会保留[发布](#publish-a-version)部分所述的现有模块/编译器缓存。三个原生平台独立运行；并行执行可缩短总耗时，但不会减少机器总时间。
diff --git a/scripts/ci_review.py b/scripts/ci_review.py
deleted file mode 100644
index e7fb16645..000000000
--- a/scripts/ci_review.py
+++ /dev/null
@@ -1,163 +0,0 @@
-#!/usr/bin/env python3
-"""Collect independent review reports and deliver one Feishu card."""
-
-import argparse
-import base64
-import hashlib
-import hmac
-import json
-import os
-from pathlib import Path
-import re
-import time
-import urllib.error
-import urllib.request
-
-
-STATUSES = {"ok": "未发现问题", "issues": "发现问题", "incomplete": "未完成"}
-MAX_SECTION = 900
-REPORT_FIELDS = {
- "code": {"changes": "实际行为变化，1–3 条 Markdown 列表", "review": "代码正确性与仓库规则审查结论", "ci": "已有 CI 结果；失败或未完成时给出具体检查项"},
- "docs": {"consistency": "文档与代码一致性", "organization": "文档矛盾、重复与归属；未改文档时写本次未修改文档"},
-}
-
-
-def report_schema(kind):
- properties = {"status": {"type": "string", "enum": list(STATUSES)}}
- properties.update({name: {"type": "string", "minLength": 1, "maxLength": MAX_SECTION, "description": description}
- for name, description in REPORT_FIELDS[kind].items()})
- return {"type": "object", "properties": properties, "required": list(properties), "additionalProperties": False}
-
-
-def incomplete(reason, kind):
- fields = dict.fromkeys(REPORT_FIELDS[kind], "未完成。")
- fields[next(iter(fields))] = reason
- return {"status": "incomplete", **fields}
-
-
-def parse_report(raw, kind):
- try:
- report = json.loads(raw)
- except (ValueError, TypeError):
- return incomplete("未收到有效报告，请查看审查日志。", kind)
- if (not isinstance(report, dict) or set(report) != {"status", *REPORT_FIELDS[kind]}
- or not isinstance(report["status"], str) or report["status"] not in STATUSES
- or any(not isinstance(report[name], str) or not report[name].strip()
- or len(report[name]) > MAX_SECTION for name in REPORT_FIELDS[kind])):
- return incomplete("报告格式不完整，请查看审查日志。", kind)
- return report
-
-
-def collect(outcome, raw, kind):
- if outcome != "success":
- return incomplete("审查未成功结束，请查看审查日志。", kind)
- return parse_report(raw, kind)
-
-
-def read_report(directory, kind):
- try:
- return parse_report((directory / f"review-{kind}.json").read_text(), kind)
- except (OSError, UnicodeError):
- return incomplete("审查报告缺失，请查看审查日志。", kind)
-
-
-def markdown_text(value):
- return re.sub(r"([\\`*_{}\[\]()<>!])", r"\\\1", value)
-
-
-def build_card(event, reports, run_url):
- pr = event["pull_request"]
- statuses = {report["status"] for report in reports.values()}
- color = "red" if "issues" in statuses else "yellow" if "incomplete" in statuses else "green"
- heading = "❌ 审查发现问题" if "issues" in statuses else "⚠️ 审查未完成" if "incomplete" in statuses else "✅ 审查通过"
- code, docs = reports["code"], reports["docs"]
-
- def text(value):
- # Feishu mentions use HTML-like tags; reports are ordinary Markdown.
- return value.replace("<", "<").replace(">", ">")
-
- sections = [
- ("1. 哪个 PR", f"**github id:** {markdown_text(pr['user']['login'])}\n"
- f"**标题:** {markdown_text(pr['title'][:200])}\n**链接:** [PR #{pr['number']}]({pr['html_url']})"),
- ("2. 改了什么", text(code["changes"])),
- ("3. 代码与仓库规则", text(code["review"])),
- ("4. CI 结果", text(code["ci"])),
- (f"5. 文档审查 · {STATUSES[docs['status']]}",
- f"**文档与代码一致性**\n{text(docs['consistency'])}\n\n"
- f"**文档矛盾、重复与归属**\n{text(docs['organization'])}"),
- ]
- elements = []
- for title, content in sections:
- if elements:
- elements.append({"tag": "hr"})
- elements.append({"tag": "markdown", "content": f"**{title}**\n\n{content}"})
- elements.append({"tag": "markdown", "content": f"[查看审查日志]({run_url})"})
- return {
- "msg_type": "interactive",
- "card": {
- "schema": "2.0",
- "header": {"template": color, "title": {"tag": "plain_text", "content": f"{heading} · PR #{pr['number']}"}},
- "body": {"elements": elements},
- },
- }
-
-
-def card_markdown(card):
- return "\n\n".join("---" if element["tag"] == "hr" else element["content"]
- for element in card["card"]["body"]["elements"]) + "\n"
-
-
-def send_card(webhook, secret, card):
- if not webhook:
- raise ValueError("FEISHU_WEBHOOK_URL is not configured")
- payload = dict(card)
- if secret:
- timestamp = str(int(time.time()))
- key = f"{timestamp}\n{secret}".encode()
- payload.update(timestamp=timestamp, sign=base64.b64encode(hmac.new(key, b"", hashlib.sha256).digest()).decode())
- data = json.dumps(payload, ensure_ascii=False).encode()
- if len(data) > 20000:
- raise ValueError("Review card exceeds the webhook message size limit")
- request = urllib.request.Request(webhook, data=data, headers={"Content-Type": "application/json"}, method="POST")
- # A timeout may follow successful delivery; retrying could send a duplicate.
- try:
- with urllib.request.urlopen(request, timeout=30) as response:
- result = json.load(response)
- except (OSError, ValueError, urllib.error.URLError):
- raise ValueError("Feishu delivery failed; delivery status is unknown") from None
- if not isinstance(result, dict) or type(result.get("code")) is not int or result["code"] != 0:
- raise ValueError("Feishu did not confirm delivery")
-
-
-def main():
- parser = argparse.ArgumentParser(description=__doc__)
- commands = parser.add_subparsers(dest="command", required=True)
- commands.add_parser("schema").add_argument("kind", choices=REPORT_FIELDS)
- collector = commands.add_parser("collect")
- collector.add_argument("kind", choices=REPORT_FIELDS)
- collector.add_argument("output", type=Path)
- commands.add_parser("notify").add_argument("directory", type=Path)
- args = parser.parse_args()
- if args.command == "schema":
- print("schema=" + json.dumps(report_schema(args.kind), separators=(",", ":")))
- elif args.command == "collect":
- report = collect(os.environ.get("REVIEW_OUTCOME"), os.environ.get("REVIEW_RESULT", ""), args.kind)
- args.output.write_text(json.dumps(report, ensure_ascii=False))
- else:
- event = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text())
- reports = {kind: read_report(args.directory, kind) for kind in ("code", "docs")}
- run_url = f"{os.environ['GITHUB_SERVER_URL']}/{os.environ['GITHUB_REPOSITORY']}/actions/runs/{os.environ['GITHUB_RUN_ID']}"
- card = build_card(event, reports, run_url)
- summary = os.environ.get("GITHUB_STEP_SUMMARY")
- if summary:
- with open(summary, "a") as output:
- output.write(card_markdown(card))
- send_card(os.environ.get("FEISHU_WEBHOOK_URL"), os.environ.get("FEISHU_WEBHOOK_SECRET"), card)
- print("代码与文档审查结果已合并发送至飞书群。")
-
-
-if __name__ == "__main__":
- try:
- main()
- except ValueError as error:
- raise SystemExit(str(error)) from None
diff --git a/scripts/ci_review_test.py b/scripts/ci_review_test.py
deleted file mode 100644
index c80fdfd99..000000000
--- a/scripts/ci_review_test.py
+++ /dev/null
@@ -1,132 +0,0 @@
-#!/usr/bin/env python3
-"""Exercise combined notification and incomplete-review behavior without sending messages."""
-
-import io
-import json
-from pathlib import Path
-import tempfile
-import unittest
-from unittest.mock import patch
-
-import ci_review as review
-
-
-class ReviewTests(unittest.TestCase):
- event = {"pull_request": {"number": 485, "title": "Review docs", "html_url": "https://github.com/org/repo/pull/485", "user": {"login": "author"}}}
- run_url = "https://github.com/org/repo/actions/runs/123"
-
- def setUp(self):
- self.ok = {"status": "ok", "changes": "- 更新安装流程", "review": "未发现问题", "ci": "全部通过 ✅"}
- self.docs = {"status": "ok", "consistency": "与代码一致", "organization": "无矛盾或重复"}
-
- def card(self, code=None, docs=None):
- return review.build_card(self.event, {"code": code or self.ok, "docs": docs or self.docs}, self.run_url)
-
- @patch("ci_review.urllib.request.urlopen")
- def test_two_reports_make_one_delivery(self, post):
- post.return_value = io.BytesIO(b'{"code":0}')
- card = self.card(docs={**self.docs, "status": "issues", "consistency": "docs/install.md:12 与代码不符"})
- review.send_card("https://example.invalid/webhook", "", card)
- post.assert_called_once()
- payload = json.loads(post.call_args.args[0].data)
- self.assertEqual(payload["card"]["schema"], "2.0")
- self.assertEqual(payload["card"]["header"]["template"], "red")
- text = review.card_markdown(payload)
- self.assertIn("3. 代码与仓库规则", text)
- self.assertIn("文档审查 · 发现问题", text)
- self.assertIn("docs/install.md:12", text)
- self.assertIn(self.run_url, text)
- self.assertNotIn("sign", payload)
-
- def test_fixed_sections_preserve_markdown_and_separators(self):
- card = self.card()
- elements = card["card"]["body"]["elements"]
- self.assertEqual(sum(element["tag"] == "hr" for element in elements), 4)
- text = review.card_markdown(card)
- for heading in ("1. 哪个 PR", "2. 改了什么", "3. 代码与仓库规则", "4. CI 结果", "5. 文档审查"):
- self.assertIn(heading, text)
- self.assertIn("- 更新安装流程", text)
- self.assertIn("全部通过 ✅", text)
- self.assertIn("文档与代码一致性", text)
- self.assertIn("文档矛盾、重复与归属", text)
- self.assertIn("---", text)
- self.assertEqual(card["card"]["header"]["template"], "green")
- self.assertIn("✅ 审查通过", card["card"]["header"]["title"]["content"])
-
- def test_pending_ci_does_not_label_the_code_review_incomplete(self):
- card = self.card(code={**self.ok, "status": "incomplete", "ci": "backend 仍在运行"})
- text = review.card_markdown(card)
- self.assertIn("**3. 代码与仓库规则**", text)
- self.assertIn("未发现问题", text)
- self.assertIn("backend 仍在运行", text)
- self.assertEqual(card["card"]["header"]["template"], "yellow")
-
- def test_each_kind_requires_its_own_sections(self):
- for kind, report in (("code", self.ok), ("docs", self.docs)):
- self.assertEqual(review.parse_report(json.dumps(report), kind), report)
- self.assertEqual(set(review.report_schema(kind)["required"]), set(report))
- for field in review.REPORT_FIELDS[kind]:
- for value in (None, " ", "x" * (review.MAX_SECTION + 1)):
- invalid = {**report, field: value}
- self.assertEqual(review.parse_report(json.dumps(invalid), kind)["status"], "incomplete")
- missing = {key: value for key, value in report.items() if key != field}
- self.assertEqual(review.parse_report(json.dumps(missing), kind)["status"], "incomplete")
-
- def test_failed_action_cannot_publish_a_success_report(self):
- for outcome in ("failure", "cancelled", "skipped", None):
- with self.subTest(outcome=outcome):
- result = review.collect(outcome, json.dumps(self.ok), "code")
- self.assertEqual(result["status"], "incomplete")
- self.assertEqual(self.card(code=result)["card"]["header"]["template"], "yellow")
-
- def test_invalid_or_missing_reports_are_incomplete(self):
- for raw in ("", "not json", "null", "[]", '{"status":"ok"}', '{"status":[],"summary":"x"}', '{"status":"ok","summary":" "}', json.dumps({"status": "ok", "summary": "x" * 2001})):
- with self.subTest(raw=raw[:50]):
- self.assertEqual(review.collect("success", raw, "code")["status"], "incomplete")
- root = Path.home() / ".oac/tests"
- root.mkdir(parents=True, exist_ok=True)
- with tempfile.TemporaryDirectory(dir=root) as directory:
- path = Path(directory)
- (path / "review-code.json").write_text(json.dumps(self.ok))
- self.assertEqual(review.read_report(path, "code"), self.ok)
- self.assertEqual(review.read_report(path, "docs")["status"], "incomplete")
-
- @patch("ci_review.urllib.request.urlopen")
- def test_http_success_requires_feishu_confirmation(self, post):
- for body in (b'{"code":19021}', b'{}', b'{"code":false}', b'not json'):
- with self.subTest(body=body):
- post.reset_mock()
- post.return_value = io.BytesIO(body)
- with self.assertRaises(ValueError):
- review.send_card("https://example.invalid/webhook", "", self.card())
- post.assert_called_once()
-
- @patch("ci_review.urllib.request.urlopen", side_effect=TimeoutError("private-webhook"))
- def test_ambiguous_delivery_is_not_retried_or_logged_with_secrets(self, post):
- with self.assertRaisesRegex(ValueError, "delivery status is unknown") as error:
- review.send_card("https://example.invalid/private-webhook", "private-signing-key", self.card())
- self.assertNotIn("private", str(error.exception))
- post.assert_called_once()
-
- @patch("ci_review.time.time", return_value=1700000000)
- @patch("ci_review.urllib.request.urlopen")
- def test_optional_signing(self, post, _clock):
- post.return_value = io.BytesIO(b'{"code":0}')
- review.send_card("https://example.invalid/webhook", "test-secret", self.card())
- payload = json.loads(post.call_args.args[0].data)
- self.assertEqual(payload["timestamp"], "1700000000")
- self.assertEqual(payload["sign"], "mbm4Y4oluIPQ00qlBIhX8vAZ0EKv3nw0LuTb91jPL84=")
-
- @patch("ci_review.urllib.request.urlopen")
- def test_bounded_unicode_reports_and_mentions(self, post):
- post.return_value = io.BytesIO(b'{"code":0}')
- reports = {kind: {"status": "issues", **dict.fromkeys(fields, "所有人" + "问" * (review.MAX_SECTION - 20))}
- for kind, fields in review.REPORT_FIELDS.items()}
- review.send_card("https://example.invalid/webhook", "", self.card(reports["code"], reports["docs"]))
- data = post.call_args.args[0].data
- self.assertLess(len(data), 20000)
- self.assertNotIn(b"
Date: Fri, 16 Oct 2026 18:19:32 +0800
Subject: [PATCH 02/74] Resume the launcher download across reruns (#743)
* Resume the launcher download across reruns
* Use a verified cached launcher download without asking again
A complete cached binary from an earlier run went back to the server,
which answers 416 and makes curl print an error on a terminal. Verify it
first, and remove the whole cache after a successful run.
---
deploy/install.ps1 | 1 +
deploy/install.sh | 55 ++++++++++++++++++++------
deploy/test_install.ps1 | 4 +-
deploy/test_install.py | 63 +++++++++++++++++++++++++++---
docs/getting-started/install.md | 2 +-
docs/zh/getting-started/install.md | 4 +-
6 files changed, 107 insertions(+), 22 deletions(-)
diff --git a/deploy/install.ps1 b/deploy/install.ps1
index 4fe1c05e6..cb70255d6 100644
--- a/deploy/install.ps1
+++ b/deploy/install.ps1
@@ -11,6 +11,7 @@
try { Invoke-WebRequest -UseBasicParsing -Uri "$base/$name" -OutFile (Join-Path $directory $name); return }
catch {
if ($_.Exception.Response -and [int]$_.Exception.Response.StatusCode -eq 404) { throw "Release $version not found." }
+ if ($attempt -lt 5) { Write-Host "Download interrupted; retrying ($($attempt + 1)/5)..." }
Start-Sleep -Seconds 3
}
}
diff --git a/deploy/install.sh b/deploy/install.sh
index 9cd2d63ee..d54cf33ec 100755
--- a/deploy/install.sh
+++ b/deploy/install.sh
@@ -1,5 +1,7 @@
#!/usr/bin/env bash
# The native oac command owns installation on every platform.
+# The whole script is one function called on the last line, so a cut-off download never runs partway.
+main() {
set -euo pipefail
case "$(uname -s)" in Linux) os=linux;; Darwin) os=darwin;; *) echo 'Use install.ps1 on Windows.' >&2; exit 1;; esac
case "$(uname -m)" in x86_64) arch=amd64;; arm64|aarch64) arch=arm64;; *) echo 'Unsupported CPU architecture.' >&2; exit 1;; esac
@@ -13,17 +15,24 @@ done
base="https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download"
if [[ "$version" != latest ]]; then base="https://github.com/MiniMax-AI/OpenAgentCore/releases/download/$version"; fi
umask 077
-temporary="$(mktemp -d "${TMPDIR:-/tmp}/oac.XXXXXX")"
-trap 'rm -rf "$temporary"' EXIT
+# An unfinished download stays in a per-account cache so a rerun resumes it. It does not depend on ~/.oac, which oac itself reports when it is not writable.
+cache="${TMPDIR:-/tmp}/oac-install-$(id -u)"
+[[ ! -L "$cache" ]] || { echo "Download cache $cache must not be a symbolic link." >&2; exit 1; }
+mkdir -p "$cache"
+[[ -d "$cache" && -O "$cache" ]] || { echo "Download cache $cache must belong to the current account." >&2; exit 1; }
+chmod 700 "$cache"
+trap 'echo "Interrupted; rerun the installer to continue." >&2; exit 130' INT
# Resume after resets, fail only when a download stalls (no total time cap), and give up after five attempts.
download() {
- local name="$1" progress="$2" attempt code
+ local name="$1" file="$2" progress="$3" attempt code
for attempt in 1 2 3 4 5; do
if code="$(curl --fail "$progress" --location --proto '=https' --proto-redir '=https' --connect-timeout 15 \
--speed-limit 1024 --speed-time 60 --continue-at - --write-out '%{http_code}' \
- --output "$temporary/$name" "$base/$name")"; then return 0; fi
+ --output "$cache/$file" "$base/$name")"; then return 0; fi
[[ "$code" != 404 ]] || { echo "Release $version not found." >&2; exit 1; }
- sleep 3
+ # The partial file already holds the whole download; the checksum decides.
+ [[ "$code" != 416 ]] || return 0
+ if (( attempt < 5 )); then echo "Download interrupted; retrying ($((attempt + 1))/5)..." >&2; sleep 3; fi
done
echo "Could not download $name from GitHub. Check the network (set HTTPS_PROXY if a proxy is required) and rerun the installer." >&2
exit 1
@@ -31,10 +40,32 @@ download() {
asset="oac-$os-$arch"
progress=--silent
if [[ -t 2 ]]; then progress=--progress-bar; fi
-download "$asset.sha256" --silent
-download "$asset" "$progress"
-cd "$temporary"
-if command -v sha256sum >/dev/null; then actual="$(sha256sum "$asset")"; else actual="$(shasum -a 256 "$asset")"; fi
-[[ "$actual" == "$(cat "$asset.sha256")" ]] || { rm -f "$asset"; echo 'Installer checksum mismatch. Rerun the installer to download it again.' >&2; exit 1; }
-chmod 700 "$asset"
-"./$asset" install "$@"
+# The checksum is always fetched fresh and names the cached binary, so a moved "latest" never mixes files.
+rm -f "$cache/$asset.sha256"
+download "$asset.sha256" "$asset.sha256" --silent
+expected=
+read -r expected _ < "$cache/$asset.sha256" || true
+[[ "$expected" =~ ^[0-9a-f]{64}$ ]] || { rm -f "$cache/$asset.sha256"; echo 'Installer checksum file is invalid. Rerun the installer to download it again.' >&2; exit 1; }
+binary="$cache/$asset.$expected"
+for stale in "$cache/$asset".*; do
+ [[ "$stale" == "$binary" || "$stale" == "$cache/$asset.sha256" || ! -e "$stale" ]] || rm -f "$stale"
+done
+verified() {
+ local actual=
+ if command -v sha256sum >/dev/null; then read -r actual _ < <(sha256sum "$binary"); else read -r actual _ < <(shasum -a 256 "$binary"); fi
+ [[ "$actual" == "$expected" ]]
+}
+# A complete file from an earlier run is used without asking the server for more.
+if [[ ! -s "$binary" ]] || ! verified; then
+ download "$asset" "$asset.$expected" "$progress"
+ verified || { rm -f "$binary"; echo 'Installer checksum mismatch. Rerun the installer to download it again.' >&2; exit 1; }
+fi
+chmod 700 "$binary"
+# oac reports its own interruption.
+trap - INT
+status=0
+"$binary" install "$@" || status=$?
+if (( status == 0 )); then rm -rf "$cache"; fi
+exit "$status"
+}
+main "$@"
diff --git a/deploy/test_install.ps1 b/deploy/test_install.ps1
index bf7423671..c0a19cf98 100644
--- a/deploy/test_install.ps1
+++ b/deploy/test_install.ps1
@@ -21,7 +21,7 @@ function Invoke-WebRequest {
# A failure writes one error and sets a non-zero exit code; the session stays open.
function Assert-Failure([string]$Pattern, [string[]]$Arguments = @('--help')) {
$global:LASTEXITCODE = 0
- $output = (& "$PSScriptRoot/install.ps1" @Arguments 2>&1 | Out-String)
+ $output = (& "$PSScriptRoot/install.ps1" @Arguments *>&1 | Out-String)
if ($LASTEXITCODE -eq 0 -or $output -notlike $Pattern) { throw "Expected a failure matching $Pattern, got exit $LASTEXITCODE`: $output" }
}
& "$PSScriptRoot/install.ps1" --help
@@ -35,5 +35,5 @@ Assert-Failure '*Missing release tag*' @('--version')
$testAssets.Status = 404
Assert-Failure '*Release v9.9.9 not found*' @('--version=v9.9.9')
$testAssets.Status = 503
-Assert-Failure '*Check the network*'
+Assert-Failure '*retrying (2/5)...*Check the network*'
exit 0
diff --git a/deploy/test_install.py b/deploy/test_install.py
index 0db560185..7523fe949 100644
--- a/deploy/test_install.py
+++ b/deploy/test_install.py
@@ -10,7 +10,7 @@
class LauncherTests(unittest.TestCase):
- def run_launcher(self, system='Darwin', machine='arm64', corrupt=False, arguments=('--install-dir', '/path with spaces/core', '--version', 'v1.2.3'), missing=False, outage=False):
+ def run_launcher(self, system='Darwin', machine='arm64', corrupt=False, arguments=('--install-dir', '/path with spaces/core', '--version', 'v1.2.3'), missing=False, outage=False, seed=None, interrupt=False):
with tempfile.TemporaryDirectory() as directory:
root = Path(directory)
binary = b'#!/bin/sh\nprintf "%s\\n" "$@"\n'
@@ -18,24 +18,42 @@ def run_launcher(self, system='Darwin', machine='arm64', corrupt=False, argument
scripts = {
'uname': '#!/bin/sh\nif [ "$1" = -s ]; then echo ' + system + '; else echo ' + machine + '; fi\n',
'curl': '''#!/usr/bin/env python3
-import pathlib,sys
+import os,pathlib,signal,sys,time
args=sys.argv
url=args[-1]; target=pathlib.Path(args[args.index('--output') + 1])
asset=url.rsplit('/',1)[1]
+if INTERRUPT:
+ os.kill(os.getppid(), signal.SIGINT); time.sleep(0.2); sys.exit(2)
if asset.endswith('.sha256'):
target.write_text(DIGEST + ' ' + asset.removesuffix('.sha256') + '\\n')
+elif target.exists():
+ # Like curl --continue-at -: append the rest, or answer 416 when the file is already complete.
+ have = target.stat().st_size
+ with open(HERE + '/curl.log', 'a') as log: log.write(str(have) + '\\n')
+ if have >= len(BINARY):
+ sys.stdout.write('416'); sys.exit(22)
+ with open(target, 'ab') as out: out.write(BINARY[have:])
else:
target.write_bytes(BINARY)
if OUTAGE: sys.exit(22)
if MISSING:
sys.stdout.write('404'); sys.exit(22)
-'''.replace('OUTAGE', repr(outage)).replace('MISSING', repr(missing)).replace('DIGEST', repr('0' * 64 if corrupt else digest)).replace('BINARY', repr(binary)),
+'''.replace('OUTAGE', repr(outage)).replace('MISSING', repr(missing)).replace('DIGEST', repr('0' * 64 if corrupt else digest)).replace('BINARY', repr(binary)).replace('INTERRUPT', repr(interrupt)).replace('HERE', repr(str(root))),
}
scripts['sleep'] = '#!/bin/sh\n'
for name, contents in scripts.items():
(root / name).write_text(contents); (root / name).chmod(0o700)
- return subprocess.run(['/bin/bash', str(SCRIPT), *arguments],
- env={**os.environ, 'PATH': str(root) + os.pathsep + os.environ['PATH']}, capture_output=True, text=True)
+ cache = root / f'oac-install-{os.getuid()}'
+ if seed:
+ cache.mkdir(mode=0o700)
+ for name, contents in seed.items():
+ (cache / name).write_bytes(contents)
+ result = subprocess.run(['/bin/bash', str(SCRIPT), *arguments],
+ env={**os.environ, 'TMPDIR': str(root), 'PATH': str(root) + os.pathsep + os.environ['PATH']}, capture_output=True, text=True)
+ result.cache = sorted(path.name for path in cache.iterdir()) if cache.exists() else []
+ log = root / 'curl.log'
+ result.resumed = [int(line) for line in log.read_text().split()] if log.exists() else []
+ return result
def test_linux_and_mac_share_argument_forwarding(self):
for system, machine in [('Linux', 'x86_64'), ('Linux', 'aarch64'), ('Darwin', 'arm64'), ('Darwin', 'x86_64')]:
@@ -65,6 +83,41 @@ def test_download_failures_say_what_to_do(self):
self.assertIn('Check the network', result.stderr)
self.assertEqual(result.stdout, '')
+ def test_download_failures_print_each_retry(self):
+ result = self.run_launcher(outage=True)
+ self.assertEqual(result.stderr.count('Download interrupted; retrying'), 4)
+ self.assertIn('retrying (2/5)...', result.stderr)
+
+ def test_rerun_resumes_the_unfinished_download(self):
+ binary = b'#!/bin/sh\nprintf "%s\\n" "$@"\n'
+ name = 'oac-linux-amd64.' + hashlib.sha256(binary).hexdigest()
+ result = self.run_launcher('Linux', 'x86_64', seed={name: binary[:10], 'oac-linux-amd64.' + '1' * 64: b'old'})
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual(result.resumed, [10])
+ self.assertEqual(result.cache, [])
+
+ def test_complete_cached_binary_runs_without_downloading_again(self):
+ binary = b'#!/bin/sh\nprintf "%s\\n" "$@"\n'
+ name = 'oac-linux-amd64.' + hashlib.sha256(binary).hexdigest()
+ result = self.run_launcher('Linux', 'x86_64', seed={name: binary})
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual(result.resumed, [])
+ self.assertNotIn('curl', result.stderr)
+
+ def test_corrupt_cached_file_is_discarded(self):
+ binary = b'#!/bin/sh\nprintf "%s\\n" "$@"\n'
+ name = 'oac-linux-amd64.' + hashlib.sha256(binary).hexdigest()
+ result = self.run_launcher('Linux', 'x86_64', seed={name: b'x' * (len(binary) + 5)})
+ self.assertEqual(result.returncode, 1)
+ self.assertIn('checksum mismatch', result.stderr)
+ self.assertEqual(result.stdout, '')
+ self.assertNotIn(name, result.cache)
+
+ def test_interrupt_says_how_to_continue(self):
+ result = self.run_launcher(interrupt=True)
+ self.assertEqual(result.returncode, 130)
+ self.assertIn('Interrupted; rerun the installer to continue.', result.stderr)
+
def test_corrupt_binary_is_never_executed(self):
result = self.run_launcher(corrupt=True)
self.assertNotEqual(result.returncode, 0)
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 0804e9736..bb3920985 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -57,7 +57,7 @@ The script downloads that release's Compose files, checks their SHA-256, and:
The installer prints the console address and, on a fresh install only, the Core key; a rerun or upgrade prints `oac core-key --show` instead. When the installer chose the console address itself, it adds that browsers must open exactly that address and how to change it with `OAC_PUBLIC_URL`. After signing in, configure execution resources and create Projects in Web.
-Downloads and configuration checks happen before the installation directory is published. After that, failures preserve the configuration and data. A rejected setting or data volume is reported by itself: fix it as the message says. A service that does not become healthy within three minutes is named together with the `docker compose logs --tail 50` command for it; fix the cause and rerun the same command. Ctrl-C prints `Interrupted; rerun the installer to continue.` and leaves the installation ready for that rerun. Rerun the same command, or specify the installation directory:
+Downloads and configuration checks happen before the installation directory is published. After that, failures preserve the configuration and data. A rejected setting or data volume is reported by itself: fix it as the message says. A service that does not become healthy within three minutes is named together with the `docker compose logs --tail 50` command for it; fix the cause and rerun the same command. Ctrl-C prints `Interrupted; rerun the installer to continue.` and leaves the installation ready for that rerun. On Linux and macOS the launcher keeps an unfinished `oac` download in `${TMPDIR:-/tmp}/oac-install-` and a rerun resumes it; if curl prints an error and nothing installs, rerun the same command. Rerun the same command, or specify the installation directory:
```bash
curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --install-dir "$HOME/.oac/core"
diff --git a/docs/zh/getting-started/install.md b/docs/zh/getting-started/install.md
index 88216b03f..bf44fac6c 100644
--- a/docs/zh/getting-started/install.md
+++ b/docs/zh/getting-started/install.md
@@ -1,7 +1,7 @@
---
title: "安装 Core 和 Web"
source: docs/getting-started/install.md
-source_hash: 5589a96a188bc9d778f5bebf8cab78db7f9fbebffb1656a0b91001ac05f31d95
+source_hash: 9ca5e983c99230810d97f783db12c2810e3f20cd0a67ae38004ee399a684eddd
---
一条命令即可在 Linux、macOS 或 Windows 上安装 Core、Web 控制台和 PostgreSQL。用 Core 密钥登录 Web，设置默认模型并签发项目 API 密钥。应用使用这些密钥调用 Core。Session 在你添加的节点上的沙箱中运行，也可以在 E2B 上运行。
@@ -59,7 +59,7 @@ curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --public-url https:
安装器会打印控制台地址；仅在全新安装时打印 Core 密钥，重新运行或升级则打印 `oac core-key --show`。控制台地址由安装器自行选定时，它还会提示浏览器必须打开的确切地址，以及如何用 `OAC_PUBLIC_URL` 修改。登录后，在 Web 中配置执行资源并创建项目。
-安装目录就位前，先完成下载和配置检查。之后的失败会保留配置与数据。被拒绝的设置或数据卷会单独报告，按提示修复即可。服务三分钟内未变为健康时，会列出这些服务和查看其日志的 `docker compose logs --tail 50` 命令；修复原因后重新执行同一命令。按 Ctrl-C 会打印 `Interrupted; rerun the installer to continue.`，安装保持可继续的状态。重新执行同一命令，或指定安装目录即可继续：
+安装目录就位前，先完成下载和配置检查。之后的失败会保留配置与数据。被拒绝的设置或数据卷会单独报告，按提示修复即可。服务三分钟内未变为健康时，会列出这些服务和查看其日志的 `docker compose logs --tail 50` 命令；修复原因后重新执行同一命令。按 Ctrl-C 会打印 `Interrupted; rerun the installer to continue.`，安装保持可继续的状态。在 Linux 和 macOS 上，启动脚本把未完成的 `oac` 下载保存在 `${TMPDIR:-/tmp}/oac-install-`，重新执行时从断点继续；若 curl 报错且没有安装任何内容，重新执行同一命令即可。重新执行同一命令，或指定安装目录即可继续：
```bash
curl -fsSL https://openagentcore.dev/install.sh | bash -s -- --install-dir "$HOME/.oac/core"
From fc78bb7a2764eeb3bb2df17d12911a3ddcc834e2 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Fri, 16 Oct 2026 18:19:39 +0800
Subject: [PATCH 03/74] Drop the offline node payload bind on a published
upgrade (#742)
* Drop the offline node payload bind on a published upgrade
* Escape the payload path in the override test
---
docs/configuration.md | 2 +-
docs/zh/configuration.md | 4 +--
services/core/cmd/oac/install.go | 47 +++++++++++++++++++++++++--
services/core/cmd/oac/install_test.go | 38 ++++++++++++++++++++++
4 files changed, 85 insertions(+), 6 deletions(-)
diff --git a/docs/configuration.md b/docs/configuration.md
index 1306c3e8f..6e1d27f79 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -246,7 +246,7 @@ The installer creates `~/.oac/core` by default (`$HOME/.oac/core` on Windows). I
| --- | --- | --- |
| `.env` | Process settings and the stable Compose project name | You, then `oac apply` |
| `compose.yaml` | Verified release service definition | The installer, when it installs or [upgrades](./getting-started/operations.md#upgrade) |
-| `compose.override.yaml` | Optional local Compose entries. For a source bundle it is JSON and also holds the four service images and Web's `/node-payload` bind | You. `install.py` replaces only its own entries and requires JSON |
+| `compose.override.yaml` | Optional local Compose entries. For a source bundle it is JSON and also holds the four service images and Web's `/node-payload` bind | You. `install.py` replaces only its own entries and requires JSON. `oac install --upgrade` removes the `/node-payload` bind and the host `node-payload/` directory, because a release serves its payload from the data volume |
| `oac` (`oac.exe` on Windows) | Native management command | The installer |
The sibling `.lock` directory remains for synchronization; `.staging` holds unpublished installation files. Neither contains service data. On Unix the installer creates private directories with mode `0700` and configuration files with mode `0600`.
diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md
index 6be99025d..ce7c86e1b 100644
--- a/docs/zh/configuration.md
+++ b/docs/zh/configuration.md
@@ -1,7 +1,7 @@
---
title: "配置参考"
source: docs/configuration.md
-source_hash: 600946b2952a270983450ee93e75fbcdb950c2249ff845c7e3fc81a6154a6910
+source_hash: 9837b4bdb1b09598ff3ed0c439c831af06a59a6b7201ec14d74916067ac544c7
---
Core 安装的每项设置都恰好只有一个归属位置，分属以下三类：
@@ -250,7 +250,7 @@ Session 创建可以在异步工作区准入之前成功。容量耗尽时，Cor
| --- | --- | --- |
| `.env` | 进程设置和固定的 Compose 项目名 | 用户修改后运行 `oac apply` |
| `compose.yaml` | 已校验的发行版服务定义 | 安装程序，在安装或[升级](getting-started/operations.md#upgrade)时 |
-| `compose.override.yaml` | 可选的本地 Compose 条目。源码包安装中它是 JSON，还保存四个服务镜像和 Web 的 `/node-payload` 绑定 | 用户。`install.py` 只替换自己的条目，并要求 JSON 格式 |
+| `compose.override.yaml` | 可选的本地 Compose 条目。源码包安装中它是 JSON，还保存四个服务镜像和 Web 的 `/node-payload` 绑定 | 用户。`install.py` 只替换自己的条目，并要求 JSON 格式。`oac install --upgrade` 会删除 `/node-payload` 绑定和主机上的 `node-payload/` 目录，因为发布版本从数据卷提供该载荷 |
| `oac`（Windows 为 `oac.exe`） | 原生管理命令 | 安装程序 |
同级 `.lock` 目录用于同步操作并一直保留；`.staging` 保存尚未就位的安装文件。两者都不保存服务数据。Unix 上安装程序以 `0700` 创建私有目录，以 `0600` 创建配置文件。
diff --git a/services/core/cmd/oac/install.go b/services/core/cmd/oac/install.go
index 2ebb1b700..9324170bf 100644
--- a/services/core/cmd/oac/install.go
+++ b/services/core/cmd/oac/install.go
@@ -276,6 +276,7 @@ func (i installer) installLocked(ctx context.Context, o installOptions, detected
return fmt.Errorf("This installation runs release %s; this installer is %s. Back up the installation (Upgrade in the operations guide), then rerun with --upgrade.", short(installed), short(buildRevision))
}
compose := installCompose{docker: i.docker, dir: o.dir}
+ cleanedOverride := false
if fresh || upgrade {
if fresh {
listener, err := net.Listen("tcp", net.JoinHostPort(o.host, strconv.Itoa(o.port)))
@@ -308,8 +309,17 @@ func (i installer) installLocked(ctx context.Context, o installOptions, detected
} else {
// The staged release runs with the installation's settings, project name and override.
compose.files = []string{"-f", filepath.Join(stage, "compose.yaml")}
- if _, err := os.Stat(filepath.Join(o.dir, "compose.override.yaml")); err == nil {
- compose.files = append(compose.files, "-f", filepath.Join(o.dir, "compose.override.yaml"))
+ override := filepath.Join(o.dir, "compose.override.yaml")
+ if raw, err := os.ReadFile(override); err == nil {
+ if cleaned, changed := dropPayloadBind(raw); changed {
+ // The release serves the node payload from the data volume, so the offline installer's host bind goes.
+ if err := os.WriteFile(filepath.Join(stage, "compose.override.yaml"), cleaned, 0o600); err != nil {
+ return err
+ }
+ override = filepath.Join(stage, "compose.override.yaml")
+ cleanedOverride = true
+ }
+ compose.files = append(compose.files, "-f", override)
}
compose.files = append(compose.files, "--project-directory", o.dir)
}
@@ -344,11 +354,19 @@ func (i installer) installLocked(ctx context.Context, o installOptions, detected
return fmt.Errorf("Upgrade stopped; the running services are unchanged: %w", err)
}
}
- for _, name := range []string{cliName(), "compose.yaml"} {
+ names := []string{cliName(), "compose.yaml"}
+ if cleanedOverride {
+ names = append(names, "compose.override.yaml")
+ }
+ for _, name := range names {
if err := os.Rename(filepath.Join(stage, name), filepath.Join(o.dir, name)); err != nil {
return err
}
}
+ if cleanedOverride {
+ // Nothing serves the offline installer's host copy any more.
+ _ = os.RemoveAll(filepath.Join(o.dir, "node-payload"))
+ }
}
if !fresh {
// Installations from earlier releases kept a checksum that no longer describes compose.yaml.
@@ -400,6 +418,29 @@ func (i installer) installLocked(ctx context.Context, o installOptions, detected
return nil
}
+// dropPayloadBind removes the offline installer's Web bind of /node-payload from a JSON override and keeps every other entry. Other formats are the operator's and stay as they are.
+func dropPayloadBind(raw []byte) ([]byte, bool) {
+ var override map[string]any
+ if json.Unmarshal(raw, &override) != nil {
+ return nil, false
+ }
+ services, _ := override["services"].(map[string]any)
+ web, _ := services["web"].(map[string]any)
+ volumes, _ := web["volumes"].([]any)
+ kept := make([]any, 0, len(volumes))
+ for _, volume := range volumes {
+ if entry, ok := volume.(map[string]any); !ok || entry["target"] != "/node-payload" {
+ kept = append(kept, volume)
+ }
+ }
+ if len(kept) == len(volumes) {
+ return nil, false
+ }
+ web["volumes"] = kept
+ cleaned, err := json.MarshalIndent(override, "", " ")
+ return append(cleaned, '\n'), err == nil
+}
+
// portHolderHint names an OpenAgentCore Compose project that publishes the port. A project whose directory is gone keeps running; one whose directory exists is a live installation, so the hint names it instead of offering to delete it.
func (i installer) portHolderHint(ctx context.Context, port int) string {
rows, err := i.docker(ctx, "", "ps", "--filter", "publish="+strconv.Itoa(port), "--format", `{{.Label "com.docker.compose.project"}} {{.Label "com.docker.compose.project.working_dir"}}`)
diff --git a/services/core/cmd/oac/install_test.go b/services/core/cmd/oac/install_test.go
index 2a2311d2a..8174e43ee 100644
--- a/services/core/cmd/oac/install_test.go
+++ b/services/core/cmd/oac/install_test.go
@@ -3,6 +3,7 @@ package main
import (
"context"
"crypto/sha256"
+ "encoding/json"
"errors"
"fmt"
"io"
@@ -297,6 +298,43 @@ func TestInstallUpgradesAnotherReleaseOnlyWhenRequested(t *testing.T) {
}
}
+func TestUpgradeDropsTheOfflineNodePayloadBind(t *testing.T) {
+ f := newInstallFixture(t)
+ setBuildRevision(t, "a1b2c3d4e5f6a7b8c9d0a1b2c3d4e5f6a7b8c9d0")
+ if err := f.run(); err != nil {
+ t.Fatal(err)
+ }
+ payload := filepath.Join(f.options.dir, "node-payload")
+ os.Mkdir(payload, 0o755)
+ source, _ := json.Marshal(payload)
+ override := `{"services":{"web":{"volumes":[{"type":"bind","source":` + string(source) + `,"target":"/node-payload","read_only":true},{"type":"bind","source":"/srv/ca","target":"/ca"}]}}}`
+ path := filepath.Join(f.options.dir, "compose.override.yaml")
+ os.WriteFile(path, []byte(override), 0o600)
+ setBuildRevision(t, "development")
+ f.options.upgrade = true
+ f.failure = "staged compose run --rm --no-deps init"
+ if err := f.run(); err == nil {
+ t.Fatal("upgrade should have stopped")
+ }
+ if raw, _ := os.ReadFile(path); string(raw) != override {
+ t.Fatal("a stopped upgrade changed the override")
+ }
+ if _, err := os.Stat(payload); err != nil {
+ t.Fatal("a stopped upgrade removed the node payload")
+ }
+ f.failure = ""
+ if err := f.run(); err != nil {
+ t.Fatal(err)
+ }
+ raw, _ := os.ReadFile(path)
+ if strings.Contains(string(raw), "/node-payload") || !strings.Contains(string(raw), "/srv/ca") {
+ t.Fatalf("override after upgrade: %s", raw)
+ }
+ if _, err := os.Stat(payload); !os.IsNotExist(err) {
+ t.Fatal("upgrade kept the node payload directory")
+ }
+}
+
func setBuildRevision(t *testing.T, revision string) {
previous := buildRevision
buildRevision = revision
From 87d1aec48cb9cd2c18d44567cd9ca853e9c697df Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Fri, 16 Oct 2026 20:56:03 +0800
Subject: [PATCH 04/74] Lead the README with install and a first API call
(#744)
* Lead the README with install and a first API call
* Drop the llms.txt row from the README documentation table
---
README.ja.md | 87 ++++++++++++++++++++++++-----------------------
README.md | 87 ++++++++++++++++++++++++-----------------------
README.zh-CN.md | 89 ++++++++++++++++++++++++++-----------------------
3 files changed, 139 insertions(+), 124 deletions(-)
diff --git a/README.ja.md b/README.ja.md
index 5d15a9c99..e1a7d0677 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -4,75 +4,80 @@
# OpenAgentCore
-複数のネイティブ実行エンジンに対応し、自分のインフラにデプロイできる OpenAI Agents API のオープンソース実装です。
+オープンソースでセルフホストできる OpenAI Agents API。公式 OpenAI SDK から、自分のマシンと自分のモデルで Codex、Claude Code、MiniMax Code を実行できます。
-[公式サイト](https://openagentcore.dev/) · [インストール](#インストール) · [API を使う](https://openagentcore.dev/docs/getting-started/quickstart) · [ドキュメント](https://openagentcore.dev/docs/getting-started/) · [コントリビューション](CONTRIBUTING.md)
+[](https://github.com/MiniMax-AI/OpenAgentCore/releases/latest) [](LICENSE)
+
+[公式サイト](https://openagentcore.dev/) · [ドキュメント](https://openagentcore.dev/docs/getting-started/) · [クイックスタート](#クイックスタート) · [コントリビューション](CONTRIBUTING.md)
[English](README.md) · [简体中文](README.zh-CN.md) · **日本語**
-## コンポーネントの関係
-
-
+- **OpenAI と同じ API。** `OPENAI_BASE_URL` を設定すれば、[公式 OpenAI SDK](https://developers.openai.com/api/docs/libraries)または直接の HTTP リクエストがそのまま動作します。
+- **自分のエージェント、自分のモデル。** 各 Session は Codex、Claude Code、MiniMax Code のいずれかをネイティブに実行し、設定したモデルプロバイダーを使用します。詳しくは [Harness の機能](https://openagentcore.dev/contracts/agents-api/harness-capabilities)をご覧ください。
+- **計算資源は休止し、ワークスペースは残る。** microsandbox と独立したワークスペースストレージの組み合わせでは、アイドル状態のサンドボックスが計算資源を解放し、互換性のあるノードでファイルをそのまま再開します。E2B、Docker、自分の Linux、macOS、Windows マシンでも Session を実行できます。詳しくは[サンドボックスプロバイダーの追加](https://openagentcore.dev/docs/sandbox-provider)をご覧ください。
+- **置き換え可能なコンポーネント。** サンドボックスプロバイダー、ワークスペースファイルシステム、Harness、モデルプロバイダーは、[定義されたプロトコル](AGENTS.md#protocols-at-every-boundary)を通じて接続されます。
-アプリケーションと管理者は、次の Core API を使用します。
+
-| API | パス | 利用者 |
-| --- | --- | --- |
-| **[Agents API](https://openagentcore.dev/docs/api/public-agent-api)** | `/v1` | アプリケーション。[OpenAI の Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) と同じプロトコルを使用 |
-| **[Core API](https://openagentcore.dev/contracts/agents-api/admin-api)** | `/core/v1` | 管理者。Web 経由で利用 |
+## クイックスタート
-Core は実行状態を永続化し、Runtime は Environment 内で選択した Harness を実行します。各コンポーネントは定義されたプロトコルで接続されているため、個別に置き換えられます。詳しくは[アーキテクチャガイド](https://openagentcore.dev/docs/architecture)をご覧ください。
+[前提条件](https://openagentcore.dev/docs/getting-started/install#prerequisites)に従って Docker をセットアップした Linux または macOS で、Core、Web、PostgreSQL をインストールします。
-## OpenAgentCore とは
+```sh
+curl -fsSL https://openagentcore.dev/install.sh | bash
+```
-OpenAgentCore は、自分のインフラ上で AI エージェントを実行し、[OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) を提供します。
+Windows では PowerShell で実行します。
-- **OpenAI と同じ API。** [公式 OpenAI SDK](https://developers.openai.com/api/docs/guides/agents/sdk) または直接の HTTP リクエストで、接続先を変更するだけで利用できます。新しいクライアントを覚える必要はありません。
-- **エージェントを選択可能。** 各 [Session](https://openagentcore.dev/docs/api/public-agent-api) は、[Codex](https://github.com/openai/codex)、[Claude Code](https://code.claude.com/docs/en/overview)、[MiniMax Code](https://github.com/MiniMax-AI/minimax-code) のいずれかの[ネイティブ Harness](https://openagentcore.dev/contracts/agents-api/harness-onboarding) を実行し、[設定したモデルプロバイダー](https://openagentcore.dev/contracts/agents-api/model-execution)を使用します。
-- **計算資源を再利用し、ワークスペースを永続化。** [microsandbox](https://github.com/zerocore-ai/microsandbox) と[独立したワークスペースストレージ](https://openagentcore.dev/docs/workspace-provider)の組み合わせを推奨します。アイドル状態のサンドボックスは休止して計算資源を解放し、互換性のあるノードで再開できます。[E2B](https://e2b.dev/) はマネージド環境の選択肢です。Docker や自分の Linux、macOS、Windows マシンでの実行もサポートします。
-- **すべてのコンポーネントを置き換え可能。** [サンドボックス](https://openagentcore.dev/docs/sandbox-provider)、[ワークスペースファイルシステム](https://openagentcore.dev/docs/workspace-provider)、[Harness](https://openagentcore.dev/contracts/agents-api/harness-onboarding)、[モデルプロバイダー](https://openagentcore.dev/contracts/agents-api/model-execution)は、[定義されたプロトコル](AGENTS.md#protocols-at-every-boundary)を通じて接続されます。
+```powershell
+irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex
+```
-## スクリーンショット
+Web で、インストーラーが表示する Core key でサインインし、パブリックアドレスを設定し、デフォルトモデルを設定し、Project API key を発行して、サンドボックスの容量（ノードまたは E2B）を追加します。各手順は[Core と Web のインストール](https://openagentcore.dev/docs/getting-started/install)をご覧ください。
-| 概要 | エージェントの監視 |
-| --- | --- |
-|  |  |
+続いて OpenAI SDK から呼び出します。`OPENAI_BASE_URL` に API のベース URL（`https://core.example/v1`）、`OPENAI_API_KEY` に Project API key を設定してください。
-## インストール
+```python
+from openai import OpenAI
-[前提条件](https://openagentcore.dev/docs/getting-started/install#prerequisites)に従って Docker をセットアップした Linux または macOS で、次のコマンドを実行します。
-
-```sh
-curl -fsSL https://openagentcore.dev/install.sh | bash
+client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
+session = client.beta.agents.sessions.create(
+ environment={"type": "openai_hosted"},
+ input="Create /workspace/hello.txt with a short greeting, then describe it.",
+ extra_body={"agent": {"x_agents_core": {"harness": "codex"}}},
+)
+print(session.id)
```
-Windows PowerShell の場合：
+[最初の Session を実行](https://openagentcore.dev/docs/getting-started/quickstart)では、結果を待って読み戻します。
-```powershell
-irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex
-```
+## 仕組み
+
+
-続いて、以下の手順で設定します。
+アプリケーションと管理者は、次の Core API を使用します。
-1. インストーラーが生成した Core key で **Web（管理コンソール）にサインイン**し、**ドメインと HTTPS を設定**します。
-2. **デフォルトモデルを設定**し、**Project API key を発行**します。
-3. ノード、E2B、または自分のマシンを**実行リソースとして追加**します。
-4. OpenAI SDK で **[最初の Session を実行](https://openagentcore.dev/docs/getting-started/quickstart)** します。
+| API | パス | 利用者 |
+| --- | --- | --- |
+| **[Agents API](https://openagentcore.dev/docs/api/public-agent-api)** | `/v1` | アプリケーション。[OpenAI の Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) と同じプロトコルを使用 |
+| **[Core API](https://openagentcore.dev/contracts/agents-api/admin-api)** | `/core/v1` | 管理者。Web 経由で利用 |
-[インストールガイド](https://openagentcore.dev/docs/getting-started/install)では、各手順に加え、HTTPS の設定とローカルで手軽に試す方法を説明しています。リッスンアドレスやポートなどの設定は、[インストールオプション](https://openagentcore.dev/docs/getting-started/install-options)をご覧ください。
+Core は実行状態を永続化し、Runtime は Environment 内で選択した Harness を実行します。各コンポーネントは定義されたプロトコルで接続されているため、個別に置き換えられます。詳しくは[アーキテクチャ](https://openagentcore.dev/docs/architecture)をご覧ください。
## ドキュメント
| 目的 | 参照先 |
| --- | --- |
-| インストールと運用 | [インストールガイド](https://openagentcore.dev/docs/getting-started/install)、続いて[運用ガイド](https://openagentcore.dev/docs/getting-started/operations) |
-| API を使ったアプリケーション開発 | [クイックスタート](https://openagentcore.dev/docs/getting-started/quickstart)、続いて [Agents API ガイド](https://openagentcore.dev/docs/api/public-agent-api) |
+| インストールと運用 | [Core と Web のインストール](https://openagentcore.dev/docs/getting-started/install)、続いて[運用](https://openagentcore.dev/docs/getting-started/operations) |
+| API を使ったアプリケーション開発 | [最初の Session を実行](https://openagentcore.dev/docs/getting-started/quickstart)、続いて [Agents API ガイド](https://openagentcore.dev/docs/api/public-agent-api) |
| 完成したアプリケーションの確認 | [サンプル](https://openagentcore.dev/docs/examples) |
| 自分のマシンでエージェントを実行 | [セルフホスト実行](https://openagentcore.dev/docs/getting-started/self-hosted) |
| Harness の機能と制限の確認 | [Harness の機能](https://openagentcore.dev/contracts/agents-api/harness-capabilities) |
-| 設計の理解 | [アーキテクチャガイド](https://openagentcore.dev/docs/architecture) |
-| 新しいサンドボックス、Harness などのコンポーネントの追加 | [開発ガイド](https://openagentcore.dev/docs/development) |
+| 設計の理解 | [アーキテクチャ](https://openagentcore.dev/docs/architecture) |
+| 新しいサンドボックス、Harness などのコンポーネントの追加 | [OpenAgentCore の開発](https://openagentcore.dev/docs/development) |
+
+## コントリビューションとライセンス
-すべてのドキュメントは[ドキュメント一覧](https://openagentcore.dev/docs/getting-started/)から参照できます。コードを変更する前に、[コントリビューションガイド](CONTRIBUTING.md)をお読みください。
+コードを変更する前に [CONTRIBUTING.md](CONTRIBUTING.md) をお読みください。バグ報告と質問は [GitHub Issues](https://github.com/MiniMax-AI/OpenAgentCore/issues) へお寄せください。[MIT License](LICENSE) で公開しています。
diff --git a/README.md b/README.md
index dacf6142f..696893c8c 100644
--- a/README.md
+++ b/README.md
@@ -4,75 +4,80 @@
# OpenAgentCore
-An open-source, self-hosted implementation of the OpenAI Agents API with multiple native Harnesses.
+The OpenAI Agents API, open source and self-hosted. Run Codex, Claude Code or MiniMax Code on your own machines with your own models, through the official OpenAI SDK.
-[Website](https://openagentcore.dev/) · [Install](#install) · [Call the API](https://openagentcore.dev/docs/getting-started/quickstart) · [Documentation](https://openagentcore.dev/docs/getting-started/) · [Contributing](CONTRIBUTING.md)
+[](https://github.com/MiniMax-AI/OpenAgentCore/releases/latest) [](LICENSE)
+
+[Website](https://openagentcore.dev/) · [Documentation](https://openagentcore.dev/docs/getting-started/) · [Quickstart](#quickstart) · [Contributing](CONTRIBUTING.md)
**English** · [简体中文](README.zh-CN.md) · [日本語](README.ja.md)
-## What it is
+- **Same API as OpenAI.** Set `OPENAI_BASE_URL` and the [official OpenAI SDK](https://developers.openai.com/api/docs/libraries), or plain HTTP, works unchanged.
+- **Your agent, your model.** Each Session runs Codex, Claude Code or MiniMax Code natively, with the model provider you configure. See [Harness capabilities](https://openagentcore.dev/contracts/agents-api/harness-capabilities).
+- **Compute that sleeps, workspaces that stay.** On microsandbox with independent workspace storage, idle sandboxes release compute and resume on a compatible node with their files intact. E2B, Docker and your own Linux, macOS or Windows machine also run Sessions. See [Add a Sandbox Provider](https://openagentcore.dev/docs/sandbox-provider).
+- **Replaceable parts.** Sandbox Providers, workspace filesystems, Harnesses and model providers plug in through [defined protocols](AGENTS.md#protocols-at-every-boundary).
-OpenAgentCore runs AI agents on your own infrastructure behind the [OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview).
+
-- **Same API as OpenAI.** Point the [OpenAI Agent API](https://developers.openai.com/api/docs/guides/agents/sdk), or plain HTTP, at your installation. No new client to learn.
-- **Your choice of agent.** Each [Session](https://openagentcore.dev/docs/api/public-agent-api) runs a [native Harness](https://openagentcore.dev/contracts/agents-api/harness-onboarding): [Codex](https://github.com/openai/codex), [Claude Code](https://code.claude.com/docs/en/overview) or [MiniMax Code](https://github.com/MiniMax-AI/minimax-code), with the [model provider you configure](https://openagentcore.dev/contracts/agents-api/model-execution).
-- **Reusable compute, persistent workspaces.** We recommend [microsandbox](https://github.com/zerocore-ai/microsandbox) with [independent workspace storage](https://openagentcore.dev/docs/workspace-provider): idle sandboxes suspend, release compute and resume on compatible nodes. [E2B](https://e2b.dev/) is the managed alternative; Docker and your own Linux, macOS or Windows machine remain supported execution choices.
-- **Every part is replaceable.** [Sandboxes](https://openagentcore.dev/docs/sandbox-provider), [workspace filesystems](https://openagentcore.dev/docs/workspace-provider), [Harnesses](https://openagentcore.dev/contracts/agents-api/harness-onboarding) and [model providers](https://openagentcore.dev/contracts/agents-api/model-execution) plug in through [defined protocols](AGENTS.md#protocols-at-every-boundary).
+## Quickstart
-## How it fits together
+Install Core, Web and PostgreSQL on Linux or macOS with [Docker](https://openagentcore.dev/docs/getting-started/install#prerequisites):
-
+```sh
+curl -fsSL https://openagentcore.dev/install.sh | bash
+```
-Applications and operators use these Core APIs:
+On Windows, in PowerShell:
-| API | Path | Used by |
-| --- | --- | --- |
-| **[Agents API](https://openagentcore.dev/docs/api/public-agent-api)** | `/v1` | Your applications. Same protocol as [OpenAI's Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) |
-| **[Core API](https://openagentcore.dev/contracts/agents-api/admin-api)** | `/core/v1` | Operators, through Web |
-
-Core keeps durable execution state. The Runtime runs the chosen Harness inside the Environment. Each connection is a defined protocol, so any part can be replaced on its own. See the [architecture guide](https://openagentcore.dev/docs/architecture).
+```powershell
+irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex
+```
-## Screenshots
+In Web, sign in with the Core key the installer prints, configure the public address, set a default model, issue a Project API key and add sandbox capacity (a node or E2B). [Install Core and Web](https://openagentcore.dev/docs/getting-started/install) covers each step.
-| Overview | Agent metrics |
-| --- | --- |
-|  |  |
+Then call it with the OpenAI SDK, with `OPENAI_BASE_URL` set to your API base URL (`https://core.example/v1`) and `OPENAI_API_KEY` to the Project API key:
-## Install
+```python
+from openai import OpenAI
-On Linux or macOS with [Docker configured](https://openagentcore.dev/docs/getting-started/install#prerequisites):
-
-```sh
-curl -fsSL https://openagentcore.dev/install.sh | bash
+client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
+session = client.beta.agents.sessions.create(
+ environment={"type": "openai_hosted"},
+ input="Create /workspace/hello.txt with a short greeting, then describe it.",
+ extra_body={"agent": {"x_agents_core": {"harness": "codex"}}},
+)
+print(session.id)
```
-Windows PowerShell:
+[Run your first Session](https://openagentcore.dev/docs/getting-started/quickstart) waits for the result and reads it back.
-```powershell
-irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex
-```
+## How it works
+
+
-Then:
+Applications and operators use these Core APIs:
-1. **Sign in to Web**, the admin console, with the Core key the installer created, and **configure the domain and HTTPS**.
-2. **Set a default model** and **issue a Project API key**.
-3. **Add execution capacity:** a node, E2B, or your own machine.
-4. **[Run your first Session](https://openagentcore.dev/docs/getting-started/quickstart)** with the OpenAI SDK.
+| API | Path | Used by |
+| --- | --- | --- |
+| **[Agents API](https://openagentcore.dev/docs/api/public-agent-api)** | `/v1` | Your applications. Same protocol as [OpenAI's Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) |
+| **[Core API](https://openagentcore.dev/contracts/agents-api/admin-api)** | `/core/v1` | Operators, through Web |
-The [installation guide](https://openagentcore.dev/docs/getting-started/install) covers each step, HTTPS and a quick local trial. Listen addresses, ports and other options: [installation options](https://openagentcore.dev/docs/getting-started/install-options).
+Core keeps durable execution state. The Runtime runs the chosen Harness inside the Environment. Each connection is a defined protocol, so any part can be replaced on its own. See [Architecture](https://openagentcore.dev/docs/architecture).
## Documentation
| I want to | Start with |
| --- | --- |
-| Install and operate an installation | [Installation](https://openagentcore.dev/docs/getting-started/install), then [operations](https://openagentcore.dev/docs/getting-started/operations) |
-| Build an application on the API | [Quickstart](https://openagentcore.dev/docs/getting-started/quickstart), then the [Agents API guide](https://openagentcore.dev/docs/api/public-agent-api) |
+| Install and operate an installation | [Install Core and Web](https://openagentcore.dev/docs/getting-started/install), then [Operations](https://openagentcore.dev/docs/getting-started/operations) |
+| Build an application on the API | [Run your first Session](https://openagentcore.dev/docs/getting-started/quickstart), then the [Agents API guide](https://openagentcore.dev/docs/api/public-agent-api) |
| See a complete application | [Examples](https://openagentcore.dev/docs/examples) |
-| Run agents on my own machine | [Self-hosted execution](https://openagentcore.dev/docs/getting-started/self-hosted) |
+| Run agents on my own machine | [Run self-hosted Sessions](https://openagentcore.dev/docs/getting-started/self-hosted) |
| Check Harness capabilities and limits | [Harness capabilities](https://openagentcore.dev/contracts/agents-api/harness-capabilities) |
| Understand the design | [Architecture](https://openagentcore.dev/docs/architecture) |
-| Add a sandbox, Harness or other component | [Developer guide](https://openagentcore.dev/docs/development) |
+| Add a sandbox, Harness or other component | [Develop OpenAgentCore](https://openagentcore.dev/docs/development) |
+
+## Contributing and license
-All pages: [documentation index](https://openagentcore.dev/docs/getting-started/). Before changing code, read the [contributor rules](CONTRIBUTING.md).
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing code. Report bugs and ask questions in [GitHub Issues](https://github.com/MiniMax-AI/OpenAgentCore/issues). Released under the [MIT License](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index dee2b6a84..92ceed216 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -4,75 +4,80 @@
# OpenAgentCore
-OpenAI Agents API 的开源实现，支持多种原生 Harness，可部署在自己的基础设施上。
+开源、可自部署的 OpenAI Agents API。用官方 OpenAI SDK，在你自己的机器上用你自己的模型运行 Codex、Claude Code 或 MiniMax Code。
-[官网](https://openagentcore.dev/zh/) · [安装](#安装) · [调用 API](https://openagentcore.dev/zh/docs/getting-started/quickstart) · [文档](https://openagentcore.dev/zh/docs/getting-started/) · [参与贡献](CONTRIBUTING.md)
+[](https://github.com/MiniMax-AI/OpenAgentCore/releases/latest) [](LICENSE)
+
+[官网](https://openagentcore.dev/zh/) · [文档](https://openagentcore.dev/zh/docs/getting-started/) · [快速开始](#快速开始) · [参与贡献](CONTRIBUTING.md)
[English](README.md) · **简体中文** · [日本語](README.ja.md)
-## 组件关系
-
-
+- **与 OpenAI 相同的 API。** 设置 `OPENAI_BASE_URL` 后，[官方 OpenAI SDK](https://developers.openai.com/api/docs/libraries)或直接的 HTTP 调用无需改动即可使用。
+- **你的 Agent，你的模型。** 每个 Session 原生运行 Codex、Claude Code 或 MiniMax Code，并使用你配置的模型提供商。详见 [Harness 能力](https://openagentcore.dev/zh/contracts/agents-api/harness-capabilities)。
+- **计算会休眠，工作区会保留。** 在 microsandbox 配合独立工作区存储时，空闲沙箱释放计算资源，并在兼容节点上带着文件恢复。E2B、Docker 以及你自己的 Linux、macOS 或 Windows 机器同样可以运行 Session。详见[添加沙箱提供商](https://openagentcore.dev/zh/docs/sandbox-provider)。
+- **部件可替换。** 沙箱提供商、工作区文件系统、Harness 和模型提供商都通过[既定协议](AGENTS.md#protocols-at-every-boundary)接入。
-应用和管理员使用以下 Core API：
+
-| API | 路径 | 调用方 |
-| --- | --- | --- |
-| **[Agents API](https://openagentcore.dev/zh/docs/api/public-agent-api)** | `/v1` | 你的应用，与 [OpenAI 的 Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) 协议一致 |
-| **[Core API](https://openagentcore.dev/zh/contracts/agents-api/admin-api)** | `/core/v1` | 管理员，通过 Web 调用 |
+## 快速开始
-持久化执行状态由 Core 保存；Runtime 在 Environment 中运行所选 Harness。各部件之间都通过既定协议连接， 任何一个都可以单独替换。详见[架构说明](https://openagentcore.dev/zh/docs/architecture)。
+在 Linux 或 macOS 上，按[前置条件](https://openagentcore.dev/zh/docs/getting-started/install#prerequisites)准备好 Docker 后，安装 Core、Web 和 PostgreSQL：
-## 这是什么
+```sh
+curl -fsSL https://openagentcore.dev/install.sh | bash
+```
-OpenAgentCore 在你自己的基础设施上运行 AI Agent，对外提供 [OpenAI Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview)。
+在 Windows 上，使用 PowerShell：
-- **与 OpenAI 相同的 API。** [官方 OpenAI SDK](https://developers.openai.com/api/docs/guides/agents/sdk) 或直接 HTTP 调用，改一下地址即可，无需学习新客户端。
-- **自选 Agent。** 每个 [Session](https://openagentcore.dev/zh/docs/api/public-agent-api) 运行一个[原生 Harness](https://openagentcore.dev/zh/contracts/agents-api/harness-onboarding)：[Codex](https://github.com/openai/codex)、[Claude Code](https://code.claude.com/docs/en/overview) 或 [MiniMax Code](https://github.com/MiniMax-AI/minimax-code)， 使用[你配置的模型供应商](https://openagentcore.dev/zh/contracts/agents-api/model-execution)。
-- **计算可复用，工作区持久化。** 推荐 [microsandbox](https://github.com/zerocore-ai/microsandbox) 配合[独立工作区存储](https://openagentcore.dev/zh/docs/workspace-provider)：空闲沙箱挂起、释放计算资源，并在兼容节点上恢复。[E2B](https://e2b.dev/) 是托管计算的另一选择；也支持 Docker 和你自己的 Linux、macOS 或 Windows 机器。
-- **每个部件都可替换。** [沙箱](https://openagentcore.dev/zh/docs/sandbox-provider)、[工作区文件系统](https://openagentcore.dev/zh/docs/workspace-provider)、[Harness](https://openagentcore.dev/zh/contracts/agents-api/harness-onboarding) 和[模型供应商](https://openagentcore.dev/zh/contracts/agents-api/model-execution)都通过[既定协议](AGENTS.md#protocols-at-every-boundary)接入。
+```powershell
+irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex
+```
-## 界面预览
+在 Web 中，用安装程序输出的 Core 密钥登录，配置公共地址，设置默认模型，签发项目 API 密钥，并添加沙箱容量（节点或 E2B）。每一步见[安装 Core 和 Web](https://openagentcore.dev/zh/docs/getting-started/install)。
-| 概览 | Agent 监控 |
-| --- | --- |
-|  |  |
+然后用 OpenAI SDK 调用，将 `OPENAI_BASE_URL` 设为你的 API 基础地址（`https://core.example/v1`），`OPENAI_API_KEY` 设为项目 API 密钥：
-## 安装
+```python
+from openai import OpenAI
-在已按[前置条件](https://openagentcore.dev/zh/docs/getting-started/install#prerequisites)准备 Docker 的 Linux 或 macOS 上：
-
-```sh
-curl -fsSL https://openagentcore.dev/install.sh | bash
+client = OpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
+session = client.beta.agents.sessions.create(
+ environment={"type": "openai_hosted"},
+ input="Create /workspace/hello.txt with a short greeting, then describe it.",
+ extra_body={"agent": {"x_agents_core": {"harness": "codex"}}},
+)
+print(session.id)
```
-Windows PowerShell:
+[运行第一个 Session](https://openagentcore.dev/zh/docs/getting-started/quickstart)会等待结果并读回。
-```powershell
-irm https://github.com/MiniMax-AI/OpenAgentCore/releases/latest/download/install.ps1 | iex
-```
+## 工作原理
+
+
-然后：
+应用和管理员使用以下 Core API：
-1. 用安装器生成的 Core 密钥 **登录 Web**（管理控制台），并**配置域名和 HTTPS**。
-2. **设置默认模型**，并**签发项目 API 密钥**。
-3. **添加执行资源**：节点、E2B，或你自己的机器。
-4. 用 OpenAI SDK **[运行第一个 Session](https://openagentcore.dev/zh/docs/getting-started/quickstart)**。
+| API | 路径 | 调用方 |
+| --- | --- | --- |
+| **[Agents API](https://openagentcore.dev/zh/docs/api/public-agent-api)** | `/v1` | 你的应用，与 [OpenAI 的 Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) 协议一致 |
+| **[Core API](https://openagentcore.dev/zh/contracts/agents-api/admin-api)** | `/core/v1` | 管理员，通过 Web 调用 |
-[安装指南](https://openagentcore.dev/zh/docs/getting-started/install)详细介绍每一步，以及 HTTPS 配置和本地快速试用。监听地址、端口等参数见[安装配置选项](https://openagentcore.dev/zh/docs/getting-started/install-options)。
+持久化执行状态由 Core 保存；Runtime 在 Environment 中运行所选 Harness。各部件之间都通过既定协议连接，任何一个都可以单独替换。详见[架构](https://openagentcore.dev/zh/docs/architecture)。
## 文档
| 我想要 | 从这里开始 |
| --- | --- |
-| 安装并运维 | [安装指南](https://openagentcore.dev/zh/docs/getting-started/install)，然后看[运维](https://openagentcore.dev/zh/docs/getting-started/operations) |
-| 基于 API 开发应用 | [快速开始](https://openagentcore.dev/zh/docs/getting-started/quickstart)，然后看 [Agents API 指南](https://openagentcore.dev/zh/docs/api/public-agent-api) |
+| 安装并运维 | [安装 Core 和 Web](https://openagentcore.dev/zh/docs/getting-started/install)，然后看[运维](https://openagentcore.dev/zh/docs/getting-started/operations) |
+| 基于 API 开发应用 | [运行第一个 Session](https://openagentcore.dev/zh/docs/getting-started/quickstart)，然后看 [Agents API 指南](https://openagentcore.dev/zh/docs/api/public-agent-api) |
| 看一个完整的应用 | [示例](https://openagentcore.dev/zh/docs/examples) |
-| 在自己的机器上运行 Agent | [自托管执行](https://openagentcore.dev/zh/docs/getting-started/self-hosted) |
+| 在自己的机器上运行 Agent | [自托管执行器](https://openagentcore.dev/zh/docs/getting-started/self-hosted) |
| 查看 Harness 能力和限制 | [Harness 能力](https://openagentcore.dev/zh/contracts/agents-api/harness-capabilities) |
-| 了解设计 | [架构说明](https://openagentcore.dev/zh/docs/architecture) |
-| 接入新的沙箱、Harness 或其他组件 | [开发指南](https://openagentcore.dev/zh/docs/development) |
+| 了解设计 | [架构](https://openagentcore.dev/zh/docs/architecture) |
+| 接入新的沙箱、Harness 或其他组件 | [开发 OpenAgentCore](https://openagentcore.dev/zh/docs/development) |
+
+## 参与贡献与许可证
-全部文档见[文档目录](https://openagentcore.dev/zh/docs/getting-started/)。修改代码前请阅读[贡献规范](CONTRIBUTING.md)。
+修改代码前请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。缺陷和问题请提交到 [GitHub Issues](https://github.com/MiniMax-AI/OpenAgentCore/issues)。基于 [MIT 许可证](LICENSE)发布。
From 2847566066e38b505d597c339e3a8f226a5a3959 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Fri, 16 Oct 2026 21:01:43 +0800
Subject: [PATCH 05/74] Separate the node wire protocol from node storage
(#745)
* Separate the node wire protocol from node storage
* Show the node as the sender of retention requests
---
AGENTS.md | 2 +-
CONTRIBUTING.md | 2 +-
.../agents-api/node-generation-protocol.md | 112 +++++++++++------
.../agents-api/zh/node-generation-protocol.md | 114 ++++++++++++------
deploy/node/README.md | 44 +++++++
docs/architecture.md | 2 +-
docs/workspace-provider.md | 70 ++++++++++-
docs/zh/architecture.md | 4 +-
docs/zh/workspace-provider.md | 71 ++++++++++-
.../tools/microsandbox-provider/README.md | 2 +-
10 files changed, 329 insertions(+), 94 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 57626aa7c..ffc629edc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,7 @@ Do not multiply entities without necessity. The long-term goal is minimal code,
| Application–Core (`/v1`) | Official schema pinned by `contracts/agents-api/upstream.json` plus Go-owned `x_agents_core` extensions; `make openapi` generates public Go types and `contracts/agents-api/openapi.yaml` | [Agents API guide](docs/api/public-agent-api.md) |
| Web and operators–Core (`/core/v1`) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/core.openapi.yaml` | [Core administration API](contracts/agents-api/admin-api.md) |
| Nodes and daemons–Core (`/api/v1` HTTP routes; the node and daemon wire protocols are separate rows) | Route annotations in `services/core/internal/api/`; `make openapi` generates `contracts/agents-api/runtime.openapi.yaml` | [Machine connection API](contracts/agents-api/machine-api.md) |
-| Core and sandbox nodes–Workspace filesystem | `services/core/internal/workspacefs/workspacefs.go` | [Workspace filesystem providers](docs/workspace-provider.md) |
+| Core and sandbox nodes–Workspace filesystem | `services/core/internal/workspacefs/workspacefs.go` | [Workspace filesystem protocol](docs/workspace-provider.md) |
| Core–Sandbox Provider | `services/core/internal/sandbox/sandbox_provider.go` | [Sandbox Provider guide](docs/sandbox-provider.md) |
| Core–sandbox node | `services/core/internal/sandbox/node/wire.go` | [Sandbox node protocol](contracts/agents-api/node-generation-protocol.md) |
| Provider–Runtime startup | `internal/runtimebootstrap/bootstrap.go` | [Runtime bootstrap](docs/runtime-bootstrap.md) |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d581c0b0e..4ced9942f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,7 +21,7 @@ This guide owns how to work in the repository: documentation ownership, the repo
| Harness registration, service qualification and acceptance | [Harness onboarding](contracts/agents-api/harness-onboarding.md) |
| Harness capabilities by placement | [Harness capabilities](contracts/agents-api/harness-capabilities.md) |
| Harness selection, model providers and native parameters | [Model execution](contracts/agents-api/model-execution.md) |
-| Independent workspace filesystem protocol and adapter behavior | [Workspace filesystem providers](docs/workspace-provider.md) |
+| Independent workspace filesystem protocol and adapter behavior | [Workspace filesystem protocol](docs/workspace-provider.md) |
| Provider registration and lifecycle | [Sandbox Provider guide](docs/sandbox-provider.md) |
| Sandbox deployment, selection and administrative transitions | [Sandbox deployment](contracts/agents-api/sandbox-deployment.md) |
| Operator node tasks | [Nodes guide](docs/getting-started/nodes.md) |
diff --git a/contracts/agents-api/node-generation-protocol.md b/contracts/agents-api/node-generation-protocol.md
index 4e37d8407..5b54a0a1d 100644
--- a/contracts/agents-api/node-generation-protocol.md
+++ b/contracts/agents-api/node-generation-protocol.md
@@ -2,7 +2,24 @@
title: "Sandbox node protocol"
---
-A sandbox node runs the Docker or microsandbox Provider on its host and connects to Core over one WebSocket. Core sends Provider operations over that connection; the node runs them against its local provider and reports readiness, host measurements and the deployment generations it holds. Core stays the only lifecycle owner: the node never retries a mutation or schedules work. The frames and validators live in [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node) (`wire.go`, `generation_wire.go`); the HTTP routes a node uses to enroll and read its configuration are in the [machine connection API](./machine-api.md#node-routes).
+The sandbox node protocol connects Core to a Docker or microsandbox host, which runs Provider operations against its local provider and reports readiness, host measurements and the deployment generations it holds.
+
+| | |
+| --- | --- |
+| Caller | Core, the only lifecycle owner; the node never retries a mutation or schedules work |
+| Implementations | The sandbox node program with the Docker and microsandbox Providers |
+| Code | [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node) (`wire.go`, `generation_wire.go`) |
+| Transport | One WebSocket, `GET /api/v1/sandbox-node/connect`; the HTTP routes a node uses to enroll and read its configuration are in the [machine connection API](./machine-api.md#node-routes) |
+| Version rule | Exact match on `node.ProtocolVersion`, see [Frames and version](#frames-and-version) |
+
+Node-local storage, generation leases and recovery are not part of the wire protocol; the [Node installer](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md#generation-storage-and-recovery) owns them.
+
+## Roles
+
+| Party | Owns |
+| --- | --- |
+| Core | Node identity and presence, the owner epoch, the target generation, every request and its sequence, and every retention decision |
+| Node | Its local provider, the generations it prepares and serves, health and host measurements, and the execution of each request against the provider |
## Frames and version
@@ -10,12 +27,28 @@ Every frame is one JSON text message whose `version` equals `node.ProtocolVersio
## Connection
+```mermaid
+sequenceDiagram
+ participant N as Node
+ participant C as Core
+ N->>C: dial /sandbox-node/connect with Bearer credential
+ Note over C: 401 rejected credential (permanent), 409 duplicate connection
+ N->>C: hello (identity, health, generation observations)
+ C->>N: welcome (connection_id, owner_epoch, deployment)
+ loop every 10 s
+ N->>C: heartbeat (connection_id, owner_epoch, health)
+ C->>N: heartbeat_ack (deployment)
+ end
+ C->>N: request (id, sequence, operation)
+ N->>C: response (id, result or error_code)
+```
+
1. The node dials `/api/v1/sandbox-node/connect?node_id=` on its stored Core origin (`wss` for `https`) with its node credential as a Bearer header. Core answers 401 to a rejected credential, which the node treats as permanent; any other failure, including a 403 from a proxy, is retried with bounded backoff. Core refuses a second connection for a node identity while one is opening, live or closing, with 409.
2. Within 15 seconds the node sends `hello` with its identity (`node_id`, `installation_id`, `provider`, `backend_fingerprint`, the enrolled `deployment_generation` and `specification_digest`, `max_active`, `max_retained`), its first health report and, when it can prepare and retain several deployment generations, `generation_management: true`. Core closes the connection unless the identity matches the authenticated node.
3. Core records the node's presence, then replies `welcome` with a new `connection_id`, the current `owner_epoch` and, for a generation-managing node, `deployment`: the target `generation`, its `specification_digest` and a nullable `serving_generation`. The node stores a higher owner epoch and refuses a lower one.
4. Every 10 seconds the node sends `heartbeat` with `connection_id`, `owner_epoch` and health. On each heartbeat Core authenticates the node credential again and checks the owner epoch, records the health and replies `heartbeat_ack`, with `deployment` for a generation-managing node. Either peer closes the connection after 35 seconds without a frame.
-Core counts a node as online while it is connected under the current owner epoch and its last heartbeat is less than 45 seconds old. A heartbeat establishes provider readiness and the last host measurements, never Session activity.
+Core counts a node as online while it is connected under the current owner epoch and its last heartbeat is less than 45 seconds old. A heartbeat establishes provider readiness and the last host measurements, never Session activity. [Timeouts and limits](#timeouts-and-limits) lists every timer.
Health carries `provider_ready`, an optional fixed `diagnostic`, `observed_at`, `active_operations` (at most 32) and the host measurements that the [Runtime telemetry API](./runtime-observability-api.md#node-host-observations-and-history) reports. A node without generation management probes its provider for every report; an unready provider reports the Provider-neutral readiness class of its first failed check, from the class error the probe wraps, and the probe text, vendor detail and host paths stay on the node. A `diagnostic` in node or generation health that is not a declared class makes the frame invalid. The [nodes guide](../../docs/getting-started/nodes.md#readiness-codes) lists the classes and their causes. A generation-managing node reports readiness per generation instead, as described below.
@@ -71,56 +104,57 @@ A failed response carries no result, except an `info` that is an exact-reference
Node startup and generation loading validate complete Provider operation declarations before accepting work, and the Core proxy uses the same registered declaration, so an unsupported operation rejects before node resolution or native I/O. The [operation contract](../../docs/sandbox-provider.md#explicit-operation-contracts) owns the inventory. An `unsupported` response carries an `unsupported` object with the exact method `operation` and an authored safe `reason`; the proxy checks both against the request. Missing, malformed or mismatched evidence is an unconfirmed result, never proof that a mutation was rejected. Unsupported stays distinct from observation unavailability and unknown compute or command results, and it neither settles resource ownership nor authorizes a replay.
+Create bootstrap and Resume requests may carry an optional workspace filesystem binding. The node validates its tenant and Environment against the allocation reference, its immutable ObjectID, and its attachment configuration ID against the supplied configuration before forwarding it. The filesystem resolver validates adapter-native ownership. A missing binding selects owned storage; a present binding cannot fall back. Error responses may retain a Resume target only when its nonempty native ID, name, generation and snapshot provenance match the requested target; this is cleanup evidence, never successful restore.
+
## Generation control
A node without generation management serves only its enrolled generation, with fixed configuration, and receives no preparation or retention frames. It can report that exact generation in `Health.Generations`; a checkpoint-capable provider must do so, including its verified checkpoint qualification. `provider_ready` and the reported state must agree. A generation-managing node prepares the target generation Core announces in `welcome` and `heartbeat_ack` and keeps serving its durable serving generation while it does; target preparation is independent of the serving provider's readiness.
Its `hello` and heartbeats carry at most eight generation observations. Each names a positive signed-64-bit generation, its lowercase SHA-256 specification digest, a `ready`, `preparing` or `failed` state and an optional fixed diagnostic. The target and serving generations come first; other records rotate fairly. Eight bounds one message, not the number of generations a node may keep. An omitted observation never authorizes deletion or implies absence. A ready checkpoint-capable generation includes `checkpoint` with nonempty opaque `artifact_domain` and `execution_class` tokens, each at most 256 bytes. Unsupported providers omit it; preparing or failed generations never advertise it. Core persists the declaration with the authenticated connection and generation, and uses it only while that generation is ready on the current online connection. The [Provider contract](../../docs/sandbox-provider.md#checkpoint-transfer) defines archive and execution compatibility.
-Retention uses its own bounded exchange. A `retention` request names at most eight local `(generation, specification_digest)` references, a UUID, a sequence that increases by one, the current `connection_id` and the owner epoch. The `retention_ack` must match the complete pending request, entry order and identity included, and give an explicit boolean `keep` for every entry. One exchange is pending per connection, and a disconnect discards it. An unsolicited, replayed, stale, partial or mixed acknowledgement deletes nothing. Retention traffic never uses the Provider request queue.
-
-## Local retention and helper lifetime
-
-A Core drop grant is necessary but not sufficient for collection. Queued and running provider calls, preparation, the local target and the serving pin all keep references; collection rechecks them and refuses on an already canceled connection. A canceled provider caller does not prove that its native helper stopped: the node counts a helper until its actual `Wait` returns.
-
-Every generation owns a permanent private lease file, `state/node/generations/.lease`. Before starting a native helper, the node takes a shared flock on it, validates the durable lease identity under that lock, and requires the published final provider configuration and no preparing, collecting or dropped journal. The helper inherits the descriptor; the node closes its own copy only after `Wait` and never unlocks the shared open-file description, so a canceled caller or a node exit does not release a live helper's reference. Native helpers set the descriptor close-on-exec before calling the SDK, so VM and daemon descendants do not inherit it.
-
-Collection takes the exclusive nonblocking flock before it inspects references, removes shared images or release files, or publishes the dropped marker, and holds it through those changes. Lease files belong to stable node state and are never removed or replaced during collection; symlinks, multiply linked files, foreign ownership, unsafe permissions and replaced lock paths are refused. Before the first helper can start, the installer creates the lease exclusively and fsyncs it, then atomically persists and fsyncs a private `.lease-identity` record and its directory. The record binds installation, generation, specification digest, device and inode. The Python collector and the Go helper opener validate the same record on every open, including after a restart; neither adopts a missing identity, replaces its inode or erases it after collection. An installation interrupted before the identity is durable refuses re-adoption and is kept for inspection. A removed identity or a replaced lease refuses even when its current metadata agree.
-
-A dropped generation can never be prepared or used again. A helper's exit is evidence about local files only, not proof that a remote mutation or an uncertain provider receipt has been released; Core's durable allocation and placement retention stays independent.
+```mermaid
+stateDiagram-v2
+ [*] --> preparing
+ preparing --> ready
+ preparing --> failed
+ failed --> preparing: repair
+ ready --> [*]: dropped
+ failed --> [*]: dropped
+```
-## Matched fresh installation
+A generation is the target, the serving generation, both or neither. The node reports each held generation as `preparing`, `ready` or `failed`; a dropped generation is never prepared or used again. Local collection of a dropped generation is described in the [Node installer](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md#generation-storage-and-recovery).
-The host program release and Core's selected Runtime release are independent. A fresh node gets its executable and private preparer from the console's current release, and reads the exact Runtime source, image identities and native runtime and firmware digests from its authenticated configuration. When that Runtime is older, the console still serves its immutable `releases//` manifest, checksums and allowlisted artifacts: the Runtime helper, firmware, seccomp profile and image bytes come from the selected release, and artifact URLs stay pinned to their verified manifest even if the console's current release changes during a download.
+Retention uses its own bounded exchange: the node asks and Core decides. The node's `retention` request names at most eight local `(generation, specification_digest)` references, a UUID, a sequence that increases by one, the current `connection_id` and the owner epoch. Core's `retention_ack` must match the complete pending request, entry order and identity included, and give an explicit boolean `keep` for every entry. One exchange is pending per connection, and a disconnect discards it. An unsolicited, replayed, stale, partial or mixed acknowledgement deletes nothing. Retention traffic never uses the Provider request queue.
-A missing retained release refuses the installation rather than substituting the current Runtime, and so does a local bundle that holds only a different Runtime. These refusals happen before the installer writes the node identity, imports the Runtime, registers the node or starts its service.
+```mermaid
+sequenceDiagram
+ participant N as Node
+ participant C as Core
+ N->>C: retention (id, sequence, up to 8 references)
+ C->>N: retention_ack (keep for every entry, same order)
+ Note over C,N: One exchange is pending per connection
+```
-A published console release keeps its metadata and artifact bytes. Publishing it again first validates all metadata and every existing declared artifact, then may atomically add only missing, checksum-matched declared artifacts; any conflict prevents every addition, and nothing is overwritten.
+## Readiness diagnostics
-## Restart recovery
-
-Missing Runtime bytes never move a pinned placement to the current Runtime. The node keeps the original generation and specification digest as unready and asks Core's authenticated configuration route for that exact generation before recovery. Missing seccomp bytes may leave an unready provider placeholder; missing image or native artifacts found by a provider probe queue a repair without advertising readiness.
-
-Preparation and repair are serialized. Target and serving generations come first, with bounded progress on the others. Each attempt has a 30-minute deadline, and failures back off for 1, 2, 5 and 10 minutes, then at most 30. Nothing is prepared before the connection has delivered deployment facts. Repair keeps existing configurations and paths, verifies the selected release and every existing sibling checksum, and downloads only missing immutable files. Conflicting bytes or a different retained specification refuse repair, and a missing provider configuration without an exact preparation plan is refused rather than reconstructed.
-
-Repair takes the same exclusive generation lease and installation lock as collection, so a live helper or a running collector keeps ownership and repair retries later. After the bytes are restored, the node still runs the provider's readiness probe; file presence and executable capability never establish readiness.
-
-## Preparation and collection records
-
-New preparation writes two distinct records. Before downloads, `.preparing` holds the installation, generation and specification identity, the private provider paths and `import_started: false`; it is a recovery and collection plan, not a provider. Before the importer runs, the plan records `import_started: true`. Python retention discovery and Go restart recovery both recognize pending-only plans but never build, probe or acquire a provider from them, and recovery or collection still needs authorization on the current connection.
-
-Only a successful preparation publishes the final `.json` provider configuration, which is write-once. Docker records the immutable local image ID its resolver returns; either the builder's config identity or the manifest identity can be valid for the same specification. Publication is durable before the preparation journal is cleared. An interruption between the two revalidates the same plan and final identity; plan, specification or path drift refuses. A canceled or failed import stays visible to Core's retention exchange without becoming a serving generation.
-
-Before any native or release deletion, the node persists a private collection journal bound to its installation, generation and specification digest. After a restart an unfinished journal is only a retention-exchange candidate: it cannot prepare, probe, acquire or advertise that generation, and a fresh correlated Core drop grant is needed to resume. Native completion is persisted before release files are removed, so a retry can finish a partly removed release without running an already removed helper. The digest-bound dropped marker follows durable file cleanup and prevents re-adoption; the small configuration and ownership journals stay as local identity records.
-
-For the installation-private microsandbox store, a successful, complete native image inventory distinguishes absence from a CLI failure; a failed query, malformed inventory, native in-use refusal or unknown ownership keeps the bytes. Shared microsandbox images and private releases stay until their last local reference. Docker images belong to the host's shared daemon: automatic collection never removes or prunes them, and only the host administrator can remove them after confirming that no installation on the host needs them.
+The readiness classes, one exported error and one code each, are authored in `services/core/internal/sandbox/node_diagnostic.go`. The shared `services/core/internal/sandbox/testdata/node-diagnostics.json` fixture checks the Go mapping, OpenAPI source annotations and generated enums, and the TypeScript client declaration. Web uses the client normalizer and checks localized messages for every declared code. Update these projections with a code change; clients read an unknown code as `provider_unavailable`.
-A fresh installation also records the verified checksums of its Runtime files separately from the host program. Collecting the original generation removes only the exact private Runtime helper, executable, firmware, seccomp and import-cache files that no retained configuration references. Every remaining file is checked before the first deletion; an unknown hash, changed bytes, links or missing ownership metadata refuse cleanup. The node executable, preparer, identity, base provider configuration and manifests stay, so a restarted node can still read its enrolled identity and construct a newer retained provider. Shared native paths are compared across all retained configurations before removal.
+Preparation diagnostics keep fixed typed causes. Only artifact transfer, checksum or release-provenance failures report `runtime_download_failed`; the private preparer signals that class through its exit category, without Core or the node parsing stderr. Provider, ownership, cancellation and unclassified failures keep their typed code or `provider_unavailable`. No raw provider text crosses the protocol.
-An interrupted download repairs only missing bytes at the original paths. When collection comes before any import attempt, the preparation journal proves that the generation has no imported native image. A generation whose native executable is missing and whose import may have started stays retained: missing files never prove native absence, and an empty native inventory never erases receipt or store history.
+## Timeouts and limits
-The readiness classes, one exported error and one code each, are authored in `services/core/internal/sandbox/node_diagnostic.go`. The shared `services/core/internal/sandbox/testdata/node-diagnostics.json` fixture checks the Go mapping, OpenAPI source annotations and generated enums, and the TypeScript client declaration. Web uses the client normalizer and checks localized messages for every declared code. Update these projections with a code change; clients read an unknown code as `provider_unavailable`.
+| Value | Applies to | On expiry or excess |
+| --- | --- | --- |
+| 15 s | `hello` after the connection opens | The connection closes |
+| 10 s | Heartbeat interval; also the write deadline of each frame | A failed write ends the connection |
+| 35 s | Any frame on an open connection | Either peer closes the connection |
+| 45 s | Age of the last heartbeat for an online node | Core counts the node as offline |
+| 1 to 120000 ms | Request `timeout_ms` | The request fails as unavailable or uncertain |
+| 32 | Pending requests per connection; `active_operations` in health | A full node queue closes the connection |
+| 32 KiB | Control frames | The connection closes |
+| 72 MiB | `request` and `response` frames | The connection closes |
+| 8 | Generation observations per message; references per `retention` request | An omitted observation implies nothing |
-Preparation diagnostics keep fixed typed causes. Only artifact transfer, checksum or release-provenance failures report `runtime_download_failed`; the private preparer signals that class through its exit category, without Core or the node parsing stderr. Provider, ownership, cancellation and unclassified failures keep their typed code or `provider_unavailable`. No raw provider text crosses the protocol.
+## Conformance
-Create bootstrap and Resume requests may carry an optional workspace filesystem binding. The node validates its tenant and Environment against the allocation reference, its immutable ObjectID, and its attachment configuration ID against the supplied configuration before forwarding it. The filesystem resolver validates adapter-native ownership. A missing binding selects owned storage; a present binding cannot fall back. Error responses may retain a Resume target only when its nonempty native ID, name, generation and snapshot provenance match the requested target; this is cleanup evidence, never successful restore.
+The Go tests in [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node) cover frames, connection ordering and fencing, request budgets, generation control and Provider operations. `make check-core` runs them. The Python node installer tests in `deploy/node` cover the node side of generation preparation and collection.
diff --git a/contracts/agents-api/zh/node-generation-protocol.md b/contracts/agents-api/zh/node-generation-protocol.md
index d60bc1d1d..064d6efad 100644
--- a/contracts/agents-api/zh/node-generation-protocol.md
+++ b/contracts/agents-api/zh/node-generation-protocol.md
@@ -1,10 +1,27 @@
---
title: "沙箱节点协议"
source: contracts/agents-api/node-generation-protocol.md
-source_hash: 06982830caebaaaa95b37a78c73710555a332a4a182aeab6d73836a964805443
+source_hash: fddbe0a4e99431dacba2f368d0d0d3b350b6fcb1ea8723e0eb889f23d1f61fb7
---
-沙箱节点在其主机上运行 Docker 或 microsandbox 提供商，并通过一个 WebSocket 与 Core 相连。Core 通过该连接发送提供商操作；节点针对本地提供商执行这些操作，并报告就绪状态、主机测量值及其持有的部署代次。Core 始终是唯一的生命周期所有者：节点绝不重试变更操作或调度工作。帧和校验器位于 [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node)（`wire.go`、`generation_wire.go`）；节点用于注册和读取配置的 HTTP 路由位于[机器连接 API](machine-api.md#node-routes)。
+沙箱节点协议连接 Core 与 Docker 或 microsandbox 主机：主机针对其本地提供商执行提供商操作，并报告就绪状态、主机测量值及其持有的部署代次。
+
+| | |
+| --- | --- |
+| 调用方 | Core，唯一的生命周期所有者；节点从不重试变更，也不调度工作 |
+| 实现 | 沙箱节点程序，搭配 Docker 与 microsandbox 提供商 |
+| 代码 | [`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node)（`wire.go`、`generation_wire.go`） |
+| 传输 | 一个 WebSocket，`GET /api/v1/sandbox-node/connect`；节点用于登记和读取配置的 HTTP 路由见[机器连接 API](machine-api.md#node-routes) |
+| 版本规则 | 与 `node.ProtocolVersion` 精确匹配，见[帧与版本](#frames-and-version) |
+
+节点本地存储、代次租约和恢复不属于线路协议，由 [Node installer](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md#generation-storage-and-recovery) 负责。
+
+## 角色 {#roles}
+
+| 参与方 | 负责 |
+| --- | --- |
+| Core | 节点身份与在线状态、所有者 epoch、目标代次、每个请求及其序号，以及每个保留决定 |
+| 节点 | 其本地提供商、其准备并服务的代次、健康状态与主机测量值，以及针对提供商执行每个请求 |
## 帧与版本 {#frames-and-version}
@@ -12,12 +29,28 @@ source_hash: 06982830caebaaaa95b37a78c73710555a332a4a182aeab6d73836a964805443
## 连接 {#connection}
+```mermaid
+sequenceDiagram
+ participant N as Node
+ participant C as Core
+ N->>C: dial /sandbox-node/connect with Bearer credential
+ Note over C: 401 rejected credential (permanent), 409 duplicate connection
+ N->>C: hello (identity, health, generation observations)
+ C->>N: welcome (connection_id, owner_epoch, deployment)
+ loop every 10 s
+ N->>C: heartbeat (connection_id, owner_epoch, health)
+ C->>N: heartbeat_ack (deployment)
+ end
+ C->>N: request (id, sequence, operation)
+ N->>C: response (id, result or error_code)
+```
+
1. 节点在其存储的 Core 源地址上发起对 `/api/v1/sandbox-node/connect?node_id=` 的连接（对于 `https` 使用 `wss`），并以 Bearer 请求头发送节点凭据。Core 对被拒绝的凭据返回 401，节点将其视为永久性拒绝；其他任何失败（包括代理返回的 403）都会使用有界退避进行重试。当某个节点身份已有一个连接正在建立、存活或关闭时，Core 会以 409 拒绝第二个连接。
2. 节点须在 15 秒内发送 `hello`，其中包含节点身份（`node_id`、`installation_id`、`provider`、`backend_fingerprint`、已登记的 `deployment_generation` 和 `specification_digest`、`max_active`、`max_retained`）、首次健康报告；如果节点能够准备并保留多个部署代次，还包含 `generation_management: true`。除非身份与已认证节点匹配，否则 Core 会关闭连接。
3. Core 记录节点的存在状态，然后回复 `welcome`，其中包含新的 `connection_id` 和当前 `owner_epoch`；对于支持代次管理的节点，还包含 `deployment`：目标 `generation`、其 `specification_digest` 和可空的 `serving_generation`。节点保存更高的所有者 epoch，并拒绝更低的值。
4. 节点每 10 秒发送一次 `heartbeat`，其中包含 `connection_id`、`owner_epoch` 和健康状态。对于每次心跳，Core 都会再次认证节点凭据并检查所有者 epoch，记录健康状态并回复 `heartbeat_ack`；对于支持代次管理的节点，回复中还包含 `deployment`。任一端连续 35 秒未收到任何帧时都会关闭连接。
-只要节点在当前所有者 epoch 下保持连接，并且最近一次心跳距今不足 45 秒，Core 就会将该节点计为在线。心跳会确立提供商的就绪状态和最近的主机测量值，但绝不表示 Session 活动。
+只要节点在当前所有者 epoch 下保持连接，并且最近一次心跳距今不足 45 秒，Core 就会将该节点计为在线。心跳会确立提供商的就绪状态和最近的主机测量值，但绝不表示 Session 活动。[超时与限制](#timeouts-and-limits)列出所有计时器。
健康报告包含 `provider_ready`、可选的固定 `diagnostic`、`observed_at`、最多为 32 的 `active_operations`，以及 [Runtime 遥测 API](runtime-observability-api.md#node-host-observations-and-history) 报告的主机测量值。未启用代次管理的节点每次报告时都会探测其提供商；未就绪的提供商会报告其首个失败检查所属的、与提供商无关的就绪类别，该类别取自探测所包装的类别错误；探测文本、厂商细节和主机路径保留在节点上。节点或代次健康状态中的 `diagnostic` 若不是已声明的类别，该帧即无效。[节点指南](../../../docs/zh/getting-started/nodes.md#readiness-codes) 列出了这些类别及其原因。支持代次管理的节点则按下文所述按代次报告就绪状态。
@@ -73,56 +106,57 @@ Core 发送包含以下内容的 `request` 帧：
节点启动和代次加载会在接受工作前验证完整的提供商操作声明，Core 代理使用同一份已注册声明，因此不支持的操作会在节点解析或原生 I/O 之前被拒绝。操作清单由[操作契约](../../../docs/zh/sandbox-provider.md#explicit-operation-contracts)维护。`unsupported` 响应包含一个 `unsupported` 对象，其中有精确的方法 `operation` 和经作者编写且安全的 `reason`；代理会将两者与请求进行核对。证据缺失、格式错误或不匹配会得到 `unconfirmed` 结果，而绝不会证明变更操作被拒绝。`unsupported` 始终不同于观察不可用，也不同于计算或命令结果未知；它既不确定资源所有权，也不授权重放。
+Create 引导和 Resume 请求可携带可选的工作区文件系统绑定。节点在转发前校验其租户及 Environment 与分配引用一致、ObjectID 不可变且有效，以及挂载配置 ID 与所传配置一致。文件系统解析器负责适配器原生所有权校验。未提供绑定时选择自有存储；已提供绑定时不得回退。错误响应仅可保留原生 ID 非空且名称、代次、快照来源均匹配请求的 Resume 目标；这仅为清理证据，不代表恢复成功。
+
## 代次控制 {#generation-control}
未启用代次管理的节点只服务其登记的代次，配置固定，并且不会收到准备或保留帧。它可以在 `Health.Generations` 报告该精确代次；支持检查点的提供商必须报告，并包含已验证的检查点资格。`provider_ready` 必须与报告的状态一致。支持代次管理的节点会准备 Core 在 `welcome` 和 `heartbeat_ack` 中通告的目标代次，并在此期间继续服务其持久化的服务代次；目标代次的准备独立于服务提供商的就绪状态。
节点的 `hello` 和心跳最多携带八条代次观察记录。每条记录指定一个正值的有符号 64 位代次编号、其小写 SHA-256 规范摘要、`ready`、`preparing` 或 `failed` 状态，以及可选的固定诊断信息。目标代次和服务代次的记录排在前面，其余记录公平轮换。八条记录限制的是单条消息，而不是节点可保留的代次数量。省略某条观察记录绝不会授权删除，也不会暗示不存在。 支持检查点的 ready 代次携带 `checkpoint`，包含非空且不透明的 `artifact_domain` 和 `execution_class` token，各最多 256 字节。不支持的提供商省略该字段；preparing 或 failed 代次不声明它。Core 将声明与已认证连接和代次一起持久化，仅在当前在线连接的该代次仍 ready 时使用。[提供商契约](../../../docs/zh/sandbox-provider.md#checkpoint-transfer) 定义归档与执行兼容性。
-保留使用独立且有界的交换。`retention` 请求最多指定八个本地 `(generation, specification_digest)` 引用、一个 UUID、一个每次递增 1 的 `sequence`、当前 `connection_id` 和所有者 epoch。`retention_ack` 必须与完整的待处理请求匹配，包括条目顺序和身份信息，并为每个条目给出显式布尔值 `keep`。每条连接只能有一个交换处于待处理状态，断连会将其丢弃。任何未经请求、重放、过期、不完整或混合的确认都不会删除任何内容。保留流量从不使用提供商请求队列。
-
-## 本地保留与辅助程序生命周期 {#local-retention-and-helper-lifetime}
-
-Core 的丢弃授权是回收的必要条件，但并非充分条件。排队和运行中的提供商调用、准备过程、本地目标代次以及服务固定引用都会保留引用；回收会再次检查这些引用，并拒绝在已取消的连接上执行。取消提供商调用方并不能证明其原生辅助程序已经停止；节点会将该辅助程序计为存活，直到其实际 `Wait` 返回。
-
-每个代次都拥有一个永久私有租约文件 `state/node/generations/.lease`。在启动原生辅助程序之前，节点先在该文件上获取共享 flock，在持有该锁时验证持久化租约身份，并要求最终提供商配置已经发布且不存在 preparing、collecting 或 dropped 日志。辅助程序继承该描述符；节点仅在 `Wait` 返回后关闭自己的副本，且绝不显式解锁该共享打开文件描述，因此取消调用方或节点退出都不会释放仍在运行的辅助程序所持的引用。原生辅助程序在调用 SDK 前会设置描述符的 close-on-exec 标志，因此 VM 和守护进程后代不会继承它。
-
-回收在检查引用、删除共享镜像或版本文件或发布 dropped 标记之前，先获取独占非阻塞 flock，并在这些变更期间持续持有该锁。租约文件属于稳定的节点状态，回收期间绝不删除或替换；符号链接、多重硬链接文件、外来所有权、不安全权限以及被替换的锁定路径都会被拒绝。在第一个辅助程序能够启动之前，安装器先独占创建租约并对其执行 fsync，随后以原子方式持久化私有 `.lease-identity` 记录，并对该记录及其目录执行 fsync。该记录绑定安装、代次、规范摘要、设备号和 inode。Python 回收器和 Go 辅助程序打开器在每次打开时都会验证同一记录，包括重启后；身份记录缺失时，两者都不会进行接管，也不会替换其 inode 或在回收后将其擦除。若安装在身份记录持久化前中断，则会拒绝重新接管，并保留该安装以供检查。身份记录被移除或租约被替换时，即使当前元数据一致，也会拒绝重新接管。
-
-已丢弃代次绝不能再次准备或使用。辅助程序退出只能证明本地文件方面的状态，不能证明远程变更操作或结果不确定的提供商回执已释放；Core 对分配和放置的持久保留仍保持独立。
+```mermaid
+stateDiagram-v2
+ [*] --> preparing
+ preparing --> ready
+ preparing --> failed
+ failed --> preparing: repair
+ ready --> [*]: dropped
+ failed --> [*]: dropped
+```
-## 完全匹配的新安装 {#matched-fresh-installation}
+一个代次可以是目标代次、服务代次、两者兼是或两者皆非。节点将所持有的每个代次报告为 `preparing`、`ready` 或 `failed`；已丢弃的代次不会再被准备或使用。已丢弃代次的本地回收见 [Node installer](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/deploy/node/README.md#generation-storage-and-recovery)。
-主机程序版本与 Core 选择的 Runtime 版本彼此独立。全新节点从控制台当前版本获取其可执行文件和私有准备器，并从经认证的配置中读取确切的 Runtime 源、镜像身份以及原生运行时和固件摘要。当该 Runtime 较旧时，控制台仍会提供其不可变的 `releases//` 清单、校验和以及允许列表中的制品：Runtime 辅助程序、固件、seccomp 配置文件和镜像字节都来自所选版本；即使下载期间控制台的当前版本发生变化，制品 URL 仍固定到已验证的清单。
+保留使用独立且有界的交换：由节点询问，由 Core 决定。节点的 `retention` 请求最多指定八个本地 `(generation, specification_digest)` 引用、一个 UUID、一个每次递增 1 的 `sequence`、当前 `connection_id` 和所有者 epoch。Core 的 `retention_ack` 必须与完整的待处理请求匹配，包括条目顺序和身份信息，并为每个条目给出显式布尔值 `keep`。每条连接只能有一个交换处于待处理状态，断连会将其丢弃。任何未经请求、重放、过期、不完整或混合的确认都不会删除任何内容。保留流量从不使用提供商请求队列。
-所需的保留版本缺失时，安装会被拒绝，而不会替换为当前 Runtime；仅包含另一个 Runtime 的本地捆绑包也会导致拒绝。所有这些拒绝都发生在安装器写入节点身份、导入 Runtime、注册节点或启动服务之前。
+```mermaid
+sequenceDiagram
+ participant N as Node
+ participant C as Core
+ N->>C: retention (id, sequence, up to 8 references)
+ C->>N: retention_ack (keep for every entry, same order)
+ Note over C,N: One exchange is pending per connection
+```
-已发布的控制台版本会保留其元数据和制品字节。再次发布时，会先验证所有元数据及每个已存在的已声明制品，然后可以原子地仅添加缺失且校验和匹配的已声明制品；任何冲突都会阻止全部添加，并且不会覆盖任何内容。
+## 就绪诊断 {#readiness-diagnostics}
-## 重启恢复 {#restart-recovery}
-
-Runtime 字节缺失时，绝不将固定的放置实例迁移到当前 Runtime。节点将原始代次和规范摘要保留为未就绪状态，并在恢复前通过 Core 的经认证配置路由请求该精确代次。缺少 seccomp 字节可能留下未就绪的提供商占位项；提供商探测发现镜像或原生制品缺失时，会将修复排队，但不会通告就绪状态。
-
-准备和修复串行执行。目标代次和服务代次优先，其余代次则以有界方式推进。每次尝试的截止时间为 30 分钟；失败后依次退避 1、2、5 和 10 分钟，此后最多退避 30 分钟。在连接提供部署信息之前，不准备任何内容。修复保留现有配置和路径，验证所选版本及每个现有同级文件的校验和，并且只下载缺失的不可变文件。字节冲突或保留规范不同都会拒绝修复；如果缺少提供商配置且没有精确的准备计划，也会拒绝，而不是重建该配置。
-
-修复与回收使用相同的独占代次租约和安装锁，因此正在运行的辅助程序或回收器会保持所有权，修复稍后重试。字节恢复后，节点仍会运行提供商的就绪探测；文件存在和具备可执行能力永远不能证明就绪。
-
-## 准备与回收记录 {#preparation-and-collection-records}
-
-新的准备过程会写入两条不同的记录。下载前，`.preparing` 保存安装、代次和规范身份、私有提供商路径以及 `import_started: false`；它是恢复和回收计划，而不是提供商。导入器运行前，计划会记录 `import_started: true`。Python 保留发现流程和 Go 重启恢复流程都能识别仅有待处理状态的计划，但绝不会据此构建、探测或获取提供商；恢复或回收仍需要当前连接上的授权。
-
-只有准备成功才会发布最终 `.json` 提供商配置，该配置只写入一次。Docker 记录其解析器返回的不可变本地镜像 ID；对于同一规范，构建器的配置身份或清单身份均可有效。准备日志清除之前，发布结果必须已经持久化。两者之间发生中断时，会重新验证同一计划和最终身份；计划、规范或路径发生漂移时会拒绝。已取消或失败的导入仍会向 Core 的保留交换保持可见，但不会成为服务代次。
-
-在删除任何原生层对象或版本文件之前，节点都会持久化一份私有回收日志，并将其绑定到安装、代次和规范摘要。重启后，未完成的日志仅是保留交换的候选项：它不能准备、探测、获取或通告该代次，必须重新获取一份与之关联的新 Core 丢弃授权后才能继续。在删除版本文件之前先持久化原生清理完成状态，因此重试可以完成部分删除的版本，而不会运行已经删除的辅助程序。完成持久化文件清理后，再写入与摘要绑定的 dropped 标记，以防重新接管；这些小型的配置和所有权日志会保留为本地身份记录。
-
-对于仅属于该安装的 microsandbox 存储，成功且完整的原生镜像清单可以区分“不存在”和“CLI 失败”；查询失败、清单格式错误、原生层因正在使用而拒绝或所有权不明时，都会保留这些字节。共享 microsandbox 镜像和私有版本会一直保留到最后一个本地引用消失。Docker 镜像属于主机的共享守护进程：自动回收绝不删除或修剪这些镜像，只有主机管理员在确认主机上没有安装需要它们后才能删除。
+就绪类别编写于 `services/core/internal/sandbox/node_diagnostic.go`，每个类别对应一个导出错误和一个代码。共享的 `services/core/internal/sandbox/testdata/node-diagnostics.json` 测试夹具检查 Go 映射、OpenAPI 源注释和生成的枚举，以及 TypeScript 客户端声明。Web 使用客户端规范化器，并检查每个已声明代码的本地化消息。代码变更时要同步更新这些投影；客户端将未知代码读作 `provider_unavailable`。
-全新安装还会另行记录其 Runtime 文件的已验证校验和，与主机程序分开保存。回收原始代次时，只删除未被任何保留配置引用的确切私有 Runtime 辅助程序、可执行文件、固件、seccomp 和导入缓存文件。第一次删除前会检查每个剩余文件；哈希未知、字节发生变化、存在链接或缺少所有权元数据时，都会拒绝清理。节点可执行文件、准备器、身份、基础提供商配置和清单会保留，因此重启后的节点仍可读取其登记身份并构建较新的保留提供商。删除共享原生路径前，会先在所有保留配置之间对这些路径进行比较。
+准备诊断使用固定的类型化原因。只有制品传输、校验和或版本来源验证失败才会报告 `runtime_download_failed`；私有准备器通过退出类别指示这一类失败，Core 和节点都不解析 stderr。提供商故障、所有权故障、取消和未分类故障保留其类型化代码，或使用 `provider_unavailable`。协议中不会传输任何提供商原始文本。
-下载中断后，只会修复原始路径中缺失的字节。如果在任何导入尝试之前执行回收，准备日志会证明该代次没有已导入的原生镜像。如果某代次的原生可执行文件缺失，且导入可能已经开始，该代次仍会保留：文件缺失永远不能证明原生制品不存在，而空的原生清单也永远不能抹除回执或存储历史。
+## 超时与限制 {#timeouts-and-limits}
-就绪类别编写于 `services/core/internal/sandbox/node_diagnostic.go`，每个类别对应一个导出错误和一个代码。共享的 `services/core/internal/sandbox/testdata/node-diagnostics.json` 测试夹具检查 Go 映射、OpenAPI 源注释和生成的枚举，以及 TypeScript 客户端声明。Web 使用客户端规范化器，并检查每个已声明代码的本地化消息。代码变更时要同步更新这些投影；客户端将未知代码读作 `provider_unavailable`。
+| 值 | 适用于 | 到期或超出时 |
+| --- | --- | --- |
+| 15 秒 | 连接打开后的 `hello` | 连接关闭 |
+| 10 秒 | 心跳间隔；也是每个帧的写入截止时间 | 写入失败会结束连接 |
+| 35 秒 | 已打开连接上的任意帧 | 任一端关闭连接 |
+| 45 秒 | 在线节点最近一次心跳的时长 | Core 将该节点计为离线 |
+| 1 到 120000 毫秒 | 请求的 `timeout_ms` | 请求以不可用或不确定结束 |
+| 32 | 每个连接的待处理请求数；健康状态中的 `active_operations` | 节点队列已满时关闭连接 |
+| 32 KiB | 控制帧 | 连接关闭 |
+| 72 MiB | `request` 和 `response` 帧 | 连接关闭 |
+| 8 | 每条消息的代次观察记录数；每个 `retention` 请求的引用数 | 缺失的观察记录不代表任何含义 |
-准备诊断使用固定的类型化原因。只有制品传输、校验和或版本来源验证失败才会报告 `runtime_download_failed`；私有准备器通过退出类别指示这一类失败，Core 和节点都不解析 stderr。提供商故障、所有权故障、取消和未分类故障保留其类型化代码，或使用 `provider_unavailable`。协议中不会传输任何提供商原始文本。
+## 一致性测试 {#conformance}
-Create 引导和 Resume 请求可携带可选的工作区文件系统绑定。节点在转发前校验其租户及 Environment 与分配引用一致、ObjectID 不可变且有效，以及挂载配置 ID 与所传配置一致。文件系统解析器负责适配器原生所有权校验。未提供绑定时选择自有存储；已提供绑定时不得回退。错误响应仅可保留原生 ID 非空且名称、代次、快照来源均匹配请求的 Resume 目标；这仅为清理证据，不代表恢复成功。
+[`services/core/internal/sandbox/node`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/sandbox/node) 中的 Go 测试覆盖帧、连接顺序与围栏、请求预算、代次控制和提供商操作，由 `make check-core` 运行。`deploy/node` 中的 Python 节点安装程序测试覆盖代次准备与回收的节点侧。
diff --git a/deploy/node/README.md b/deploy/node/README.md
index 883810251..9a98e0645 100644
--- a/deploy/node/README.md
+++ b/deploy/node/README.md
@@ -44,6 +44,50 @@ The distribution manifest is the one download contract for nodes: flat versioned
- Release downloads are anonymous. Never add repository credentials to installed node or Runtime configuration.
- Manual builds use the `build-` release tag and tag builds the `v*` tag. The manifest's download base must match the release tag; artifact file names and source provenance keep the full source SHA.
+## Generation storage and recovery
+
+A node stores the deployment generations it prepares under its installation state and keeps, collects and repairs them on its own. The [Sandbox node protocol](../../contracts/agents-api/node-generation-protocol.md) defines what crosses the wire: generation observations, the retention exchange and the readiness classes.
+
+### Local retention and helper lifetime
+
+A Core drop grant is necessary but not sufficient for collection. Queued and running provider calls, preparation, the local target and the serving pin all keep references; collection rechecks them and refuses on an already canceled connection. A canceled provider caller does not prove that its native helper stopped: the node counts a helper until its actual `Wait` returns.
+
+Every generation owns a permanent private lease file, `state/node/generations/.lease`. Before starting a native helper, the node takes a shared flock on it, validates the durable lease identity under that lock, and requires the published final provider configuration and no preparing, collecting or dropped journal. The helper inherits the descriptor; the node closes its own copy only after `Wait` and never unlocks the shared open-file description, so a canceled caller or a node exit does not release a live helper's reference. Native helpers set the descriptor close-on-exec before calling the SDK, so VM and daemon descendants do not inherit it.
+
+Collection takes the exclusive nonblocking flock before it inspects references, removes shared images or release files, or publishes the dropped marker, and holds it through those changes. Lease files belong to stable node state and are never removed or replaced during collection; symlinks, multiply linked files, foreign ownership, unsafe permissions and replaced lock paths are refused. Before the first helper can start, the installer creates the lease exclusively and fsyncs it, then atomically persists and fsyncs a private `.lease-identity` record and its directory. The record binds installation, generation, specification digest, device and inode. The Python collector and the Go helper opener validate the same record on every open, including after a restart; neither adopts a missing identity, replaces its inode or erases it after collection. An installation interrupted before the identity is durable refuses re-adoption and is kept for inspection. A removed identity or a replaced lease refuses even when its current metadata agree.
+
+A dropped generation can never be prepared or used again. A helper's exit is evidence about local files only, not proof that a remote mutation or an uncertain provider receipt has been released; Core's durable allocation and placement retention stays independent.
+
+### Matched fresh installation
+
+The host program release and Core's selected Runtime release are independent. A fresh node gets its executable and private preparer from the console's current release, and reads the exact Runtime source, image identities and native runtime and firmware digests from its authenticated configuration. When that Runtime is older, the console still serves its immutable `releases//` manifest, checksums and allowlisted artifacts: the Runtime helper, firmware, seccomp profile and image bytes come from the selected release, and artifact URLs stay pinned to their verified manifest even if the console's current release changes during a download.
+
+A missing retained release refuses the installation rather than substituting the current Runtime, and so does a local bundle that holds only a different Runtime. These refusals happen before the installer writes the node identity, imports the Runtime, registers the node or starts its service.
+
+A published console release keeps its metadata and artifact bytes. Publishing it again first validates all metadata and every existing declared artifact, then may atomically add only missing, checksum-matched declared artifacts; any conflict prevents every addition, and nothing is overwritten.
+
+### Restart recovery
+
+Missing Runtime bytes never move a pinned placement to the current Runtime. The node keeps the original generation and specification digest as unready and asks Core's authenticated configuration route for that exact generation before recovery. Missing seccomp bytes may leave an unready provider placeholder; missing image or native artifacts found by a provider probe queue a repair without advertising readiness.
+
+Preparation and repair are serialized. Target and serving generations come first, with bounded progress on the others. Each attempt has a 30-minute deadline, and failures back off for 1, 2, 5 and 10 minutes, then at most 30. Nothing is prepared before the connection has delivered deployment facts. Repair keeps existing configurations and paths, verifies the selected release and every existing sibling checksum, and downloads only missing immutable files. Conflicting bytes or a different retained specification refuse repair, and a missing provider configuration without an exact preparation plan is refused rather than reconstructed.
+
+Repair takes the same exclusive generation lease and installation lock as collection, so a live helper or a running collector keeps ownership and repair retries later. After the bytes are restored, the node still runs the provider's readiness probe; file presence and executable capability never establish readiness.
+
+### Preparation and collection records
+
+New preparation writes two distinct records. Before downloads, `.preparing` holds the installation, generation and specification identity, the private provider paths and `import_started: false`; it is a recovery and collection plan, not a provider. Before the importer runs, the plan records `import_started: true`. Python retention discovery and Go restart recovery both recognize pending-only plans but never build, probe or acquire a provider from them, and recovery or collection still needs authorization on the current connection.
+
+Only a successful preparation publishes the final `.json` provider configuration, which is write-once. Docker records the immutable local image ID its resolver returns; either the builder's config identity or the manifest identity can be valid for the same specification. Publication is durable before the preparation journal is cleared. An interruption between the two revalidates the same plan and final identity; plan, specification or path drift refuses. A canceled or failed import stays visible to Core's retention exchange without becoming a serving generation.
+
+Before any native or release deletion, the node persists a private collection journal bound to its installation, generation and specification digest. After a restart an unfinished journal is only a retention-exchange candidate: it cannot prepare, probe, acquire or advertise that generation, and a fresh correlated Core drop grant is needed to resume. Native completion is persisted before release files are removed, so a retry can finish a partly removed release without running an already removed helper. The digest-bound dropped marker follows durable file cleanup and prevents re-adoption; the small configuration and ownership journals stay as local identity records.
+
+For the installation-private microsandbox store, a successful, complete native image inventory distinguishes absence from a CLI failure; a failed query, malformed inventory, native in-use refusal or unknown ownership keeps the bytes. Shared microsandbox images and private releases stay until their last local reference. Docker images belong to the host's shared daemon: automatic collection never removes or prunes them, and only the host administrator can remove them after confirming that no installation on the host needs them.
+
+A fresh installation also records the verified checksums of its Runtime files separately from the host program. Collecting the original generation removes only the exact private Runtime helper, executable, firmware, seccomp and import-cache files that no retained configuration references. Every remaining file is checked before the first deletion; an unknown hash, changed bytes, links or missing ownership metadata refuse cleanup. The node executable, preparer, identity, base provider configuration and manifests stay, so a restarted node can still read its enrolled identity and construct a newer retained provider. Shared native paths are compared across all retained configurations before removal.
+
+An interrupted download repairs only missing bytes at the original paths. When collection comes before any import attempt, the preparation journal proves that the generation has no imported native image. A generation whose native executable is missing and whose import may have started stays retained: missing files never prove native absence, and an empty native inventory never erases receipt or store history.
+
## Image identity
The manifest's `images` records each exported image's config digest, and `image_manifest_digests` its OCI manifest or index digest. Derive and verify both from the same archive, including its referenced config and layer bytes, and require the build host's selected image ID to match one of them.
diff --git a/docs/architecture.md b/docs/architecture.md
index 8047b305e..d46d30d92 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -38,7 +38,7 @@ Dashed arrows show provisioning and installation. Solid arrows show component in
| --- | --- | --- |
| Core | Authenticate callers, resolve and freeze configuration, schedule Turns, handle cancellation and pending interactions, persist resources and execution facts in PostgreSQL | [Core service](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/README.md) |
| Sandbox Provider | Create, observe, renew and reclaim compute; supply Runtime startup input | [Sandbox Provider](./sandbox-provider.md), [Runtime bootstrap](./runtime-bootstrap.md) |
-| Workspace filesystem adapter | Create, observe and delete durable Environment storage; validate and resolve its compute attachment | [Workspace filesystem providers](./workspace-provider.md) |
+| Workspace filesystem adapter | Create, observe and delete durable Environment storage; validate and resolve its compute attachment | [Workspace filesystem protocol](./workspace-provider.md) |
| Sandbox node | Operate a Docker or microsandbox host and reconcile its assigned generation and allocations | [Sandbox node protocol](../contracts/agents-api/node-generation-protocol.md) |
| Runtime | Prepare the workspace and capabilities, manage Session Executors, execute Turns and report events and receipts | [Core–Runtime protocol](./runtime-protocol.md) |
| Harness adapter | Validate native configuration, invoke the upstream SDK or protocol, translate events and confirm native cleanup | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) |
diff --git a/docs/workspace-provider.md b/docs/workspace-provider.md
index 37d287c13..e9dc19c2e 100644
--- a/docs/workspace-provider.md
+++ b/docs/workspace-provider.md
@@ -1,8 +1,38 @@
---
-title: Workspace filesystem providers
+title: Workspace filesystem protocol
---
-The independent workspace filesystem boundary is defined in [`workspacefs.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/workspacefs/workspacefs.go). This document specifies the required integration contract; it does not establish that every Sandbox Provider or placement implements it. Filesystem adapters own storage objects and native attachment resolution. [Sandbox Providers](sandbox-provider.md) own compute. Core selects and validates their combination before allocating either resource.
+The workspace filesystem protocol connects Core and sandbox nodes to the adapter that owns durable Environment storage. Core creates, observes and deletes storage objects; a node resolves an object to a host directory that its [Sandbox Provider](sandbox-provider.md) attaches to compute. It is for authors of filesystem adapters and Sandbox Providers.
+
+| | |
+| --- | --- |
+| Caller | Core (`Control`) and the sandbox node (`Resolver`) |
+| Implementations | The kernel NFS adapter (`nfs`), registered in `services/core/internal/workspacefs/providers` |
+| Code | [`workspacefs.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/workspacefs/workspacefs.go) |
+| Transport | In-process Go interfaces; a `Binding` crosses the [Sandbox node protocol](../contracts/agents-api/node-generation-protocol.md#provider-requests) in `Create` bootstrap and `Resume` requests |
+
+Core selects and validates the combination of a Sandbox Provider and a filesystem adapter before it allocates either resource.
+
+| Sandbox Provider | External workspace storage |
+| --- | --- |
+| microsandbox | Supported (`host_directory`, `user_xattr`) |
+| Docker, E2B | Not supported; the Provider's own Environment disk |
+
+## Implement an adapter
+
+1. Define `Parameters` and the optional credential, and implement `Normalize` ([Identity and configuration](#identity-and-configuration)).
+2. Implement `Declaration`, `Check`, `Create`, `Observe` and `Delete` in `Control`, and `Resolve` in `Resolver` ([Operations and outcomes](#operations-and-outcomes)).
+3. Declare the attachment kind, user xattr support and quota enforcement ([Capability validation](#capability-validation)).
+4. Keep one writer per object and delete only on Core's authorization ([Lifetime and filesystem scope](#lifetime-and-filesystem-scope)).
+
+## Roles
+
+| Party | Owns |
+| --- | --- |
+| Core | Identities, the persisted `Reference`, configuration and credential, admitted capacity, the lifecycle order and every deletion decision |
+| Filesystem adapter | Native storage objects, their receipts, native ownership checks and path resolution |
+| Sandbox Provider | Compute, and attaching the resolved directory to it |
+
## Identity and configuration
@@ -31,7 +61,18 @@ Every control adapter implements `Declaration`, `Check`, `Create`, `Observe` and
| `Delete(ctx, reference)` | Converge on terminal deletion of the verified owned object after Core has authorized deletion and confirmed compute stop. |
| `Resolve(ctx, binding)` | Validate native ownership and resolve the attachment for local compute. |
-Errors support `errors.Is`: `ErrInvalid` for invalid input, `ErrOwnership` for a reference or configuration mismatch, `ErrUnavailable` for unavailable storage, `ErrUnconfirmed` for an unknown mutation outcome, `ErrNotFound` for a missing object and `ErrUnsupported` for an unsupported combination. Adapters preserve these outcomes when wrapping errors. A missing observation does not prove an earlier mutation settled. A timeout or canceled context ends the caller's wait; it does not prove native stop or rollback. Core retains ownership on unknown outcomes. It may retry `Create` or `Delete` with the same persisted immutable reference and configuration, including after `ErrUnconfirmed`; it must never substitute a new object identity to retry an uncertain operation.
+Errors support `errors.Is`. Adapters preserve these outcomes when wrapping errors.
+
+| Error | Condition |
+| --- | --- |
+| `ErrInvalid` | Invalid input |
+| `ErrOwnership` | A reference or configuration mismatch |
+| `ErrUnavailable` | Storage is unavailable |
+| `ErrUnconfirmed` | The mutation outcome is unknown |
+| `ErrNotFound` | The object is missing |
+| `ErrUnsupported` | The combination is unsupported |
+
+A missing observation does not prove an earlier mutation settled. A timeout or canceled context ends the caller's wait; it does not prove native stop or rollback. Core retains ownership on unknown outcomes. It may retry `Create` or `Delete` with the same persisted immutable reference and configuration, including after `ErrUnconfirmed`; it must never substitute a new object identity to retry an uncertain operation.
Same-reference retry and concurrent convergence are mandatory adapter guarantees. `Create` preserves any existing object data and returns the attachment for that owned object; it never reinitializes a live object. Repeated and concurrent `Delete` calls converge on the same terminal deletion. Once terminal deletion is recorded, concurrent, delayed or retried `Create` calls must not resurrect the object, and `Resolve` must not expose it. Retained deletion metadata and further cleanup of settled in-flight operations are permitted. These guarantees apply to storage lifecycle operations; they do not establish mutation settlement at timeout or distributed compute fencing.
@@ -53,11 +94,19 @@ The object contains the whole `/environment` tree, including the workspace, stag
Workspace storage is retained with its Session until explicit Session deletion. Archival, expiration, reset and compute checkpoint deletion do not authorize workspace deletion. Core calls `Delete` only after explicit Session deletion and confirmed compute stop; unresolved compute or storage mutations retain ownership. Failed creation does not authorize deleting storage while its Session is retained. Eligible nonterminal Sessions can survive checkpoint retention expiry and later attach the same object to fresh compute under the [cold replacement lifecycle](sandbox-provider.md#cold-replacement-after-checkpoint-retention). This does not revive archived, reset or deleted execution.
+## Attachment
+
+`Bootstrap.Workspace` and `ResumeRequest.Workspace` optionally carry a [workspace filesystem binding](#identity-and-configuration). Absence selects the Provider's owned Environment disk; presence selects the exact external object and never permits a fallback to an owned disk. Providers validate the tenant and Environment against the binding and its configuration receipt before resolving it. `LocalOptions.Workspace` injects the filesystem resolver; Sandbox Providers never interpret filesystem adapter parameters or native receipts.
+
+`DeploymentPolicy.Workspace` declares supported attachment requirements; absence means external storage is unsupported. The derived immutable `DeploymentSpec.Workspace` receipt selects the generation mode and capabilities; its [deployment workflow](../contracts/agents-api/sandbox-deployment.md#resources) never copies filesystem configuration into the generation. Microsandbox requires `host_directory` and `user_xattr`; Docker and E2B reject external attachments. `ValidateWorkspacePolicy` uses the filesystem protocol's combination validator: an external filesystem without an enforced quota rejects a positive `EnvironmentDiskMiB`, while zero requests no quota. Root disk capacity is still required. Without an external declaration, the existing owned disk bounds apply.
+
+Microsandbox resolves each Create and Resume binding, including observation of an interrupted restore, and passes only the local directory and immutable ObjectID to its private helper. The helper binds the whole `/environment`; its retained contents and private native history follow the [workspace filesystem scope](#lifetime-and-filesystem-scope) and [Runtime resource directories](configuration.md#runtime-resource-directories). Private HOME, credentials and the compute root are not a durable history store. Explicit mode, object and path labels qualify native resources; mount shape alone never selects a mode. Checkpoint restore verifies the snapshot's object, remaps `/environment` through SDK `Volumes`, requires strict external mount policy and rejects every restore warning. Partial restore errors retain the exact target identity for cleanup and never establish readiness. Unknown outcomes remain observations of the original operation. Native Bind checkpoint and guest-local flock continuity do not establish fencing against an unknown writer.
+
## Kernel NFS adapter
The `nfs` adapter uses an operator-premounted Linux kernel NFS filesystem. The supported setup is NFSv4.2 on trusted AUTH_SYS clients with `root_squash`, using the same export and absolute mount path on Core and nodes. The adapter neither mounts exports nor manages NFS credentials or service accounts. Other operating systems return `ErrUnsupported`. [Configuration](./configuration.md#independent-workspace-storage) owns installation steps and selection.
-Parameters contain `root`, `namespace_id`, `uid` and, in quota mode, `quota`. `root` is a clean absolute mount path; `namespace_id` is a canonical nonzero UUID; `uid` is the nonzero effective host UID required on both Core and nodes. The initial deployment uses 65532. The operator prepares the mounted root with mode `0700`, owned by this UID, and a regular `.oac-storage-root` file with mode `0600`, owned by the same UID, containing exactly the namespace UUID followed by one newline. Do this on the export's server-side storage as its administrator; root-squashed clients cannot assume privileged ownership changes. The root marker is an assertion of the selected export's identity, not a credential or distributed lock.
+Parameters contain `root`, `namespace_id`, `uid` and, in quota mode, `quota`. `root` is a clean absolute mount path; `namespace_id` is a canonical nonzero UUID; `uid` is the nonzero effective host UID required on both Core and nodes. A Compose installation uses 65532, the UID of Core's container. The operator prepares the mounted root with mode `0700`, owned by this UID, and a regular `.oac-storage-root` file with mode `0600`, owned by the same UID, containing exactly the namespace UUID followed by one newline. Do this on the export's server-side storage as its administrator; root-squashed clients cannot assume privileged ownership changes. The root marker is an assertion of the selected export's identity, not a credential or distributed lock.
Construction validates and canonicalizes JSON without filesystem I/O. `Check` verifies the opened root is kernel NFS, the effective UID and private ownership/modes match, the namespace marker matches, and real file-descriptor `user.*` xattr set/get/remove operations succeed. Every filesystem operation, including opening the root and checking availability, runs within one process-wide budget of 32 in-flight operations. A timed-out caller receives `ErrUnconfirmed`; its slot remains occupied until the kernel call returns. An exhausted budget returns `ErrUnavailable`. Directory-descriptor-relative operations stay anchored to the opened root. An unavailable mount or a local directory at the configured path fails validation; no local fallback is created.
@@ -77,6 +126,19 @@ The bound is authoritative when `Create` succeeds; `Resolve` does not re-attest
Each object owns `objects//identity`, `staging/`, `live/`, `trash/` and, after deletion begins, `deleted-marker`. The permanent identity binds the tenant, Environment and object UUIDs. Create prepares and syncs a private unique staging envelope before atomically publishing its nonempty directory as `live`; replay cannot overwrite existing live data. Delete first records a durable object-local terminal marker, retires live data to unique object-local trash and removes data before its ownership markers. Concurrent deleters converge. Minimal identity and deletion metadata remain intentionally; deletion does not mean every metadata file disappears. Create and Resolve refuse the retired identity. A late in-flight Create can leave empty controlled metadata requiring a repeated Delete after its syscall settles; it cannot authorize a new writer or reuse the object identity. Cleanup examines only that object's staging and trash, without a namespace-wide sweep or background service.
+```mermaid
+stateDiagram-v2
+ [*] --> staging: Create
+ staging --> live: publish
+ live --> deleted: Delete (marker written)
+ deleted --> [*]: data removed from trash
+ note right of deleted: Create and Resolve refuse the retired identity
+```
+
NFS storage does not supply compute fencing or automatic distributed failover. Guest `flock` is not a cross-VM writer lock. The single-writer and explicit-deletion requirements above remain mandatory. Confirmed release can permit a fresh VM on another compatible node to attach the same object, but an offline node or an unknown Create, Kill or snapshot-cleanup result never proves that the old writer stopped. Native history and database behavior require qualification of the selected Runtime, Harness and filesystem combination; file persistence alone is not a guarantee of native Session recovery, cross-node memory restore or arbitrary crash durability.
Core requires the selected Harness profile to support `retained_native_history` when the selected deployment generation uses external workspace storage. Creation validates that generation while holding the deployment lock, before committing the Session or compute reservation. Existing Sessions use their immutable workspace binding for Runtime admission and the final execution check. Owned workspace storage does not require this capability.
+
+## Conformance
+
+The shared validators and the combination check are covered by `services/core/internal/workspacefs/workspacefs_test.go`, and the kernel NFS adapter by the tests in `services/core/internal/workspacefs/nfs`. `make check-core-packages` runs them.
diff --git a/docs/zh/architecture.md b/docs/zh/architecture.md
index 7417c58bc..2402d3100 100644
--- a/docs/zh/architecture.md
+++ b/docs/zh/architecture.md
@@ -1,7 +1,7 @@
---
title: "架构"
source: docs/architecture.md
-source_hash: ed19d090bf0b65d33895ff59ee2f134916b03df74536ffb9b2659a3d3cb952c9
+source_hash: 14bf80d857aff5eb984a9ba235acf85f4919cde01319597fc54285d26bf4f49d
---
OpenAgentCore 是 Agent 运行平台，通过可替换的协议实现统一组织 Harness、模型、工具、Session 和执行环境。它将编排、计算资源和原生执行分开。Core 负责 API 和持久状态。沙箱提供商管理计算资源。独立工作区文件系统 adapter 通过单独的协议管理 Environment 持久存储。Runtime daemon 准备 Environment 并运行选定的 Harness；Harness 的原生 SDK 或协议负责模型与工具循环。
@@ -40,7 +40,7 @@ flowchart TB
| --- | --- | --- |
| Core | 认证调用方，解析并冻结配置，调度 Turn，处理取消和待处理交互，将资源与执行事实持久化到 PostgreSQL | [Core 服务](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/README.md) |
| 沙箱提供商 | 创建、观察、续期和回收计算资源；提供 Runtime 启动输入 | [沙箱提供商](sandbox-provider.md)、[Runtime 引导](runtime-bootstrap.md) |
-| Workspace filesystem adapter | 创建、观察和删除 Environment 持久存储；验证并解析计算资源所需的挂载 | [工作区文件系统提供商](workspace-provider.md) |
+| Workspace filesystem adapter | 创建、观察和删除 Environment 持久存储；验证并解析计算资源所需的挂载 | [工作区文件系统协议](workspace-provider.md) |
| Sandbox node | 运行 Docker 或 microsandbox 主机，协调分配给它的 generation 与 allocation | [Sandbox node 协议](../../contracts/agents-api/zh/node-generation-protocol.md) |
| Runtime | 准备工作区和能力，管理 Session Executor，执行 Turn 并报告事件与回执 | [Core–Runtime 协议](runtime-protocol.md) |
| Harness adapter | 验证原生配置，调用上游 SDK 或协议，转换事件并确认原生清理完成 | [Harness 接入](../../contracts/agents-api/zh/harness-onboarding.md) |
diff --git a/docs/zh/workspace-provider.md b/docs/zh/workspace-provider.md
index f29da1f80..537a74bc6 100644
--- a/docs/zh/workspace-provider.md
+++ b/docs/zh/workspace-provider.md
@@ -1,10 +1,39 @@
---
-title: 工作区文件系统提供商
+title: 工作区文件系统协议
source: docs/workspace-provider.md
-source_hash: ff018b1117a7f87786a23737212f1ed6b265d17fde43a0ef847f9f104788df2c
+source_hash: 1627563bb3b40ce2876913938d3cb7bf702aaacab8ad709acb1813e74d2b93c5
---
-独立工作区文件系统边界由 [`workspacefs.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/workspacefs/workspacefs.go) 定义。本文规定必需的集成契约，并不表示所有沙箱提供商或执行位置均已实现。文件系统适配器拥有存储对象与原生挂载解析职责；[沙箱提供商](sandbox-provider.md) 拥有计算资源职责。Core 在分配任一资源前选择并验证二者的组合。
+工作区文件系统协议连接 Core 和沙箱节点与拥有 Environment 持久存储的适配器。Core 创建、观察和删除存储对象；节点将对象解析为主机目录，由其[沙箱提供商](sandbox-provider.md)挂载到计算资源。本文面向文件系统适配器和沙箱提供商的作者。
+
+| | |
+| --- | --- |
+| 调用方 | Core（`Control`）和沙箱节点（`Resolver`） |
+| 实现 | 内核 NFS 适配器（`nfs`），注册于 `services/core/internal/workspacefs/providers` |
+| 代码 | [`workspacefs.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/workspacefs/workspacefs.go) |
+| 传输 | 进程内 Go 接口；`Binding` 通过 `Create` 引导和 `Resume` 请求经[沙箱节点协议](../../contracts/agents-api/zh/node-generation-protocol.md#provider-requests)传递 |
+
+Core 在分配任一资源前，选择并验证沙箱提供商与文件系统适配器的组合。
+
+| 沙箱提供商 | 外部工作区存储 |
+| --- | --- |
+| microsandbox | 支持（`host_directory`、`user_xattr`） |
+| Docker、E2B | 不支持；使用提供商自有的 Environment 磁盘 |
+
+## 实现适配器 {#implement-an-adapter}
+
+1. 定义 `Parameters` 和可选凭据，并实现 `Normalize`（[标识与配置](#identity-and-configuration)）。
+2. 在 `Control` 中实现 `Declaration`、`Check`、`Create`、`Observe` 和 `Delete`，在 `Resolver` 中实现 `Resolve`（[操作与结果](#operations-and-outcomes)）。
+3. 声明挂载类型、用户扩展属性支持和配额强制执行（[能力验证](#capability-validation)）。
+4. 每个对象保持单一写入方，仅在 Core 授权时删除（[生命周期与文件系统范围](#lifetime-and-filesystem-scope)）。
+
+## 角色 {#roles}
+
+| 参与方 | 负责 |
+| --- | --- |
+| Core | 标识、持久化的 `Reference`、配置和凭据、已准入容量、生命周期顺序以及每个删除决定 |
+| 文件系统适配器 | 原生存储对象及其回执、原生归属检查和路径解析 |
+| 沙箱提供商 | 计算资源，以及将解析出的目录挂载到计算资源 |
## 标识与配置 {#identity-and-configuration}
@@ -33,7 +62,18 @@ source_hash: ff018b1117a7f87786a23737212f1ed6b265d17fde43a0ef847f9f104788df2c
| `Delete(ctx, reference)` | Core 授权删除且确认计算资源停止后，收敛到已验证归属对象的终态删除。 |
| `Resolve(ctx, binding)` | 验证原生归属并为本地计算解析挂载。 |
-错误支持 `errors.Is`：`ErrInvalid` 表示无效输入，`ErrOwnership` 表示引用或配置不匹配，`ErrUnavailable` 表示存储不可用，`ErrUnconfirmed` 表示变更结果未知，`ErrNotFound` 表示对象不存在，`ErrUnsupported` 表示不支持的组合。适配器包装错误时保留这些结果。观察到不存在不证明先前变更已结束。超时或上下文取消只结束调用方的等待，不证明原生操作停止或回滚。结果未知时 Core 保留归属。Core 可以使用同一持久化不可变引用和配置重试 `Create` 或 `Delete`，包括收到 `ErrUnconfirmed` 后；绝不能通过替换新对象标识重试结果不确定的操作。
+错误支持 `errors.Is`。适配器包装错误时保留这些结果。
+
+| 错误 | 条件 |
+| --- | --- |
+| `ErrInvalid` | 无效输入 |
+| `ErrOwnership` | 引用或配置不匹配 |
+| `ErrUnavailable` | 存储不可用 |
+| `ErrUnconfirmed` | 变更结果未知 |
+| `ErrNotFound` | 对象不存在 |
+| `ErrUnsupported` | 不支持的组合 |
+
+观察到不存在不证明先前变更已结束。超时或上下文取消只结束调用方的等待，不证明原生操作停止或回滚。结果未知时 Core 保留归属。Core 可以使用同一持久化不可变引用和配置重试 `Create` 或 `Delete`，包括收到 `ErrUnconfirmed` 后；绝不能通过替换新对象标识重试结果不确定的操作。
同一引用的重试与并发收敛是适配器必须提供的保证。`Create` 保留现有对象数据并返回该归属对象的挂载凭据，绝不重新初始化存活对象。重复或并发的 `Delete` 调用收敛到同一终态删除。一旦记录终态删除，并发、延迟或重试的 `Create` 均不得使对象复活，`Resolve` 也不得暴露该对象。允许保留删除元数据，并在先前进行中的操作结束后继续清理。这些保证适用于存储生命周期操作，不表示超时时变更已结束，也不提供分布式计算隔离。
@@ -55,11 +95,19 @@ source_hash: ff018b1117a7f87786a23737212f1ed6b265d17fde43a0ef847f9f104788df2c
工作区存储随 Session 保留，直至显式删除 Session。归档、过期、重置和删除计算检查点均不授权删除工作区。Core 仅在显式删除 Session 且确认计算资源停止后调用 `Delete`；未解决的计算或存储变更须保留归属。Session 仍被保留时，创建失败不授权删除其存储。符合条件且未终结的 Session 可以在检查点保留期结束后继续保留，并按[冷替换生命周期](sandbox-provider.md#cold-replacement-after-checkpoint-retention)将同一对象挂载到新的计算资源。此流程不会复活已归档、重置或删除的执行。
+## 挂载 {#attachment}
+
+`Bootstrap.Workspace` 和 `ResumeRequest.Workspace` 可携带[工作区文件系统绑定](#identity-and-configuration)。未提供时使用提供商自有的 Environment 磁盘；提供时选择精确的外部对象，不得回退到自有磁盘。提供商在解析前校验租户、Environment、绑定及其配置回执。`LocalOptions.Workspace` 注入文件系统解析器；沙箱提供商不解释文件系统适配器参数或原生回执。
+
+`DeploymentPolicy.Workspace` 声明挂载要求；未声明表示不支持外部存储。派生的不可变 `DeploymentSpec.Workspace` 回执选择代次的模式和能力；[部署流程](../../contracts/agents-api/zh/sandbox-deployment.md#resources)不会将文件系统配置复制进代次。Microsandbox 要求 `host_directory` 和 `user_xattr`；Docker 和 E2B 拒绝外部挂载。`ValidateWorkspacePolicy` 使用文件系统协议的组合校验器：不强制容量配额的外部文件系统拒绝正值 `EnvironmentDiskMiB`，零表示不请求配额。根磁盘容量仍为必需。未提供外部声明时，继续使用自有磁盘的容量边界。
+
+Microsandbox 在每次 Create 和 Resume（包括观察中断的恢复）时解析绑定，仅向私有 helper 传递本地目录和不可变 ObjectID。Helper 挂载整个 `/environment`；保留内容与私有原生历史遵循[工作区文件系统范围](#lifetime-and-filesystem-scope)和 [Runtime 资源目录](configuration.md#runtime-resource-directories)。私有 HOME、凭据和计算根磁盘不是持久历史存储。原生资源通过明确的模式、对象和路径标签校验，不根据挂载形状推断模式。检查点恢复校验快照对象，通过 SDK `Volumes` 重映射 `/environment`，要求严格外部挂载策略，并拒绝任何恢复警告。恢复部分失败时保留精确目标身份用于清理，不证明就绪。未知结果继续观察原操作。原生 Bind 检查点及 guest 内 flock 连续性不证明对未知 writer 的隔离。
+
## 内核 NFS 适配器 {#kernel-nfs-adapter}
`nfs` 适配器使用由运维人员预挂载的 Linux 内核 NFS 文件系统。支持的配置是受信任 AUTH_SYS 客户端上的 NFSv4.2，启用 `root_squash`，Core 和节点使用相同导出和绝对挂载路径。适配器不挂载导出，也不管理 NFS 凭据或服务账户。其他操作系统返回 `ErrUnsupported`。[配置文档](./configuration.md#independent-workspace-storage)负责安装步骤和选择方式。
-参数包含 `root`、`namespace_id`、`uid`，配额模式下还包含 `quota`。`root` 是规范的绝对挂载路径；`namespace_id` 是非零规范 UUID；`uid` 是 Core 和节点均须使用的非零有效主机 UID。初始部署使用 65532。运维人员将挂载根目录设置为该 UID 所有、权限 `0700`，并准备同 UID 所有、权限 `0600` 的常规文件 `.oac-storage-root`，内容精确为命名空间 UUID 加一个换行符。应由导出服务端管理员在服务端存储上完成此操作；启用 root squash 的客户端不能假定有权变更所有者。根标记声明所选导出的身份，并非凭据或分布式锁。
+参数包含 `root`、`namespace_id`、`uid`，配额模式下还包含 `quota`。`root` 是规范的绝对挂载路径；`namespace_id` 是非零规范 UUID；`uid` 是 Core 和节点均须使用的非零有效主机 UID。Compose 安装使用 65532，即 Core 容器的 UID。运维人员将挂载根目录设置为该 UID 所有、权限 `0700`，并准备同 UID 所有、权限 `0600` 的常规文件 `.oac-storage-root`，内容精确为命名空间 UUID 加一个换行符。应由导出服务端管理员在服务端存储上完成此操作；启用 root squash 的客户端不能假定有权变更所有者。根标记声明所选导出的身份，并非凭据或分布式锁。
构造函数只验证并规范化 JSON，不执行文件系统 I/O。`Check` 验证打开的根目录确实位于内核 NFS，有效 UID 与私有所有权和权限匹配，命名空间标记匹配，并且实际文件描述符上的 `user.*` xattr 设置、读取和删除成功。包括打开根目录和可用性检查在内的所有文件系统操作，共享每进程最多 32 个在途操作的预算。调用者超时后收到 `ErrUnconfirmed`；该操作仍占用名额，直到内核调用返回。预算耗尽返回 `ErrUnavailable`。相对于目录描述符的操作始终锚定已打开的根目录。挂载不可用或配置路径只是本地目录时，验证失败，不创建本地回退。
@@ -79,6 +127,19 @@ source_hash: ff018b1117a7f87786a23737212f1ed6b265d17fde43a0ef847f9f104788df2c
每个对象拥有 `objects//identity`、`staging/`、`live/`、`trash/`，以及删除开始后的 `deleted-marker`。永久标识绑定租户、Environment 和对象 UUID。Create 先准备并同步唯一的私有 staging 封装目录，再原子发布其非空目录为 `live`；重放不会覆盖现有 live 数据。Delete 先持久记录对象本地的终态标记，将 live 数据退役到唯一的对象本地 trash，再先删除数据、后删除其所有权标记。并发删除者收敛。最少量的标识和删除元数据会有意保留；删除不代表所有元数据文件均消失。Create 和 Resolve 拒绝已退役标识。迟到的在途 Create 可能留下空的受控元数据，需要在其系统调用完成后重复 Delete；它不能授权新写入者或复用对象标识。清理只查看该对象的 staging 和 trash，不全量扫描命名空间，也不使用后台服务。
+```mermaid
+stateDiagram-v2
+ [*] --> staging: Create
+ staging --> live: publish
+ live --> deleted: Delete (marker written)
+ deleted --> [*]: data removed from trash
+ note right of deleted: Create and Resolve refuse the retired identity
+```
+
NFS 存储不提供计算 fencing 或自动分布式故障转移。Guest `flock` 不是跨 VM 写入者锁。上述单写入者和显式删除要求仍然必须遵守。确认释放后，可以允许另一兼容 node 上的新 VM 挂载同一对象，但 node 离线或 Create、Kill、快照清理结果未知均不证明旧写入方已停止。原生历史和数据库行为需要对所选 Runtime、Harness、文件系统组合进行资格验证；仅保留文件不保证原生 Session 恢复、跨 node 内存恢复或任意崩溃后的持久性。
所选部署代次使用外部工作区存储时，Core 要求所选 Harness profile 支持 `retained_native_history`。创建流程在持有部署锁时校验该代次，然后才提交 Session 或计算预留。既有 Session 的 Runtime 准入和最终执行检查以不可变工作区绑定为依据。自带工作区存储不要求此能力。
+
+## 一致性测试 {#conformance}
+
+共享校验器和组合检查由 `services/core/internal/workspacefs/workspacefs_test.go` 覆盖，内核 NFS 适配器由 `services/core/internal/workspacefs/nfs` 中的测试覆盖，由 `make check-core-packages` 运行。
diff --git a/services/core/tools/microsandbox-provider/README.md b/services/core/tools/microsandbox-provider/README.md
index 66f170841..28faf3dc5 100644
--- a/services/core/tools/microsandbox-provider/README.md
+++ b/services/core/tools/microsandbox-provider/README.md
@@ -20,7 +20,7 @@ The checkpoint root is a separate adapter-owned directory, mode 0700, with a pri
Create names the VM from a hash of the installation and allocation reference plus the compute generation; a name never serves another incarnation. It creates the VM with the saved CPUs and memory as both initial and maximum, a managed root disk of `root_disk_mib`, an owned ext4 disk of `environment_disk_mib` or the explicitly resolved external directory mounted at `/environment`, user 1000:1000, working directory `/` and the node's network policy ([`bootstrap.go`](bootstrap.go)). The resource checks run before bootstrap. Creation and restore retain the SDK's strict hostname policy enforcement; the adapter does not disable it.
-Workspace, staging and outputs share the `/environment` filesystem, which keeps the Runtime's cross-device and link checks intact; the layered root filesystem can report different device IDs for a directory and its upper-layer files, so it holds no workspace data. In owned mode, full snapshots and sandbox removal capture, restore and reclaim this disk. In external mode, the filesystem provider owns the directory; sandbox removal never deletes it. The binding and resource rules belong to [Independent workspace attachment](../../../../docs/sandbox-provider.md#independent-workspace-attachment). The [Runtime bootstrap](../../../../docs/runtime-bootstrap.md) owns the Runtime directory layout.
+Workspace, staging and outputs share the `/environment` filesystem, which keeps the Runtime's cross-device and link checks intact; the layered root filesystem can report different device IDs for a directory and its upper-layer files, so it holds no workspace data. In owned mode, full snapshots and sandbox removal capture, restore and reclaim this disk. In external mode, the filesystem provider owns the directory; sandbox removal never deletes it. The binding and resource rules belong to [Workspace filesystem protocol](../../../../docs/workspace-provider.md#attachment). The [Runtime bootstrap](../../../../docs/runtime-bootstrap.md) owns the Runtime directory layout.
VM creation does not run the image's entry point. The bootstrap runs as root through confidential standard input, with a two-minute limit. It creates the Runtime directories and the private control directory `/run/oac` (mode 0700, owned by UID 1000), writes the [Runtime bootstrap](../../../../docs/runtime-bootstrap.md) file to `/home/runtime/runtime-bootstrap.json`, bind-mounts `/environment/workspace` at `/workspace` and starts `oac-daemon connect --bootstrap-file` in the background as UID/GID 1000. `OAC_RUNTIME_DAEMON_SUSPEND_PID_FILE=/run/oac/daemon-suspend.json` enables the daemon's park and wake control. The `io.oac.bootstrap` label then changes from `pending` to `complete` through the SDK's next-start modification policy, because v0.7.8 cannot update the labels of a running VM. That label confirms only these writes and the launch, not authentication or native readiness.
From a6012a597e869f62d663a49f344409752306284a Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Fri, 16 Oct 2026 21:13:11 +0800
Subject: [PATCH 06/74] Give the Runtime protocol pages one structure (#748)
---
contracts/agents-api/harness-onboarding.md | 99 ++++---
contracts/agents-api/zh/harness-onboarding.md | 101 +++++---
docs/runtime-bootstrap.md | 49 +++-
docs/runtime-protocol.md | 242 +++++++++++++----
docs/zh/runtime-bootstrap.md | 51 +++-
docs/zh/runtime-protocol.md | 243 ++++++++++++++----
6 files changed, 588 insertions(+), 197 deletions(-)
diff --git a/contracts/agents-api/harness-onboarding.md b/contracts/agents-api/harness-onboarding.md
index 93acd1c66..c36363e6b 100644
--- a/contracts/agents-api/harness-onboarding.md
+++ b/contracts/agents-api/harness-onboarding.md
@@ -1,26 +1,28 @@
---
-title: "Add a Harness"
+title: "Harness protocol"
---
-A **Harness** is a native agent engine (Codex, Claude Code, MiniMax Code) that runs the model and tool loop. A **Harness adapter** translates the Runtime's Executor and Turn contract into that engine's SDK or protocol. This document is the Runtime–Harness protocol: the adapter interfaces and their lifecycle obligations, registration, Core qualification and acceptance. [Harness capabilities](./harness-capabilities.md) records what each current Harness supports.
+A **Harness** is a native agent engine (Codex, Claude Code, MiniMax Code) that runs the model and tool loop; a **Harness adapter** translates the Runtime's Executor and Turn contract into that engine's SDK or protocol. The Harness protocol is the contract between the Runtime and the adapter: the adapter interfaces and their lifecycle obligations, registration, Core qualification and acceptance. It is for developers who add or maintain a Harness.
-Start from two entry points:
-
-- [`internal/harnessconfig/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/harnessconfig/harness.go): the shared model configuration contract (declarations and preparation).
-- [`agent/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/apps/daemon/internal/agent/harness.go): the execution lifecycle, the extension contracts and the registration methods.
+| Property | Value |
+| --- | --- |
+| Caller | The Runtime ([dispatch](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/apps/daemon/internal/dispatch)) |
+| Implementations | The Codex, Claude Code and MiniMax Code adapters ([Native references](#native-references)). [Harness capabilities](./harness-capabilities.md) records what each supports. |
+| Code | [`agent/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/apps/daemon/internal/agent/harness.go): the execution lifecycle, the extension contracts and the registration methods. [`internal/harnessconfig/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/harnessconfig/harness.go): the shared model configuration contract (declarations and preparation). |
+| Transport | In-process Go interfaces. The Runtime speaks the [Core–Runtime protocol](../../docs/runtime-protocol.md) to Core. |
+| Version rule | A change to the interfaces edits this page and every adapter in one change. |
## Ownership
-```text
-Core: Session, Turn, immutable configuration, durable events
- |
- common Runtime protocol
- |
-Runtime: Executor preparation, reuse, idle expiry, recovery
- |
- Harness adapter package
- |
- native SDK, process or connection
+```mermaid
+flowchart TB
+ Core["Core Session, Turn, immutable configuration, durable events"]
+ Runtime["Runtime Executor preparation, reuse, idle expiry, recovery"]
+ Adapter["Harness adapter package"]
+ Native["Native SDK, process or connection"]
+ Core -->|"Core-Runtime protocol"| Runtime
+ Runtime -->|"Executor and Turn interfaces"| Adapter
+ Adapter --> Native
```
| Component | Responsibility | Location |
@@ -48,8 +50,7 @@ Implement the mandatory text lifecycle and handle every extension explicitly. Qu
## Architecture rules
-- Codex, Claude Code and future Harnesses have equal standing. The common Runtime wire protocol and Executor and Turn interfaces own lifecycle, input receipts, cancellation, recovery and resource access; each adapter keeps its native implementation and model and tool loop.
-- A new engine supplies an adapter, a qualified profile, registration and an independently verified deployment. It adds no engine-name branches to API handlers, persistence, dispatch, scheduling or Environment providers, and no handler, store table, scheduler, event projector or model loop for capabilities the contract already represents.
+[Complexity stays in the adapter](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#complexity-stays-in-the-adapter) applies to every Harness. These rules are Harness-specific:
- Keep required lifecycle declarations, extension interfaces and registration methods in `agent/harness.go`. Result types, errors and Registry storage may stay in focused files.
- Use the existing `proto.SupportedAgentKind` and `AgentKindCapabilities` schema. Do not add a second capability descriptor or a combined optional interface.
- Onboarding does not require feature equality. Harnesses need not match each other's optional features, and MCP, functions, images or verbosity control are not required to register. Verify the common lifecycle obligations and use the same public assertions for each declared operation. An omitted declaration or a missing extension implementation blocks onboarding; a native difference does not.
@@ -102,6 +103,21 @@ The service profile qualifies public combinations and the Runtime advertises the
A Session owns one reusable Executor in its connected Runtime; a Turn owns one input execution, its output stream and its cancellation. `agent.ExecutorFactory` prepares the fixed configuration without model input, and `Executor.StartTurn` creates a new `agent.Turn` without replacing healthy native resources. Normal completion settles only the Turn. `Executor.Close` releases native resources on idle expiry, Environment shutdown or confirmed invalidation; it releases neither the Environment allocation nor the workspace. Core keeps no second Executor cache. The same lifecycle applies to hosted, self-hosted and `none` placements.
+An Executor moves through these states. Each Turn runs between `StartTurn` and `AwaitSettlement`.
+
+```mermaid
+stateDiagram-v2
+ direction LR
+ [*] --> Idle: prepared
+ Idle --> Running: StartTurn
+ Running --> Idle: reusable
+ Running --> Closing: not reusable or shutdown
+ Idle --> Closing: idle expiry, shutdown or invalidation
+ Closing --> Closing: Close failed, retry
+ Closing --> Closed: Close confirmed
+ Closed --> [*]
+```
+
**Binding.** The Runtime binds its Executor record to the Session, Environment, connection and immutable execution configuration. Resume identity and prior-Turn recovery flags are continuity assertions, not configuration changes. A supplied native identity must match the retained owner, and when existing history is required, recovery never starts a new root. A configuration conflict is an error, not a hot switch. An ordinary lost connection retires its owners and handles; [planned suspension](../../docs/runtime-protocol.md#preparation-and-execution-order) retains settled idle owners through exact authenticated resume. Old timers, output and cancellation cannot affect replacement owners.
**Per-Turn state.** Each Turn gets a fresh wrapper, output channel and receipt state. Steering and function interfaces belong to that Turn. Native callbacks capture the originating Turn before asynchronous work, so a late event is never attributed to whichever Turn is active. Native processes, query or transport connections, fixed capability configuration and native session identity belong to the Executor. Do not reset completed `sync.Once` values or reuse an old Turn object.
@@ -117,7 +133,7 @@ A Session owns one reusable Executor in its connected Runtime; a Turn owns one i
- Every `Session` declares `CancellationOutcome`. `Turn` inherits it. The snapshot keeps observed native identity, Usage and output and remains readable after cancellation. Missing evidence stays unset; an empty `DonePayload` means nothing has been observed, not that cancellation succeeded or is unsupported. Reading the snapshot does not wait for settlement.
- `Session.Cancel` requests cancellation; output closure signals teardown. Turn settlement still requires `AwaitSettlement` and any required `Executor.Close`; neither a successful cancellation request nor its snapshot replaces those waits.
-**What the Runtime does around a Turn.** One output consumer starts before native Start, drains the bounded 64-frame channel and keeps the terminal observation until Start publication, Turn settlement and admitted operation receipts finish. Natural completion never calls Cancel. Input and function admission close before settlement; operations already admitted hold their barrier through native receipts and outbound acknowledgement. The Runtime sends cancellation to the Turn before waiting on that barrier, because a written input may need a native interrupt to produce its receipt. It joins native settlement, any required confirmed Executor close, output drain and all admitted operations before an applied acknowledgement or reuse, and only then forwards Done or an applied cancellation receipt. A failed Close can report failure while keeping the same Run and outstanding operations for retry; a closed caller wait cannot manufacture an applied input receipt. The Runtime commits native continuity and releases the old Run's admission before publishing Done, since the receiver may start another Turn at once; a late terminal-send failure belongs to the old Run and cannot invalidate a successor that already owns the Executor. Connection shutdown owns transport-loss cleanup. The settlement wait is ten seconds and the receipt send budget five seconds; a timeout is not proof of quiescence.
+**What the Runtime does around a Turn.** One output consumer starts before native Start, drains the bounded output channel and keeps the terminal observation until Start publication, Turn settlement and admitted operation receipts finish. Natural completion never calls Cancel. Input and function admission close before settlement; operations already admitted hold their barrier through native receipts and outbound acknowledgement. The Runtime sends cancellation to the Turn before waiting on that barrier, because a written input may need a native interrupt to produce its receipt. It joins native settlement, any required confirmed Executor close, output drain and all admitted operations before an applied acknowledgement or reuse, and only then forwards Done or an applied cancellation receipt. A failed Close can report failure while keeping the same Run and outstanding operations for retry; a closed caller wait cannot manufacture an applied input receipt. The Runtime commits native continuity and releases the old Run's admission before publishing Done, since the receiver may start another Turn at once; a late terminal-send failure belongs to the old Run and cannot invalidate a successor that already owns the Executor. Connection shutdown owns transport-loss cleanup. The settlement wait and the receipt send budget are bounded ([Timeouts and limits](../../docs/runtime-protocol.md#timeouts-and-limits)); a timeout is not proof of quiescence.
## Events, inputs and optional capabilities
@@ -158,7 +174,7 @@ The Runtime resolves the [state directory](../../docs/configuration.md#runtime-r
| 1 | `RegisterKind(proto.SupportedAgentKind, harnessconfig.Configuration)` | Kind, availability, version, `AgentKindCapabilities` and the model configuration declaration. It resets the other registrations, so call it first. |
| 2 | `RegisterExecutor(kind, agent.ExecutorFactory)` | The Executor and Turn lifecycle used for execution; derives the `Preparation` capability |
-Every `proto.AgentKindCapabilities` field must be explicitly `proto.CapabilitySupported` or `proto.CapabilityUnsupported`, even for an unavailable Harness. `proto.CapabilityUnspecified` is invalid: zero values and omitted fields never mean Unsupported. An installation probe may set an individual field with `proto.CapabilityFromBool`; it must not populate unmentioned or future fields. Availability stays separate in `SupportedAgentKind.Available`. Registration validates the complete declaration before changing the registry, and the wire carries an explicit boolean for every field, so omitted and null fields are invalid. A new field requires a decision in every production declaration. Runtime consumers use `IsSupported()` and reject unsupported requests before native operations; an interface assertion verifies implementation, never support. Every declaration must match the behavior verified for that installation; the [Core–Runtime protocol](../../docs/runtime-protocol.md#capability-declarations) owns how declarations travel and are frozen.
+Fill every field of `proto.AgentKindCapabilities` explicitly, even for an unavailable Harness; [Capability declarations](../../docs/runtime-protocol.md#capability-declarations) defines how declarations are encoded, validated and frozen. An installation probe may set an individual field with `proto.CapabilityFromBool`; it must not populate unmentioned or future fields. Availability stays separate in `SupportedAgentKind.Available`. Code that reads a declaration uses `IsSupported()`; an interface assertion verifies implementation, never support. Every declaration must match the behavior verified for that installation.
The admission mapping is explicit. `Steering` controls non-durable `Steerer` input. `DurableInputReceipts` controls `DurableSteerer` input and also requires the Turn settlement contract; neither implies the other, and Core's public text profile requires both. Workspace declarations describe the authorized resource owner, including the common Runtime workspace implementation. `WorkspaceReadPreparation` admits `execution_prepare` with `workspace_read_only`. The Runtime readies that preparation itself and serves its reads from the bound local workspace directory without calling the Executor factory, so an adapter declares it only when this kind's Environment workspace is that local directory. Registration does not derive it. Runtime registration does not grant Core qualification; the service profile does.
@@ -180,7 +196,7 @@ The profile is pure: it declares supported placements, public configuration and
### Explicit service qualification
-`engine.Profile` is the service's qualification declaration, separate from the Runtime's `AgentKindCapabilities`. Its capability fields reuse the small `proto.CapabilitySupport` value type: every field must explicitly select `CapabilitySupported` or `CapabilityUnsupported`. `CapabilityUnspecified`, including an omitted field, is rejected. Sharing this value type does not let a Runtime advertisement grant service authorization.
+`engine.Profile` is the service's qualification declaration, separate from the Runtime's `AgentKindCapabilities`. Its capability fields reuse the small `proto.CapabilitySupport` value type and follow the same explicit-value rule ([Capability declarations](../../docs/runtime-protocol.md#capability-declarations)). Sharing this value type does not let a Runtime advertisement grant service authorization.
Each of `ConfigurationValidation`, `ToolsValidation` and `FunctionResultValidation` chooses one of two strategies:
@@ -203,6 +219,31 @@ A supplied `model` must be a nonempty string, and an explicit `model_provider` r
The declaration's ordered `protocols` list is the only source of accepted protocols and the default (the first entry); it also feeds Core's configuration-support descriptor, and Core and Runtime reject unsupported combinations through it. Adapters connect directly through native configuration; they never introduce a model API proxy or protocol converter, a second model capability registry, or capabilities inferred from model names. Claude's private bridge receives compiled native options and performs structural checks only, not a second copy of the declaration's rules.
+## Native installer participation
+
+An adapter may supply `agent.Installation` from `installation.go` in its own package: registered kind, pinned version, supported platforms, activation environment and a bounded readiness probe. Register it in `cli/native_harness.go` and add its pinned component to the native distribution builder. This optional contract does not change Executor and Turn semantics. The Runtime owns checksums, copying, locks and additive installation; adapters own native layout and probes. Validate installation and execution on each advertised platform. Missing or incompatible native content fails; it never installs itself during a Turn.
+
+## Native process ownership
+
+The daemon's `clirunner` starts every native child in its own Unix process group (a Job object on Windows); other hosts reject the launch. Explicit and parent-context cancellation share a TERM grace period and a bounded KILL escalation. An internal reaper also cleans remaining group members when the direct process exits, even if a descendant still holds stdout open; during cancellation, surviving descendants keep the remaining grace after the leader exits. The daemon's `stop` command waits within its limit for confirmed shutdown, which covers that grace period and the pipe and owner cleanup after it.
+
+Owned output pipes stay readable after the leader exits. Consumers drain stdout and stderr before calling `Wait`, which joins the cached process result and closes the readers. `Done` reports leader reaping and group cleanup signals; it is not a native execution receipt or proof of persisted history. SDK adapters settle each Turn and drain its observations before publishing completion, and Executor close also closes the query and awaits the native child. Process groups are lifecycle supervision, not isolation or containment of descendants that leave the group.
+
+Adapters run native tools unattended with the launching user's permissions, and a Harness never asks a human. Codex runs with approval policy `never`, under which it settles MCP elicitation itself without reaching the client, and with full access; the adapter also disables its blocking `request_user_input` tool. Claude runs through the adapter's tool callback, which allows or denies without asking, in native `default` permission mode with the SDK sandbox disabled. MiniMax runs with bypassed permissions and its sandbox disabled; the adapter disables `askUser`, advertises no elicitation and answers `session/request_permission` with the ACP `cancelled` outcome, which MiniMax treats as a denial. No native permission or question request reaches Core: a human in the loop goes through a function tool, the Session reads [`requires_action`](./sessions-events.md#session-status) and the application submits the function result. Do not add permission profiles, bubblewrap wrappers or native sandbox settings; there is one execution path for every Environment origin. Resource paths are operator configuration, not a permission boundary.
+
+An unreachable model host must not hold a Turn open. The adapter keeps the Harness's own connection retries bounded through native settings, and the Harness's final connection error becomes `connection_failed` when the Harness reports it as structured data ([native failure classification](../../docs/runtime-protocol.md#native-failure-classification)). Core adds no model timeout of its own. Each adapter guide states its Harness's bound.
+
+Network admission follows [Restricted network](./environments.md#restricted-network).
+
+## Timeouts and limits
+
+The Runtime's per-Turn limits (settlement wait, receipt send budget and output channel) are in the [Core–Runtime protocol](../../docs/runtime-protocol.md#timeouts-and-limits). The limits on native child processes are:
+
+| Value | Applies to | On expiry |
+| --- | --- | --- |
+| 3 seconds (default) | The TERM grace period of a native child process on explicit or parent-context cancellation | The Runtime escalates to a bounded KILL. |
+| 10 seconds | The daemon's `stop` command waiting for confirmed shutdown, which covers the grace period and the pipe and owner cleanup after it | Shutdown is not confirmed. |
+
## Qualify the adapter
Before starting, record the operation set, expected results, exclusions and stopping conditions. A qualification ends when its declared operations pass; it does not expand to match another Harness's feature list.
@@ -236,22 +277,6 @@ Keep provider keys in private operator files, never in commits or logs. Existing
| MiniMax native history binding | `mcode/session_test.go` |
| Explicit refusals without native effects or fabricated results | Each adapter's `unsupported_test.go` |
-## Native installer participation
-
-An adapter may supply `agent.Installation` from `installation.go` in its own package: registered kind, pinned version, supported platforms, activation environment and a bounded readiness probe. Register it in `cli/native_harness.go` and add its pinned component to the native distribution builder. This optional contract does not change Executor and Turn semantics. The Runtime owns checksums, copying, locks and additive installation; adapters own native layout and probes. Validate installation and execution on each advertised platform. Missing or incompatible native content fails; it never installs itself during a Turn.
-
-## Native process ownership
-
-The daemon's `clirunner` starts every native child in its own Unix process group (a Job object on Windows); other hosts reject the launch. Explicit and parent-context cancellation share a TERM grace period (three seconds by default) and a bounded KILL escalation. An internal reaper also cleans remaining group members when the direct process exits, even if a descendant still holds stdout open; during cancellation, surviving descendants keep the remaining grace after the leader exits. The daemon's `stop` command waits up to ten seconds for confirmed shutdown, which covers that grace period and the pipe and owner cleanup after it.
-
-Owned output pipes stay readable after the leader exits. Consumers drain stdout and stderr before calling `Wait`, which joins the cached process result and closes the readers. `Done` reports leader reaping and group cleanup signals; it is not a native execution receipt or proof of persisted history. SDK adapters settle each Turn and drain its observations before publishing completion, and Executor close also closes the query and awaits the native child. Process groups are lifecycle supervision, not isolation or containment of descendants that leave the group.
-
-Adapters run native tools unattended with the launching user's permissions, and a Harness never asks a human. Codex runs with approval policy `never`, under which it settles MCP elicitation itself without reaching the client, and with full access; the adapter also disables its blocking `request_user_input` tool. Claude runs through the adapter's tool callback, which allows or denies without asking, in native `default` permission mode with the SDK sandbox disabled. MiniMax runs with bypassed permissions and its sandbox disabled; the adapter disables `askUser`, advertises no elicitation and answers `session/request_permission` with the ACP `cancelled` outcome, which MiniMax treats as a denial. No native permission or question request reaches Core: a human in the loop goes through a function tool, the Session reads [`requires_action`](./sessions-events.md#session-status) and the application submits the function result. Do not add permission profiles, bubblewrap wrappers or native sandbox settings; there is one execution path for every Environment origin. Resource paths are operator configuration, not a permission boundary.
-
-An unreachable model host must not hold a Turn open. The adapter keeps the Harness's own connection retries bounded through native settings, and the Harness's final connection error becomes `connection_failed` when the Harness reports it as structured data ([native failure classification](../../docs/runtime-protocol.md#native-failure-classification)). Core adds no model timeout of its own. Each adapter guide states its Harness's bound.
-
-Network admission follows [Restricted network](./environments.md#restricted-network).
-
## Native references
| Harness | Adapter | Native transport | Runtime guide |
diff --git a/contracts/agents-api/zh/harness-onboarding.md b/contracts/agents-api/zh/harness-onboarding.md
index 7dd671a16..a99084b36 100644
--- a/contracts/agents-api/zh/harness-onboarding.md
+++ b/contracts/agents-api/zh/harness-onboarding.md
@@ -1,28 +1,30 @@
---
-title: "添加 Harness"
+title: "Harness 协议"
source: contracts/agents-api/harness-onboarding.md
-source_hash: a1db7d464a42cc82bbe285b12a3290d76d0535c5a6a8fb2563586631c6b9136c
+source_hash: fbeb2f838dc5836a9bad8e744a456ac1cb2c68831460f5b513d80f9cc387bc4e
---
-**Harness** 是一种运行模型和工具循环的原生代理引擎（Codex、Claude Code、MiniMax Code）。**Harness 适配器**将 Runtime 的 Executor 和 Turn 契约转换到该引擎的 SDK 或协议。本文档定义 Runtime–Harness 协议：适配器接口及其生命周期义务、注册、Core 资格认定和验收。[Harness capabilities](harness-capabilities.md) 记录了当前每个 Harness 支持的功能。
+**Harness** 是一种运行模型和工具循环的原生代理引擎（Codex、Claude Code、MiniMax Code）；**Harness 适配器**将 Runtime 的 Executor 和 Turn 契约转换到该引擎的 SDK 或协议。Harness 协议是 Runtime 与适配器之间的契约：适配器接口及其生命周期义务、注册、Core 资格认定和验收。本文面向添加或维护 Harness 的开发者。
-从两个入口开始：
-
-- [`internal/harnessconfig/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/harnessconfig/harness.go)：共享模型配置契约（声明和准备）。
-- [`agent/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/apps/daemon/internal/agent/harness.go)：执行生命周期、扩展契约和注册方法。
+| 属性 | 内容 |
+| --- | --- |
+| 调用方 | Runtime（[dispatch](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/apps/daemon/internal/dispatch)） |
+| 实现方 | Codex、Claude Code 和 MiniMax Code 适配器（[原生参考](#native-references)）。[Harness capabilities](harness-capabilities.md) 记录了每个 Harness 支持的功能。 |
+| 代码 | [`agent/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/apps/daemon/internal/agent/harness.go)：执行生命周期、扩展契约和注册方法。[`internal/harnessconfig/harness.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/harnessconfig/harness.go)：共享模型配置契约（声明和准备）。 |
+| 传输 | 进程内 Go 接口。Runtime 通过 [Core–Runtime 协议](../../../docs/zh/runtime-protocol.md)与 Core 通信。 |
+| 版本规则 | 接口变更须在同一次变更中修改本文和每个适配器。 |
## 所有权 {#ownership}
-```text
-Core: Session, Turn, immutable configuration, durable events
- |
- common Runtime protocol
- |
-Runtime: Executor preparation, reuse, idle expiry, recovery
- |
- Harness adapter package
- |
- native SDK, process or connection
+```mermaid
+flowchart TB
+ Core["Core Session, Turn, immutable configuration, durable events"]
+ Runtime["Runtime Executor preparation, reuse, idle expiry, recovery"]
+ Adapter["Harness adapter package"]
+ Native["Native SDK, process or connection"]
+ Core -->|"Core-Runtime protocol"| Runtime
+ Runtime -->|"Executor and Turn interfaces"| Adapter
+ Adapter --> Native
```
| 组件 | 职责 | 位置 |
@@ -50,8 +52,7 @@ Environment 提供执行资源。受管 E2B、Docker 和 microsandbox 机器以
## 架构规则 {#architecture-rules}
-- Codex、Claude Code 和未来的 Harness 地位平等。通用 Runtime 线协议以及 Executor 和 Turn 接口负责生命周期、输入回执、取消、恢复和资源访问；每个适配器保留其原生实现以及模型和工具循环。
-- 新引擎需要提供适配器、已认定合格的 profile、注册以及经过独立验证的部署。它不得在 API 处理程序、持久化、调度、调度器或 Environment 提供商中添加按引擎名称分支的实现，也不得为契约已经涵盖的能力添加处理程序、存储表、调度器、事件投影器或模型循环。
+[Complexity stays in the adapter](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#complexity-stays-in-the-adapter) 适用于每个 Harness。以下规则为 Harness 专有：
- 将必需的生命周期声明、扩展接口和注册方法保留在 `agent/harness.go` 中。结果类型、错误和 Registry 存储可以保留在聚焦的文件中。
- 使用现有的 `proto.SupportedAgentKind` 和 `AgentKindCapabilities` schema。不要添加第二套能力描述符或组合式可选接口。
- 接入不要求功能完全一致。Harness 不必匹配彼此的可选功能，并且注册时不强制要求 MCP、函数、图像或详细程度控制。验证通用生命周期义务，并对每个声明的操作使用相同的公共断言。缺少声明或扩展实现会阻止接入；原生差异不会。
@@ -104,6 +105,21 @@ func (s *Session) SubmitFunctionResult(context.Context, proto.FunctionResultPayl
Session 在其已连接的 Runtime 中拥有一个可复用的 Executor；Turn 拥有一次输入执行、其输出流和其取消操作。`agent.ExecutorFactory` 在没有模型输入的情况下准备固定配置，而 `Executor.StartTurn` 创建新的 `agent.Turn`，不替换健康的原生资源。正常完成仅结算 Turn。`Executor.Close` 在空闲过期、Environment 关闭或确认失效时释放原生资源；它既不释放 Environment 分配，也不释放工作区。Core 不保留第二套 Executor 缓存。相同的生命周期适用于托管、自托管和 `none` 放置方式。
+Executor 按下列状态转移。每个 Turn 在 `StartTurn` 与 `AwaitSettlement` 之间运行。
+
+```mermaid
+stateDiagram-v2
+ direction LR
+ [*] --> Idle: prepared
+ Idle --> Running: StartTurn
+ Running --> Idle: reusable
+ Running --> Closing: not reusable or shutdown
+ Idle --> Closing: idle expiry, shutdown or invalidation
+ Closing --> Closing: Close failed, retry
+ Closing --> Closed: Close confirmed
+ Closed --> [*]
+```
+
**绑定。** Runtime 将其 Executor 记录绑定到 Session、Environment、连接和不可变执行配置。恢复身份和先前 Turn 恢复标志是连续性断言，而不是配置更改。提供的原生身份必须与保留的所有者匹配；当需要现有历史时，恢复绝不能启动新的根。配置冲突属于错误，而不是热切换。普通连接丢失会让其所有者和句柄退役；[计划性挂起](../../../docs/zh/runtime-protocol.md#preparation-and-execution-order) 则保留已结算的空闲所有者，直至精确匹配且已认证的恢复完成。旧计时器、输出和取消操作不能影响替代所有者。
**每 Turn 状态。** 每个 Turn 都会获得全新的包装器、输出通道和回执状态。引导和函数接口均属于该 Turn。原生回调必须在异步工作开始前捕获来源 Turn，因此迟到事件绝不会被归到当前活动的 Turn 上。原生进程、query 或传输连接、固定能力配置和原生 session 身份均属于 Executor。不要重置已完成的 `sync.Once` 值，也不要复用旧 Turn 对象。
@@ -119,7 +135,7 @@ Session 在其已连接的 Runtime 中拥有一个可复用的 Executor；Turn
- 每个 `Session` 都要声明 `CancellationOutcome`。`Turn` 继承该声明。快照保留已观察到的原生身份、Usage 和输出，并在取消后仍可读取。缺失的证据保持未设置；空的 `DonePayload` 表示未观察到任何内容，而不是表示取消成功或不受支持。读取快照不会等待结算。
- `Session.Cancel` 请求取消；输出关闭表示拆卸开始。Turn 结算仍需要 `AwaitSettlement` 和所需的任何 `Executor.Close`；取消请求成功或其快照都不能替代这些等待。
-**Runtime 在 Turn 前后执行的工作。** 一个输出消费者会在原生 Start 之前启动，耗尽有界的 64 帧通道，并将终态观察保留到 Start 发布、Turn 结算和已准入操作回执完成为止。正常完成绝不调用 Cancel。输入和函数准入会在结算前关闭；已准入的操作会持有其屏障，直至原生回执和出站确认完成。Runtime 会在等待该屏障之前向 Turn 发送取消，因为已写入的输入可能需要原生中断才能生成回执。Runtime 会汇合原生结算、所需的已确认 Executor 关闭、输出耗尽和所有已准入操作，然后应用确认或执行复用，之后才会转发 Done 或已应用的取消回执。Close 失败可以报告失败，同时保留同一 Run 和未完成操作以供重试；已关闭的调用方等待无法凭空生成已应用输入回执。Runtime 会在发布 Done 前提交原生连续性状态并释放旧 Run 的准入，因为接收方可能立即启动另一个 Turn；迟到的终态发送失败属于旧 Run，不能使已拥有 Executor 的后继对象失效。连接关闭负责传输丢失清理。结算等待时间为十秒，回执发送预算为五秒；超时不能证明已达到静默状态。
+**Runtime 在 Turn 前后执行的工作。** 一个输出消费者会在原生 Start 之前启动，耗尽有界的输出通道，并将终态观察保留到 Start 发布、Turn 结算和已准入操作回执完成为止。正常完成绝不调用 Cancel。输入和函数准入会在结算前关闭；已准入的操作会持有其屏障，直至原生回执和出站确认完成。Runtime 会在等待该屏障之前向 Turn 发送取消，因为已写入的输入可能需要原生中断才能生成回执。Runtime 会汇合原生结算、所需的已确认 Executor 关闭、输出耗尽和所有已准入操作，然后应用确认或执行复用，之后才会转发 Done 或已应用的取消回执。Close 失败可以报告失败，同时保留同一 Run 和未完成操作以供重试；已关闭的调用方等待无法凭空生成已应用输入回执。Runtime 会在发布 Done 前提交原生连续性状态并释放旧 Run 的准入，因为接收方可能立即启动另一个 Turn；迟到的终态发送失败属于旧 Run，不能使已拥有 Executor 的后继对象失效。连接关闭负责传输丢失清理。结算等待时间和回执发送预算均有上限（见[超时与限制](../../../docs/zh/runtime-protocol.md#timeouts-and-limits)）；超时不能证明已达到静默状态。
## 事件、输入和可选能力 {#events-inputs-and-optional-capabilities}
@@ -160,7 +176,7 @@ Runtime 统一解析[状态目录](../../../docs/zh/configuration.md#runtime-res
| 1 | `RegisterKind(proto.SupportedAgentKind, harnessconfig.Configuration)` | Kind、可用性、版本、`AgentKindCapabilities` 和模型配置声明。它会重置其他注册项，因此必须首先调用。 |
| 2 | `RegisterExecutor(kind, agent.ExecutorFactory)` | 执行所用的 Executor 和 Turn 生命周期；据此派生 `Preparation` 能力 |
-每个 `proto.AgentKindCapabilities` 字段都必须显式设为 `proto.CapabilitySupported` 或 `proto.CapabilityUnsupported`，即使 Harness 不可用也是如此。`proto.CapabilityUnspecified` 无效：零值和省略字段绝不表示 Unsupported。安装探测可以使用 `proto.CapabilityFromBool` 设置单个字段；但不得填充未提及字段或未来字段。可用性通过 `SupportedAgentKind.Available` 单独表示。注册会在更改 registry 之前验证完整声明；线协议会为每个字段携带显式布尔值，因此省略字段和 null 字段均无效。添加新字段时，每个生产声明都必须作出决定。Runtime 使用者应调用 `IsSupported()`，并在原生操作前拒绝不受支持的请求；接口断言用于验证实现，绝不表示支持。每个声明都必须与针对该安装验证的行为一致；[Core–Runtime protocol](../../../docs/zh/runtime-protocol.md#capability-declarations) 负责声明的传输方式和冻结方式。
+显式填写 `proto.AgentKindCapabilities` 的每个字段，即使 Harness 不可用也是如此；[能力声明](../../../docs/zh/runtime-protocol.md#capability-declarations)定义声明的编码、验证和冻结方式。安装探测可以使用 `proto.CapabilityFromBool` 设置单个字段；但不得填充未提及字段或未来字段。可用性通过 `SupportedAgentKind.Available` 单独表示。读取声明的代码应调用 `IsSupported()`；接口断言用于验证实现，绝不表示支持。每个声明都必须与针对该安装验证的行为一致。
准入映射是显式的。`Steering` 控制非持久化 `Steerer` 输入。`DurableInputReceipts` 控制 `DurableSteerer` 输入，并且还要求 Turn 结算契约；二者互不隐含，而且 Core 的公共文本 profile 要求同时具备二者。工作区声明描述授权资源所有者，包括通用 Runtime 工作区实现。`WorkspaceReadPreparation` 准入带 `workspace_read_only` 的 `execution_prepare`。Runtime 自行就绪该 preparation，并从绑定的本地工作区目录提供读取，不调用 Executor 工厂；因此仅当该 kind 的 Environment 工作区就是该本地目录时，adapter 才声明它。注册过程不会派生它。Runtime 注册不会授予 Core 资格；服务 profile 才会授予。
@@ -182,7 +198,7 @@ profile 是纯逻辑：它使用现有的公共类型和协议类型，声明受
### 显式服务资格认定 {#explicit-service-qualification}
-`engine.Profile` 是服务的资格声明，独立于 Runtime 的 `AgentKindCapabilities`。其能力字段复用小型 `proto.CapabilitySupport` 值类型：每个字段都必须显式选择 `CapabilitySupported` 或 `CapabilityUnsupported`。`CapabilityUnspecified`（包括省略字段）会被拒绝。复用此值类型并不意味着 Runtime 的宣称可以授予服务授权。
+`engine.Profile` 是服务的资格声明，独立于 Runtime 的 `AgentKindCapabilities`。其能力字段复用小型 `proto.CapabilitySupport` 值类型，并遵循相同的显式取值规则（[能力声明](../../../docs/zh/runtime-protocol.md#capability-declarations)）。复用此值类型并不意味着 Runtime 的宣称可以授予服务授权。
`ConfigurationValidation`、`ToolsValidation` 和 `FunctionResultValidation` 分别选择以下两种策略之一：
@@ -205,6 +221,31 @@ profile 是纯逻辑：它使用现有的公共类型和协议类型，声明受
声明中的有序 `protocols` 列表是接受协议及默认协议（第一个条目）的唯一来源；它还为 Core 的配置支持描述符提供数据，Core 和 Runtime 通过它拒绝不受支持的组合。适配器通过原生配置直接连接；它们绝不引入模型 API 代理或协议转换器、第二套模型能力 registry，也不会从模型名称推断能力。Claude 的私有 bridge 接收编译后的原生选项，并且只执行结构检查，而不是声明规则的第二份副本。
+## 原生安装器参与 {#native-installer-participation}
+
+适配器可以从自身包中的 `installation.go` 提供 `agent.Installation`：已注册 kind、锁定版本、受支持平台、激活环境和有界就绪探测。在 `cli/native_harness.go` 中注册它，并将其锁定组件添加到原生分发构建器。此可选契约不会改变 Executor 和 Turn 语义。Runtime 负责校验和、复制、锁和增量安装；适配器负责原生布局和探测。必须在每个宣称的平台上验证安装和执行。原生内容缺失或不兼容时必须失败；绝不会在 Turn 期间自行安装。
+
+## 原生进程所有权 {#native-process-ownership}
+
+daemon 的 `clirunner` 让每个原生子进程在自己的 Unix 进程组中启动（Windows 上为 Job 对象）；其他主机会拒绝启动。显式取消和父上下文取消共享 TERM 宽限期以及有界的 KILL 升级过程。当直接进程退出时，内部回收器也会清理进程组的剩余成员，即使某个后代进程仍保持 stdout 打开；在取消过程中，主进程退出后，存活的后代进程仍会保留剩余宽限时间。daemon 的 `stop` 命令在限定时间内等待确认关闭，该时间涵盖该宽限期以及之后的管道和所有者清理。
+
+所属输出管道在主进程退出后仍可读取。消费者在调用 `Wait` 之前耗尽 stdout 和 stderr；`Wait` 会汇合缓存的进程结果并关闭读取器。`Done` 报告主进程回收和进程组清理信号；它不是原生执行回执，也不是历史已持久化的证据。SDK 适配器会结算每个 Turn，并在发布完成状态前耗尽其观察结果；Executor 关闭还会关闭 Query 并等待原生子进程。进程组用于生命周期监管，而不是隔离或遏制离开进程组的后代进程。
+
+适配器以启动用户的权限无人值守运行原生工具，Harness 从不询问人类。Codex 使用批准策略 `never` 和完全访问权限，在该策略下 Codex 自行处理 MCP elicitation，不会发给客户端；适配器还禁用其阻塞式 `request_user_input` 工具。Claude 通过适配器的工具回调运行，回调直接允许或拒绝、不会询问，使用原生 `default` 权限模式并禁用 SDK sandbox。MiniMax 绕过权限并禁用 sandbox；适配器禁用 `askUser`、不声明 elicitation，并以 ACP `cancelled` 结果答复 `session/request_permission`，MiniMax 将其视为拒绝。原生权限或问题请求都不会到达 Core：需要人工介入时通过 function 工具完成，Session 读取 [`requires_action`](./sessions-events.md#session-status)，由应用提交 function 结果。不要添加权限 profile、bubblewrap 包装器或原生 sandbox 设置；每种 Environment 来源都只有一条执行路径。资源路径属于操作员配置，而不是权限边界。
+
+模型主机不可达时不能让 Turn 一直挂起。适配器通过原生设置让 Harness 自身的连接重试保持有界；Harness 以结构化数据报告最终连接错误时，该错误归为 `connection_failed`（[原生失败分类](../../../docs/zh/runtime-protocol.md#native-failure-classification)）。Core 不另设模型超时。各适配器指南写明其 Harness 的上限。
+
+网络准入遵循 [Restricted network](environments.md#restricted-network)。
+
+## 超时与限制 {#timeouts-and-limits}
+
+Runtime 对每个 Turn 的限制（结算等待、回执发送预算和输出通道）见 [Core–Runtime 协议](../../../docs/zh/runtime-protocol.md#timeouts-and-limits)。原生子进程的限制如下：
+
+| 数值 | 适用对象 | 到期时 |
+| --- | --- | --- |
+| 3 秒（默认） | 显式取消或父上下文取消时，原生子进程的 TERM 宽限期 | Runtime 升级为有界的 KILL。 |
+| 10 秒 | daemon 的 `stop` 命令等待确认关闭，涵盖该宽限期及之后的管道和所有者清理 | 关闭未得到确认。 |
+
## 认定适配器资格 {#qualify-the-adapter}
开始前，记录操作集、预期结果、排除项和停止条件。当其声明的操作通过时，资格认定即结束；它不会扩展为匹配另一个 Harness 的功能列表。
@@ -238,22 +279,6 @@ Environment 验收使用 `services/core/tests/official_environment_{templates,se
| MiniMax 原生历史绑定 | `mcode/session_test.go` |
| 无原生副作用或伪造结果的明确拒绝 | 每个适配器的 `unsupported_test.go` |
-## 原生安装器参与 {#native-installer-participation}
-
-适配器可以从自身包中的 `installation.go` 提供 `agent.Installation`：已注册 kind、锁定版本、受支持平台、激活环境和有界就绪探测。在 `cli/native_harness.go` 中注册它，并将其锁定组件添加到原生分发构建器。此可选契约不会改变 Executor 和 Turn 语义。Runtime 负责校验和、复制、锁和增量安装；适配器负责原生布局和探测。必须在每个宣称的平台上验证安装和执行。原生内容缺失或不兼容时必须失败；绝不会在 Turn 期间自行安装。
-
-## 原生进程所有权 {#native-process-ownership}
-
-daemon 的 `clirunner` 让每个原生子进程在自己的 Unix 进程组中启动（Windows 上为 Job 对象）；其他主机会拒绝启动。显式取消和父上下文取消共享 TERM 宽限期（默认为三秒）以及有界的 KILL 升级过程。当直接进程退出时，内部回收器也会清理进程组的剩余成员，即使某个后代进程仍保持 stdout 打开；在取消过程中，主进程退出后，存活的后代进程仍会保留剩余宽限时间。daemon 的 `stop` 命令最多等待十秒以确认关闭，这涵盖该宽限期以及之后的管道和所有者清理。
-
-所属输出管道在主进程退出后仍可读取。消费者在调用 `Wait` 之前耗尽 stdout 和 stderr；`Wait` 会汇合缓存的进程结果并关闭读取器。`Done` 报告主进程回收和进程组清理信号；它不是原生执行回执，也不是历史已持久化的证据。SDK 适配器会结算每个 Turn，并在发布完成状态前耗尽其观察结果；Executor 关闭还会关闭 Query 并等待原生子进程。进程组用于生命周期监管，而不是隔离或遏制离开进程组的后代进程。
-
-适配器以启动用户的权限无人值守运行原生工具，Harness 从不询问人类。Codex 使用批准策略 `never` 和完全访问权限，在该策略下 Codex 自行处理 MCP elicitation，不会发给客户端；适配器还禁用其阻塞式 `request_user_input` 工具。Claude 通过适配器的工具回调运行，回调直接允许或拒绝、不会询问，使用原生 `default` 权限模式并禁用 SDK sandbox。MiniMax 绕过权限并禁用 sandbox；适配器禁用 `askUser`、不声明 elicitation，并以 ACP `cancelled` 结果答复 `session/request_permission`，MiniMax 将其视为拒绝。原生权限或问题请求都不会到达 Core：需要人工介入时通过 function 工具完成，Session 读取 [`requires_action`](./sessions-events.md#session-status)，由应用提交 function 结果。不要添加权限 profile、bubblewrap 包装器或原生 sandbox 设置；每种 Environment 来源都只有一条执行路径。资源路径属于操作员配置，而不是权限边界。
-
-模型主机不可达时不能让 Turn 一直挂起。适配器通过原生设置让 Harness 自身的连接重试保持有界；Harness 以结构化数据报告最终连接错误时，该错误归为 `connection_failed`（[原生失败分类](../../../docs/zh/runtime-protocol.md#native-failure-classification)）。Core 不另设模型超时。各适配器指南写明其 Harness 的上限。
-
-网络准入遵循 [Restricted network](environments.md#restricted-network)。
-
## 原生参考 {#native-references}
| Harness | 适配器 | 原生传输方式 | Runtime 指南 |
diff --git a/docs/runtime-bootstrap.md b/docs/runtime-bootstrap.md
index 7397e07fa..f4d9b73ea 100644
--- a/docs/runtime-bootstrap.md
+++ b/docs/runtime-bootstrap.md
@@ -2,7 +2,39 @@
title: "Runtime bootstrap"
---
-A Sandbox Provider starts a managed Runtime by handing it one bootstrap file. This document owns that Provider-to-Runtime startup input. The type and validator live in [`internal/runtimebootstrap`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/runtimebootstrap/bootstrap.go); Go providers build it with `sandbox.Bootstrap.RuntimeConnection()` in [`runtime_bootstrap.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/sandbox/runtime_bootstrap.go), and SDK helpers forward the serialized object unchanged. A provider never reads or writes the Runtime's private authentication store.
+The Runtime bootstrap protocol connects a Sandbox Provider to the managed Runtime it starts. The Provider hands the Runtime one bootstrap file, which is the Runtime's only authentication input for that launch.
+
+| Property | Value |
+| --- | --- |
+| Caller | The Sandbox Provider. Go Providers build the input with `sandbox.Bootstrap.RuntimeConnection()` in [`runtime_bootstrap.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/sandbox/runtime_bootstrap.go); SDK helpers forward the serialized object unchanged. |
+| Implementations | The Runtime, and the Providers listed under [Reference implementations](#reference-implementations) |
+| Code | [`internal/runtimebootstrap`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/runtimebootstrap/bootstrap.go): the type and validator |
+| Transport | A JSON file whose absolute path is passed to `oac-daemon connect --bootstrap-file` |
+| Version rule | The exact `version` ([Launch input](#launch-input)) |
+
+## Responsibilities and readiness
+
+| Party | Owns | Never does |
+| --- | --- | --- |
+| Sandbox Provider | The account, mounts and workspace; delivering the file; the Runtime's resource and Environment binding settings; starting the daemon as the unprivileged Runtime account | Reads or writes the Runtime's private authentication store |
+| Runtime | Validating the input, authentication and the connection | Accepts a second authentication source for the same launch |
+
+A successful launch proves only the handoff: an authenticated connection, prepared capabilities and execution readiness are separate observations under the [Core–Runtime protocol](./runtime-protocol.md), and the [Sandbox Provider protocol](./sandbox-provider.md#four-distinct-readiness-facts) lists what each one proves.
+
+Self-hosted executors and operator-provisioned devices get their daemon identity in other ways; the [machine connection API](../contracts/agents-api/machine-api.md#credentials) lists every credential source. All of them enter the same Runtime execution loop.
+
+## Startup order
+
+```mermaid
+sequenceDiagram
+ participant P as Sandbox Provider
+ participant R as Runtime daemon
+ participant C as Core
+ Note over P: Write the bootstrap file
+ P->>R: start oac-daemon connect --bootstrap-file PATH
+ Note over R: Validate the file, read the credential into memory
+ R->>C: Connect over the Core-Runtime protocol
+```
## Launch input
@@ -19,17 +51,22 @@ oac-daemon connect --bootstrap-file /home/runtime/runtime-bootstrap.json
| `device_id` | Canonical nonzero UUID of the daemon identity Core issued |
| `credential` | Nonempty daemon credential Core issued, without whitespace or NUL |
-The decoder rejects unknown, duplicate, missing and case-aliased fields, other versions and documents larger than `runtimebootstrap.MaxBytes` (16 KiB). Errors never include submitted values. A missing or malformed file fails before the daemon connects.
+The decoder rejects unknown, duplicate, missing and case-aliased fields, other versions and documents larger than `runtimebootstrap.MaxBytes`. Errors never include submitted values. A missing or malformed file fails before the daemon connects.
The file is the only authentication input for this launch: the daemon refuses to combine it with self-hosted enrollment options, and reads the credential into memory without saving it to a stored profile. Credentials never go in command arguments, environment variables or receipts. The provider keeps the file for process restarts and removes it only during explicit cleanup of the resources it owns.
-## Responsibilities and readiness
+## Timeouts and limits
-The provider creates the account, mounts and workspace, delivers this file, sets the Runtime's resource and Environment binding settings, and starts the daemon as the unprivileged Runtime account. Docker writes the file into the Runtime's owned home volume; microsandbox and E2B deliver it before launching the same command.
+| Value | Applies to | On breach |
+| --- | --- | --- |
+| 16 KiB (`runtimebootstrap.MaxBytes`) | The bootstrap document | The decoder rejects it, and the daemon fails before it connects. |
-The Runtime validates the input and owns authentication and connection. A successful launch proves only the handoff: an authenticated connection, prepared capabilities and execution readiness are separate observations under the [Core–Runtime protocol](./runtime-protocol.md), and the [Sandbox Provider guide](./sandbox-provider.md#four-distinct-readiness-facts) lists what each one proves.
+## Reference implementations
-Self-hosted executors and operator-provisioned devices get their daemon identity in other ways; the [machine connection API](../contracts/agents-api/machine-api.md#credentials) lists every credential source. All of them enter the same Runtime execution loop.
+| Provider | Delivery |
+| --- | --- |
+| Docker | Writes the file into the Runtime's owned home volume. |
+| microsandbox, E2B | Deliver the file before launching the same command. |
## Verification
diff --git a/docs/runtime-protocol.md b/docs/runtime-protocol.md
index e2623f159..b771b50c2 100644
--- a/docs/runtime-protocol.md
+++ b/docs/runtime-protocol.md
@@ -2,26 +2,55 @@
title: "Core\u2013Runtime protocol"
---
-This protocol connects Core to a Runtime daemon after the daemon has its machine credential. It defines the meaning and order of the messages on the daemon connection. The wire types, limits and validators live once in [`internal/agentdaemon/proto`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/internal/agentdaemon/proto); Core's [gateway](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/runtimegateway) and the reference Runtime's [dispatcher](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/apps/daemon/internal/dispatch) both use them, so there is no second payload schema to keep in sync. The HTTP routes that issue credentials and open the connection are in the [machine connection API](../contracts/agents-api/machine-api.md).
+The Core–Runtime protocol connects Core to a Runtime daemon and defines the meaning and order of the messages on the daemon connection. Hosted and self-hosted Runtimes use the same protocol.
-Hosted and self-hosted Runtimes use the same protocol. A Harness joins through the [Harness adapter contract](../contracts/agents-api/harness-onboarding.md), which owns the Executor and Turn lifecycle obligations behind the Runtime registry.
+| Property | Value |
+| --- | --- |
+| Caller | Core's [gateway](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/runtimegateway) |
+| Implementations | The reference Runtime's [dispatcher](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/apps/daemon/internal/dispatch). A Harness joins through the [Harness protocol](../contracts/agents-api/harness-onboarding.md), which owns the Executor and Turn lifecycle obligations behind the Runtime registry. |
+| Code | [`internal/agentdaemon/proto`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/internal/agentdaemon/proto): wire types, limits and validators, defined once and used by both sides, so there is no second payload schema to keep in sync |
+| Transport | JSON [envelopes](#envelope-and-identity) over a WebSocket at `/api/v1/agent-daemon/ws`. The HTTP routes that issue credentials and open the connection are in the [Machine connection API](../contracts/agents-api/machine-api.md). |
+| Version rule | Exact match of `proto.Version` ([Versioning](#versioning)) |
## Ownership and connection
-Core owns durable Session, Turn, input and Environment records, scheduling and reconciliation. Runtime owns native Executors, active Turns, transfer state and cleanup until settlement. A Sandbox Provider owns placement and the surrounding compute. Releasing an execution admission or closing an Executor never deletes, suspends or reclaims a sandbox. The daemon is not an isolation boundary; see [Runtime and outer isolation](./concepts.md#runtime-and-outer-isolation).
+| Party | Owns | Never does |
+| --- | --- | --- |
+| Core | Durable Session, Turn, input and Environment records, scheduling and reconciliation | Replays input, initialization, transfers or unresolved mutations after a reconnection |
+| Runtime | Native Executors, active Turns, transfer state and cleanup until settlement | Deletes, suspends or reclaims a sandbox when it releases an execution admission or closes an Executor; the daemon is not an isolation boundary ([Runtime and outer isolation](./concepts.md#runtime-and-outer-isolation)) |
+| Sandbox Provider | Placement and the surrounding compute | Owns Executors or Turns |
A Runtime connects in this order:
-1. Obtain a daemon credential and device ID. The [machine connection API](../contracts/agents-api/machine-api.md#credentials) lists the credential kinds; Project API keys and the Core key are never Runtime credentials.
-2. Call `POST /api/v1/agent-daemon/bootstrap` with the credential as a Bearer header and the device ID. Use the connection URL it returns.
-3. Dial the WebSocket at `/api/v1/agent-daemon/ws` with `device_id` and `version` query parameters and the Bearer header. Never put a credential in a URL, a payload log or a trace.
-4. Send a heartbeat at once, then at the interval bootstrap returned. Each heartbeat declares `supported_agent_kinds`, their availability and their [capabilities](#capability-declarations). Before the first heartbeat, capabilities are unknown; a kind missing from a heartbeat is not advertised. Neither permits inference.
-5. Exchange ordered JSON [envelopes](#envelope-and-identity). Heartbeats establish liveness only, never execution progress or a receipt for an earlier message.
-
-The wire version is [`proto.Version`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/version.go), independent of the Runtime build version that heartbeats report. Core accepts only an exact match, including the patch component. A mismatch returns HTTP 426 `incompatible_version` before any dispatch; the daemon treats it as permanent and stops reconnecting. Deploy matching peers together.
+```mermaid
+sequenceDiagram
+ participant R as Runtime
+ participant C as Core
+ R->>C: POST /api/v1/agent-daemon/bootstrap (device ID, Bearer credential)
+ C-->>R: connection URL, heartbeat interval
+ R->>C: WebSocket /api/v1/agent-daemon/ws?device_id&version
+ alt version differs from proto.Version
+ C-->>R: HTTP 426 incompatible_version
+ end
+ R->>C: heartbeat (supported_agent_kinds, availability, capabilities)
+ loop every heartbeat interval
+ R->>C: heartbeat
+ end
+ C->>R: ordered envelopes
+ R->>C: ordered envelopes
+```
+
+- The [Machine connection API](../contracts/agents-api/machine-api.md#credentials) lists the credential kinds. Project API keys and the Core key are never Runtime credentials.
+- Both requests carry the credential as a Bearer header. A credential never appears in a URL, a payload log or a trace.
+- The first heartbeat is sent at once, then at the interval that bootstrap returned. Each heartbeat declares `supported_agent_kinds`, their availability and their [capabilities](#capability-declarations). Before the first heartbeat, capabilities are unknown; a kind missing from a heartbeat is not advertised. Neither permits inference.
+- Heartbeats establish liveness only, never execution progress or a receipt for an earlier message.
Each physical connection has fresh routing, admission handles and transfer state. A newer connection for the same device replaces the previous one: Core fences the owner lease and evicts the old Run routes, and the new connection inherits none of them. A valid credential and connection are never authority to choose another Session or Environment binding.
+## Versioning
+
+The wire version is [`proto.Version`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/version.go), independent of the Runtime build version that heartbeats report. Core accepts only an exact match, including the patch component. A mismatch returns HTTP 426 `incompatible_version` before any dispatch; the daemon treats it as permanent and stops reconnecting. Deploy matching peers together; a change to a payload or its semantics changes `proto.Version`.
+
## Capability declarations
`AgentKindCapabilities` in [`inbound.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/inbound.go) describes one composed Runtime and Harness, independently of `available` and of Core's engine profile. Every field is a `CapabilitySupport`: supported or unsupported. The zero value is unspecified and invalid, even for an unavailable Harness. Registration validates the complete declaration before changing the registry; there is no implicit basic descriptor.
@@ -30,7 +59,7 @@ On the wire each field is a JSON boolean, and every field is present, including
Each admitted Executor and Turn keeps the declaration it was admitted with. A later heartbeat cannot add operations to an existing owner. Optional operations check this snapshot before any native call; the presence of a Go interface never grants support. A declared operation that returns `agent.ErrUnsupportedOperation` is a contract violation, distinct from unavailability, a failed native call or an uncertain write. Uncertain operations keep their receipts and ownership and are never replayed automatically. Workspace support includes the common Runtime workspace implementation, so a native adapter's unsupported workspace method does not disable that composition.
-A new field requires an explicit decision in every production declaration. Contract tests enumerate every field for registration, wire round trips and the persisted boolean projection; the shared test fixture lists fields individually and supplies no defaults for future ones. [Harness onboarding](../contracts/agents-api/harness-onboarding.md) owns the adapter side of each declaration.
+A new field requires an explicit decision in every production declaration. Contract tests enumerate every field for registration, wire round trips and the persisted boolean projection; the shared test fixture lists fields individually and supplies no defaults for future ones. The [Harness protocol](../contracts/agents-api/harness-onboarding.md#register-the-adapter) owns the adapter side of each declaration.
A declaration describes what the Runtime can do. Core admits a public feature only when the Harness's engine profile also qualifies it, and checks the declaration of the selected device during device selection and again at the final check before it claims a Turn:
@@ -56,23 +85,6 @@ Core has no admission rule for `usage` and `resume`.
`retained_native_history` means the composed Runtime and Harness can reopen the same native Session from its private retained state after confirmed native shutdown. It does not promise process memory, background processes or external connection recovery. The selected filesystem must separately provide retained storage. Core uses the previous device's persisted declaration to determine whether compute can be released without terminating the Session, and validates the replacement Runtime before admitting execution. Missing or invalid native history fails explicitly; it never authorizes a new native root or replay of prior input.
-The `execution_prepare` configuration carries the opt-ins Core sets for each Run:
-
-| Field | Set by Core |
-| --- | --- |
-| `agent_options` | Always `model` and `system_prompt` from the Agent; `model_provider` when the Session froze one; `harness_config` when the Agent sets `x_agents_core.harness_config`. Core sends no other key; the Runtime rejects any other key with `unsupported_configuration` before preparation |
-| `execution_controls` | Always: web search `disabled`, the resolved text verbosity (default `medium`), an explicit programmatic-tool-calling disable and any `json_schema` output format. Native option names belong to the adapter |
-| `observe_messages` | When the Runtime declares `message_items`. Text deltas then carry the native item ID, and `output_message` frames report message start, completion, phase and the completion text |
-| `observe_subagent_identities`, `disable_subagents` | From the Agent's `multi_agent.enabled` |
-| `disable_execution_environment` | For an Environment of type `none` |
-| `local_environment` | For `openai_hosted` and `self_hosted`, with the exact Environment binding. The request carries no working directory; the Runtime checks `workspace_directory` against its binding |
-| `require_existing_native_session` | When a native Session must be recovered |
-| `durable_receipt` on `prompt_steer` | For every active input Core delivers |
-
-An execution configuration requires exactly one of `local_environment` and `disable_execution_environment`; `execution_prepare` rejects neither or both with `unsupported_configuration`.
-
-Requests without an opt-in keep the frames and fields they had without it. A `tool_call` frame carries the engine-neutral `observation` whenever the adapter maps the native tool.
-
## Envelope and identity
Every data frame is one JSON [`Envelope`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/envelope.go): `type`, a type-dependent `id`, a typed `payload` and an optional W3C `trace`. The trace is diagnostic correlation only; missing or invalid trace data creates a local trace and never changes ownership. Never use a trace ID as a request ID.
@@ -110,37 +122,135 @@ Usage frames and the final usage snapshot each carry the cumulative measurement
## Preparation and execution order
-Environment initialization uses `runtime_prepare` on every connection, managed or user-owned; the [Environment contract](../contracts/agents-api/environments.md#runtime-capability-preparation) owns what is prepared and when. For a file or archive, send `begin`, wait for `ready`, send ordered chunks and await each matching `received` offset, then send `commit` and await `completed`. Initialization and finalization have typed headers without file data. Every `begin` requires `budget_ms`, an integer from 1 through 1800000 carrying the remaining Core-owned initialization budget; chunks and commits omit it. The Runtime enforces that relative budget from receipt of `begin`, and Core waits no longer than its original operation deadline. The complete `begin`–`commit` staging phase has a separate two-minute limit; applying a committed operation and waiting for `completed` use the remaining initialization budget, not the staging limit. Expiry before application rejects the transfer; expiry during application reports `unknown` after local mutations stop and never authorizes replay. Validate the expected outcome, offset, size and finite error code with the shared validator. One transfer is allowed per connection. A chunk receipt confirms staged bytes, not installation; a completed commit confirms that operation, not that a later Turn ran.
-
-An execution Turn runs in five steps:
-
-1. Subscribe to preparation status, then send `execution_prepare` with the immutable Session configuration and no Run input.
-2. `preparing` means the Runtime owns preparation. `ready` supplies the Executor ID, admission handle, revision and expiry. Neither submits user input.
-3. Subscribe to the Run, then send `execution_start` with that Executor ID, handle, Run ID and ordered input. A valid start transfers the reservation once. `started` confirms the transfer to the Turn, not its completion; output can race the status, so it must already have a subscriber.
-4. Consume Run events until a native terminal outcome or loss of observation. An execution error is followed by `done`, which closes the stream; the preceding errors remain part of its outcome.
-5. To abandon before start, send `execution_release`. After ownership passes to a Run, use `prompt_cancel`; releasing the old handle cannot cancel its successor.
-
-A preparation reserves a per-Turn admission, not a new Executor. It carries an explicit Session identity and immutable configuration without model input or a Run ID. A fresh request returns a connection-local handle and the owning Executor ID; a reused healthy Executor returns `ready` without native preparation. Per-handle revisions order status observations: ignore older or repeated revisions and never apply a status to another handle. Typical transitions are `preparing → ready → starting → started`, or termination by `released`, `expired` or `failed`. A `rejected` control operation carries an `operation` and error code and does not replace the handle's current revision. Releasing an admission abandons only that admission; it does not close the Session's idle Executor or cancel a later Turn.
-
-Preparation and start run outside the receive loop and router lock. An admission expires five minutes after it is granted, and retries do not extend that deadline; expiry does not remove the Runtime's obligation to settle cleanup. The Runtime bounds active preparation and execution separately from idle retained resources and counts closing or uncertain resources until their cleanup succeeds. A definite `execution_prepare` rejection with `preparation_capacity` leaves the queued Turn unclaimed for the Worker to retry, including when cleanup holds the capacity; any other error or uncertain delivery authorizes no replay. The Runtime retains at most 64 admission records, and an old handle never consumes a replacement's admission. These records are connection-local, not durable input replay.
+Environment initialization uses `runtime_prepare` on every connection, managed or user-owned; the [Environment contract](../contracts/agents-api/environments.md#runtime-capability-preparation) owns what is prepared and when. A file or archive moves in one transfer, shown below.
+
+```mermaid
+sequenceDiagram
+ participant C as Core
+ participant R as Runtime
+ C->>R: runtime_prepare begin (budget_ms)
+ R-->>C: runtime_prepare_result ready
+ loop each chunk
+ C->>R: runtime_prepare chunk (offset)
+ R-->>C: runtime_prepare_result received (offset)
+ end
+ C->>R: runtime_prepare commit
+ R-->>C: runtime_prepare_result completed
+```
+
+Initialization and finalization have typed headers without file data. Every `begin` carries `budget_ms`, the remaining Core-owned initialization budget; chunks and commits omit it. The Runtime enforces that relative budget from receipt of `begin`, and Core waits no longer than its original operation deadline. The `begin`–`commit` staging phase has its own limit; applying a committed operation and waiting for `completed` use the remaining initialization budget, not the staging limit. Expiry before application rejects the transfer; expiry during application reports `unknown` after local mutations stop and never authorizes replay. Validate the expected outcome, offset, size and finite error code with the shared validator. One transfer is allowed per connection. A chunk receipt confirms staged bytes, not installation; a completed commit confirms that operation, not that a later Turn ran.
+
+An execution Turn runs as follows. Core subscribes to preparation status before it sends `execution_prepare` and to the Run before it sends `execution_start`, because output can race the status.
+
+```mermaid
+sequenceDiagram
+ participant C as Core
+ participant R as Runtime
+ participant H as Harness adapter
+ Note over C: Subscribe to preparation status
+ C->>R: execution_prepare (Session configuration, no Run input)
+ alt new Executor
+ R-->>C: preparation_status preparing
+ R->>H: ExecutorFactory
+ R-->>C: preparation_status ready (Executor ID, handle, revision, expiry)
+ else reused healthy Executor
+ R-->>C: preparation_status ready
+ end
+ alt abandon before start
+ C->>R: execution_release
+ R-->>C: preparation_status released
+ else start
+ Note over C: Subscribe to the Run
+ C->>R: execution_start (Executor ID, handle, Run ID, input)
+ R-->>C: preparation_status starting
+ R->>H: StartTurn
+ R-->>C: preparation_status started
+ loop until a native terminal outcome
+ R-->>C: delta, tool_call, usage, error
+ end
+ alt Run ends
+ R-->>C: done
+ else cancel during the Run
+ C->>R: prompt_cancel
+ R-->>C: interaction_decision_ack
+ end
+ end
+```
+
+- `preparing` means the Runtime owns preparation. `ready` supplies the Executor ID, admission handle, revision and expiry. Neither submits user input.
+- A valid `execution_start` transfers the reservation once. `started` confirms the transfer to the Turn, not its completion.
+- Consume Run events until a native terminal outcome or loss of observation. An execution error is followed by `done`, which closes the stream; the preceding errors remain part of its outcome.
+- To abandon before start, send `execution_release`. After ownership passes to a Run, use `prompt_cancel`; releasing the old handle cannot cancel its successor.
+
+A preparation reserves a per-Turn admission, not a new Executor. It carries an explicit Session identity and immutable configuration without model input or a Run ID. A fresh request returns a connection-local handle and the owning Executor ID; a reused healthy Executor returns `ready` without native preparation. Per-handle revisions order status observations: ignore older or repeated revisions and never apply a status to another handle. An admission moves through the states below. A `rejected` control operation carries an `operation` and error code and does not replace the handle's current revision. Releasing an admission abandons only that admission; it does not close the Session's idle Executor or cancel a later Turn.
+
+```mermaid
+stateDiagram-v2
+ direction LR
+ [*] --> preparing: execution_prepare
+ [*] --> ready: reused Executor
+ preparing --> ready
+ ready --> starting: execution_start
+ starting --> started
+ starting --> failed
+ preparing --> released: execution_release
+ ready --> released: execution_release
+ preparing --> expired
+ ready --> expired
+ preparing --> failed
+ ready --> failed
+```
+
+Preparation and start run outside the receive loop and router lock. An admission expires at a fixed deadline that retries do not extend; expiry does not remove the Runtime's obligation to settle cleanup. The Runtime bounds active preparation and execution separately from idle retained resources and counts closing or uncertain resources until their cleanup succeeds. A definite `execution_prepare` rejection with `preparation_capacity` leaves the queued Turn unclaimed for the Worker to retry, including when cleanup holds the capacity; any other error or uncertain delivery authorizes no replay. The Runtime retains a bounded number of admission records, and an old handle never consumes a replacement's admission. These records are connection-local, not durable input replay.
Idle expiry of an Executor is a Runtime resource policy, separate from Core's active-Turn concurrency. On shutdown the Runtime closes active and idle Executors, keeps any target whose close failed and allows a later serialized retry. An ordinary disconnection closes the failed transport and keeps the exact router until shutdown succeeds; a wait timeout or failed cleanup never authorizes reconnection, and process shutdown keeps waiting rather than discarding owned native resources. For Runtime initialization, shutdown joins the synchronous apply operation and its receipt delivery before releasing the connection; an `unknown` result remains unknown and blocks further preparation on that Router, but does not prevent reconnection after local mutations have stopped. Core retains the failed initialization and never replays it. Workspace operations keep their binding and settlement rules across Turn boundaries and Executor closure.
Suspension closes admission and drains admitted work and receipts while retaining settled idle Executors before acknowledging `environment_quiesced`. Active, preparing, invalid or otherwise unsettled owners prevent suspension. Idle expiry is stopped and its callbacks fenced throughout suspension; exact authenticated `environment_resume` restores a fresh idle interval on the same owners. Only this planned reconnect preserves the Router and native owners across sockets; ordinary disconnect, shutdown and cancellation of the connection lifecycle still require confirmed cleanup. A drain failure keeps admission closed until shutdown. Preparation after resume retains the same native identity and immutable-configuration checks, including credential conflicts; it never silently replaces a conflicting resident Executor. The Sandbox Provider remains responsible for the filesystem flush and compute-stop guarantees of its checkpoint implementation; Runtime quiescence alone proves neither those guarantees nor restoration of native RAM or external network connections.
-## Active input receipts
+### Execution configuration
-Core delivers active input as `prompt_steer` with `durable_receipt: true`, one input at a time per Run, and waits for its receipt before sending the next:
+The `execution_prepare` configuration carries the opt-ins Core sets for each Run:
-| Phase | Timer |
+| Field | Set by Core |
| --- | --- |
-| Native write | The Runtime bounds the adapter's native write at 10 seconds; the timer stops once the write is complete |
-| `written` acknowledgement | Core waits at most 30 seconds from delivery for `written`; otherwise the input outcome is unknown |
-| Receipt send | Each receipt send has its own 5-second, shutdown-aware budget |
-| Native acceptance | `accepted` arrives under the Turn lifetime, with no automatic redelivery |
-| Done | The Runtime sends `done` after native Turn settlement and after the receipt send of any in-flight input; the native write and receipt send budgets bound that input |
+| `agent_options` | Always `model` and `system_prompt` from the Agent; `model_provider` when the Session froze one; `harness_config` when the Agent sets `x_agents_core.harness_config`. Core sends no other key; the Runtime rejects any other key with `unsupported_configuration` before preparation |
+| `execution_controls` | Always: web search `disabled`, the resolved text verbosity (default `medium`), an explicit programmatic-tool-calling disable and any `json_schema` output format. Native option names belong to the adapter |
+| `observe_messages` | When the Runtime declares `message_items`. Text deltas then carry the native item ID, and `output_message` frames report message start, completion, phase and the completion text |
+| `observe_subagent_identities`, `disable_subagents` | From the Agent's `multi_agent.enabled` |
+| `disable_execution_environment` | For an Environment of type `none` |
+| `local_environment` | For `openai_hosted` and `self_hosted`, with the exact Environment binding. The request carries no working directory; the Runtime checks `workspace_directory` against its binding |
+| `require_existing_native_session` | When a native Session must be recovered |
+| `durable_receipt` on `prompt_steer` | For every active input Core delivers |
+
+An execution configuration requires exactly one of `local_environment` and `disable_execution_environment`; `execution_prepare` rejects neither or both with `unsupported_configuration`.
-Neither `written` nor a send failure advances Core's input cursor. Once cancellation is sent, its receipt owns the terminal outcome even if an input becomes unknown first; Core records `cancel_unconfirmed` when no cancellation confirmation arrives within 15 seconds. A cancellation receipt carries the stopped Turn's confirmed continuity snapshot when no `done` is emitted.
+Requests without an opt-in keep the frames and fields they had without it. A `tool_call` frame carries the engine-neutral `observation` whenever the adapter maps the native tool.
+
+## Active input receipts
+
+Core delivers active input as `prompt_steer` with `durable_receipt: true`, one input at a time per Run, and waits for its receipt before sending the next.
+
+```mermaid
+sequenceDiagram
+ participant C as Core
+ participant R as Runtime
+ participant H as Harness adapter
+ C->>R: prompt_steer (durable_receipt)
+ Note over C,R: written wait limit, from delivery
+ R->>H: SteerWithReceipt
+ Note over R,H: native write limit
+ H-->>R: write complete
+ Note over R,C: receipt send limit
+ R-->>C: prompt_steer_ack written
+ H-->>R: native application receipt
+ Note over R,C: receipt send limit
+ R-->>C: prompt_steer_ack accepted
+ R-->>C: done after Turn settlement
+```
+
+`accepted` arrives under the Turn lifetime, with no automatic redelivery. The Runtime sends `done` after native Turn settlement and after the receipt send of any in-flight input; the native write and receipt send limits bound that input. The limits are in [Timeouts and limits](#timeouts-and-limits).
+
+Neither `written` nor a send failure advances Core's input cursor. Once cancellation is sent, its receipt owns the terminal outcome even if an input becomes unknown first; Core records `cancel_unconfirmed` when no cancellation confirmation arrives before its limit expires. A cancellation receipt carries the stopped Turn's confirmed continuity snapshot when no `done` is emitted.
## What each acknowledgement proves
@@ -188,18 +298,42 @@ Core stores accepted values in the Turn outcome as `engine_error_code` and `engi
A workspace read that needs no running Turn uses the read-only preparation profile: `execution_prepare` with `workspace_read_only`, which requires the `workspace_read_preparation` capability. It accepts only the bound Environment and resource identity; execution options, model and MCP credentials, native Session continuation and model or tool input are excluded, and the owner rejects `execution_start`. The Runtime serves it from its bound local workspace without starting a Harness process. The profile publishes `released` after the Runtime drops the preparation's ownership; a stale status snapshot never publishes success. A release request, HTTP disconnect or remote socket closure alone does not confirm the release.
-`workspace_read` targets an existing preparation handle, or the Run it was transferred to, on the same authenticated device connection, with the exact frozen Environment identity; callers cannot supply sockets, credentials or workspace roots. `operation: directory` lists one workspace-relative directory (an empty path selects the root) with mutually exclusive byte and entry limits. A result carries at most 1024 single-component UTF-8 names of at most 255 bytes each, the entry kind, regular-file sizes and explicit truncation, and is returned only after directory access and handle cleanup settle. There is no snapshot, recursion or pagination at this layer. Byte and directory reads share target checks, correlation, capacity and retained operation waits.
+`workspace_read` targets an existing preparation handle, or the Run it was transferred to, on the same authenticated device connection, with the exact frozen Environment identity; callers cannot supply sockets, credentials or workspace roots. `operation: directory` lists one workspace-relative directory (an empty path selects the root) with mutually exclusive byte and entry limits. A result carries a bounded number of single-component UTF-8 names, the entry kind, regular-file sizes and explicit truncation, and is returned only after directory access and handle cleanup settle. There is no snapshot, recursion or pagination at this layer. Byte and directory reads share target checks, correlation, capacity and retained operation waits.
-Request payloads are bounded at 8 KiB and correlation IDs at 128 bytes before admission; oversized IDs are not echoed, and oversized trace metadata is omitted from replies. Raw read results are bounded at 1 MiB within the 4 MiB transport frame. These are private transport limits, not public Files parameters. A successful read requires complete bytes or explicit truncation and an acknowledged native close. A safe native rejection carries no bytes; an interrupted or ambiguous read stays unknown and stops further reads on that owner. A dispatched read keeps its bounded waiter across observer cancellation and resource transfer or release, and resource closure stops new admission. The gateway bounds subscriptions and never retries or replays a read on reconnect; a duplicate pending operation ID cannot start another read.
+Request payloads and correlation IDs are bounded before admission; oversized IDs are not echoed, and oversized trace metadata is omitted from replies. Raw read results are bounded within the transport frame. These are private transport limits, not public Files parameters. A successful read requires complete bytes or explicit truncation and an acknowledged native close. A safe native rejection carries no bytes; an interrupted or ambiguous read stays unknown and stops further reads on that owner. A dispatched read keeps its bounded waiter across observer cancellation and resource transfer or release, and resource closure stops new admission. The gateway bounds subscriptions and never retries or replays a read on reconnect; a duplicate pending operation ID cannot start another read.
Core runs an idle directory read on the Worker's Session scheduling reservation and targets the exact Run during active execution. It keeps the reservation through the bounded read and release, returns data only after a confirmed close (an incomplete read or uncertain cleanup returns unavailable without data), releases the reservation before delivering the result, and revokes the scoped read credential on completion or failure. The Runtime keeps uncertain cleanup ownership and capacity. The [Environment Files contract](../contracts/agents-api/environment-files.md) owns public authorization, paths and pagination.
-`workspace_write` transfers a complete bounded body in acknowledged 64 KiB frames before the native writer runs, verifies the declared digest and runs no model. The private transfer bound is 50 MiB, separate from the public 5 MiB decoded inline bound that the API checks before any Runtime work. The Runtime excludes execution while it receives or applies a write; a malformed, incomplete or expired transfer never reaches the installer. An exact commit or rejection receipt releases the mutation owner. A missing or ambiguous receipt keeps the uncertainty: observer cancellation and local process exit cannot prove that nothing changed. Before public admission Core durably reserves the write under the Session lock and blocks successor mutations across restarts until exact settlement; the request is never replayed. Every platform uses the daemon's Go implementation for bounded reads, directory listing, file creation and output export, with no external helper or staging directory.
+`workspace_write` transfers a complete bounded body in acknowledged frames before the native writer runs, verifies the declared digest and runs no model. The private transfer bound is separate from the public decoded inline bound that the API checks before any Runtime work. The Runtime excludes execution while it receives or applies a write; a malformed, incomplete or expired transfer never reaches the installer. An exact commit or rejection receipt releases the mutation owner. A missing or ambiguous receipt keeps the uncertainty: observer cancellation and local process exit cannot prove that nothing changed. Before public admission Core durably reserves the write under the Session lock and blocks successor mutations across restarts until exact settlement; the request is never replayed. Every platform uses the daemon's Go implementation for bounded reads, directory listing, file creation and output export, with no external helper or staging directory.
## MCP connection authority
Every public `MCPHTTPServer` in an `execution_prepare` configuration carries an explicit `connection_origin`; a missing or unknown value rejects rather than selecting a default, and Core freezes the public default before dispatch. The Runtime validates the origin with the common validator before selecting a factory and resolves public and installed MCP into transient effective bindings. The [Environment contract](../contracts/agents-api/environments.md#public-mcp-connection-origin) owns the supported combinations, native limits and failure ownership.
+## Timeouts and limits
+
+Every number in this protocol is stated here. The Harness side of the Turn lifetime is in the [Harness protocol](../contracts/agents-api/harness-onboarding.md#timeouts-and-limits).
+
+| Value | Applies to | On expiry or breach |
+| --- | --- | --- |
+| 5 minutes | An execution admission, from the moment it is granted; retries do not extend it | The admission becomes `expired`. The Runtime still owes cleanup settlement. |
+| 64 records | Admission records a Runtime retains per connection | `execution_prepare` is rejected with `preparation_capacity`, and Core leaves the queued Turn unclaimed for the Worker to retry. |
+| 64 frames | The bounded output channel of a Turn | A single consumer, started before native Start, drains it. |
+| 10 seconds | The Runtime's settlement wait around a Turn | A timeout is not proof of quiescence; the resources stay owned until cleanup is confirmed. |
+| 1 to 1,800,000 ms | `budget_ms` of a `runtime_prepare` `begin`: the remaining Core-owned initialization budget | Expiry before application rejects the transfer; expiry during application reports `unknown` and is never replayed. |
+| 2 minutes | The `begin`–`commit` staging phase of one `runtime_prepare` transfer | The transfer is rejected. |
+| 64 KiB | One chunk of a `runtime_prepare` transfer or a `workspace_write` body | A larger chunk fails validation. |
+| 50 MiB | One `runtime_prepare` transfer or `workspace_write` body (private bound) | The transfer is rejected before it reaches the installer. |
+| 5 MiB | The decoded inline body of a public write, checked by the API before any Runtime work | The API rejects the request. |
+| 4 MiB | One inbound transport frame | The frame is refused. |
+| 8 KiB, 128 bytes | A `workspace_read` request payload, and a correlation ID, checked before admission | The request is rejected; an oversized ID is not echoed and oversized trace metadata is omitted from replies. |
+| 1 MiB | The raw result of a `workspace_read`, within the transport frame | The result is explicitly truncated. |
+| 1024 names, 255 bytes each | One directory result | The result is explicitly truncated. |
+| 10 seconds | The adapter's native write of an active input; the timer stops when the write completes | The Runtime acknowledges `outcome_unknown` and never redelivers the input automatically. |
+| 30 seconds | Core's wait for `written`, from delivery | The input outcome is unknown. |
+| 5 seconds | Each receipt send, which is shutdown-aware | The send fails; a send failure does not advance Core's input cursor. |
+| 15 seconds | Core's wait for a cancellation confirmation | Core records `cancel_unconfirmed`. |
+
## Contract verification
Run `make check-runtime-contract` from the repository root. It exercises the shared wire validators, gateway, transport and dispatcher, the shared wire scenarios on both sides, the [observation-result regression](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/execution/runtime_protocol_test.go) and the Harness declaration tests. It needs no model credentials or external sandbox, and `make check` runs the same tests through `check-go` and `check-core`.
@@ -208,4 +342,4 @@ Each [wire scenario](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/inter
The suite covers incompatible versions, preparation failure, cancellation settlement, connection loss without invented terminal events, reconnection without replay, stale or duplicate handles and receipts, cleanup failures, bounded transfer validation and resource ownership after a timeout. Detailed fault injection stays next to the gateway and dispatcher code it tests.
-Another Runtime replays the same scenarios against a scripted Core, then runs native acceptance for every capability it declares. A controlled-adapter test establishes the transport contract, not native Harness behavior, operating-system support, provider authentication or sandbox isolation. Change the shared types, this document and the contract checks together. Harness adapters also run the shared text assertions described in [Harness onboarding](../contracts/agents-api/harness-onboarding.md).
+Another Runtime replays the same scenarios against a scripted Core, then runs native acceptance for every capability it declares. A controlled-adapter test establishes the transport contract, not native Harness behavior, operating-system support, provider authentication or sandbox isolation. Change the shared types, this document and the contract checks together. Harness adapters also run the shared text assertions described in [Harness protocol](../contracts/agents-api/harness-onboarding.md#qualify-the-adapter).
diff --git a/docs/zh/runtime-bootstrap.md b/docs/zh/runtime-bootstrap.md
index f7d147c2a..6040851f3 100644
--- a/docs/zh/runtime-bootstrap.md
+++ b/docs/zh/runtime-bootstrap.md
@@ -1,10 +1,42 @@
---
title: "Runtime 引导"
source: docs/runtime-bootstrap.md
-source_hash: f7e9275feee79ac1fb1299227e148b85c26efc8b8af5ca0e8f498126c563d182
+source_hash: fa560c06d329dc21212e9567bd36dfcdfec6d5f9e1d29ca7b08bc525587e80b5
---
-沙箱提供商通过交付一个引导文件来启动托管 Runtime。本文负责提供商到 Runtime 的启动输入。类型与验证器位于 [`internal/runtimebootstrap`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/runtimebootstrap/bootstrap.go)；Go 提供商使用 [`runtime_bootstrap.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/sandbox/runtime_bootstrap.go) 中的 `sandbox.Bootstrap.RuntimeConnection()` 构造输入，SDK helper 原样转发序列化对象。提供商不读取或写入 Runtime 的私有认证存储。
+Runtime 引导协议连接沙箱提供商与其启动的托管 Runtime。提供商向 Runtime 交付一个引导文件，该文件是此次启动中 Runtime 唯一的认证输入。
+
+| 属性 | 内容 |
+| --- | --- |
+| 调用方 | 沙箱提供商。Go 提供商使用 [`runtime_bootstrap.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/sandbox/runtime_bootstrap.go) 中的 `sandbox.Bootstrap.RuntimeConnection()` 构造输入；SDK helper 原样转发序列化对象。 |
+| 实现方 | Runtime，以及[参考实现](#reference-implementations)中列出的提供商 |
+| 代码 | [`internal/runtimebootstrap`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/runtimebootstrap/bootstrap.go)：类型与验证器 |
+| 传输 | 一个 JSON 文件，其绝对路径传给 `oac-daemon connect --bootstrap-file` |
+| 版本规则 | 精确的 `version`（[启动输入](#launch-input)） |
+
+## 职责与就绪状态 {#responsibilities-and-readiness}
+
+| 参与方 | 拥有 | 绝不 |
+| --- | --- | --- |
+| 沙箱提供商 | 账户、挂载和工作区；交付该文件；Runtime 的资源与 Environment 绑定配置；以无特权 Runtime 账户启动 daemon | 读取或写入 Runtime 的私有认证存储 |
+| Runtime | 验证输入、认证和连接 | 为同一次启动接受第二个认证来源 |
+
+启动成功仅证明交付完成：经过认证的连接、已准备的能力和执行就绪是 [Core–Runtime 协议](runtime-protocol.md) 下的独立观测；[沙箱提供商协议](sandbox-provider.md#four-distinct-readiness-facts) 列出各自证明的事实。
+
+自托管执行器和运维人员供应的设备通过其他方式获取 daemon 身份；[机器连接 API](../../contracts/agents-api/zh/machine-api.md#credentials) 列出所有凭据来源。它们都进入同一 Runtime 执行循环。
+
+## 启动顺序 {#startup-order}
+
+```mermaid
+sequenceDiagram
+ participant P as Sandbox Provider
+ participant R as Runtime daemon
+ participant C as Core
+ Note over P: Write the bootstrap file
+ P->>R: start oac-daemon connect --bootstrap-file PATH
+ Note over R: Validate the file, read the credential into memory
+ R->>C: Connect over the Core-Runtime protocol
+```
## 启动输入 {#launch-input}
@@ -21,17 +53,22 @@ oac-daemon connect --bootstrap-file /home/runtime/runtime-bootstrap.json
| `device_id` | Core 签发的 daemon 身份的规范非零 UUID |
| `credential` | Core 签发的非空 daemon 凭据，不含空白或 NUL |
-解码器拒绝未知、重复、缺失和大小写别名字段，拒绝其他版本及超过 `runtimebootstrap.MaxBytes`（16 KiB）的文档。错误不包含提交的值。文件缺失或格式错误时，daemon 在连接前失败。
+解码器拒绝未知、重复、缺失和大小写别名字段，拒绝其他版本及超过 `runtimebootstrap.MaxBytes`的文档。错误不包含提交的值。文件缺失或格式错误时，daemon 在连接前失败。
该文件是此次启动唯一的认证输入：daemon 拒绝将其与自托管注册选项组合使用，并将凭据读入内存而不保存到存储的 profile。凭据不进入命令参数、环境变量或回执。提供商为进程重启保留该文件，仅在明确清理自己拥有的资源时删除。
-## 职责与就绪状态 {#responsibilities-and-readiness}
+## 超时与限制 {#timeouts-and-limits}
-提供商创建账户、挂载和工作区，交付该文件，设置 Runtime 的资源与 Environment 绑定配置，然后以无特权 Runtime 账户启动 daemon。Docker 将文件写入 Runtime 拥有的 home volume；microsandbox 和 E2B 在启动同一命令之前交付文件。
+| 数值 | 适用对象 | 超出时 |
+| --- | --- | --- |
+| 16 KiB（`runtimebootstrap.MaxBytes`） | 引导文档 | 解码器拒绝该文档，daemon 在连接前失败。 |
-Runtime 验证输入，并负责认证与连接。启动成功仅证明交付完成：经过认证的连接、已准备的能力和执行就绪是 [Core–Runtime 协议](runtime-protocol.md) 下的独立观测；[沙箱提供商指南](sandbox-provider.md#four-distinct-readiness-facts) 列出各自证明的事实。
+## 参考实现 {#reference-implementations}
-自托管执行器和运维人员供应的设备通过其他方式获取 daemon 身份；[机器连接 API](../../contracts/agents-api/zh/machine-api.md#credentials) 列出所有凭据来源。它们都进入同一 Runtime 执行循环。
+| 提供商 | 交付方式 |
+| --- | --- |
+| Docker | 将文件写入 Runtime 拥有的 home volume。 |
+| microsandbox、E2B | 在启动同一命令之前交付文件。 |
## 验证 {#verification}
diff --git a/docs/zh/runtime-protocol.md b/docs/zh/runtime-protocol.md
index 73ec88be4..74252da8c 100644
--- a/docs/zh/runtime-protocol.md
+++ b/docs/zh/runtime-protocol.md
@@ -1,29 +1,58 @@
---
title: "Core–Runtime 协议"
source: docs/runtime-protocol.md
-source_hash: 2daf6711170282ee521509c9305c25f3286ab6de48f84f589ad33f95768eabc3
+source_hash: 2b4bd6958c7addec906c30ccba8b359d98e267049ff87a6d54fe73be8de16e85
---
-此协议在 Runtime daemon 获取机器凭据后连接 Core 与 daemon，定义 daemon 连接上消息的含义和顺序。wire 类型、限制和验证器仅在 [`internal/agentdaemon/proto`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/internal/agentdaemon/proto) 中定义一次；Core 的 [gateway](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/runtimegateway) 与参考 Runtime 的 [dispatcher](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/apps/daemon/internal/dispatch) 都使用它们，因此无需同步第二套 payload schema。签发凭据和打开连接的 HTTP 路由见[机器连接 API](../../contracts/agents-api/zh/machine-api.md)。
+Core–Runtime 协议连接 Core 与 Runtime daemon，定义 daemon 连接上消息的含义和顺序。托管和自托管 Runtime 使用同一协议。
-托管和自托管 Runtime 使用同一协议。Harness 通过 [Harness adapter 契约](../../contracts/agents-api/zh/harness-onboarding.md)接入，该契约负责 Runtime registry 后的 Executor 和 Turn 生命周期义务。
+| Property | Value |
+| --- | --- |
+| 调用方 | Core 的 [gateway](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/services/core/internal/runtimegateway) |
+| 实现方 | 参考 Runtime 的 [dispatcher](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/apps/daemon/internal/dispatch)。Harness 通过 [Harness 协议](../../contracts/agents-api/zh/harness-onboarding.md)接入，该协议负责 Runtime registry 后的 Executor 和 Turn 生命周期义务。 |
+| 代码 | [`internal/agentdaemon/proto`](https://github.com/MiniMax-AI/OpenAgentCore/tree/main/internal/agentdaemon/proto)：wire 类型、限制和验证器仅定义一次，供两端共用，因此无需同步第二套 payload schema |
+| 传输 | 通过 `/api/v1/agent-daemon/ws` 的 WebSocket 传输 JSON [envelope](#envelope-and-identity)。签发凭据和打开连接的 HTTP 路由见[机器连接 API](../../contracts/agents-api/zh/machine-api.md)。 |
+| 版本规则 | `proto.Version` 精确匹配（[版本](#versioning)） |
## 所有权与连接 {#ownership-and-connection}
-Core 拥有持久化的 Session、Turn、input 和 Environment 记录、调度与协调。Runtime 拥有原生 Executor、活动 Turn、传输状态和清理责任，直到完成结算。沙箱提供商拥有执行位置与外围计算资源。释放执行准入或关闭 Executor 不会删除、暂停或回收沙箱。daemon 不是隔离边界；参见 [Runtime 与外层隔离](concepts.md#runtime-and-outer-isolation)。
+| 参与方 | 拥有 | 绝不 |
+| --- | --- | --- |
+| Core | 持久化的 Session、Turn、input 和 Environment 记录、调度与协调 | 重连后重放 input、初始化、transfer 或未决 mutation |
+| Runtime | 原生 Executor、活动 Turn、传输状态和清理责任，直到完成结算 | 因释放执行准入或关闭 Executor 而删除、暂停或回收沙箱；daemon 不是隔离边界（参见 [Runtime 与外层隔离](concepts.md#runtime-and-outer-isolation)） |
+| 沙箱提供商 | 执行位置与外围计算资源 | 拥有 Executor 或 Turn |
Runtime 按以下顺序连接：
-1. 获取 daemon 凭据和 device ID。[机器连接 API](../../contracts/agents-api/zh/machine-api.md#credentials) 列出凭据类型；项目 API 密钥和 Core 密钥都不是 Runtime 凭据。
-2. 调用 `POST /api/v1/agent-daemon/bootstrap`，通过 Bearer header 提供凭据，并提供 device ID。使用返回的连接 URL。
-3. 连接 `/api/v1/agent-daemon/ws` 的 WebSocket，传入 `device_id`、`version` 查询参数和 Bearer header。凭据不得出现在 URL、payload 日志或 trace 中。
-4. 立即发送 heartbeat，之后按 bootstrap 返回的间隔发送。每个 heartbeat 声明 `supported_agent_kinds`、其可用性和[能力](#capability-declarations)。第一个 heartbeat 之前能力未知；heartbeat 中缺失的 kind 视为未声明。两者都不允许推断。
-5. 交换有序 JSON [envelope](#envelope-and-identity)。Heartbeat 仅证明存活，不证明执行进度，也不充当此前消息的回执。
-
-wire 版本为 [`proto.Version`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/version.go)，独立于 heartbeat 报告的 Runtime 构建版本。Core 仅接受精确匹配，包括 patch 部分。不匹配时，在任何 dispatch 前返回 HTTP 426 `incompatible_version`；daemon 将其视为永久错误并停止重连。应一起部署版本匹配的两端。
+```mermaid
+sequenceDiagram
+ participant R as Runtime
+ participant C as Core
+ R->>C: POST /api/v1/agent-daemon/bootstrap (device ID, Bearer credential)
+ C-->>R: connection URL, heartbeat interval
+ R->>C: WebSocket /api/v1/agent-daemon/ws?device_id&version
+ alt version differs from proto.Version
+ C-->>R: HTTP 426 incompatible_version
+ end
+ R->>C: heartbeat (supported_agent_kinds, availability, capabilities)
+ loop every heartbeat interval
+ R->>C: heartbeat
+ end
+ C->>R: ordered envelopes
+ R->>C: ordered envelopes
+```
+
+- [机器连接 API](../../contracts/agents-api/zh/machine-api.md#credentials) 列出凭据类型；项目 API 密钥和 Core 密钥都不是 Runtime 凭据。
+- 两个请求都通过 Bearer header 提供凭据。凭据不得出现在 URL、payload 日志或 trace 中。
+- 立即发送第一个 heartbeat，之后按 bootstrap 返回的间隔发送。每个 heartbeat 声明 `supported_agent_kinds`、其可用性和[能力](#capability-declarations)。第一个 heartbeat 之前能力未知；heartbeat 中缺失的 kind 视为未声明。两者都不允许推断。
+- Heartbeat 仅证明存活，不证明执行进度，也不充当此前消息的回执。
每条物理连接拥有新的路由、admission handle 和传输状态。同一设备的新连接替代旧连接：Core 隔离 owner lease，移除旧 Run 路由，新连接不继承这些状态。有效凭据和连接不授权选择其他 Session 或 Environment 绑定。
+## 版本 {#versioning}
+
+wire 版本为 [`proto.Version`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/version.go)，独立于 heartbeat 报告的 Runtime 构建版本。Core 仅接受精确匹配，包括 patch 部分。不匹配时，在任何 dispatch 前返回 HTTP 426 `incompatible_version`；daemon 将其视为永久错误并停止重连。应一起部署版本匹配的两端；payload 或其语义的任何变更都会改变 `proto.Version`。
+
## 能力声明 {#capability-declarations}
[`inbound.go`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/inbound.go) 中的 `AgentKindCapabilities` 描述一个 Runtime 与 Harness 组合，独立于 `available` 和 Core 的 engine profile。每个字段都是 `CapabilitySupport`：支持或不支持。零值表示未指定且无效，即使 Harness 不可用也如此。注册在修改 registry 前验证完整声明；不存在隐含的基础 descriptor。
@@ -32,7 +61,7 @@ wire 上每个字段都是 JSON boolean，所有字段都必须出现，包括 `
每个已准入的 Executor 和 Turn 保留准入时的声明。后续 heartbeat 不能给已有 owner 增加操作。可选操作在任何原生调用前检查此快照；存在 Go interface 不代表支持。已声明操作返回 `agent.ErrUnsupportedOperation` 属于契约违规，与不可用、原生调用失败或不确定写入不同。不确定操作保留回执与所有权，绝不自动重放。工作区支持包括公共 Runtime 工作区实现，因此原生 adapter 不支持的 workspace 方法不会禁用该组合。
-新增字段要求每个生产声明都作出明确决定。契约测试为注册、wire 往返和持久化 boolean 投影逐一枚举字段；共享测试 fixture 单独列出字段，不为未来字段提供默认值。[Harness 接入](../../contracts/agents-api/zh/harness-onboarding.md)负责各声明的 adapter 侧规则。
+新增字段要求每个生产声明都作出明确决定。契约测试为注册、wire 往返和持久化 boolean 投影逐一枚举字段；共享测试 fixture 单独列出字段，不为未来字段提供默认值。[Harness 协议](../../contracts/agents-api/zh/harness-onboarding.md#register-the-adapter)负责各声明的 adapter 侧规则。
声明描述 Runtime 能做什么。Core 仅在 Harness 的 engine profile 也通过资格验证时准入公开功能，并在设备选择及领取 Turn 前的最终检查中检查选定设备的声明：
@@ -58,23 +87,6 @@ wire 上每个字段都是 JSON boolean，所有字段都必须出现，包括 `
Core 对 `usage` 和 `resume` 没有准入规则。
-`execution_prepare` 的配置携带 Core 为各 Run 设置的显式启用项：
-
-| 字段 | Core 设置方式 |
-| --- | --- |
-| `agent_options` | 始终设置 Agent 的 `model` 和 `system_prompt`；Session 冻结了模型提供商时设置 `model_provider`；Agent 设置 `x_agents_core.harness_config` 时设置 `harness_config`。Core 不发送其他键；Runtime 在准备之前以 `unsupported_configuration` 拒绝任何其他键 |
-| `execution_controls` | 始终设置：web search 为 `disabled`、解析后的 text verbosity（默认 `medium`）、明确禁用 programmatic tool calling，以及任何 `json_schema` 输出格式。原生选项名称由 adapter 负责 |
-| `observe_messages` | Runtime 声明 `message_items` 时设置。文本 delta 随后携带原生 item ID，`output_message` frame 报告消息开始、完成、phase 和完成文本 |
-| `observe_subagent_identities`, `disable_subagents` | 根据 Agent 的 `multi_agent.enabled` 设置 |
-| `disable_execution_environment` | Environment 类型为 `none` 时设置 |
-| `local_environment` | 为 `openai_hosted` 和 `self_hosted` 设置，包含精确的 Environment 绑定。请求不携带 working directory；Runtime 按自身绑定检查 `workspace_directory` |
-| `require_existing_native_session` | 需要恢复原生 Session 时设置 |
-| `prompt_steer` 上的 `durable_receipt` | Core 交付的每个活动输入都设置 |
-
-执行配置必须且只能包含 `local_environment` 和 `disable_execution_environment` 之一；两者都缺失或同时存在时，`execution_prepare` 以 `unsupported_configuration` 拒绝。
-
-未携带显式启用项的请求保留未启用时的 frame 和字段。只要 adapter 映射了原生工具，`tool_call` frame 就携带与 engine 无关的 `observation`。
-
## Envelope 与身份 {#envelope-and-identity}
每个数据 frame 都是一个 JSON [`Envelope`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/internal/agentdaemon/proto/envelope.go)：`type`、随类型变化的 `id`、类型化 `payload` 和可选 W3C `trace`。trace 仅用于诊断关联；trace 数据缺失或无效时创建本地 trace，不改变所有权。不要将 trace ID 用作 request ID。
@@ -112,38 +124,135 @@ Usage frame 和最终 usage snapshot 都携带当前执行的累计测量，替
## 准备与执行顺序 {#preparation-and-execution-order}
-无论托管还是用户自有环境，每条连接都通过 `runtime_prepare` 初始化 Environment；[Environment 契约](../../contracts/agents-api/zh/environments.md#runtime-capability-preparation)负责准备内容和时机。传输文件或 archive 时，发送 `begin`，等待 `ready`，发送有序 chunk 并等待每个匹配的 `received` offset，再发送 `commit` 并等待 `completed`。初始化和终结阶段使用不含文件数据的类型化 header。每个 `begin` 必须携带 `budget_ms`，取值为 1 至 1800000 的整数，表示 Core 所拥有的初始化预算剩余毫秒数；chunk 和 commit 不携带该字段。Runtime 从收到 `begin` 起执行此相对预算，Core 的等待不超过原操作期限。完整的 `begin`–`commit` 暂存阶段另有两分钟限制；应用已提交操作及等待 `completed` 使用剩余初始化预算，不受暂存期限限制。应用前到期会拒绝传输；应用中到期则在本地变更停止后报告 `unknown`，绝不授权重放。使用共享 validator 验证预期结果、offset、size 和有限错误 code。每条连接允许一个 transfer。chunk 回执确认暂存字节，不确认安装；完成的 commit 确认该操作，不证明后续 Turn 已运行。
+无论托管还是用户自有环境，每条连接都通过 `runtime_prepare` 初始化 Environment；[Environment 契约](../../contracts/agents-api/zh/environments.md#runtime-capability-preparation)负责准备内容和时机。文件或 archive 通过一次 transfer 传输，流程如下。
+
+```mermaid
+sequenceDiagram
+ participant C as Core
+ participant R as Runtime
+ C->>R: runtime_prepare begin (budget_ms)
+ R-->>C: runtime_prepare_result ready
+ loop each chunk
+ C->>R: runtime_prepare chunk (offset)
+ R-->>C: runtime_prepare_result received (offset)
+ end
+ C->>R: runtime_prepare commit
+ R-->>C: runtime_prepare_result completed
+```
+
+初始化和终结阶段使用不含文件数据的类型化 header。每个 `begin` 携带 `budget_ms`，表示 Core 所拥有的初始化预算剩余毫秒数；chunk 和 commit 不携带该字段。Runtime 从收到 `begin` 起执行此相对预算，Core 的等待不超过原操作期限。`begin`–`commit` 暂存阶段另有独立限制；应用已提交操作及等待 `completed` 使用剩余初始化预算，不受暂存限制约束。应用前到期会拒绝传输；应用中到期则在本地变更停止后报告 `unknown`，绝不授权重放。使用共享 validator 验证预期结果、offset、size 和有限错误 code。每条连接允许一个 transfer。chunk 回执确认暂存字节，不确认安装；完成的 commit 确认该操作，不证明后续 Turn 已运行。
+
+执行 Turn 流程如下。Core 在发送 `execution_prepare` 之前订阅 preparation status，在发送 `execution_start` 之前订阅 Run，因为输出可能与 status 竞争。
+
+```mermaid
+sequenceDiagram
+ participant C as Core
+ participant R as Runtime
+ participant H as Harness adapter
+ Note over C: Subscribe to preparation status
+ C->>R: execution_prepare (Session configuration, no Run input)
+ alt new Executor
+ R-->>C: preparation_status preparing
+ R->>H: ExecutorFactory
+ R-->>C: preparation_status ready (Executor ID, handle, revision, expiry)
+ else reused healthy Executor
+ R-->>C: preparation_status ready
+ end
+ alt abandon before start
+ C->>R: execution_release
+ R-->>C: preparation_status released
+ else start
+ Note over C: Subscribe to the Run
+ C->>R: execution_start (Executor ID, handle, Run ID, input)
+ R-->>C: preparation_status starting
+ R->>H: StartTurn
+ R-->>C: preparation_status started
+ loop until a native terminal outcome
+ R-->>C: delta, tool_call, usage, error
+ end
+ alt Run ends
+ R-->>C: done
+ else cancel during the Run
+ C->>R: prompt_cancel
+ R-->>C: interaction_decision_ack
+ end
+ end
+```
+
+- `preparing` 表示 Runtime 拥有 preparation。`ready` 提供 Executor ID、admission handle、revision 和 expiry。两者都不提交用户输入。
+- 有效的 `execution_start` 将预约转移一次。`started` 确认转移给 Turn，不确认完成。
+- 消费 Run 事件，直到原生终结结果或观测丢失。执行 error 后跟随 `done`，关闭流；之前的 error 仍属于结果的一部分。
+- start 前放弃时发送 `execution_release`。所有权转给 Run 后使用 `prompt_cancel`；释放旧 handle 不能取消后继 Turn。
+
+preparation 预约每个 Turn 的准入，而不是新 Executor。它携带明确 Session 身份和不可变配置，不包含模型输入或 Run ID。新请求返回连接本地 handle 与所属 Executor ID；复用健康 Executor 时直接返回 `ready`，无需原生 preparation。每个 handle 的 revision 决定 status 观测顺序：忽略旧的或重复的 revision，不将 status 应用于其他 handle。admission 按下列状态转移。`rejected` 控制操作携带 `operation` 和 error code，不替代 handle 的当前 revision。释放 admission 仅放弃该 admission；不关闭 Session 的空闲 Executor，也不取消后续 Turn。
+
+```mermaid
+stateDiagram-v2
+ direction LR
+ [*] --> preparing: execution_prepare
+ [*] --> ready: reused Executor
+ preparing --> ready
+ ready --> starting: execution_start
+ starting --> started
+ starting --> failed
+ preparing --> released: execution_release
+ ready --> released: execution_release
+ preparing --> expired
+ ready --> expired
+ preparing --> failed
+ ready --> failed
+```
+
+preparation 和 start 在 receive loop 与 router lock 之外运行。admission 在固定截止时间到期，重试不延长该时间；到期不解除 Runtime 完成清理结算的义务。Runtime 分别限制活动 preparation、execution 和保留的空闲资源，关闭中或不确定资源持续计入限制，直到清理成功。明确的 `execution_prepare` 拒绝若为 `preparation_capacity`，会让排队 Turn 保持未领取，供 Worker 重试，包括清理占用容量的情况；其他错误或不确定交付都不授权重放。Runtime 保留有限数量的 admission 记录，旧 handle 不会消耗替代项的 admission。这些记录仅属于连接，不是持久化输入重放。
-执行 Turn 分为五步：
+Executor 空闲到期属于 Runtime 资源策略，与 Core 的活动 Turn 并发限制独立。关闭时 Runtime 关闭活动和空闲 Executor，保留关闭失败的目标，并允许稍后串行重试。普通断连会关闭失败的 transport 并保留原 router，直到 shutdown 成功；等待超时或清理失败不授权重连，进程 shutdown 继续等待，不丢弃自己拥有的原生资源。对于 Runtime 初始化，shutdown 会等待同步 apply 操作和回执发送结束后才释放连接；`unknown` 结果仍是不确定结果，并阻止该 Router 上的后续准备，但本地变更停止后不再阻止重连。Core 保留失败的初始化状态，绝不重放初始化。工作区操作在跨 Turn 和 Executor 关闭后仍保留绑定与结算规则。
-1. 订阅 preparation status，再发送 `execution_prepare`，携带不可变 Session 配置，不包含 Run 输入。
-2. `preparing` 表示 Runtime 拥有 preparation。`ready` 提供 Executor ID、admission handle、revision 和 expiry。两者都不提交用户输入。
-3. 订阅 Run，再发送 `execution_start`，携带该 Executor ID、handle、Run ID 和有序输入。有效 start 将预约转移一次。`started` 确认转移给 Turn，不确认完成；输出可能与 status 竞争，因此必须事先有 subscriber。
-4. 消费 Run 事件，直到原生终结结果或观测丢失。执行 error 后跟随 `done`，关闭流；之前的 error 仍属于结果的一部分。
-5. start 前放弃时发送 `execution_release`。所有权转给 Run 后使用 `prompt_cancel`；释放旧 handle 不能取消后继 Turn。
+挂起先关闭准入、排空已接纳工作与回执，同时保留已结算的空闲 Executor，随后才确认 `environment_quiesced`。活动、准备中、失效或其他未结算的所有者会阻止挂起。整个挂起期间停止空闲到期计时并隔离其回调；精确匹配且已认证的 `environment_resume` 为同一批所有者恢复一个新的空闲计时间隔。只有这种计划性重连跨 socket 保留 Router 与原生所有者；普通断连、shutdown 和连接生命周期取消仍要求确认清理完成。排空失败后，准入保持关闭直到 shutdown。恢复后的准备仍检查相同的原生身份与不可变配置，包括凭据冲突；绝不静默替换配置冲突的驻留 Executor。沙箱提供商仍负责其 checkpoint 实现的文件系统刷新和计算停止保证；Runtime 静止本身既不证明这些保证，也不证明原生 RAM 或外部网络连接已恢复。
-preparation 预约每个 Turn 的准入，而不是新 Executor。它携带明确 Session 身份和不可变配置，不包含模型输入或 Run ID。新请求返回连接本地 handle 与所属 Executor ID；复用健康 Executor 时直接返回 `ready`，无需原生 preparation。每个 handle 的 revision 决定 status 观测顺序：忽略旧的或重复的 revision，不将 status 应用于其他 handle。典型状态转移为 `preparing → ready → starting → started`，或由 `released`、`expired`、`failed` 终止。`rejected` 控制操作携带 `operation` 和 error code，不替代 handle 的当前 revision。释放 admission 仅放弃该 admission；不关闭 Session 的空闲 Executor，也不取消后续 Turn。
+### 执行配置 {#execution-configuration}
-preparation 和 start 在 receive loop 与 router lock 之外运行。admission 在授予五分钟后到期，重试不延长截止时间；到期不解除 Runtime 完成清理结算的义务。Runtime 分别限制活动 preparation、execution 和保留的空闲资源，关闭中或不确定资源持续计入限制，直到清理成功。明确的 `execution_prepare` 拒绝若为 `preparation_capacity`，会让排队 Turn 保持未领取，供 Worker 重试，包括清理占用容量的情况；其他错误或不确定交付都不授权重放。Runtime 最多保留 64 条 admission 记录，旧 handle 不会消耗替代项的 admission。这些记录仅属于连接，不是持久化输入重放。
+`execution_prepare` 的配置携带 Core 为各 Run 设置的显式启用项：
-Executor 空闲到期属于 Runtime 资源策略，与 Core 的活动 Turn 并发限制独立。关闭时 Runtime 关闭活动和空闲 Executor，保留关闭失败的目标，并允许稍后串行重试。普通断连会关闭失败的 transport 并保留原 router，直到 shutdown 成功；等待超时或清理失败不授权重连，进程 shutdown 继续等待，不丢弃自己拥有的原生资源。对于 Runtime 初始化，shutdown 会等待同步 apply 操作和回执发送结束后才释放连接；`unknown` 结果仍是不确定结果，并阻止该 Router 上的后续准备，但本地变更停止后不再阻止重连。Core 保留失败的初始化状态，绝不重放初始化。工作区操作在跨 Turn 和 Executor 关闭后仍保留绑定与结算规则。
+| 字段 | Core 设置方式 |
+| --- | --- |
+| `agent_options` | 始终设置 Agent 的 `model` 和 `system_prompt`；Session 冻结了模型提供商时设置 `model_provider`；Agent 设置 `x_agents_core.harness_config` 时设置 `harness_config`。Core 不发送其他键；Runtime 在准备之前以 `unsupported_configuration` 拒绝任何其他键 |
+| `execution_controls` | 始终设置：web search 为 `disabled`、解析后的 text verbosity（默认 `medium`）、明确禁用 programmatic tool calling，以及任何 `json_schema` 输出格式。原生选项名称由 adapter 负责 |
+| `observe_messages` | Runtime 声明 `message_items` 时设置。文本 delta 随后携带原生 item ID，`output_message` frame 报告消息开始、完成、phase 和完成文本 |
+| `observe_subagent_identities`, `disable_subagents` | 根据 Agent 的 `multi_agent.enabled` 设置 |
+| `disable_execution_environment` | Environment 类型为 `none` 时设置 |
+| `local_environment` | 为 `openai_hosted` 和 `self_hosted` 设置，包含精确的 Environment 绑定。请求不携带 working directory；Runtime 按自身绑定检查 `workspace_directory` |
+| `require_existing_native_session` | 需要恢复原生 Session 时设置 |
+| `prompt_steer` 上的 `durable_receipt` | Core 交付的每个活动输入都设置 |
+执行配置必须且只能包含 `local_environment` 和 `disable_execution_environment` 之一；两者都缺失或同时存在时，`execution_prepare` 以 `unsupported_configuration` 拒绝。
-挂起先关闭准入、排空已接纳工作与回执，同时保留已结算的空闲 Executor，随后才确认 `environment_quiesced`。活动、准备中、失效或其他未结算的所有者会阻止挂起。整个挂起期间停止空闲到期计时并隔离其回调；精确匹配且已认证的 `environment_resume` 为同一批所有者恢复一个新的空闲计时间隔。只有这种计划性重连跨 socket 保留 Router 与原生所有者；普通断连、shutdown 和连接生命周期取消仍要求确认清理完成。排空失败后，准入保持关闭直到 shutdown。恢复后的准备仍检查相同的原生身份与不可变配置，包括凭据冲突；绝不静默替换配置冲突的驻留 Executor。沙箱提供商仍负责其 checkpoint 实现的文件系统刷新和计算停止保证；Runtime 静止本身既不证明这些保证，也不证明原生 RAM 或外部网络连接已恢复。
+未携带显式启用项的请求保留未启用时的 frame 和字段。只要 adapter 映射了原生工具，`tool_call` frame 就携带与 engine 无关的 `observation`。
## 活动输入回执 {#active-input-receipts}
-Core 通过 `prompt_steer` 交付活动输入，设置 `durable_receipt: true`，每个 Run 一次交付一个输入，并等待回执后再发送下一个：
-
-| 阶段 | 定时器 |
-| --- | --- |
-| 原生写入 | Runtime 将 adapter 原生写入限制为 10 秒；写入完成后停止计时 |
-| `written` 确认 | Core 从交付开始最多等待 30 秒取得 `written`；否则输入结果未知 |
-| 回执发送 | 每次发送回执都有独立的 5 秒预算，并感知 shutdown |
-| 原生接受 | `accepted` 在 Turn 生命周期内到达，不自动重新交付 |
-| Done | Runtime 在原生 Turn 结算完成、且正在处理的输入的回执发送结束后才发送 `done`；该输入受原生写入与回执发送预算限制 |
-
-`written` 和发送失败都不会推进 Core 的 input cursor。取消发出后，即使输入先变为未知，终结结果也由取消回执负责；15 秒内没有取消确认时，Core 记录 `cancel_unconfirmed`。未发出 `done` 时，取消回执携带已停止 Turn 的已确认 continuity snapshot。
+Core 通过 `prompt_steer` 交付活动输入，设置 `durable_receipt: true`，每个 Run 一次交付一个输入，并等待回执后再发送下一个。
+
+```mermaid
+sequenceDiagram
+ participant C as Core
+ participant R as Runtime
+ participant H as Harness adapter
+ C->>R: prompt_steer (durable_receipt)
+ Note over C,R: written wait limit, from delivery
+ R->>H: SteerWithReceipt
+ Note over R,H: native write limit
+ H-->>R: write complete
+ Note over R,C: receipt send limit
+ R-->>C: prompt_steer_ack written
+ H-->>R: native application receipt
+ Note over R,C: receipt send limit
+ R-->>C: prompt_steer_ack accepted
+ R-->>C: done after Turn settlement
+```
+
+`accepted` 在 Turn 生命周期内到达，不自动重新交付。Runtime 在原生 Turn 结算完成、且正在处理的输入的回执发送结束后才发送 `done`；该输入受原生写入与回执发送限制约束。限制数值见[超时与限制](#timeouts-and-limits)。
+
+`written` 和发送失败都不会推进 Core 的 input cursor。取消发出后，即使输入先变为未知，终结结果也由取消回执负责；取消确认限制到期仍无确认时，Core 记录 `cancel_unconfirmed`。未发出 `done` 时，取消回执携带已停止 Turn 的已确认 continuity snapshot。
## 每类确认所证明的事实 {#what-each-acknowledgement-proves}
@@ -191,18 +300,42 @@ Core 在 Turn outcome 中将接受的值保存为 `engine_error_code` 和 `engin
无需运行 Turn 的工作区读取使用只读 preparation profile：带 `workspace_read_only` 的 `execution_prepare`，要求 `workspace_read_preparation` 能力。仅接受绑定的 Environment 和 resource 身份；不包含 execution option、model 与 MCP 凭据、原生 Session continuation、model 或 tool 输入，owner 拒绝 `execution_start`。Runtime 从绑定的本地工作区提供读取，不启动 Harness 进程。profile 在 Runtime 放弃该 preparation 的所有权后发布 `released`；旧 status snapshot 不发布成功。release 请求、HTTP 断连或远端 socket 关闭本身都不确认释放。
-`workspace_read` 在同一已认证设备连接上，针对现有 preparation handle 或它已转移给的 Run，使用精确冻结的 Environment 身份；调用方不能提供 socket、凭据或 workspace root。`operation: directory` 列出一个 workspace 相对目录（空路径选择根目录），字节与条目限制互斥。结果最多携带 1024 个单路径组件 UTF-8 名称，每个最多 255 字节，并包含 entry kind、普通文件大小和明确截断信息；仅在目录访问与 handle 清理结算后返回。此层没有快照、递归或分页。字节读取与目录读取共享目标检查、关联、容量和保留的操作等待。
+`workspace_read` 在同一已认证设备连接上，针对现有 preparation handle 或它已转移给的 Run，使用精确冻结的 Environment 身份；调用方不能提供 socket、凭据或 workspace root。`operation: directory` 列出一个 workspace 相对目录（空路径选择根目录），字节与条目限制互斥。结果携带有限数量的单路径组件 UTF-8 名称，并包含 entry kind、普通文件大小和明确截断信息；仅在目录访问与 handle 清理结算后返回。此层没有快照、递归或分页。字节读取与目录读取共享目标检查、关联、容量和保留的操作等待。
-准入前，请求 payload 限制为 8 KiB，correlation ID 限制为 128 字节；过长 ID 不回显，过大的 trace metadata 不进入回复。原始 read result 限制为 1 MiB，位于 4 MiB transport frame 内。这些是私有 transport 限制，不是公开 Files 参数。成功读取要求完整字节或明确截断，并确认原生 close。安全的原生拒绝不携带字节；中断或有歧义的读取保持未知，并停止该 owner 的后续读取。已 dispatch 的读取在 observer 取消以及资源转移或释放后仍保留有限时等待方，资源关闭阻止新准入。gateway 限制订阅，不在重连后重试或重放读取；重复的 pending operation ID 不能启动另一次读取。
+准入前，请求 payload 与 correlation ID 受限；过长 ID 不回显，过大的 trace metadata 不进入回复。原始 read result 受限于 transport frame 之内。这些是私有 transport 限制，不是公开 Files 参数。成功读取要求完整字节或明确截断，并确认原生 close。安全的原生拒绝不携带字节；中断或有歧义的读取保持未知，并停止该 owner 的后续读取。已 dispatch 的读取在 observer 取消以及资源转移或释放后仍保留有限时等待方，资源关闭阻止新准入。gateway 限制订阅，不在重连后重试或重放读取；重复的 pending operation ID 不能启动另一次读取。
Core 在 Worker 的 Session 调度预约上运行空闲目录读取，活动执行时针对精确 Run。它在有限时 read 与 release 期间保留预约，仅在确认 close 后返回数据（不完整读取或不确定清理返回 unavailable，不包含数据），在交付结果前释放预约，并在完成或失败后撤销限定作用域的读取凭据。Runtime 保留不确定清理的所有权和容量。[Environment Files 契约](../../contracts/agents-api/zh/environment-files.md)负责公开授权、路径和分页。
-`workspace_write` 在原生 writer 运行前，通过已确认的 64 KiB frame 传输完整且有界的 body，验证声明的 digest，不运行模型。私有 transfer 限制为 50 MiB，与公开 API 在任何 Runtime 工作前检查的 5 MiB decoded inline 限制独立。Runtime 在接收或应用写入时排除执行；格式错误、不完整或到期的 transfer 不会到达 installer。精确的 commit 或拒绝回执释放 mutation owner。缺失或有歧义的回执保留不确定性：observer 取消和本地进程退出不能证明没有改变任何内容。公开准入前，Core 在 Session lock 下持久预约写入，跨重启阻止后继 mutation，直到精确结算；请求不重放。各平台都使用 daemon 的 Go 实现进行有界读取、目录列举、文件创建与输出导出，不使用外部 helper 或 staging directory。
+`workspace_write` 在原生 writer 运行前，通过已确认的 frame 传输完整且有界的 body，验证声明的 digest，不运行模型。私有 transfer 限制与公开 API 在任何 Runtime 工作前检查的 decoded inline 限制相互独立。Runtime 在接收或应用写入时排除执行；格式错误、不完整或到期的 transfer 不会到达 installer。精确的 commit 或拒绝回执释放 mutation owner。缺失或有歧义的回执保留不确定性：observer 取消和本地进程退出不能证明没有改变任何内容。公开准入前，Core 在 Session lock 下持久预约写入，跨重启阻止后继 mutation，直到精确结算；请求不重放。各平台都使用 daemon 的 Go 实现进行有界读取、目录列举、文件创建与输出导出，不使用外部 helper 或 staging directory。
## MCP 连接权限 {#mcp-connection-authority}
`execution_prepare` 配置中每个公开 `MCPHTTPServer` 都携带明确的 `connection_origin`；值缺失或未知时拒绝，不选择默认值，Core 在 dispatch 前冻结公开默认值。Runtime 在选择 factory 前用公共 validator 验证 origin，并将公开和已安装 MCP 解析为临时 effective binding。[Environment 契约](../../contracts/agents-api/zh/environments.md#public-mcp-connection-origin)负责支持的组合、原生限制和故障所有权。
+## 超时与限制 {#timeouts-and-limits}
+
+本协议中的所有数值都在此处给出。Turn 生命周期中 Harness 一侧的限制见 [Harness 协议](../../contracts/agents-api/zh/harness-onboarding.md#timeouts-and-limits)。
+
+| 数值 | 适用对象 | 到期或超出时 |
+| --- | --- | --- |
+| 5 分钟 | 执行 admission，自授予起算；重试不延长 | admission 变为 `expired`。Runtime 仍须完成清理结算。 |
+| 64 条记录 | Runtime 在每条连接上保留的 admission 记录 | `execution_prepare` 被 `preparation_capacity` 拒绝，Core 让排队 Turn 保持未领取，供 Worker 重试。 |
+| 64 个 frame | Turn 的有界输出 channel | 由原生 Start 之前启动的单个消费者排空。 |
+| 10 秒 | Runtime 围绕 Turn 的结算等待 | 超时不证明已静默；资源保持被占用，直到清理得到确认。 |
+| 1 至 1,800,000 ms | `runtime_prepare` `begin` 的 `budget_ms`：Core 所拥有的初始化预算剩余量 | 应用前到期会拒绝传输；应用中到期报告 `unknown`，绝不重放。 |
+| 2 分钟 | 一次 `runtime_prepare` transfer 的 `begin`–`commit` 暂存阶段 | 传输被拒绝。 |
+| 64 KiB | `runtime_prepare` transfer 或 `workspace_write` body 的单个 chunk | 更大的 chunk 验证失败。 |
+| 50 MiB | 一次 `runtime_prepare` transfer 或 `workspace_write` body（私有限制） | 传输在到达 installer 前被拒绝。 |
+| 5 MiB | 公开写入的 decoded inline body，由 API 在任何 Runtime 工作前检查 | API 拒绝请求。 |
+| 4 MiB | 单个入站 transport frame | frame 被拒绝。 |
+| 8 KiB、128 字节 | `workspace_read` 请求 payload 与 correlation ID，在准入前检查 | 请求被拒绝；过长 ID 不回显，过大的 trace metadata 不进入回复。 |
+| 1 MiB | `workspace_read` 的原始结果，位于 transport frame 内 | 结果明确截断。 |
+| 1024 个名称，每个 255 字节 | 一次目录结果 | 结果明确截断。 |
+| 10 秒 | adapter 对活动输入的原生写入；写入完成后停止计时 | Runtime 确认 `outcome_unknown`，绝不自动重新交付该输入。 |
+| 30 秒 | Core 自交付起等待 `written` | 输入结果未知。 |
+| 5 秒 | 每次回执发送，感知 shutdown | 发送失败；发送失败不会推进 Core 的 input cursor。 |
+| 15 秒 | Core 等待取消确认 | Core 记录 `cancel_unconfirmed`。 |
+
## 契约验证 {#contract-verification}
在仓库根目录运行 `make check-runtime-contract`。它执行共享 wire validator、gateway、transport 和 dispatcher 测试、两端共享 wire scenario、[观测结果回归测试](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/execution/runtime_protocol_test.go)以及 Harness 声明测试。不需要模型凭据或外部沙箱；`make check` 通过 `check-go` 和 `check-core` 运行相同测试。
@@ -211,4 +344,4 @@ Core 在 Worker 的 Session 调度预约上运行空闲目录读取，活动执
套件覆盖不兼容版本、preparation 失败、取消结算、连接丢失而不虚构终结事件、重连而不重放、陈旧或重复 handle 与回执、清理失败、有界 transfer 验证，以及超时后的资源所有权。详细故障注入测试放在所测 gateway 和 dispatcher 代码旁。
-其他 Runtime 对接脚本化 Core 重放同一组 scenario，再对每个声明的能力运行原生验收。受控 adapter 测试证明 transport 契约，不证明原生 Harness 行为、操作系统支持、提供商认证或沙箱隔离。共享类型、本文和契约检查应一起修改。Harness adapter 还需运行 [Harness 接入](../../contracts/agents-api/zh/harness-onboarding.md)中描述的共享文本断言。
+其他 Runtime 对接脚本化 Core 重放同一组 scenario，再对每个声明的能力运行原生验收。受控 adapter 测试证明 transport 契约，不证明原生 Harness 行为、操作系统支持、提供商认证或沙箱隔离。共享类型、本文和契约检查应一起修改。Harness adapter 还需运行 [Harness 协议](../../contracts/agents-api/zh/harness-onboarding.md#qualify-the-adapter)中描述的共享文本断言。
From 86931f933741f05f960b4818415b28955dabb661 Mon Sep 17 00:00:00 2001
From: SaladDay <1203511142@qq.com>
Date: Fri, 16 Oct 2026 21:13:42 +0800
Subject: [PATCH 07/74] Retake the console screenshots (#747)
---
apps/web/public/onboarding/monitor-en.webp | Bin 43958 -> 35660 bytes
apps/web/public/onboarding/monitor-zh.webp | Bin 40016 -> 33258 bytes
apps/web/public/onboarding/platform-en.webp | Bin 44328 -> 37354 bytes
apps/web/public/onboarding/platform-zh.webp | Bin 41966 -> 36570 bytes
apps/web/public/onboarding/resources-en.webp | Bin 57274 -> 47958 bytes
apps/web/public/onboarding/resources-zh.webp | Bin 55806 -> 47322 bytes
docs/assets/console-add-node-en.webp | Bin 0 -> 78978 bytes
docs/assets/console-add-node-zh.webp | Bin 0 -> 76104 bytes
docs/assets/console-agent-metrics-en.webp | Bin 252836 -> 111690 bytes
docs/assets/console-agent-metrics-zh.webp | Bin 246034 -> 109718 bytes
docs/assets/console-connect-host-en.webp | Bin 0 -> 108252 bytes
docs/assets/console-connect-host-zh.webp | Bin 0 -> 99452 bytes
docs/assets/console-default-model-en.webp | Bin 0 -> 70698 bytes
docs/assets/console-default-model-zh.webp | Bin 0 -> 65414 bytes
docs/assets/console-getting-started-en.webp | Bin 0 -> 124692 bytes
docs/assets/console-getting-started-zh.webp | Bin 0 -> 114234 bytes
docs/assets/console-issue-key-en.webp | Bin 0 -> 118592 bytes
docs/assets/console-issue-key-zh.webp | Bin 0 -> 113722 bytes
docs/assets/console-node-ready-en.webp | Bin 0 -> 50602 bytes
docs/assets/console-node-ready-zh.webp | Bin 0 -> 47042 bytes
docs/assets/console-overview-en.webp | Bin 171520 -> 109488 bytes
docs/assets/console-overview-zh.webp | Bin 152376 -> 98702 bytes
docs/assets/console-request-log-en.webp | Bin 0 -> 87776 bytes
docs/assets/console-request-log-zh.webp | Bin 0 -> 85344 bytes
docs/assets/console-session-log-en.webp | Bin 0 -> 109278 bytes
docs/assets/console-session-log-zh.webp | Bin 0 -> 105318 bytes
26 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 docs/assets/console-add-node-en.webp
create mode 100644 docs/assets/console-add-node-zh.webp
create mode 100644 docs/assets/console-connect-host-en.webp
create mode 100644 docs/assets/console-connect-host-zh.webp
create mode 100644 docs/assets/console-default-model-en.webp
create mode 100644 docs/assets/console-default-model-zh.webp
create mode 100644 docs/assets/console-getting-started-en.webp
create mode 100644 docs/assets/console-getting-started-zh.webp
create mode 100644 docs/assets/console-issue-key-en.webp
create mode 100644 docs/assets/console-issue-key-zh.webp
create mode 100644 docs/assets/console-node-ready-en.webp
create mode 100644 docs/assets/console-node-ready-zh.webp
create mode 100644 docs/assets/console-request-log-en.webp
create mode 100644 docs/assets/console-request-log-zh.webp
create mode 100644 docs/assets/console-session-log-en.webp
create mode 100644 docs/assets/console-session-log-zh.webp
diff --git a/apps/web/public/onboarding/monitor-en.webp b/apps/web/public/onboarding/monitor-en.webp
index 70aab640be883b11fc895540d9284bd8325c4ee5..61873b45a935069be93505ba90637074880489e5 100644
GIT binary patch
literal 35660
zcmZs=V|XU*(k>k9j%`~L+mlReXJSum+vY?Q+qP}nwr$*dp0)Oi_3iIh_tAZHb#+x;
zC$3hK{P9CH5(GqDOhiFVfs2^y?>Un^SSBcK4a60gfB{pI1UYFQS#E7wjvqYiFPr!4
zq{~P{Up4-eZ)%exDJWI1GYHxo-H)5s_1T3${!iPd;&&ps6md88{bv-$*Td--qE%qi
z2RzW|^LVZLX?g|8uKS8;45<3~_D1)We}eYv`t)rn76^p)ed;#re0~G*l>@4tLju*;
z(w~)Ad|!z^V`Y3zx;JB`qqXGWf%0F|Z_l4b2gL(Gwy);Tlqb6P;jd~9UzAtDOTG2(
zZeaS?@w@Y5@7?e{aLtSFb@_^DzkAl#5Lo^Wyc4{&t@QQzn*5^rLVE7rLJITk2I_t8
ze662U9|B8!)4%%PBR}^Kux^0|f?L2!U^uY$b9ygw6WHe)3FQ2`e+G{3a{&>)(m%zo
zIeW0m1=)b#KChoGKg_P0N5r#${$HD4Mt?&Cfk09phEKeYl;`U$qFX&65JWH*$OB~l
z?0!~%zXk$di41&=fvunSqpTN1`@l_L!ND83tzcKtKFkA8ju?f%Zx?gB_ws>6TM(zXH;NA
zTu|`E!nET`l9OO<-1LSMlQuuU4zwI$nX%fEOG0vucN`!q;*HmrV_z3bIR5`c_@BUp
ze7Ey7fYtb_qpA6xPI>JVCd(+1M=F86&r=QI2Mp85}Kk)udqvJPVux_Gf>t$9O
z!6(nmhAO~C(Q*}60ZW)$1(sYPQwD;yWb~!A)Eai{sGH2s@tT<(p`R4VxEP^(;8RWy
z?6$Y0rXs@l0hxqShca?G0)Gb*lV9adx>sDPO5YNb70sx?dpGMOBMH?i{KU1}L{NB`
zyr-rIX7gxAq;N&#yOrF($|s~Ob45kEjZ#uEzJ!`pj+wP+3F8Eq_Zb9rAmrv9(wnyK
z0sl5RyyKCT#bYn9$f=!};}7$luNClPo(7WnjDIvFz~VjW9r46*>(v377h;D#Q(j{Vd^j(<
z_=vyllj)cI=`pwBbfmx?0wJ_!rp_Y}1C)|8XozT|3BYG(;0SWD_}CeL?2NwlCf)~9
z9Ye`a{k@E>Vy>v(sfj7Q(};HSEwq4)gBD|4=qJ|#-GT9sMZHwXLKV4zUbMYIY3Gr5
zt-OZy%L++uN8c2Mg2TVv!)fh@G>hTP
z;tjEma2vf=W-Yw$GOw_&j&nU?ioYDecT5+ZB85vLE51$NEV(@@RRX^GR6o>cK%TBQ
zZ9jb(2aojE5R6;!j>5sdFtWx_Vz(bvX^(0FzQD84ha~QN8#muwtB?l
z2kR#47ih$AF*ZmlBEzIYjb;s`rjc(z1LO1=x9`@B{<{p;e~AB+z*~l`uG5g!n5K_#a
z%Y(YkbO${K2>DZ03)$>K9?joI|8|~d{d8b)_terfC=u;13?RFKiK*0VhXjd;!=S`2
zAk(Rdvn78>R41E-NwiA;?DtB1miYdS@D1<~)PM^C&!H~bRyU+yi+n^m65WM{qNTZG
zzMBoDWx$@H^wvCQC;8eR(p*H63iw9;)OFDB(T0Nf7i1px*R;I6J`sn69GjlIlbN(X
zFDw1#!Np~Ip0N>G`&fxLuT{(8l-q9MV=5K``~2+b)EP#D?1qRONj)&p;6$EAHch`M
zmljhP;{G(t{xaka{7@z*f&iR+QA3j82*RMou}nB2WX7fMvS`EcbMvHA1ap>P8RQcv
zB4pgpV0&#yKv;z0#b?s?y)Dp6c?uC><*sWbB~ud4BD%6ow!Ohf78Dt8#+WuYq~qTM
zO7I&+(LG|ewdU9yF+JqEd9rYBQp7Dc@aLDWyPkXuN=dSv@EV+mS+AYshV!QWH<LDLBmbG!K$gZE$j#Tg@jo3F~9S)
zS$h^imnM9g(+oz_X)#&Kfkq%61W+Z2O-7F$_i1O)=C;dA%+DJdU>wSxbQONbSWqUx@y
zq)O|90%@Qw!@264dM3XA7gmOq1pfsq@h_$6tcjnKW!?XUE!nqkVt|HtgWtB&z*F9P
zq67^^`}+uJL$-jJ_Q6X}rV-53_`x^BWU~F0>|_BU<^Bb_|KyzhpRFmNwmWk=VBcR~
z{+Ut#yJmfhpTS9u-Xzu#X_spMAm6D+lTP5+`EMOIvAzQ&#GmJ9053od;_pneFkxC=6dy&Hk0Mu(Wv|J*kP(PHnNrUCeeB=Ctbx}^6sgW2|CiyM;v-26
zC$rh4g1+9q;qXvT&|{_JDDet-n*gNm2H8jFMh@{ROQI)wJxIb#xUumNv|vHRcJ{#Z
z2$SutUr{TQ+|7Tt*Md&V&f%7TBSNU_;hXyNdUH2XTl!W!M5e8xFZH4Ri)Qzz-XaNQ
zBp)E6EMW!8fBNr;F_BWfjeY~ML2stb`0io^q>H(wD>>`7n;TRLpD^RC8^X?CUy)J%
zA0+-wVvBSO^bb~jjY(zUyvTAuru-MhxJ%RVmI&AFM8Hv$PbN8(>m2z@xWN8z2!HCI
zgpN(@lGfw(voPsghYM{T{Wr-|TXcLwnKgr{e<_Lkr@R5_L!YJ`1OFoe`1$QL1_F#f
zF7_yfPuQQCYZil&P~*}6vKtBQdr}FgxSAo;@|9Hl4sI^jZI&?
zl!yUW0h2tauk7U|3#zA_%67Z!t?FY`;+QNoH;ccJU3hg=5SJEl19~ACwn<|_?Q;v8
zgc28>|bt_~*n*~)GkloO7Np{<9@?}&?6#f3~o#*LOtT;UxWGxF@1oV)|>b=X!?bWGWc-eCbYGTvh)v`o`_S
ztlml?|N0lnPTt$Jskf7mfK-vQ{(+^N*AyUi6_D@Updq-ZOizaYH<&$OXH*d*1H($YhWK
z{*`uB1fK0Z3uWagY*^0POyjSHY5nPyn_7@8;Xc!yJvBkWjk16KB}j$K140y4h!)9?
zc;a8SgFQqI;1>*?jbXFe+t(WCK~|0GDnP%2a#uA2$hUb3Dc1VZV_o@3$#65bG5UuR@ecfcb@Ap0Oj-QvC(H(K|DTtP5j=
zMeR-AnP1zzD1B$?5KU8=iueuD30q1h?09RB4$&0c4e~_WT2faWF84{_<+60-!T`Bg`4jgiEIm|jHrHnu-k|7TXHh |NrDzs-|4|Vho2kilxzHXTOw4nbcDD+*PeKN*#XVQk_zoMI$OCD&@zh!EFQ;8HS0!>iw^E
z*?JFO3~^^U*g_>~Ik~6@%&j%I=B%rKitACK2KCw-eqz=ev>lcT@7JRJ-d+1
zpK^e3*Ra~85Bq6*KJz=pk1}+$grW7{(}1*zZ>1znRDZ{tqFKNhTDx!iIpOglOd4NA
z8~?P&zq>n}+iKD3^ps~{>gBQJS5Y+^;#A-dQdYj{)^LERe21mxnOY>sX)sbG7_%cm
zZ$<`{3=^OHK}?aI*yAYDB3Qh#(nf{4!QgQBzCCLRTKw0+96iZOCbtOExVgO!Q|%9;
z9mSrj6NZ`#5ZL%X_6W5Tb+_n+bIqQKc`0sEb3<|7zvz{MW5}<3w)UN!^)sJ?SJM>*
zi{e>Zb5yqv#dBe~XFAK4kmJ_>k&FL!jnei1ZBj5ozFQUgq&_wGBaoXRFEsxrihtOy
zs$5CL2HLIkFjh}E|JO~8@5I_Wj3M46_DJvCFte{ki5}p=Vz#^|;Hlt8duhEb-iCj{
z{eO(ffBF?`(<XyTOT6S@8$JA)(0X-auy(|&$x&Y2XP7VI0&
zt-eQ}Z2KW#N%vv$XM7f@B~{V4P=)%B)@FmKoJ-ni1=mux3};_!A`?0R?TrrY`J^+S
z(D^g%_>VpM&n*6mb~*^}GpEoy2}t(C6W$zJM6^-&alBn9G^QJ5{}F_0Pn9@LQLZVbwL5OsdU
z*1F^R+F(w}rN-)P^4yrxwR~aN#80q>k>@a_8SMzips9yJ((IsT_pDUIe2_iJEy9j
z+_Ta4=Ad;;7K{rbGHi>$;K#Qw#K`lIA8VgIGP7v}IAeD<>RcJ)OdZy*7G%?p80u&3
z%1Ga2l-HyW7rU?C@}UkTvx;vvTX}v)Du{U#Z!pj!ZfQDfGimK4u2u?Zxbp!To%*|O
z3^Gu_8%HK3Rx^)lJbAJBMjXPn_m&*At94#kiyZ(n3S%i2tQPRG;+6#WA}DTGRvEy~
z6?34~juZOWncLl3&5VxGIk+b#gFCL?q2=>KVT>g7z(o
zxl(y*sC=OR(sh|t5A03+3Xqj0aryowC%di6#;E%pyo_!3vNupAZz4TE
zGhx(@_uY;e1uBbN)8yTwH>7**iiy=Yyw9SlLc2fm5zgSL5bK2HO4D}=^>5kRcGb~j
zFpoyS@8gQ*C7e24RBdO9;-OKf9h)GzMd`e?H;Y-=!QoP#z@x|`r+p7j%cgTmI`6??nNDGHc>wiipXst
z<8}7=*}Ttpk}eMwo2E#FkKuizw5J|AK69;K%BE*=i@&JdR|?_4pafId$D=2?MH4~!
z8eVa02i(L=P3wZ-B1p_8KE0r
z2W86ztv+JWNq(w!OJb14V{_3bG9}0^F~dLF<+GgU>MtJPl*EvAf6iXGtbdIP;yo}}
zdj~TL-_(t0yB}urU0T~1b}=gh=DXt{bZphF#KJ;82HYf))~Z+grz1)b289!3);##c
z<9R^4dizXksQs2GL!}DDM;mDTPG1Li5G}u`!N5_JHzcA3s@puY4=yM;d7Prf0cM$FzMnGw
ziNl7~7c=unWp~wrCa?m6mUEi~wme+=TnRH3O-7eZVB-1Yaw@d)Jj3(gRZJa7wMc57%WaY!fIKb;cE({!aVwU
z)2=W}_cPOtiq|`CV99rmT1mkbR(BN@*?bx$@meGr7Rh02N-b?7Lf(L>o&s7dh%3zu
z;t;z>i_Vd1l2^JR8Jg0X>a;=U70!1yT;)p7_0dW>DdFB{5_I%}E$N$w{}fC;GR
zcnvok?fLw|b1M}5k|Mc_h$y@LeaDo_XBi82`vn<
z1+O}K?4m)iHVKb1jaV#=zQ;pKGvfz*ScVcloj)2WXrWsTJ;uzj#Pm-=(UzsehEDc;nn(2-T+BY!dS6VuLQ^sp9qOFur#uaz*SNQ$8+GB8-fK0~{#61zT68
zb9~=dwfE9M4^+^$HFIbU3)2Q>FnQZ(vYX@6-lL0&PBdwi2s2hAm3m73oGxL=KVsI!6E;ZO5yJ@4rE3f7
zZ8Wv2#D?UDg6r9Yxx}8bV(ZP~%yy6#beJ*aYBPE)*nt2fKw!KW`Bzlu|7cmHvoV8G
zF~-lO!OKoYi0V8%5uGMQ^z(F=sC6i^=%lOw_z5R9T0C7Tl;j4XO3qnEGxu7Dn^KY)
zS01M>bGxFS%M)sDvC{RZ(@4=YAxeqDcT9+4f0$Ax8apn@MxBZwI9~gNtIq`)d~ZU%
z4j@EkZ|jFO)C8NF2#}wPk4hZ}Nje=V2X`fPJ2QR4Uq20w!P$
z1!}>C7fQNj`_W>RT~dZuS)H2)<8#cEs|t2A9)UBxfH&IzWKU`$Qw$g4+F1FZdE{7U
z{XO>6rQ8vWTzJq^LeP=(dlSb|;KE%CXZ=8?k-zG~xann<-yo2RwlF|Rwmme%R@^vN
zM%B3FJ1C4%S*FSg9nGr-W|M;9Mv%!jv6VrOidx)@cx11sB7>sexRhEML*FF2)yBk+fOzeoK#!<<_YDE`xWpyE|
zvXu(6cm~$vjF@>9e7sFx+`Nj@9bYvsaJ>w!$povy95;P(+|^vXytVci?+UpF<>6XiJNZndrwIiXVOm
zVMkBeZ(}>B0)37^&4C*Vwm$4I=3$EeEs2wVt6!}FS8PF#Hb$ctxd`#JD3~Btfown+
zjqW7A7llKrCjl=~>>dS3ZO0;eS*2haxuw-tS_W72;mqUsMZOCF+z6o*wRX}$8C~=b
z%M^+pd~b+u^y`ir1Nk*k$y)qghXsc}}>p*qa9+Xsk
z{5hBeDKm;^XD$Ie1LM_f&|KvJ*8)aLs~2>PxHzTojcY0L+m0EXw`tthA$vq+hNp8ugFHf%#IU!1OEY&~W?-RiFtZ
z$d5$f?SR+@9v*ToJ3b9lu?yt3=)4w&EA_^?fK-Pr`p(?ta-Ne`pm3I(eQ;hjsguvPu-PI81d~_&dB@~qEp3rG`sVnjE4d4Z%Z7dWt1ITHjfHP3
z56M(dPD=2lgu_{Ksv1d*Cq4OrksP+t6%%4mgQiWA}`4vNqS{{wXX(9s*JLySeD<
z-zh~0ulYML)N
zbe%yYZ_QCg>TC-s$_`7hd_SMMrUen8vFlT>(m$lLk2G@Ja*?T>4BexmkKs@zx`~S~
z>Nnk^SP1H%X4=wObwv*doZHuLPY+NDaK{swQ#%6+ldBB`YjW+DJKrk(t*sznN1J&)
zsp3I<;(bL6{(OcDSyd9EWu@m!QeO)?V~={-4ZIo(lzCHbu7k+nKj>%ql%+h@=AJAo
z+0MMyOyWrD4_FFOvoOv<<_mqCl_Q+LZ=Ypuze+#{TvBtWLi$_>Eh(qw_3Do7SCKU-
zeN#Xt_@TKl20v$|m__8pYsvpE{_;9(o;Z&lAOczu>M}S-Y@1ThMNrtV=6&1*0|h6<
zw!@8Z`SClwHHN;<4Kk8|(0I(ar`(G6yS!qR~c?=}T&%c#4
zo;tK@{HfI*dd`xwV#`e)rZ~1i(jS8i4JE*w;4*OGfcuIQ96QvHR4hMFdjp$+G>SE~
z@$7h${%sSkVI+Ti`UJvXC<+=x0=NpXgx3k7-MNH#16?7&HnjHPuD*G=+6h#!#OCXYif{e=w9R`;l!;*_M?>T7nY;cV53seNmf_
zN*u(C7TTBn1Id+@AH3*q!s*SZa!Cq#v7NUCa3*^*uIPx(zv4wcv0m7^!?zGCg!mNLc$t+^8fc
zf`RMNTYxDV?MHCeVki;;8)v+2&wy?tYu*f4uNX$aWFsxmeaKECfnQq
z&c%A{(_c}BE2psb++yrK*dQ0<5o*BTA)1}n(A`QP2lSP2K`rC0QI)OU!0rQ`bvDgG
zUih+%n-YN45C#88aGitS3OpgC^4|XPEO#(=c!R$o+aJLqfR$v99L!ho?zkIyKb{5QG+F2Aa-(bZ1J=Q>x+&&AQKHuqwNeaTh%ZxN)>Dj-XS8
zQbx2JmV8WppL=BCuuG3(=ft>6Prgk5L%Fl@JDyc}6-B|1;GW(8HHYzT3Jfgw=5
zu}J1s^;8G`8tXuJ4p|K`0nECBQLIT$8mXKF9VzTZjOL~eDLM&kQ2T<6N`}@at$1np
zbvMQJ0LmwNX-0mO-qyKh@h7AEPHD7VfA7XfElC4tHYoy~-=FaL*(?YGYR3p048G;V
zHQ^4P(FfE6pqpO)1YE%3?Z)D{ve>MK!sYIKi>eLk(P^>S?)2v-J^AZTJ6GN;QD+KY
zt-HNtLyIf)Nlo>*6IuX_?Wq*89B1%}7!VQrHdGFtiSWa}fUW&OOIdmFIB0u_B_<4er9jhViWHI0s$2#?I+${D3zZjfvLel%46RyhSgL3e;n*lggc0L!jQl$&P4^1K
zw*)AAU8gvWJd?2VSFCJWdlpV4&jQ3>_?tBMqyw;MuHcG8d5~ZE&{Kar2GDC+AZANH
zs(8k8oJ{>sB-h3GI1%zLBg*`bC`e86VlmGA7=-m!ZfZix1JkCzGZn%e5sRFaw*+Z{
zcaVm)F+yF@yB}h@zO4L_5I?-DZ>}Qq`zN#=dRPe
zIJu@Wj=`6LKzvbuw00lJ{uw!tepZzA*l)eCaw}mYrI=lzZQoiTfD0pRvyq7e2VLT-
zjcM>)-i1qZb=qDHE}xTDq&rNJXuE8OumSp+1U31gm}5l%aS9^w+#IKNf!CN#4dR
zOp#4?ppJ*ra7H7Cd~7bo`+2A>!py1kbP8Z!@bPeAko<#M#{JVuAS+YX?D~x~JVgKE
zDkx~2I187@d4z!KE2mr7-fAy98FC1!GJSQe9RYVH5U1L038n_$*=m=P2m?Tq@$aRg
z$n*{hNNZy8{*H=VT_`9A-nZS%ei`=3`7XFwyDvFL#oib}GFssoCAG}Q}Y&5cJPgPRx3HVeDPHouqI}$o2T>fg%D>~dpz+vVe=Uoe>3C`N*IRDN^fZoWI
zVI}LKIn%{+Xk2SMqE$7V)3%t{{h;Nc{BSA0Aqqmbr|WTXXNE%MUyED1k)P%y&^Ny9
zpLZn@`p_|^9r<>Qo6CZ_5W;l5Cq)h17*|6Dya$$Ga~oRqgqeNo-l2>b!wMcj&0N*x
zag)d%VYKU`7!*S(D0{@sksqt)^y1D8Zp3Y{cL(?Lm?#%)vFuVur=*s+0DG?(9AhH6
zH5z_YTUv~OVUvRg!_h5?)^FS^MkS2S%;~GBeErvCWav7gL>Fu(seVdN)apF>;Ekw5D~JTvOKaw`szW}~F^7@>ZFPM$ZX{6H4j
zTvOlTjl^-bTjY|^`i!P#dBRv_XjtZnCN?mEW;uX!fWdszBoL#ME`FenKNZ~*;Z=Yw
z6$tZF`83?*9C6K&G!928SLU#CSTNuLrPj$dCoRnjyXK^gWKBOGkYh62%FUj5gET>X
z+GXG_Wf1E-#Pm+-62fxFzBB`nP0g;?8L&oBTa8o)ZtqS^aRE
zWw4OXQv(u3w{hWyROF_7WaW13;-t*$4S$M%qJz!B6OKoHGBD^xZRnUReFY*e$3YVx
z4*Th4+RWucEI7&td6xBiNL+S1BBS-7xdI2$4hWb)0Ei#qF>y8HlC#c?_Rs-&f5=H_
zeO}dydS>nHD0h-WB1nGplSRJ;Sf_13R1-H41*+JqEPCDrgXr*Y0azBfu{`kP6a`dv
z9ya}j3s+%^+dSi4*hTY;K5~^@*h=7IO0^uuvLg$W1JbBMhK&5vz9pJURxgA(3BN1>
z@vbZ5z>mVTTLh5Cj2kSj4w|P*|6XRueQvK2GbO{SS#KM(f
zIvnP&Vqeu%^fR?T!mQZeLs}TmT#zHlN`olVFnMJiGBDB@ebV3pL*A2TIXd2w+3nU8
zitCE)U30|%l=|MJ$?aTpZAb!V(9h&RUTf-N8(|IRk(LZ_D=r2e#{X*U!r3cV6dk&n
zzk?bV`{jEKCtLLdYbOwRQ~Wb@&$zAKD%O_BC^ouaN3@1FV4Hf<8&pO>baB$f74^$5
zTYZ}sr)y<)B%?*Qj#3tSBrTgPhM5glF`%)gUsS>}ega8a!dbOskZa4jK6Bc)eAexBkbjE!bHqVN`ov4#Ual^MtJtOZZ6EeEknogFv_lhx
zdMsj17!s#AilJC7xi*MJ2z#{$Yp8;90^iC87+ZNyIuP9OOgzB=m4SMg+3=1aIa^t3|Fw+1Pm%d&}$
zuoIG#0VQw3%5^?E>D+-FJg<$3%Z$VZMSB4M>d#38s;eTj5yQ>2U)-G=%FZ?IpqGlR
zx)~4nZ1Z~Ug9Mih?LSbDY}y!p>*f8ve7)4E;A)vtU}RlkaR$BJ`y*=Eswno8OH{Rr
zGWn*kvy%SDc}8=luF97XPUi61x=U8_HbgLJWpUT+v
zEV2uCQs6I4rwtcqT)5gU-ytyChaN5$=kanbOq&6hH|A-HOGD$GJTrnF*sl*&XA|lO
zoK+ctW(H19H$N%@IEm8!++B%d5RGNxBs7ysn4X!Q(PfQg-hq{SU?Y?kI43V2Mj+M0
zqa#WdmQAj&TqdR8_p?Q{cT8{3zhr3=@rXHj^j19A^#4cK3iU$LAAgu2LDZ0-aQb
zl0==k=8#Tplb3SVA7M-7Omq?O{7UR)=ell>2@?ehu%*GD!c0z-l8xj-v{$?i0tw1o
z)`=*5(YTPcAZ}#z{!V+OT=bFj4ynY(U|Z+wv*G=|Xl5Vk)cxW{i)NPG6*+W-JDr1K
zw;W|+VE8saaYr29U<<={=6*y34mNaD&(6am%raMy1ftoF@dW;$foJ)Hl_PZ^FPT7M
zvbnEvtoFtog@W?&b>HVpsAq8?opz(NtRQYRCyggFCBKQ}nX*^njb|3JQOH_nhYFkA
z1c#!1*Uo75;<;8L1iX6&baOp9>rf;iqq_?45v4r`W~|h
zd~ME&+!Y4;)59->wncJ$f_AJ^Gd5X;jb~%-#~kxsy@KYOW~r5jKy7d0CFt90r>Qn8
z65CoXhW5#Q2ogAv<`k>?ju2v_)a-gf_;lvG!Si=|cOScU2w`wS)9S^%)!k?YRbLOMq@v6AUsJIVvts(3ds`5!xep|BUU0u3}gYf@L`RXJD@Xv
z7Srz_>g4s6eLwdM>evzprYA@4d80M8R6bcPL{c1xXug@wU`n1o_mnn;swz-M@4B46
zJ=B-(#PvML!2dMaA_f5kwowErs)1HdlYtyJTvk37?i23R{yiGZTG68xt2S~KAJ-KO
zxp5ZrdB9bD+x8Q%Azp!-{shhL>Xnj=Jb3Qgit}zhY`TBc>I33?;(a5HJFOMi*+ubf
zwdh;P{=74;{*xD|H;Uis5@Y$J3&(>bYe=d%{9b=cs0bv|gH{n6BG~ZpZoZtEM|{1@
z74pT1ON$6d_u2g$zNY-``(wIQZ?P1B(nZi~jvkJFB=4+j=eMXB{PWCJC0yw37Y-y7
z%eiLrNQK_Yln80ooSD$oBH$LSYHLpV1Xn#YCWA(8mTAyi2=vTJrUt+~4_tUTyx(p)
z?lbiIhA=Ca&qA+;&{r4DDa=iKW?`T+yYi^D%e@?1VbzIKQfCpF1be&%o1^cbTR%iP
zx|xaa{*(+9QZ(1
z-4&G+$J6|91#^y^%|RS`FRl3v?iIM`T681CHpV!+VSd&y2}LGP6x$piXthK`?Sn;u
z8bLM!>=)U0l_F%%H8O1_rpV4x~AFB
zA