Document the agent-host cutover

contracts/agents-api/index.md

@@ -123,6 +123,7 @@ Each item is Core's deliberate or native behavior where the official service beh
 - Pinned Codex can lose command output emitted before its stream subscription.
 - Behind the [credential gateway](./model-execution.md#credential-gateway), pinned Codex compacts history locally and never calls `/responses/compact`.
 - Claude Code and MiniMax Code report no public usage.
+- Claude Code and MiniMax Code do not support `native_session_recovery`: when a Session has a started Turn but Core has no recorded native Session ID, execution is rejected. Cold continuation with an already recorded native ID is a separate case; this declaration neither rejects it nor qualifies it. See [public-path qualification](./harness-onboarding.md#qualify-the-public-path).
 - Core gives no crash-safe or exactly-once guarantee for native side effects; claimed work fails on restart without replay.
 - Message images must be inline PNG or JPEG data URIs; remote URLs, `file_id` and `detail` are rejected.
 

contracts/agents-api/zh/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Agents API 覆盖台账"
 source: contracts/agents-api/index.md
-source_hash: 8feb92673f53693a526366264e0ff5094f69112859bfa0882e217a2b3ca07282
+source_hash: 7f7326bcbc718daa44de601d9df6321d4e1a32fa713f081bc3877e4b23d000fd
 ---
 
 Core 旨在以下方固定版本为准支持完整的 OpenAI Agents API（[public API rule](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#public-api)）。本台账记录 Core 对各项资源实现了哪些内容、哪些契约保存其详细信息，并列出相对于 OpenAI 服务的所有已知差异和所有未解决缺口。[API namespaces and credentials](../../../docs/zh/api/index.md) 说明谁调用哪些 API；[Agents API guide](../../../docs/zh/api/public-agent-api.md) 介绍使用方法。
@@ -125,6 +125,7 @@ Core 自身字段位于 `x_agents_core` 中（[Core extensions](../../../docs/zh
 - 固定版本的 Codex 可能会丢失在订阅其流之前发出的命令输出。
 - 在[凭据网关](./model-execution.md#credential-gateway)之后，固定版本的 Codex 在本地压缩历史，从不调用 `/responses/compact`。
 - Claude Code 和 MiniMax Code 都不报告公共用量。
+- Claude Code 和 MiniMax Code 不支持 `native_session_recovery`：Session 已有启动过的 Turn，但 Core 未记录原生 Session ID 时，执行会被拒绝。已有原生 ID 时的冷启动续聊属于另一种情况；该声明既不拒绝它，也不证明它已通过验收。参见[公共路径验收](./harness-onboarding.md#qualify-the-public-path)。
 - 对于原生副作用，Core 不提供崩溃安全或恰好一次保证；已认领的工作若不重放，会在重启后失败。
 - 消息图像必须是内嵌的 PNG 或 JPEG data URI；远程 URL、`file_id` 和 `detail` 会被拒绝。
 

docs/architecture.md

@@ -2,29 +2,30 @@
 title: "Architecture"
 ---
 
-OpenAgentCore separates orchestration, compute and native execution. Core owns the API and durable state. Sandbox Providers manage compute. A Runtime daemon prepares an Environment and runs the selected Harness, whose native SDK or protocol owns the model and tool loop.
+OpenAgentCore separates orchestration, compute and native execution. Core owns the API and durable state. Sandbox Providers manage compute. The Runtime runs on a Linux agent host near Core, prepares Environments through Sandbox I/O and runs each native Harness in a Session view. The Harness's upstream SDK or protocol owns the model and tool loop.
 
 ```mermaid
 flowchart TB
-    App["Application / official SDK"] <-->|"Agents API /v1: HTTP and SSE"| Core
+    App["Application / official SDK"] <-->|"Agents API /v1"| Core
     Web["Web administrator console"] <-->|"Core API /core/v1"| Core
-    Core["Core: authorization, configuration snapshots,<br/>orchestration and durable state"]
-    Core --- DB[("PostgreSQL")]
-    Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider: Docker / E2B / microsandbox"]
-    SP -.->|"Provision compute and bootstrap Runtime"| R
-    User["User-machine installer"] -.->|"Start Runtime"| R
-    Core <-->|"Core–Runtime protocol:<br/>preparation, execution, events and receipts"| R
-    subgraph Env["Environment: managed sandbox or user-owned machine"]
-        R["Runtime daemon"] --> P["Workspace and capability preparation"]
-        P -->|"Harness protocol"| A["Harness adapter"]
-        A <-->|"Native SDK or protocol"| H["Native Harness: model and tool loop"]
-        H <--> F["Workspace, tools and artifacts"]
+    Core <-->|"Durable state"| DB[("PostgreSQL")]
+    Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider"]
+    Core <-->|"Core–Runtime protocol"| R
+    subgraph Host["Linux agent host"]
+        R["Runtime: preparation and execution"] --> H["Session view: native Harness"]
+        H <-->|"Model and HTTP MCP"| G["Credential gateway"]
+    end
+    G <--> Upstream["Model provider / HTTP MCP servers"]
+    R <-->|"File / Process / Network"| Link["Core Link relay"]
+    Link <--> IO
+    SP -.->|"Provision and bootstrap"| IO
+    User["Self-hosted installer"] -.->|"Start"| IO
+    subgraph Env["Managed sandbox or self-hosted machine"]
+        IO["Sandbox I/O service"] <--> F["Workspace, tools and stdio MCP"]
     end
-    H <-->|"Model API"| Model["Model provider"]
-    H <-->|"MCP"| MCP["Local or remote MCP servers"]
 ```
 
-Dashed arrows show provisioning and installation. Solid arrows show component interactions, including in-process interfaces. The daemon initiates its authenticated WebSocket connection to Core. The [API index](./api/index.md) describes the application, operator and machine namespaces; [protocol boundaries](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary) lists each protocol's code and owning document.
+Dashed arrows show provisioning and installation. Solid arrows show component interactions, including in-process interfaces. The agent host connects to Core over an authenticated WebSocket; the agent host and Sandbox I/O connect to the Core Link relay. A Session with `environment: none` has an assignment and a private native home, with no sandbox workspace. The [API index](./api/index.md) describes the application, operator and machine namespaces; [protocol boundaries](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary) lists each protocol's code and owning document.
 
 ## Component responsibilities
 
@@ -33,7 +34,9 @@ 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; start the Sandbox I/O service in it | [Sandbox Provider](./sandbox-provider.md), [Sandbox bootstrap](./sandbox-bootstrap.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) |
+| Runtime on the agent host | Prepare the workspace and capabilities through Sandbox I/O, manage Session views and Executors, execute Turns and report events and receipts | [Core–Runtime protocol](./runtime-protocol.md) |
+| Sandbox I/O | Serve the sandbox's files, processes and network through the Core Link relay | [Sandbox link](./sandbox-link-protocol.md), [File access](./file-access-protocol.md), [Process](./process-protocol.md), [Network](./sandbox-network-protocol.md) |
+| Credential gateway | Hold model and HTTP MCP credentials on the agent host and inject them into permitted upstream requests | [Model execution](../contracts/agents-api/model-execution.md#credential-gateway) |
 | 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) |
 | Model provider | Serve the model protocol selected for the Harness | [Model execution](../contracts/agents-api/model-execution.md) |
 | Web | Let administrators configure and observe the installation through a server-side Core API connection | [Console server](./web/console-server.md) |
@@ -42,8 +45,8 @@ The [repository map](./development.md#repository-map) locates these components.
 
 ## A Session, end to end
 
-An application creates a Session through the Agents API. Core resolves its configuration and execution location. A managed Session obtains compute through the selected Sandbox Provider; a self-hosted Session waits for the user to run its installation command. A Session with `environment: none` uses a connected execution device without a workspace. The [application guide](./api/public-agent-api.md#create-a-session) describes these choices.
+An application creates a Session through the Agents API. Core resolves and freezes its configuration. A managed Environment obtains compute through the selected Sandbox Provider; a self-hosted Environment waits for the user to run its installation command. In both cases Sandbox I/O must Serve the Environment's resource through the Link. The [application guide](./api/public-agent-api.md#create-a-session) describes these choices.
 
-After the daemon connects, Core checks the available Harness and requested capabilities and binds the Session to that Runtime through a fenced [assignment](./runtime-protocol.md#session-assignments), which deleting the Session or releasing its Environment releases. The Runtime prepares a workspace Environment and its capability snapshot, then prepares or reuses the Session Executor. Each Turn runs through the native Harness. Core persists the output, tool interactions and receipts for application reads and events. Completion or cancellation settles the Turn; a healthy Executor can serve the next Turn in the same Environment.
+Core binds every Session to an agent host through a fenced [assignment](./runtime-protocol.md#session-assignments). For a Session with an Environment, its Link resource must be Serving before Core sends the bind; Core separately waits for the agent host's bound acknowledgement before preparation or execution. The Runtime prepares the Environment and its capability snapshot, then prepares or reuses the Session Executor. Each Turn runs through the native Harness. Core persists output, tool interactions and receipts for application reads and events. Completion or cancellation settles the Turn; a healthy Executor can serve the next Turn. Session deletion or Environment release releases the assignment.
 
 Execution and compute have separate lifetimes: closing an Executor preserves its allocation and workspace until the Provider reclaims them. Preparation, connection and execution readiness have distinct states. The [Environment contract](../contracts/agents-api/environments.md) owns preparation, and the [Core–Runtime protocol](./runtime-protocol.md) owns ordering, receipts and failure handling.

docs/configuration.md

@@ -122,13 +122,13 @@ The named Docker volume `<project>_data` contains these paths. Docker manages Li
 
 ## Docker node configuration
 
-The node installer writes Docker’s host settings into the `native` object of the node’s configuration file, which only the Docker adapter reads. Deployment resources, the Runtime release and capacity remain in [Core’s database](#runtime-settings-web).
+The node installer writes Docker’s host settings into the `native` object of the node’s configuration file, which only the Docker adapter reads. Deployment resources, the sandbox release and capacity remain in [Core’s database](#runtime-settings-web).
 
 | Field | Installer value | Meaning |
 | --- | --- | --- |
 | `host` | `unix:///var/run/docker.sock` | Explicit Docker Engine socket |
-| `image` | The Runtime image’s local ID after loading | The release’s `image_id` or `image_manifest_digest`. The host’s image store decides which digest names the loaded image, so the value is node-local; the adapter accepts only these two |
-| `network` | `oac-node-<installation-id>` | Runtime container network |
+| `image` | The sandbox image’s local ID after loading | The release’s `image_id` or `image_manifest_digest`. The host’s image store decides which digest names the loaded image, so the value is node-local; the adapter accepts only these two |
+| `network` | `oac-node-<installation-id>` | Sandbox container network |
 | `seccomp_file` | `<node-root>/runtime/seccomp.json` | Matched distribution’s seccomp profile |
 
 The [Docker adapter](./sandbox-provider.md#docker-adapter) owns container isolation, volume layout and lifecycle behavior.

docs/getting-started/install-options.md

@@ -110,11 +110,11 @@ curl -s -o /dev/null -w '%{http_code}\n' -H 'OpenAI-Beta: agents=v1' https://cor
 
 `401` means `/v1` reached Core, which asks for a key. `404` means it reached Web: fix the proxy, or application calls and every node connection will fail.
 
-TLS verification stays on everywhere. With a private certificate authority, node hosts, self-hosted machines and the Runtime image must trust it.
+TLS verification stays on everywhere. With a private certificate authority, the agent-host and sandbox images, node hosts and self-hosted machines must trust it for the HTTPS endpoints they call.
 
 ### Try it locally with a quick tunnel
 
-A [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) gives a trial installation with external ingress a temporary public HTTPS address. It forwards to one port, so put a local proxy with the same routes in front:
+A [Cloudflare quick tunnel](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) provides a temporary public HTTPS address for connection and download checks. [Quick Tunnels do not support SSE](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations), so Agents API streaming requires an HTTPS ingress that supports SSE. The tunnel forwards to one port, so put a local proxy with the same routes in front:
 
 ```caddyfile
 http://:8443 {

docs/getting-started/install.md

@@ -22,7 +22,7 @@ This page follows the default path. Every flag, existing reverse proxies and off
 - Free port 8080 for Web. See [ports](./install-options.md#ports). Docker must be able to publish it; the installer does not change host policy.
 - For anything off this machine, the origin in `OAC_PUBLIC_URL` must be the address browsers, nodes and executors use. You can sign in on this machine first.
 
-Sandbox nodes run on Linux amd64. When Core runs on macOS or Windows, connect a Linux node or use E2B.
+Sandbox nodes run on Linux amd64. When the operator launcher runs on macOS or Windows, its Docker engine must still be Linux amd64; connect a Linux sandbox node or use E2B.
 
 ## Install
 

docs/sandbox-provider.md

@@ -196,7 +196,7 @@ A [reset](../contracts/agents-api/sandbox-deployment.md#reset) is durable execut
 
 One snapshot and timestamp partition the held resources. Offline ownership comes from the allocation's or active placement's node, with the same 45-second connection and owner-epoch predicate as online presence, independently of provider readiness; no cleanup failure, offline state or empty read authorizes a synthetic release. At zero held resources, Core drains outside database transactions, rechecks under the deployment lock and clears the deployment in one transaction, then publishes a generation-bearing empty provider without fallible work. If the final write or drain fails, it restores the committed provider with a bounded owner context before releasing the mutation gate; if that recovery fails, admission stays fenced and the owner stops.
 
-An administrator [Session archive](../contracts/agents-api/admin-api.md#session-archive) keeps its Project scope and hosted eligibility checks in a Session-first transaction, together with Environment expiry, cancellation, Runtime authority revocation and audit; a reset's background archive reconstructs the actual Project scope from trusted records and keeps the requester's provenance. The ordinary provider lifecycle releases compute and snapshots. Archive cancellation keeps a healthy receipt path until the terminal commit: only the archive that first revokes a device records its exact `archive_cancel_turn_id` (ordinary revocation clears it, and repeated cleanup keeps it), and the existing authenticated delivery may drain that cancellation for at most 20 seconds from the Turn's original `cancel_requested_at`. Core tracks the delivery through `done`, the cancellation acknowledgement and the terminal commit, independently of subscription removal, and grants no new connection, input, file or MCP authority or lease renewal. No transaction or lifecycle gate waits for the receipt, and a lost peer, expiry or restart falls back to ordinary failure and cleanup, never a fabricated cancelled outcome.
+An administrator [Session archive](../contracts/agents-api/admin-api.md#session-archive) keeps its Project scope and hosted eligibility checks in a Session-first transaction, together with Environment expiry, cancellation and audit; a reset's background archive reconstructs the actual Project scope from trusted records and keeps the requester's provenance. For an allocated Environment, archive releases the Session's assignment without removing its native home and requests allocation cleanup. The ordinary provider lifecycle releases compute and snapshots. The shared agent-host credential remains valid. Cancellation follows the [Turn lifecycle](../contracts/agents-api/sessions-events.md#send-input): a cleanup request or confirmed sandbox release does not prove that the Turn has settled.
 
 ## Validate the integration
 
@@ -227,7 +227,7 @@ The Docker Sandbox Provider ([`sandbox/docker`](https://github.com/MiniMax-AI/Op
 
 Create refuses to reuse retained volumes that have no container. It copies the Sandbox bootstrap file to `/home/runtime/sandbox-io-bootstrap.json` (mode 0600, UID 1000) and the `/environment` workspace, initialization and package directories into the container, which then runs `oac-sandbox-io --bootstrap-file /home/runtime/sandbox-io-bootstrap.json` as its entry point. The service is the container's first process and reaps its orphaned descendants, so the container needs no init process. When the created container does not have the configured CPU, memory and exact image, Create returns the error with `CreateSettled`. Docker has no lease, so Renew only reads the container state. Kill checks the ownership labels of the container and both volumes before removing any of them, then confirms that all three are gone.
 
-The node uses the explicit Unix socket in its [provider configuration](./configuration.md#docker-node-configuration) and ignores `DOCKER_HOST`. No Docker socket, host home or Core credential is mounted into a Runtime.
+The node uses the explicit Unix socket in its [provider configuration](./configuration.md#docker-node-configuration) and ignores `DOCKER_HOST`. No Docker socket, host home or Core credential is mounted into a sandbox.
 
 ### Seccomp profile