Add basic Environment Templates and Session references

CONTRIBUTING.md

@@ -254,6 +254,19 @@ or an undocumented daemon installation requirement cannot replace `remote_url`.
 Keep harness cwd separate from the executor workspace where that accepted remote
 path still requires it.
 
+Public Environment Templates belong to Core and its execution database, independently
+of provider image/build templates. Resolve a tenant-owned reference once at Session
+creation, freeze the effective ordinary hosted configuration and reuse inline
+initialization. Do not pass template IDs into Provider or Runtime. Omitted network
+inherits; overrides may only narrow policy. Preserve unresolved caller intent for
+creation retries and recover committed results before reading mutable templates.
+Updates and deletion cannot rewrite existing Session snapshots. The initial profile
+admits name and enabled/disabled network, rejecting populated installation and
+confidential fields before persistence. Do not store unsupported inputs for later
+silent omission; expand both inline and template initialization together in separately
+qualified batches. Resource reads need only tenant authorization, not a live Runtime.
+See the [Template coverage and unresolved semantics](contracts/agents-api/environment-templates.md).
+
 SandboxProvider has five operations: Create, GetInfo, Renew, Kill and RunCommand.
 Use maintained provider SDKs and thin adapters, Docker first and E2B after the MVP.
 Provider initialization creates the sandbox and starts its daemon/harness;

contracts/agents-api/README.md

@@ -62,9 +62,8 @@ business Team orchestration are separate from protocol coverage.
 
 This inventory is based on the pinned Python source, not our generated OpenAPI.
 It contains 42 distinct HTTP operations in 15 resource classes, excluding async
-duplicates, overloads and client-side helpers. At merged PR #703
-(`6959654c94645aec9934ad682e277841492f7897`), 31 have handler entries and 11 are
-missing: six Subagent reads and five Environment Template operations. The separate
+duplicates, overloads and client-side helpers. There are 36 handler entries; the six
+Subagent read operations remain missing. The separate
 general `/v1/files` source-file API is outside this 42-operation count.
 
 An implemented route is not complete semantic compatibility. **Accepted** below
@@ -90,7 +89,7 @@ the Python SDK. Vault HTTP paths start at `/vaults`, not `/agents/vaults`.
 | sessions.subagents.turns.items | list | Missing |
 | environments | retrieve | Supported Codex self-hosted and three-harness Docker/E2B hosted profiles: durable status and safe empty installation metadata; populated installation inventory and full lifecycle parity remain gaps |
 | environments.files | create, list | [Bounded live listing and inline/source-file creation](environment-files.md) on qualified Docker/E2B workspaces; Codex self-hosted listing is a separate supported path. Full listing, overwrite and error semantics remain partial |
-| environments.templates | create, retrieve, update, list, delete | Missing |
+| environments.templates | create, retrieve, update, list, delete | [Basic reusable network configuration and Session snapshots](environment-templates.md); populated initialization and full semantics remain gaps |
 | vaults | create, retrieve, list, delete | Create/retrieve/list/delete with independent tenant persistence, stored status filtering, atomic Credential cascade and frozen Session attachments; archive semantics and full hosted lifecycle parity remain missing |
 | vaults.credentials | create, retrieve, update, list, delete | Static-bearer create/retrieve/list/token replacement/deletion with scoped encrypted storage; Session attachment and exact-URL HTTPS MCP binding; OAuth, archive semantics and full hosted lifecycle parity remain missing |
 
@@ -156,7 +155,7 @@ user-managed enrollment remain outside this qualification.
 | Area | Missing or unverified scope |
 | --- | --- |
 | Subagents / multi_agent | Six public child read operations, enabled execution, child lifecycle/interactions and full recovery; deferred outside the MVP |
-| Environment Templates | All five CRUD/list operations; populated installation metadata and additional Environment configurations remain separate gaps |
+| Environment Templates | Populated initialization/confidential inputs, restricted network, referenced null override semantics and exact hosted errors; basic CRUD/list and Session references are supported |
 | Input and configuration | Non-text initial input, broader content/configuration unions, structured output and reasoning/verbosity combinations |
 | Tools and interactions | Deferred functions, other tool types, effective tool-set enforcement and result/cancel publication ordering; MiniMax public functions/MCP remain unsupported |
 | Vault and Credentials | OAuth/refresh, archive semantics, revocation/concurrent mutation and exact hosted selection/error behavior; static bearer CRUD/token replacement is already present |
@@ -356,9 +355,13 @@ including further deployment qualification; this inventory describes merged beha
   describe native discovery or workspace files created by commands. Unknown
   installation configurations are rejected, not reported as empty. Reads use the
   owning live Session's project partition and do not require execution setup.
-  Populated installation metadata/configuration, templates, full hosted lifecycle and
+  Populated installation metadata/configuration, full hosted lifecycle and
   exact hosted error semantics remain gaps.
 
+Basic [Environment Templates](environment-templates.md) provide tenant-owned CRUD/list
+and immutable Session resolution through the same hosted initialization. They do not
+select an E2B image or make unsupported initialization executable.
+
 ## Delivery and verification
 
 | Capability | Current state |
@@ -396,7 +399,7 @@ operator setup: [Codex](../../services/agents-api/deploy/codex/README.md),
 [MiniMax Code](../../services/agents-api/deploy/mcode/README.md). The
 [E2B guide](../../services/agents-api/deploy/e2b/README.md) packages those qualified
 images as pinned templates.
-Populated startup installations, restricted domains, templates and hosted public
+Populated startup installations, restricted domains and hosted public
 HTTP MCP remain outside these accepted profiles. MiniMax's private MCP tool bridge
 is internal transport, not public MCP support.
 

contracts/agents-api/environment-templates.md

@@ -0,0 +1,82 @@
+# Environment Templates: basic hosted configuration
+
+Core owns reusable configuration through the five pinned
+[Template operations](https://github.com/openai/openai-python/blob/d7c41efee1b0802b79f3f88a678ef2052b06e9ce/src/openai/resources/beta/agents/environments/templates.py).
+Templates do not contain a running workspace and do not select a provider image.
+An E2B `templateID:build_UUID` remains private operator packaging configuration.
+Each referencing Session obtains its own Environment through the same initialization
+and five-operation SandboxProvider path as inline configuration.
+
+## Supported batch
+
+- Create, retrieve, update, delete and list under `/v1/agents/environments/templates`.
+  Every operation requires project authentication and `OpenAI-Beta: agents=v1`.
+  CRUD/list works without an execution deployment.
+- Optional nullable name, preserved verbatim, with a local 1–256 Unicode character
+  bound. Network supports `enabled` and `disabled`; omitted/null create network
+  defaults to the pinned enabled policy. Update omission preserves; supplied name
+  or network replaces, with null clearing name or resetting network.
+- Empty/null installation fields retain empty defaults. Responses contain the
+  pinned metadata fields, empty arrays/objects as applicable and never `env` or
+  `setup_commands`. Populated confidential/installation inputs reject before storage.
+- Listing uses `after`, `limit` (1–100, default 20), and `order` (default `desc`).
+  Creation timestamp plus ID supplies stable local ordering. Missing/foreign IDs
+  and cursors return the same not-found result. No compute is allocated by CRUD.
+- Session `environment_template_id` resolves under the caller's tenant. Omitted
+  network inherits; enabled can narrow to disabled, never the reverse. Effective
+  configuration is frozen without passing the template ID to execution.
+- Updating/deleting a template does not change existing Sessions. Creation retries
+  recover recorded caller intent before template lookup, including after deletion;
+  changed intent conflicts. This is the existing local retry policy, not a claim of
+  complete upstream idempotency semantics.
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="https://your-core.example/v1", api_key="your-project-key")
+template = client.beta.agents.environments.templates.create(
+    name="Restricted outbound access", network={"access": "disabled"}
+)
+session = client.beta.agents.sessions.create(
+    agent={"model": "your-configured-model"},
+    environment={"type": "openai_hosted", "environment_template_id": template.id},
+    input="Create /workspace/outputs/report.txt containing the result of 6 * 7.",
+)
+# Inspect Session/Turn/Items and retrieve published Artifacts after completion.
+# Delete the Session to reclaim its Environment; template deletion is independent.
+```
+
+## Explicit gaps and evidence boundaries
+
+Nonempty `env`, `setup_commands`, `files`, `packages`, `capability_directories`,
+`skills` and `plugins`, plus restricted-domain network policy, remain unsupported
+for both templates and inline initialization. Files can still be written through
+the separately accepted live Files API after connection. Do not substitute that
+later write for before-start template materialization. Unsupported requests reject
+without echoing payloads; no secret-storage or initializer framework is introduced.
+
+The [hosted guide](https://developers.openai.com/api/docs/guides/agents-api/environments/openai-hosted)
+clarifies that configured env values are readable by Agent code, files/packages
+precede setup commands, nonzero setup prevents start, and runtime-reserved env names
+must reject. Implementing those populated fields requires a separate batch with
+common initialization, safe snapshots and failure/readiness acceptance.
+
+The [current Template reference](https://developers.openai.com/api/reference/python/resources/beta/subresources/agents/subresources/environments/subresources/templates)
+mentions different GA/beta defaults; this service retains `agents=v1` and the
+[fixed baseline](upstream.json), whose omitted network is enabled. Exact upstream
+errors, no-op timestamps, concurrent pagination and referenced Session null-network
+override semantics remain unverified. The last case explicitly rejects in this
+batch rather than guessing inheritance. This batch is not full protocol compatibility.
+
+## Verification
+
+`official_environment_templates.py` checks all five fixed-SDK operations plus raw
+HTTP, exact safe response shapes, field replacement/defaults, pagination, tenant
+isolation and rejected confidential canaries. `official_e2b_v1.py` opts in with
+private `verify_environment_templates: true`; it creates its actual native/model
+Sessions from public templates, verifies frozen snapshots and creation retries
+after update/delete, then reuses the existing execution, Files/Artifacts, isolation,
+cancellation and crash/history-recovery assertions. Its disabled-network Session
+inherits that policy from another template. Runtime and provider packaging are
+unchanged. Database integration tests cover persistence and concurrent field updates;
+API tests cover parsing and caller-intent distinctions.

contracts/agents-api/environments.md

@@ -6,7 +6,8 @@ implementation plan with partial current coverage. Public execution admits
 profile, and operator-configured Docker/E2B hosted profiles for Codex, Claude Code
 and MiniMax Code below.
 Environment retrieval supports safe metadata for these environment profiles;
-populated startup installations and templates remain missing. Live file listing
+[basic reusable templates](environment-templates.md) share inline initialization, while
+populated startup installations remain missing. Live file listing
 and local inline/source writes have [partial coverage and explicit local policies](environment-files.md).
 See [current coverage](README.md#public-semantics).
 
@@ -59,7 +60,7 @@ an existing allocation's Create.
 
 Omitted/null network defaults to enabled; explicit enabled and disabled use the
 same image with adapter-selected immutable native policy. Unsupported restricted
-domains, templates, populated env/packages/setup/files/plugins/skills/capability
+domains and populated env/packages/setup/files/plugins/skills/capability
 paths fail explicitly. Empty/null installation defaults produce safe empty metadata,
 not a live workspace inventory. Hosted MCP combinations remain unimplemented.