Unify Environment preparation across managed and user machines

CONTRIBUTING.md

@@ -190,6 +190,9 @@ Two lifetimes stay separate:
 Closing a Session Executor does not release its allocation, destroy its
 Environment or delete its workspace; see
 [Executor and Turn lifetimes](docs/runtime-protocol.md#executor-and-turn-lifetimes).
+Environment preparation state belongs to the Environment, independently of any
+managed allocation. Both user-owned and managed machines use the same frozen
+preparation input and initializer; resource managers never run installation steps.
 Capability preparation follows [Environments](contracts/agents-api/environments.md#runtime-capability-preparation).
 The Runtime is not a sandbox; see
 [Runtime and outer isolation](docs/design-principles.md#runtime-and-outer-isolation).

apps/docs/content/docs/api-reference/sessions.mdx

@@ -123,29 +123,33 @@ _openapi:
           results alongside native workspace tools; HTTP MCP remains
           unsupported. Idle Sessions provision automatically; initial
           provisioning has no caller connection action. Network defaults to
-          enabled; disabled and restricted exact ASCII hostnames are supported.
-          Restricted policy requires 1–100 allowed domains. Unsupported hostname
-          forms and startup installations are rejected. Confidential env,
-          npm/Python packages and ordered setup commands use the shared
-          initialization lifecycle; requested network applies after setup.
-          System dependencies must be preinstalled in the sandbox image or
-          template, or on the host machine; packages.system is rejected. Initial
-          inline and tenant-owned file_id files freeze encrypted bytes before
-          provisioning, then install through the common Core lifecycle before
-          native execution or live Files access. With a template reference,
-          omitted/null files, env, packages and setup_commands inherit. Non-null
-          files and command lists replace; env overlays by key; each package
-          manager inherits on omission/null and otherwise replaces its list.
-          Empty lists clear their selected field. Tenant-owned
-          environment_template_id references inherit omitted/null network and
-          allow only narrowing overrides. Inline hosted network:null retains the
-          enabled default; updating a Template with network:null resets its
-          saved policy to enabled. Core freezes effective configuration;
-          template updates/deletion do not alter Session snapshots or
-          same-intent creation retries. Inline or tenant-owned skill_reference
-          Skills share initialization. Templates preserve
-          default/latest/explicit selectors; Session creation freezes concrete
-          metadata and encrypted content atomically. Skill, Plugin and
+          enabled; disabled and restricted policies reject before compute
+          allocation because the current Runtime cannot enforce them. The
+          x_agents_core.environment extension accepts common preparation fields
+          for either hosted or self-hosted placement: environment_template_id,
+          files, env, packages, setup_commands, skills, plugins and
+          capability_directories. Duplicate fields in environment and the
+          extension reject. Confidential env, npm/Python packages and ordered
+          setup commands use the same Environment-owned initialization
+          lifecycle; compute allocation does not own preparation. Unknown side
+          effects are not replayed after disconnect or restart. System
+          dependencies must be preinstalled in the sandbox image or template, or
+          on the host machine; packages.system is rejected. Initial inline and
+          tenant-owned file_id files freeze encrypted bytes before provisioning,
+          then install through the common Core lifecycle before native execution
+          or live Files access. With a template reference, omitted/null files,
+          env, packages and setup_commands inherit. Non-null files and command
+          lists replace; env overlays by key; each package manager inherits on
+          omission/null and otherwise replaces its list. Empty lists clear their
+          selected field. Tenant-owned environment_template_id references
+          inherit omitted/null network and allow only narrowing overrides.
+          Inline hosted network:null retains the enabled default; updating a
+          Template with network:null resets its saved policy to enabled. Core
+          freezes effective configuration; template updates/deletion do not
+          alter Session snapshots or same-intent creation retries. Inline or
+          tenant-owned skill_reference Skills share initialization. Templates
+          preserve default/latest/explicit selectors; Session creation freezes
+          concrete metadata and encrypted content atomically. Skill, Plugin and
           capability-directory list omission/null inherit; a non-null list
           replaces, including empty-list clearing. Omitted/null Skill version
           selectors resolve the default version. Source deletion/default updates

apps/docs/content/docs/environments-and-files.mdx

@@ -14,7 +14,7 @@ For hosted compute, the deployment selects E2B, Docker or microsandbox through
 [Hosted Sandbox Manager](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/HOSTED-SANDBOX-MANAGER.md).
 For the separate caller-managed E2B path, the user owns allocation, renewal and
 cleanup through the official SDK and [Runtime packaging](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/services/agents-api/deploy/e2b/README.md).
-[Templates](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-templates.md) remain a hosted-only resource path;
+[Templates](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-templates.md) provide reusable preparation; the Core extension also applies their execution configuration to user-managed machines;
 [Files](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environment-files.md) reuse the exact authorized local workspace.
 
 The internal Store now owns a durable Environment association for newly created
@@ -50,10 +50,10 @@ A committed creation interrupted before bootstrap is recovered without replaying
 an existing allocation's Create.
 
 Omitted/null network defaults to enabled. The daemon does not enforce disabled
-or restricted networking. An execution combination must reject unless its outer
-Environment implements and qualifies the requested behavior.
+or restricted networking. Current execution profiles reject both before Session
+creation and resource allocation.
 Templates and inline configuration share initial files, env, packages, ordered setup
-and inline or tenant-owned referenced Skills through ordered managed initialization.
+and inline or tenant-owned referenced Skills through ordered Environment initialization.
 The same authenticated daemon handles initial files, tool configuration, packages,
 setup, Skill/Plugin import and directory snapshot finalization through
 `runtime_prepare`. Providers place, create, bootstrap, inspect, renew and reclaim
@@ -142,8 +142,8 @@ bypass pending input. Function callbacks do not populate Environment installatio
 Mixed events and non-text input remain unsupported. Local capability directories
 use the same Runtime parser and installed snapshot as managed Skills and Plugins;
 preparation must finish before native execution. Reconnect reuses installed bytes,
-while new Sessions capture their own sources. Directory aliases and protected Runtime
-state are rejected. Platform support and isolation follow
+while new Sessions capture their own sources. Recursive references to the installed snapshot and escaping directory
+entries are rejected. Platform support and isolation follow
 [Platforms and isolation](#platforms-and-isolation). Enrollment must match either the `/workspace`
 logical alias or the exact canonical directory bound by the Runtime; selecting an
 arbitrary path does not grant access. `remote_url` is the configured daemon WebSocket URL,
@@ -368,7 +368,7 @@ effects have stopped. See
 
 ### Preparation order
 
-Core freezes resource versions, metadata and source selections. Managed
+Core freezes resource versions, metadata and source selections. Environment
 initialization runs in this order, every step over the common `runtime_prepare`
 exchange with the same daemon:
 
@@ -382,15 +382,56 @@ they never execute Core initialization commands. The common runner uses only
 neutral Environment/Session identity and a Runtime peer, with no Provider,
 deployment or OS branch. Harness differences belong to native adapters.
 
-A missing authenticated Runtime connection waits before capability
-initialization is claimed; an operation whose effect is unknown is not replayed.
-Self-hosted capability directories stay in immutable Environment configuration
-and never create a managed initialization row or allocation.
-
-Self-hosted input accepts only `workspace_directory` and optional local
-`capability_directories`, not managed Skill/Plugin archive fields or a hosted
-Template. Local directory discovery does not populate the public API-managed
-`skills` or `plugins` installation arrays; those describe API-managed uploads.
+A missing authenticated Runtime connection waits before initialization is claimed.
+The Environment owns durable `pending`, `running`, `complete` or `failed`
+initialization state. The leased Worker processes both locations with the same
+bounded initializer, independently of Provider maintenance. A running operation
+whose process-local owner is lost is failed as unconfirmed; setup is never replayed.
+A confirmed failure records only the safe step and exit status. Both failure paths
+settle pending input through the common Environment failure transaction. Failure
+alone does not destroy compute or remove a workspace.
+
+The pinned self-hosted input retains `workspace_directory` and optional local
+`capability_directories`. For portable preparation, applications may supply
+`x_agents_core.environment` at Session creation in either location. This is a Core
+extension, not an upstream self-hosted field. It accepts `environment_template_id`,
+`files`, `env`, `packages`, `setup_commands`, `skills`, `plugins` and
+`capability_directories`, with the same parsers and inheritance rules as hosted
+input. A field supplied in both places rejects, including explicit null; there is
+no hidden precedence. Machine location, sizing and network policy are not extension
+preparation fields. A self-hosted selection cannot use a template requiring a
+managed network restriction.
+
+```json
+{
+  "agent_id": "agent_example",
+  "environment": {
+    "type": "self_hosted",
+    "workspace_directory": "/home/user/project"
+  },
+  "x_agents_core": {
+    "environment": {
+      "environment_template_id": "env_template_example"
+    }
+  }
+}
+```
+
+Switching `environment` to `{"type":"openai_hosted"}` reuses that same
+preparation input. Resource resolution, Project authorization, concrete Skill
+versions, encrypted file contents and confidential tool variables are frozen at
+Session creation. Same-intent retries and reconnects reuse those snapshots;
+new Sessions resolve new versions. User-managed Environments never require an
+allocation record. Local directory discovery does not populate API-managed
+installation arrays; managed Skills, Plugins and initial files do, in either
+location. Session self-hosted responses retain their pinned connection shape;
+the Environment resource exposes the safe installation metadata.
+
+Transport `connected` is still a connection observation, not readiness. Execution
+and live file access wait for initialization, then the common native preparation
+owner validates the installed snapshot and Harness before admitting a Turn. The
+model-provider authority rule is unchanged: deployment credentials are not
+implicitly sent to user-owned machines.
 
 ### Transfer and paths
 
@@ -485,17 +526,16 @@ Native installation and validation limits are in the
 [native guide](/self-hosted-native). Historical acceptance evidence
 stays limited to its recorded binaries and inputs.
 
-### Allocation initialization lifecycle
+### Environment initialization and compute wake
 
-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 initialization operation per full
-maintenance scan. At allocation EOF, begin the next page in the same call rather
-than consume an observation interval on an empty page. Refill at most once, retain
-the 32-allocation per-call bound and the five-second ticker, and never loop on an
-empty store. For managed nodes these bounds apply independently to each node.
-Use process-local progress and the same node lifecycle gate as direct provisioning.
+Environment initialization has pending, running, complete and failed states.
+Authentication and connection publication are independent of preparation. Execution
+bindings and live Files wait for initialization. The leased Worker's common
+scheduler scans 32 Environments at a time, wraps at EOF and bounds concurrent
+preparations by execution concurrency. Missing sockets do not consume a pending
+attempt; unavailable Harnesses fail before installation. Each operation rechecks
+current authority and the original socket. Completion rechecks the exact binding.
+Provider bootstrap and resource cleanup retain their own owners and settlement.
 
 After a next-Turn input is durably pending, a completed managed allocation in a
 suspension/recovery phase may hint this loop. Initial inputs, cold creation,
@@ -510,8 +550,9 @@ ownership checks. Never close the hint channel while handlers may still send.
 This bounds extra maintenance work but does not bypass capacity, a busy lifecycle
 gate or multi-page scheduling, and does not guarantee a resume deadline.
 
-A recovered or uncertain running installation fails and uses existing cleanup, without replaying writes.
-A hosted provisioning failure is terminal for its Session. The allocation's cleanup
+A recovered or uncertain running installation fails without replaying writes.
+Preparation failure is terminal for its Session. It does not destroy compute or
+user files; explicit resource cleanup retains its existing owner. The Environment
 transaction stores a safe reason with the failed Environment and records
 `environment.failed`, `error` and one `agent.session.failed`; Session reads derive
 `failed`, that reason and the failure time from the same record, and live streams end
@@ -735,4 +776,15 @@ executor interoperability requirement. The superseded execution route is removed
 retain reusable filesystem helpers,
 necessary regressions and historical evidence without a compatibility layer.
 
+### Explicit local tool environment
+
+`--tool-env-file` supplies the Runtime operator's base tool variables. Common
+preparation copies these explicit values into its private initialization snapshot;
+explicit Session `env` keys override the base. Runtime does not rewrite the source
+file or inherit unrelated ambient credentials. Setup, capability resolution and
+Harness execution read the same prepared snapshot. Reconnect preserves that
+snapshot even if the operator edits the source; a new installation for a new
+Session reads the current source. A missing or invalid explicitly configured file
+fails preparation.
+
 [Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/contracts/agents-api/environments.md)

apps/docs/content/docs/runtime-protocol.mdx

@@ -515,4 +515,15 @@ its controlled native subprocess fixture. New adapters can call the same asserti
 no optional feature is implied. Native failures, uncertain cleanup and exact-history
 recovery still require the adapter's fault and real-provider acceptance tests.
 
+### Environment preparation ownership
+
+Core tracks initialization on the Environment, independently of a managed
+allocation. After authentication, both managed and user-owned Runtime connections
+receive the same `runtime_prepare` operations and resource snapshots. Core never
+replays a running initialization whose owner or confirmation was lost. Preparation
+failure settles Environment input without destroying the machine or workspace.
+The public `connected` state describes transport; initialization completion and
+native executor readiness remain separate prerequisites for execution. Input
+sources and frozen metadata follow the [Environment contract](/environments-and-files#runtime-capability-preparation).
+
 [Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/runtime-protocol.md)

apps/docs/content/docs/self-hosted-execution.mdx

@@ -75,10 +75,28 @@ environment = {
 
 Core accepts absolute Unix, Windows drive and UNC source paths without checking
 its own filesystem. Runtime validates them using the executor host's path syntax.
-Populate these directories before first execution. They are ordinary paths visible
+Populate these directories before connecting the Runtime. They are ordinary paths visible
 to that process; naming a directory does not mount it or create a sandbox.
-Self-hosted public input accepts local directories, not managed Skill/Plugin
-archives or hosted Templates.
+Use `x_agents_core.environment` for the same project-owned Skills, Plugin archives,
+files, dependencies, setup commands or Template used by a managed Session:
+
+```python
+session = client.beta.agents.sessions.create(
+    agent_id=agent_id,
+    environment=environment,
+    extra_body={"x_agents_core": {
+        "model_provider": model_provider,
+        "environment": {"environment_template_id": template_id},
+    }},
+)
+```
+
+The same extension works with `environment={"type": "openai_hosted"}`. Do not
+repeat a field in both `environment` and the extension. The
+[preparation contract](/environments-and-files#runtime-capability-preparation)
+lists fields, merge rules and failure semantics. Your machine needs the selected
+Harness and any required system dependencies; setup uses your account permissions.
+Deployment model keys are never sent automatically to a user-managed machine.
 
 Runtime snapshots sources before native execution and uses the same parser and
 `installed.json` format as managed bundles to supply Skills and Plugin MCP.

apps/docs/content/docs/self-hosted-native.mdx

@@ -171,4 +171,7 @@ On Windows, stdio MCP commands named npm or npx (including explicit .cmd
 paths) run through the selected installation's JavaScript entrypoint with Node.
 Other batch wrappers require an explicit cmd.exe command and its arguments.
 
+For precedence and snapshot behavior of `--tool-env-file` with Session
+preparation, see the [Environment contract](/environments-and-files#explicit-local-tool-environment).
+
 [Repository source](https://github.com/MiniMax-AI/parsar-core/blob/f6d258735fc601c521dd990e6f9e1ed261f4ef2d/docs/self-hosted-native.md)