You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ff3545e
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: contracts/agents-api/environments.md
+6-12Lines changed: 6 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -37,6 +37,8 @@ The two vocabularies are separate; never cast one to the other. Session environm
37
37
38
38
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.
39
39
40
+
A managed outer Environment must exclude broader application credentials and other tenants’ secrets.
41
+
40
42
## Placements
41
43
42
44
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
167
169
168
170
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.
169
171
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.
171
173
172
174
```json
173
175
{
@@ -359,11 +361,7 @@ The shared parser accepts HTTP `url`, `bearer_token_env_var` and literal `http_h
359
361
360
362
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.
361
363
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.
367
365
368
366
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.
369
367
@@ -382,12 +380,8 @@ An Agent's HTTP MCP tool ([declaration](execution-tools.md#http-mcp)) has a `con
382
380
383
381
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.
| 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.
390
384
391
385
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.
392
386
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).
Copy file name to clipboardExpand all lines: contracts/agents-api/execution-tools.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,7 +35,7 @@ The Worker fails previously claimed work without replay after execution loss; qu
35
35
36
36
## Structured output
37
37
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.
39
39
40
40
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.
41
41
@@ -81,11 +81,11 @@ Execution admits only `mode: "disabled"` and `enabled: false`. Enabled or omitte
81
81
}
82
82
```
83
83
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.
- Omitted or null `allowed_tools` permits every server tool; `[]` permits none.
87
87
-`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`.
89
89
- 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.
90
90
91
91
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.
Copy file name to clipboardExpand all lines: contracts/agents-api/harness-capabilities.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ This page lists what each Harness supports on each placement. Core decides admis
8
8
| Admitted | Core admits it through the same Runtime path, but no real-model acceptance has run on that placement |
9
9
| Rejected | Core rejects the request before execution |
10
10
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.
12
12
13
13
## Execution and input
14
14
@@ -50,7 +50,8 @@ These operations need a workspace, so they apply to hosted and self-hosted place
Copy file name to clipboardExpand all lines: contracts/agents-api/harness-onboarding.md
+3-1Lines changed: 3 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -219,6 +219,8 @@ Before starting, record the operation set, expected results, exclusions and stop
219
219
| Deferred function discovery |`TestNativeToolSearchPublicExecution`|`OAC_TEST_TOOL_SEARCH_REAL_OPTIONS`|
220
220
| Disabled web search and programmatic tool calling |`TestNativeToolPolicyPublicExecution`|`OAC_TEST_TOOL_POLICY_REAL_OPTIONS`, `OAC_TEST_TOOL_POLICY_ENGINE`|
221
221
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
+
222
224
Keep provider keys in private operator files, never in commits or logs. Existing focused tests, relative to `apps/daemon/internal/agent`:
223
225
224
226
| Boundary | Tests |
@@ -242,7 +244,7 @@ Owned output pipes stay readable after the leader exits. Consumers drain stdout
242
244
243
245
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.
244
246
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.
**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.
0 commit comments