Align template and inline environment initialization (#39)

* Document template inline composition and official evidence

* fix(agents-api): compose template initialization overrides

* Verify template composition through official client and PostgreSQL

* Record composition checks and real Codex Docker evidence

Author: SaladDay

CONTRIBUTING.md

@@ -311,6 +311,13 @@ 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.
+For template-reference Session initialization, omitted/null env, files, commands
+and packages inherit. Overlay non-null env keys; replace non-null files and command
+lists, including empty lists. Select each package manager independently: omitted/null
+inherits, while a supplied list replaces that manager. Revalidate the effective
+configuration through the existing validators and freeze it through the same
+transaction as inline initialization. Keep caller intent separate from resolved
+configuration; do not add a second installer or pass merge rules to adapters.
 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

contracts/agents-api/README.md

@@ -174,7 +174,7 @@ user-managed enrollment remain outside this qualification.
 | Area | Missing or unverified scope |
 | --- | --- |
 | Subagents / multi_agent | Six reads and same-child recovery have three-harness Docker evidence; optional native operations, live child progress, full lifecycle/interactions and tool combinations remain explicit gaps |
-| Environment Templates | Unsupported restricted hostname forms, unqualified installation overrides/null network and exact hosted errors remain gaps. CRUD/list, files, env/setup/system/npm/Python, inline/referenced Skills, Plugins, workspace capability directories and Session references have recorded coverage. Environment Plugin MCP transport and placement limits are [listed separately](environment-templates.md#environment-origin-mcp-plugins) |
+| Environment Templates | Unsupported restricted hostname forms, null network/list selection and exact hosted errors remain gaps. Template-reference env/files/commands/packages composition follows [qualified field rules](environment-templates.md#template-and-inline-configuration-composition). CRUD/list, files, env/setup/system/npm/Python, inline/referenced Skills, Plugins, workspace capability directories and Session references have recorded coverage. Environment Plugin MCP transport and placement limits are [listed separately](environment-templates.md#environment-origin-mcp-plugins) |
 | Input and configuration | Non-text initial input, broader content/configuration unions and reasoning/verbosity combinations; [structured output](structured-output.md) has qualified Claude function profiles on none and Core-managed Docker openai_hosted, with other combinations remaining gaps |
 | Tools and interactions | [Deferred discovery qualification](tool-search.md), other tool types, effective tool-set enforcement and result/cancel publication ordering; MiniMax public functions and service-origin MCP remain unsupported |
 | Vault and Credentials | Archive semantics, in-flight token withdrawal and exact hosted selection/error behavior; static/OAuth CRUD, replacement and scoped dispatch-time refresh are implemented (see credential guide for qualification) |

contracts/agents-api/environment-templates.md

@@ -67,10 +67,10 @@ sizes for both variants. Initialization keeps file data out of ordinary configur
 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.
+Template `files` omission preserves on update; null/[] clears. In a referencing
+Session, omission and null inherit, while a supplied list replaces the entire file
+set, including `[]` clearing it. Paths are not merged between the two sources.
+The effective list retains the existing validation and tenant-owned source checks.
 
 Core initializes both paths with the same trusted file installer through Provider
 RunCommand. Daemon authentication remains available, but native preparation and live
@@ -495,8 +495,8 @@ precede setup commands, nonzero setup prevents start, and runtime-reserved env n
 must reject. The shared initialization batch implements those fields with encrypted snapshots
 and the existing readiness gate. Public reads show packages but omit env/commands.
 Template updates replace each supplied field; omission preserves it and null clears
-it. Referenced Sessions inherit the snapshot; explicit env/packages/setup overrides
-with a template ID reject while override semantics remain unconfirmed.
+it. Referencing Sessions use the composition rules below; these differ from
+Template.update replacement rules.
 
 Files and resolved Skills are installed first, followed by system, npm/Python packages and ordered commands;
 the default cwd is `/workspace`. One command or package operation has the existing
@@ -520,6 +520,100 @@ errors, no-op timestamps, concurrent pagination and referenced Session null-netw
 override semantics remain unverified. The last case explicitly rejects in this
 batch rather than guessing inheritance. This batch is not full protocol compatibility.
 
+## Template and inline configuration composition
+
+The pinned Session description applies the template before inline configuration.
+Owned official API probes on 2026-09-23 establish the following narrower behavior:
+
+| Session field | Omitted or null | Non-null inline value |
+|---|---|---|
+| `env` | Inherit template keys | Overlay by key; inline value wins, `{}` preserves all keys |
+| `setup_commands` | Inherit template sequence | Replace the sequence; `[]` clears it |
+| `files` | Inherit template file set | Replace the complete set; `[]` clears it |
+| `packages` | Inherit all managers | Resolve Python/npm/system independently; `{}` inherits all |
+| Individual package manager | Inherit its template list | Replace that list; `[]` clears it |
+
+Core performs this composition once, before the existing encrypted Session snapshot
+transaction. Env values, command bodies and inline bytes remain absent from public
+metadata. Effective package/file metadata reflects the selected inputs. Caller
+intent still distinguishes omission, null and explicit fields for the local creation
+retry policy; composition does not rewrite it. Later template/source changes do not
+rewrite committed initialization. Existing per-source and effective-size validation,
+network narrowing, Skill/Plugin selection and source authorization remain in place.
+No harness or Provider participates in the merge.
+
+The official evidence used SDK 3.13.0, upstream `d7c41ef`, and `agents=v1`:
+86 authenticated calls, nine owned Sessions, four lifetime Templates (including two
+cleaned setup-script assertion failures), and six completed real `gpt-6-astra` Turns.
+Four exit-zero command outputs confirmed env values and command replacement/order
+for omitted, populated, empty and null inputs. Two further outputs confirmed full
+file replacement and null inheritance, and an initialized empty listing confirmed
+`files=[]`. The omitted-files case reached the bounded readiness limit, so its
+inheritance proof is metadata-only. Package composition is also metadata evidence;
+these official probes do not independently establish installed package versions.
+All owned resources have successful public DELETE receipts; physical upstream
+sandbox destruction was not independently observed.
+
+Private evidence: `~/.parsar/remediation/20260923/template-inline-composition/`,
+subdirectories `official-env-setup` and `official-files-packages`. Reports retain
+fixed-source snapshots, raw status/body/request IDs, command-output proofs,
+accounting, cleanup and credential scans. This covers the observed fixtures rather
+than all possible combinations. Null network and null Skill/Plugin/directory list
+selection remain outside this batch. No new protocol version is introduced.
+
+### Core checks for composition (2026-09-23)
+
+`TestTemplateCompositionOfficialClientPostgres` uses the fixed strict SDK and raw
+HTTP against real Core handlers and PostgreSQL. Six accepted cases and seven
+rejected creation keys cover effective metadata, confidential frozen bytes and
+ordered commands, tenant/source isolation, combined setup-size rejection without
+partial records, and same-intent retries after template and source deletion.
+A second Store/handler verifies reopened persistence; it is not an OS process
+restart and does not run a model. API tests additionally cover raw caller intent,
+non-mutating composition and retained field validation.
+
+The integrated server gate ran `make -o check-web check` at `5589df0`; this includes
+real PostgreSQL tests, byte-for-byte sqlc generation, builds, native bridge checks
+and Rust tests/format/Clippy. A fresh `make check-web` ran locally against the same
+unchanged production diff: 287 client, 583 Web and 76 browser tests passed. Together
+they cover every required `make check` target. `make openapi` regenerated the
+Session description. The optional MiniMax packaged-native scratch/large-output
+probe was skipped because its optional profile variables were unset; this batch
+does not add MiniMax, Claude or E2B native qualification.
+
+### Real Codex Docker composition acceptance (2026-09-23)
+
+The exact `8019ac5` production build ran independently with Core, PostgreSQL and
+Docker Runtime against the real Kimi API. Three completed native model Turns prove:
+
+- A populated-inline Session observed env key precedence, whole-file replacement,
+  ordered replacement commands, Python `packaging==26.0`, and inherited npm/system
+  tools. Its prompt named only the read operation, not the expected canary values.
+- A separate inheritance Session observed null env/files/commands inheritance,
+  retained npm/system tools and absence of the explicitly cleared Python installation
+  directory. After template mutation/deletion and an actual Core process restart,
+  identical-key creation recovered its existing identity/configuration. A second
+  native Turn returned the exact same values and append trace: initialization did
+  not run again. The populated Session itself was not resumed in this run.
+
+Five owned Core Sessions were created over the acceptance attempts. The first two
+failed before any model Turn because the reused private Skill-only runner omitted
+Docker `nested_sandbox: true`, already required by the documented initialization
+profile. Correcting that operator setting resolved the proc-mount failure without
+production changes. In the corrected pair, the populated Session completed its
+native command, but the private runner then required an optional assistant `phase`
+and unwrapped JSON. The original message instead contained matching fenced JSON
+without phase. An offline check preserved and verified the original native output
+and message bytes; no model call was repeated. One new inheritance Session completed
+the remaining two Turns. These failed assertions and operator diagnostics are
+retained alongside successful evidence, not counted as extra successful runs.
+
+Private evidence is under the same batch's `live/` directory and records source,
+binary/image hashes, operator-setting changes, exact native output and cleanup.
+This is Codex/Docker qualification for the described composition paths, not renewed
+qualification of other harnesses or Providers, every package manager combination,
+or complete Template/Agents API semantics.
+
 ## Verification
 
 ### Restricted-network Docker acceptance (2026-09-21)

contracts/agents-api/openapi.yaml

@@ -2879,13 +2879,15 @@ paths:
         initialization lifecycle; requested network applies after setup. 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. Referenced files/env/packages/setup overrides are rejected
-        pending semantic verification. Tenant-owned environment_template_id references
-        inherit omitted network and allow only narrowing overrides. Referenced network:null
-        is explicitly unsupported pending semantic verification. 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;
+        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 network and allow only narrowing overrides. Referenced
+        network:null is explicitly unsupported pending semantic verification. 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-list omission inherits and a supplied list replaces; null overrides
         and null version selectors remain unqualified and reject. Source deletion/default

services/agents-api/internal/api/environment_templates_test.go

@@ -88,7 +88,7 @@ func TestTemplateResolutionAndCreationIntent(t *testing.T) {
 	if err := h.resolveTemplateEnvironment(t.Context(), "tenant-a", &narrower); err != nil {
 		t.Fatal(err)
 	}
-	for _, raw := range []string{`{"type":"openai_hosted","environment_template_id":null}`, `{"type":"none","environment_template_id":"saved"}`, `{"type":"openai_hosted","environment_template_id":"saved","network":null}`, `{"type":"openai_hosted","environment_template_id":"saved","env":{"KEY":"secret"}}`} {
+	for _, raw := range []string{`{"type":"openai_hosted","environment_template_id":null}`, `{"type":"none","environment_template_id":"saved"}`, `{"type":"openai_hosted","environment_template_id":"saved","network":null}`} {
 		if _, _, _, err := decodeTemplateEnvironment(json.RawMessage(raw)); err == nil {
 			t.Fatal("invalid reference accepted", raw)
 		}