feat(agents-api): initialize hosted environments from template and inline files

CONTRIBUTING.md

@@ -52,12 +52,14 @@ Direct development on `main` is not allowed. Every session honours this rule.
 
 ## Independent blind review
 
-Each PR should contain one independently verifiable change; a feature may span
-several small PRs. Two or three closely related subtasks may share one functional
-PR; internal wiring steps do not require separate delivery gates. Run focused
-tests during development, then complete the full checks and applicable real
-regression once the batch stabilizes. State the expected behavior, acceptance
-results, stopping conditions and explicit scope exclusions before implementation.
+Each PR should deliver a bounded, independently usable and verifiable capability.
+Combine closely related changes that share initialization and security boundaries;
+Environment Template follow-ups should not split by field or internal wiring step.
+Separate work with independent risk or an unresolved design. Run focused tests
+during development, then complete full checks, real regression and the required
+review once the scope stabilizes, without repeating that gate for every substep.
+State acceptance results, the scope ceiling, exclusions and stopping conditions
+before implementation. Batch size must not weaken security or data consistency.
 Check uncertain design choices early. Reassess any new prerequisite against those
 results before adding it; do not let a functional batch grow without a stopping
 point. Keep unrelated refactors, features,
@@ -260,11 +262,29 @@ 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.
+Updates and deletion cannot rewrite existing Session snapshots. Initial files use
+one Core-owned installer for template and inline configurations. Keep confidential
+bytes encrypted under the execution-service key and resource-bound AEAD, separately
+from ordinary configuration and public metadata. Templates retain source references;
+Session creation freezes tenant-authorized source bytes in the same commit, independent
+of later source/template deletion. Public resource reads must not require decryption
+or load encrypted file bodies. Record original creation intent before resolution.
+
+The allocation lifecycle owns pending/running/complete initialization. Authentication
+may connect the daemon during initialization; execution bindings, native preparation,
+live Files and connected publication wait for completion. Keep Provider bootstrap
+settlement distinct. Advance at most one bounded file per full maintenance scan,
+using process-local progress and the existing lifecycle gate. A recovered or uncertain
+running installation fails and uses existing cleanup, without replaying writes.
+Completed environments never reinstall initial files on reconnect or native recovery.
+Provider RunCommand carries bounded stdin, not confidential argv. Only fixed trusted
+initializers may run with Runtime authority; user setup scripts remain unsupported.
+Reuse the packaged atomic file writer and anchored parent creation across all profiles.
+
+Name, enabled/disabled network and initial files are qualified independently of other
+installation fields. Reject unsupported inputs rather than persisting them for silent
+omission; expand 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.

contracts/agents-api/README.md

@@ -87,9 +87,9 @@ the Python SDK. Vault HTTP paths start at `/vaults`, not `/agents/vaults`.
 | sessions.subagents.items | list | Missing |
 | sessions.subagents.turns | retrieve, list | Missing |
 | 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 | retrieve | Supported Codex self-hosted and three-harness Docker/E2B hosted profiles: durable status and safe initial-file metadata; other 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 | [Basic reusable network configuration and Session snapshots](environment-templates.md); populated initialization and full semantics remain gaps |
+| environments.templates | create, retrieve, update, list, delete | [Reusable network/initial-file configuration and Session snapshots](environment-templates.md); other 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 |
 
@@ -155,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 | Populated initialization/confidential inputs, restricted network, referenced null override semantics and exact hosted errors; basic CRUD/list and Session references are supported |
+| Environment Templates | Other populated initialization, restricted network, referenced files overrides/null network and exact hosted errors; CRUD/list, initial files 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 |
@@ -351,14 +351,14 @@ including further deployment qualification; this inventory describes merged beha
   Provider adaptation must be explicit and verified before advertising support.
 - Environment retrieval returns `object: agent.environment`, its ID/type, durable
   resource status and required non-null `files`, `plugins` and `skills` arrays.
-  The supported profile has no API-managed installations; empty arrays do not
+  Hosted initial files report safe frozen metadata; empty arrays do not
   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, full hosted lifecycle and
+  Other 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
+[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.
 
@@ -399,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 and hosted public
+Other 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

@@ -1,4 +1,4 @@
-# Environment Templates: basic hosted configuration
+# Environment Templates and initial files
 
 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).
@@ -16,9 +16,9 @@ and five-operation SandboxProvider path as inline configuration.
   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.
+- Empty/null installation fields retain empty defaults. Responses contain safe
+  metadata and never `env`, `setup_commands` or inline file data. Initial files are
+  supported as described below; other populated installations reject explicitly.
 - 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.
@@ -46,14 +46,49 @@ session = client.beta.agents.sessions.create(
 # Delete the Session to reclaim its Environment; template deletion is independent.
 ```
 
+## Initial files
+
+Both inline hosted configuration and reusable templates accept `files` entries with
+an absolute destination inside `/workspace`: `inline` with standard-base64 `data`, or
+`file_id` referencing a project-owned Files API upload. The guide's limits are 50
+initial files, 5 MiB per inline file, 10 MiB total inline content, and 50 MiB per
+referenced file. Session/Template JSON requests allow 16 MiB for the base64 envelope.
+Paths must be canonical, distinct and stay within the workspace; symlinks are not
+followed. A failed install never starts native execution.
+
+Configure `AGENTS_API_CREDENTIAL_KEY_FILE` with the existing execution-service
+base64 32-byte encryption key. Template writes and Session resolution need it;
+ordinary metadata reads do not. Template inline metadata contains type/path/size,
+while references contain type/path/file_id. Sessions receive fresh file IDs and
+sizes for both variants. Initialization keeps file data out of ordinary configuration,
+resource responses, lifecycle events and command arguments. Templates keep references; each Session authorizes and
+freezes its own encrypted source bytes. Later source deletion cannot change them.
+
+Template `files` omission preserves on update; null/[] clears. Referenced Sessions
+inherit files. Supplying `files` together with `environment_template_id`, including
+null/[], explicitly rejects while replacement/merge/null semantics remain unconfirmed.
+Use a complete standalone inline configuration when a different file set is needed.
+
+Core initializes both paths with the same trusted file installer through Provider
+RunCommand. Daemon authentication remains available, but native preparation and live
+Files wait for all writes. Each file gets a two-minute transfer budget; the batch has
+a thirty-minute local budget and shares maintenance scans with other allocations.
+These are local operational limits, not verified upstream timing. Initial input
+retains its existing five-minute admission deadline; large installations can use an
+idle Session and wait for connected status before submitting input.
+
+Uncertain writes and Core restart during initialization fail the new Environment and
+reclaim it; they do not replay partial installation. After completion, reconnect and
+native-history recovery preserve user modifications instead of reinstalling files.
+Docker/E2B and all three harnesses use this same lifecycle. The Provider API remains
+five operations; public Templates are never E2B image templates.
+
 ## Explicit gaps and evidence boundaries
 
-Nonempty `env`, `setup_commands`, `files`, `packages`, `capability_directories`,
+Nonempty `env`, `setup_commands`, `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.
+for both templates and inline initialization. The separate live Files API remains
+available after initialization. Unsupported requests reject without echoing payloads.
 
 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
@@ -80,3 +115,44 @@ 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.
+
+`official_environment_initial_files.py` and the `verify_initial_files: true` option
+together with `verify_environment_templates: true` in the real E2B runner add
+both-source/template/inline metadata, source-deletion,
+foreign-tenant and actual first-native-read checks. Existing Files/Artifacts,
+cancel/crash/history checks then verify that initialization did not change the
+execution loop or overwrite later user modifications. Controlled PostgreSQL lifecycle
+tests separately exercise interrupted installation, readiness and maintenance fairness.
+A test's presence is not a passing acceptance result; retain actual run evidence.
+
+### Accepted initial-file profiles (2026-09-20)
+
+The batch passed fixed SDK 3.13.0/raw HTTP acceptance with real models on Docker
+and E2B for Codex, Claude Code and MiniMax Code. Both template and inline paths
+verified initial native reads, Files/Artifacts, tenant and credential isolation,
+source/template deletion followed by creation retry, cancellation, and preserved
+workspace changes/native history after Core and Runtime restarts. E2B also verified
+Core interruption during initialization: no native execution, no replay and owned
+resource reclamation. All six completed runs reported clean resource cleanup.
+
+Separate real Provider checks covered Docker binary stdin/backpressure and E2B
+50 MiB stdin. The real shared installer verified empty, binary, nested and 50 MiB
+files, rejected symlink destinations, and preserved outside bytes. PostgreSQL/race
+suites and `make check` passed. The optional native build probe skipped by the
+default gate is not counted as real acceptance. Runtime images were the retained
+qualified builds; Core was built from this batch. E2B runs preceded the final
+readiness guard and store-interface cleanup, which received targeted regression;
+The six-profile matrix preceded final creation-intent size and canonical-identity
+corrections. Real HTTP/PostgreSQL regression accepted a 1 MiB file and two 5 MiB
+inline files with retries, and verified canonical template/file encryption bindings.
+A further rebuilt standalone Docker/Codex run passed a 5 MiB initial file with
+real model reads, Artifacts, cancellation and retained history in 101.23 seconds.
+The original Docker matrix used Core SHA-256
+`31973b17dd96106743e581c400555e3a4b036ad8cb3e68b51530a2b56023abe3`.
+
+Docker MiniMax Code passed with the real MiniMax API at its standard HTTPS origin
+through the test network relay. Earlier Kimi/MiniMax connection timeouts remain
+recorded with unknown cause, as does a Docker reconnect failure under a different
+Core/Runtime restart order. They are not claimed as fixed. Sanitized run results,
+checks, build hashes and failed attempts are retained under the private
+`environment-template-files` acceptance directory and the linked task record.

contracts/agents-api/environments.md

@@ -6,8 +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;
-[basic reusable templates](environment-templates.md) share inline initialization, while
-populated startup installations remain missing. Live file listing
+[reusable templates and initial files](environment-templates.md) share inline initialization.
+Other 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).
 
@@ -60,8 +60,8 @@ 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 and populated env/packages/setup/files/plugins/skills/capability
-paths fail explicitly. Empty/null installation defaults produce safe empty metadata,
+domains and populated env/packages/setup/plugins/skills/capability
+paths fail explicitly. Initial inline/file_id files use the shared hosted initializer. Empty/null installation defaults produce safe empty metadata,
 not a live workspace inventory. Hosted MCP combinations remain unimplemented.
 
 Initial provisioning leaves a Session idle until a Turn starts, with no caller