Give deployment default model providers one home and close the self-hosted model gap

CONTRIBUTING.md

@@ -2228,18 +2228,29 @@ replaced; do not carry obsolete compatibility code forward to satisfy this secti
   require no key. Validate the merged harness/protocol/limits without reading keys.
   Read safe defaults and ciphertext in one database snapshot for Session creation;
   a complete Session override need not decrypt the inherited bundle.
-- Hosted Session provider selection resolves explicit bundle, saved bundle, then
-  deployment bundle, and freezes it in the existing encrypted Session-owned row.
-  Convert existing native operator options only at server composition, never in
-  scheduling. Retain the complete selected operator options in the private encrypted
-  Session snapshot for deployment fallback, preserving headers, query parameters
-  and native settings; do not reconstruct them from a smaller public input type. Keep runtime dispatch on the common adapter path and fail closed for
-  missing/decryption-failed snapshots. Agent edits/deletion, restart and idle
-  suspend/resume never resolve defaults again. Record caller intent for every new
-  hosted Session before resolving defaults, including inline deployment fallback;
-  matching retries return committed state without replay. No Turn-level overrides,
-  provider catalog or self-hosted/none credential expansion is included. Public
-  input/null semantics and examples live in `contracts/agents-api/model-execution.md`.
+- Session provider selection resolves explicit bundle, saved bundle, then the
+  deployment default of the resolved harness, and freezes it in the existing
+  encrypted Session-owned row. The deployment default is a runtime setting: one
+  complete bundle per harness in PostgreSQL, encrypted with its own
+  harness-bound purpose, managed only with the Core key through
+  `/core/v1/harnesses/{harness}/model-provider`, audited as a deployment-wide
+  write without the key, and never read back. It applies to `openai_hosted` and
+  operator-registered `none` Sessions, never to `self_hosted`, whose executor host
+  belongs to the application. Caller bundles apply to `openai_hosted` and
+  `self_hosted`. Hosted and self-hosted Sessions with no bundle are rejected at
+  creation with `model_provider_required`; legacy rows without a snapshot are
+  rejected at message admission and dispatch, never sent to a harness that would
+  fall back to a built-in endpoint. There is no operator options file: its
+  retirement fails startup, and historical snapshots keep their frozen native
+  options. Keep runtime dispatch on the common adapter path and fail closed for
+  missing/decryption-failed snapshots. Agent edits/deletion, default changes,
+  restart and idle suspend/resume never resolve defaults again. Record caller
+  intent for every new hosted Session before resolving defaults; other inline
+  Sessions keep the resolved-request rule, whose hash leaves out the deployment
+  default. Provider keys enter retry hashes only as keyed fingerprints. Matching
+  retries return committed state without replay. No Turn-level overrides or provider catalog is
+  included. Public input/null semantics and examples live in
+  `contracts/agents-api/model-execution.md`.
 - Session execution-configuration reads use a separate immutable safe projection,
   written with provenance in the same creation transaction as Session resources.
   Read no credential ciphertext and never recompute sources from current Agents
@@ -2475,7 +2486,7 @@ replaced; do not carry obsolete compatibility code forward to satisfy this secti
   before binding/claiming work. Older peers with only option-based capabilities
   must not receive controls they would ignore. The API sends resolved search and
   text verbosity values; native option names belong to adapters. Codex translates
-  them using its existing validation/catalog path after cloning operator options,
+  them using its existing validation/catalog path after cloning adapter options,
   so explicit controls take precedence without mutating those options. Omitting
   the entire block preserves ordinary product behavior; a supplied block requires
   both valid fields. This internal contract does not add public configuration or
@@ -3283,10 +3294,10 @@ success-dependent limitations remain in the profile. Image-bearing delivery alon
 requires Runtime function-result image support; text results and function
 declarations do not acquire that requirement. These are implementation limits, not changes to the upstream contract.
 Do not bypass them by dropping fields, changing model identity or fabricating usage.
-Operators may configure the daemon provider environment or the existing transient
-`AGENTS_API_EXECUTION_OPTIONS_FILE` with adapter-owned `claude_provider`
-(`base_url` HTTPS and `bearer_token`). Core forwards these opaque options without
-persisting them in Session configuration. The adapter exclusively selects the
+Operators may configure the daemon provider environment or the deployment default
+model provider for `claude_sdk` (HTTPS `base_url` and a write-only key), which Core
+freezes in the Session's encrypted snapshot and delivers as the adapter-owned
+`claude_provider`; it never enters public Session configuration. The adapter exclusively selects the
 provider environment and removes credentials from native tool environments. Product `claude_code` and product execution are unchanged.
 The `none` public profile accepts only
 text, explicit model/system instructions, managed state, exact native resume and

contracts/agents-api/README.md

@@ -485,7 +485,9 @@ operation and placement; native support is not public admission by itself.
 
 All three profiles implement user-managed `self_hosted` enrollment at `/workspace`
 through our private daemon transport; [separate real acceptance](user-managed-runtime-v1.md)
-records qualified deployments and limits. Service-origin HTTP MCP is rejected on `self_hosted` and hosted local
+records qualified deployments and limits. A `self_hosted` Session supplies its own
+model provider in the request or through a saved Agent; deployment defaults apply
+to `openai_hosted` and `none`, never to `self_hosted` ([model execution](model-execution.md)). Service-origin HTTP MCP is rejected on `self_hosted` and hosted local
 placements. This does not remove separately qualified Environment Plugin MCP.
 The [Docker lifecycle](environments.md#basic-public-docker-hosted-profile) retains
 workspace Files/Artifacts, cancellation and recovery with native isolation.

contracts/agents-api/admin-api.md

@@ -166,7 +166,10 @@ display label: normally `console` from Web and empty from direct Core key reques
 `project_id`, `resource_type`, `resource_id`, `result_ids`, `request_id`,
 `trace_id`. `result_ids` is an empty array except on historical `copy` entries.
 Executor credential writes appear with `resource_type:"executor_credential"`,
-the key ID as `resource_id` and action `issue`, `rotate` or `revoke`.
+the key ID as `resource_id` and action `issue`, `rotate` or `revoke`. Deployment
+default model provider writes are deployment-wide: `project_id` is null,
+`resource_type:"deployment_model_provider"`, the harness as `resource_id` and
+action `set` or `delete`; a `project_id` filter excludes them.
 No credential values or request bodies are recorded. Logs and historical copy
 ownership do not cascade away on resource removal or key revocation.
 

contracts/agents-api/core.openapi.yaml

@@ -180,6 +180,47 @@ definitions:
       total_sessions:
         type: integer
     type: object
+  api.CoreHarness:
+    properties:
+      default:
+        type: boolean
+      enabled:
+        type: boolean
+      id:
+        enum:
+          - claude_sdk
+          - codex
+          - mcode
+        type: string
+      model_provider:
+        allOf:
+          - $ref: '#/definitions/api.HarnessModelProvider'
+        x-nullable: true
+      object:
+        enum:
+          - core.harness
+        type: string
+    required:
+      - default
+      - enabled
+      - id
+      - model_provider
+      - object
+    type: object
+  api.CoreHarnessList:
+    properties:
+      data:
+        items:
+          $ref: '#/definitions/api.CoreHarness'
+        type: array
+      object:
+        enum:
+          - list
+        type: string
+    required:
+      - data
+      - object
+    type: object
   api.EnvironmentExecutorCredentialRequest:
     properties:
       key_id:
@@ -195,6 +236,41 @@ definitions:
           $ref: '#/definitions/store.ExecutorCredential'
         type: array
     type: object
+  api.HarnessModelProvider:
+    properties:
+      api_key_configured:
+        type: boolean
+      base_url:
+        type: string
+      context_window:
+        type: integer
+      harness:
+        enum:
+          - claude_sdk
+          - codex
+          - mcode
+        type: string
+      max_output_tokens:
+        type: integer
+      object:
+        enum:
+          - core.model_provider
+        type: string
+      protocol:
+        enum:
+          - anthropic
+          - responses
+        type: string
+      updated_at:
+        type: string
+    required:
+      - api_key_configured
+      - base_url
+      - harness
+      - object
+      - protocol
+      - updated_at
+    type: object
   api.Installation:
     properties:
       address_bindings:
@@ -638,6 +714,7 @@ definitions:
         type: string
       project_id:
         type: string
+        x-nullable: true
       request_id:
         type: string
       resource_id:
@@ -1559,6 +1636,26 @@ definitions:
       - has_more
       - object
     type: object
+  v1.ModelProviderInput:
+    properties:
+      api_key:
+        type: string
+      base_url:
+        type: string
+      context_window:
+        type: integer
+      max_output_tokens:
+        type: integer
+      protocol:
+        enum:
+          - anthropic
+          - responses
+        type: string
+    required:
+      - api_key
+      - base_url
+      - protocol
+    type: object
   v1.ModelProviderView:
     properties:
       api_key_configured:
@@ -2969,6 +3066,154 @@ paths:
       summary: Query committed administrator mutations
       tags:
         - Core Administration
+  /core/v1/harnesses:
+    get:
+      description: Core key only. Returns every harness this build supports, in name order. enabled and default are read-only views of the process configuration (AGENTS_API_ENGINE and AGENTS_API_HARNESSES). model_provider is the harness's deployment default, stored in Core, or null. Keys are never returned; api_key_configured reports that one is set.
+      produces:
+        - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/api.CoreHarnessList'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+      security:
+        - DeploymentAdminAuth: []
+      summary: List harnesses and their deployment default model providers
+      tags:
+        - Deployment Model Providers
+  /core/v1/harnesses/{harness}/model-provider:
+    delete:
+      description: Core key only. Idempotent; each successful request is audited. Sessions that already froze the default keep it. Afterwards new openai_hosted Sessions for this harness need a Session or Agent bundle.
+      parameters:
+        - description: Harness
+          enum:
+            - claude_sdk
+            - codex
+            - mcode
+          in: path
+          name: harness
+          required: true
+          type: string
+      responses:
+        "204":
+          description: No Content
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+      security:
+        - DeploymentAdminAuth: []
+      summary: Remove a harness's deployment default model provider
+      tags:
+        - Deployment Model Providers
+    get:
+      description: Core key only. Returns the safe view; the key is never returned. 404 when the harness does not exist or has no deployment default.
+      parameters:
+        - description: Harness
+          enum:
+            - claude_sdk
+            - codex
+            - mcode
+          in: path
+          name: harness
+          required: true
+          type: string
+      produces:
+        - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/api.HarnessModelProvider'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+      security:
+        - DeploymentAdminAuth: []
+      summary: Retrieve a harness's deployment default model provider
+      tags:
+        - Deployment Model Providers
+    put:
+      consumes:
+        - application/json
+      description: 'Core key only. The body is the complete x_agents_core.model_provider bundle, including the write-only api_key; there is no partial update and bundles are never merged. The provider is validated for this harness: an HTTPS base_url without credentials, query or fragment, the harness''s protocol (responses for codex, anthropic for claude_sdk and mcode) and, for mcode, positive context_window and max_output_tokens. New openai_hosted and none Sessions that resolve no Session or Agent bundle freeze this default into their encrypted snapshot; existing Sessions never change. self_hosted Sessions never use it. The key is encrypted and never returned. Each write records an administrator audit entry without the key.'
+      parameters:
+        - description: Harness
+          enum:
+            - claude_sdk
+            - codex
+            - mcode
+          in: path
+          name: harness
+          required: true
+          type: string
+        - description: Complete model provider bundle
+          in: body
+          name: body
+          required: true
+          schema:
+            $ref: '#/definitions/v1.ModelProviderInput'
+      produces:
+        - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/api.HarnessModelProvider'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "401":
+          description: Unauthorized
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "413":
+          description: Request Entity Too Large
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/v1.ErrorResponse'
+      security:
+        - DeploymentAdminAuth: []
+      summary: Replace a harness's deployment default model provider
+      tags:
+        - Deployment Model Providers
   /core/v1/installation:
     get:
       description: Core key only; available before any sandbox deployment exists. Reports the public URL that applications, nodes, sandboxes and self-hosted executors use, the API base URL, Core's source commit and installation ID, the installer's settings snapshot with where to change it, and what is bound to the current public URL. Sensitive settings report only whether they are configured.
@@ -4422,7 +4667,7 @@ paths:
         - Artifacts
   /core/v1/projects/{project_id}/sessions/{session_id}/execution-configuration:
     get:
-      description: Core key only; the Project ID selects the target space and does not authenticate. Returns the committed model, harness and safe provider selection with recorded sources. This read never decrypts credentials, resolves current defaults or probes execution health. Deployment provider details remain redacted. Historical provenance and missing provider projections are explicitly unknown/unavailable.
+      description: Core key only; the Project ID selects the target space and does not authenticate. Returns the committed model, harness and safe provider selection with recorded sources. This read never decrypts credentials, resolves current defaults or probes execution health. Deployment defaults frozen after they moved into Core show their safe view; older deployment selections remain redacted. Historical provenance and missing provider projections are explicitly unknown/unavailable.
       parameters:
         - description: Session ID
           in: path

contracts/agents-api/environment-executor-credentials.md

@@ -70,6 +70,21 @@ never contains the secret. Credentials issued by the operator CLI
 (`agents-api-environment-key`) without an Environment restriction cannot be
 managed through these routes.
 
+## Model provider
+
+The Session carries its own model provider: `x_agents_core.model_provider` at
+creation or a saved Agent that has one. Deployment default model providers do not
+apply to `self_hosted` Sessions, and creation without a provider fails with 400
+`model_provider_required`. Core freezes the bundle in the Session's encrypted
+snapshot and sends it only over the connection of the executor enrolled for this
+Environment with a current credential of the Session creator's principal. The
+executor keeps it in the Runtime's native harness home, which tools and public
+Files cannot read; the executor host's owner can. Revocation does not erase a
+bundle already delivered. A saved Agent's provider key is delivered to the
+executor of every `self_hosted` Session created with that Agent in the Project, so
+anyone who can create `self_hosted` Sessions in the Project and run an executor
+can read it.
+
 ## Executor host
 
 The distribution's `self-hosted-install.pyz` downloads the matching