Skip to content

Commit ff3545e

Browse files
committed
docs: preserve execution constraints and consolidate capability claims
1 parent 6baa9da commit ff3545e

6 files changed

Lines changed: 20 additions & 29 deletions

File tree

‎contracts/agents-api/README.md‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ with official observations separated from Core acceptance.
3333

3434
Adapter and persistence design follows the
3535
[design rules](../../AGENTS.md#complexity-stays-in-the-adapter).
36-
The [harness contract and parity baseline](harness-capabilities.md) describes equal-engine
36+
The [harness contract and parity baseline](harness-onboarding.md) describes equal-engine
3737
registration, qualification and shared acceptance.
3838
Verify configuration against actual execution: response defaults must not merely
3939
describe values the adapter never applied.
@@ -440,9 +440,7 @@ The `x_agents_core.environment` extension supplies that configuration to either
440440
placement; self-hosted machines never need a managed allocation. See
441441
[shared preparation qualification](harness-capabilities.md#environment-preparation). They do not
442442
select an E2B image or make unsupported initialization executable.
443-
The supported Docker configuration has [composed real acceptance](harness-capabilities.md#environment-preparation)
444-
across the three harnesses, including frozen source deletion, cold continuation
445-
and cancellation. This does not close the remaining protocol/transport gaps.
443+
[Harness capabilities](harness-capabilities.md#environment-preparation) records composed preparation qualification by Harness and placement.
446444

447445
## Delivery and verification
448446

@@ -499,11 +497,7 @@ The shared initialization path supports env/setup and user-directory npm/Python
499497
See the [evidence and limits](harness-capabilities.md#environment-preparation). Remaining
500498
unsupported startup installations, unqualified restricted hostname forms and hosted
501499
service-origin HTTP MCP remain outside these accepted profiles. Environment-origin
502-
MCP Plugins have a separate [Docker qualification and transport matrix](environments.md#plugin-mcp):
503-
stdio on all three harnesses, Codex HTTP with literal headers or HTTPS bearer,
504-
and Claude/MiniMax anonymous HTTP or HTTPS bearer without literal headers. This batch
505-
does not qualify those new Plugin paths on E2B. MiniMax's private workspace MCP
506-
bridge remains internal transport, distinct from installed Environment MCP servers.
500+
MCP Plugin qualification and transport limits are recorded in [Harness capabilities](harness-capabilities.md#environment-preparation).
507501

508502
The [self-hosted profile](environments.md#self-hosted-self_hosted) uses
509503
user-managed Runtime enrollment and remains distinct from Core-managed Docker. Product `claude_code`

‎contracts/agents-api/environments.md‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ The two vocabularies are separate; never cast one to the other. Session environm
3737

3838
Core creates the Environment record in the Session creation transaction; the Session upsert picks the retry winner, and retries never create or repair an Environment. The Environment derives its Project and immutable configuration from the owning Session. Its first state is `pending`. After the Session is deleted, reads hide the Environment while Core keeps the record for settlement and cleanup. A Session with `none` has no Environment.
3939

40+
A managed outer Environment must exclude broader application credentials and other tenants’ secrets.
41+
4042
## Placements
4143

4244
Both placements run the same Runtime: the daemon, the selected Harness, native tools and the workspace run together on one machine. They differ only in who owns that machine.
@@ -167,7 +169,7 @@ Core freezes resource versions, metadata and source selections at Session creati
167169

168170
The runner uses only neutral Environment and Session identity and a Runtime peer, with no Provider, deployment or operating-system branch. Harness differences stay in the adapters.
169171

170-
**Portable preparation input.** `self_hosted` input carries only `workspace_directory` and `capability_directories`. Any Session can also send `x_agents_core.environment`, a Core extension with `environment_template_id`, `files`, `env`, `packages`, `setup_commands`, `skills`, `plugins` and `capability_directories`. It uses the same parsers and inheritance rules as `openai_hosted` input. A field supplied both there and in `environment` is rejected, including an explicit null. A `self_hosted` Session names its Template only through this extension and cannot use a Template whose network is not `enabled` (400, param `x_agents_core.environment.environment_template_id`). Machine location, sizing and network policy are not extension fields.
172+
**Portable preparation input.** `self_hosted` input carries only `workspace_directory` and `capability_directories`. A Session with either workspace placement can also send `x_agents_core.environment`, a Core extension with `environment_template_id`, `files`, `env`, `packages`, `setup_commands`, `skills`, `plugins` and `capability_directories`. It uses the same parsers and inheritance rules as `openai_hosted` input. A field supplied both there and in `environment` is rejected, including an explicit null. A `self_hosted` Session names its Template only through this extension and cannot use a Template whose network is not `enabled` (400, param `x_agents_core.environment.environment_template_id`). Machine location, sizing and network policy are not extension fields.
171173

172174
```json
173175
{
@@ -359,11 +361,7 @@ The shared parser accepts HTTP `url`, `bearer_token_env_var` and literal `http_h
359361

360362
A stdio server starts through the daemon's stdio helper, which resolves the installed declaration and launches the command with the Harness's permissions. On Unix the helper replaces itself with the server; on Windows it forwards stdio inside the owned process tree. Initialized values override the declaration's variables. Process groups and Windows Jobs own cancellation and descendant cleanup, not isolation.
361363

362-
| Harness | Plugin MCP transports |
363-
| --- | --- |
364-
| Codex | stdio; HTTP with literal headers and HTTPS bearer |
365-
| Claude SDK | stdio; anonymous HTTP or HTTPS bearer, no literal headers |
366-
| MiniMax Code | stdio; anonymous HTTP or HTTPS bearer, no literal headers |
364+
[Harness capabilities](harness-capabilities.md#environment-preparation) owns the supported Plugin transports and per-Harness limits.
367365

368366
Environment MCP needs enabled network. Duplicate server identities are rejected. Claude rejects literal headers because the pinned client expands them again and forwards custom headers across origins. MiniMax ACP HTTP declarations stay in session-local native memory; tokens never enter native configuration files or process arguments. Required initialization and tool allowlists cannot be set through the Plugin manifest.
369367

@@ -382,12 +380,8 @@ An Agent's HTTP MCP tool ([declaration](execution-tools.md#http-mcp)) has a `con
382380

383381
Core's Harness profile declares `MCPOrigins`; admission and dispatch check the origin against the placement and the Runtime's advertised HTTP, bearer and required-initialization capabilities, and the Runtime validates the origin again before invoking an adapter. No Harness-name or Provider branch selects a different path.
384382

385-
| Harness | `service` | `environment` | Policy limits |
386-
| --- | --- | --- | --- |
387-
| Codex | Supported | Supported | Nullable tool allowlist; `required` supported |
388-
| Claude SDK | Supported | Supported; the packaged bridge must report `workspace_mcp_http` | Nullable tool allowlist; `required` supported |
389-
| MiniMax Code | Rejected | Supported | `allowed_tools` must be null or omitted and `required` false |
383+
[Harness capabilities](harness-capabilities.md#tools) owns per-Harness origin support and policy limits.
390384

391385
Both origins support anonymous HTTP and HTTPS bearer credentials. The attached-Vault selection freezes the credential identity, including a unique implicit URL match or an anonymous selection. Only that Project-authorized credential enters the transient Runtime request; Core defaults and unrelated Vaults are never searched. A decryption failure or missing credential fails execution without an anonymous fallback. Public Environment MCP keeps `project_vault` authority and Plugin credentials keep `environment_configuration` authority; neither overrides a duplicate server label. Bearers never enter persisted native configuration or process arguments.
392386

393-
Omitted or null `allowed_tools` permits every tool on the server and `[]` permits none. Codex and Claude keep native allowlists and initialize required servers before releasing native input, including in cold recovery. `service` origin with a workspace is rejected: Core has no forwarding proxy.
387+
Tool allowlists and required initialization follow the [HTTP MCP contract](execution-tools.md#http-mcp).

‎contracts/agents-api/execution-tools.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ The Worker fails previously claimed work without replay after execution loss; qu
3535

3636
## Structured output
3737

38-
`text.format` accepts `{type: "json_schema", schema: {...}}`, the Agents API form: it has no `name`, `strict` or other Responses API wrapper fields. The schema is saved, inherited through Agent and Session resolution and frozen in the Session snapshot. An explicit non-object root type is a protocol error on save and Session creation for every Harness. The Claude SDK reads JSON numbers as binary64, so Session admission rejects schemas whose numbers would change in that conversion; saved Agents keep them unchanged.
38+
`text.format` accepts `{type: "json_schema", schema: {...}}`, the Agents API form: it has no `name`, `strict` or other Responses API wrapper fields. The schema is saved, inherited through Agent and Session resolution and frozen in the Session snapshot. An explicit non-object root type is a protocol error on save and Session creation for every Harness. Claude requires an explicit `type: "object"` at the schema root. The Claude SDK reads JSON numbers as binary64, so Session admission rejects schemas whose numbers would change in that conversion; saved Agents keep them unchanged.
3939

4040
Core carries the schema in `ExecutionControls.OutputFormat` and requires the profile's structured-output qualification plus the Runtime's `structured_output` and message-observation capabilities, only for requests that use the option. Frozen schemas reach preparation before input and apply to initial and resumed execution; Start cannot replace them.
4141

@@ -81,11 +81,11 @@ Execution admits only `mode: "disabled"` and `enabled: false`. Enabled or omitte
8181
}
8282
```
8383

84-
- `server_label` is nonempty and unique within the Agent. Only the `http` transport is accepted; `server_url` is an absolute HTTP or HTTPS URL without credentials, query or fragment. Nonempty `headers` and `request_metadata` are rejected.
85-
- `connection_origin` is `service` or `environment`; omitted or null is saved as `service`. [Public MCP connection origin](environments.md#public-mcp-connection-origin) owns where each origin runs, per-Harness support and credential authority.
84+
- `server_label` is nonempty and unique within the Session. Only the `http` transport is accepted; `server_url` is an absolute HTTP or HTTPS URL without credentials, query or fragment. Nonempty `headers` and `request_metadata` are rejected.
85+
- [Public MCP connection origin](environments.md#public-mcp-connection-origin) owns origin defaults, placement and credential authority; [Harness capabilities](harness-capabilities.md#tools) owns per-Harness support.
8686
- Omitted or null `allowed_tools` permits every server tool; `[]` permits none.
8787
- `required: true` makes native thread creation and cold resume wait for the server to initialize; a failure stops execution without replacing retained history. It needs the Runtime's `mcp_http_required` capability. Public work can be accepted or queued during the wait.
88-
- A static bearer comes from a Vault credential attached to the Session. An explicit `credential_id` selects an attached credential for the exact HTTPS URL; omitted or null selects the unique matching credential, or stays anonymous if none matches. Ambiguity fails before Session creation with 409 `conflict_error`. The selection is frozen privately; Session reads and events show an implicitly selected credential ID in the public tool, while the stored request keeps the caller's field. Authenticated execution needs `mcp_http_bearer_auth`, and a missing or undecryptable credential never falls back to anonymous ([Vault credentials](../../services/core/credentials.md)).
88+
- Bearer authentication uses an attached static or OAuth Vault credential. [Vault credentials](../../services/core/credentials.md) owns selection, and [MCP credential authority](environments.md#public-mcp-connection-origin) owns the frozen Runtime binding. Authenticated execution requires `mcp_http_bearer_auth`.
8989
- The Runtime must advertise `mcp_http_tools`. The native Harness owns discovery, calls and results; public `mcp_call` Items use the original server and tool names and keep the observed native result.
9090

9191
Codex verifies the exact effective MCP configuration before starting or resuming a thread, excludes undeclared servers, disables native apps and plugins, and rejects reserved native labels and stored native MCP credentials. Claude accepts labels of ASCII letters, digits, underscore and hyphen except `functions`, tool names that may also contain dots, and requires connected servers with static inventories. Anonymous Claude requests send a blank Authorization header to suppress native OAuth injection. Native OAuth login is not supported.

‎contracts/agents-api/harness-capabilities.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This page lists what each Harness supports on each placement. Core decides admis
88
| Admitted | Core admits it through the same Runtime path, but no real-model acceptance has run on that placement |
99
| Rejected | Core rejects the request before execution |
1010

11-
Placements are `none` (no Environment), hosted (`openai_hosted`) and self-hosted (`self_hosted`). Hosted acceptance ran on Docker nodes; E2B and microsandbox run the same Runtime and adapters, and every hosted cell counts as Admitted there. Self-hosted acceptance ran on Linux machines; the [self-hosted guide](../../docs/getting-started/self-hosted.md#platforms) lists the supported platforms. A verified operation is verified on its own, not in every combination with other options; combinations that a profile rejects are listed in the operation's contract.
11+
Placements are `none` (no Environment), hosted (`openai_hosted`) and self-hosted (`self_hosted`). Hosted acceptance ran on Docker nodes; E2B and microsandbox run the same Runtime and adapters, and every Verified hosted cell counts as Admitted there. Self-hosted acceptance ran on Linux machines; the [self-hosted guide](../../docs/getting-started/self-hosted.md#platforms) lists the supported platforms. A verified operation is verified on its own, not in every combination with other options; combinations that a profile rejects are listed in the operation's contract.
1212

1313
## Execution and input
1414

@@ -50,7 +50,8 @@ These operations need a workspace, so they apply to hosted and self-hosted place
5050

5151
| Operation | Codex | Claude SDK | MiniMax Code |
5252
| --- | --- | --- | --- |
53-
| [Initial files, setup commands, Skills, Plugins and capability directories](environments.md#runtime-capability-preparation) | Verified: hosted, self-hosted | Verified: self-hosted; admitted: hosted | Verified: self-hosted; admitted: hosted |
53+
| [Initial files, setup commands, Skills and Plugins](environments.md#runtime-capability-preparation) | Verified: hosted, self-hosted | Verified: self-hosted; admitted: hosted | Verified: self-hosted; admitted: hosted |
54+
| Capability directories | Admitted | Admitted | Admitted |
5455
| npm and Python packages | Admitted | Admitted | Admitted |
5556
| `packages.system` | Rejected | Rejected | Rejected |
5657
| Network `disabled` or `restricted` | Rejected | Rejected | Rejected |

‎contracts/agents-api/harness-onboarding.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,8 @@ Before starting, record the operation set, expected results, exclusions and stop
219219
| Deferred function discovery | `TestNativeToolSearchPublicExecution` | `OAC_TEST_TOOL_SEARCH_REAL_OPTIONS` |
220220
| Disabled web search and programmatic tool calling | `TestNativeToolPolicyPublicExecution` | `OAC_TEST_TOOL_POLICY_REAL_OPTIONS`, `OAC_TEST_TOOL_POLICY_ENGINE` |
221221

222+
Environment acceptance uses `services/core/tests/official_environment_{templates,setup,skills,plugins,plugin_mcp,composition,initial_files,network,skill_references}.py`. For composed preparation, change the Skill default and Template, delete the sources, retry and restart; verify frozen bytes, one setup execution and MCP cancellation. `official_hosted_structured_native.py` covers hosted structured output. Record exact source revisions, native versions and commands with each acceptance result.
223+
222224
Keep provider keys in private operator files, never in commits or logs. Existing focused tests, relative to `apps/daemon/internal/agent`:
223225

224226
| Boundary | Tests |
@@ -242,7 +244,7 @@ Owned output pipes stay readable after the leader exits. Consumers drain stdout
242244

243245
Adapters run native tools unattended with the launching user's permissions: Codex with approval policy `never` and full access, Claude through the adapter's tool callback in native `default` permission mode with the SDK sandbox disabled, and MiniMax with bypassed permissions and its sandbox disabled. 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.
244246

245-
The daemon does not enforce disabled or restricted network policies. Core rejects such a combination unless the outer Environment provides and qualifies the restriction; never advertise daemon-level network isolation or run a restricted request unrestricted. A self-hosted machine uses the host's existing network.
247+
Network admission follows [Restricted network](environments.md#restricted-network).
246248

247249
## Native references
248250

‎contracts/agents-api/subagents.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ An adapter freezes root output before child settlement, keeps its native owner a
4848

4949
## Native profiles
5050

51-
Every profile rejects public functions and HTTP MCP combined with enabled `multi_agent`.
51+
[Harness capabilities](harness-capabilities.md#tools) lists rejected tool combinations.
5252

5353
**Codex.** The adapter enables the native `multi_agent` feature with a nesting depth of 64 and maps the concurrency limit to `agents.max_threads`. It disables native hooks, plugins, code mode and `multi_agent_v2`, and refuses to start if the native hook list is not empty or managed requirements force a conflicting feature. Close and reopen facts come from direct tool output correlated with the same call's persisted completion, so they need native persisted receipts. Native Turn times have second precision. Child file work can finish under the same owner after the root Turn finishes. Cancellation continues under the same owner after a caller deadline; a later call can confirm settlement without repeating the native interrupt.
5454

0 commit comments

Comments
 (0)