Document the Core/Web boundary and drop unused public security schemes

AGENTS.md

@@ -13,7 +13,7 @@ no credential works in another namespace.
 | --- | --- | --- | --- |
 | `/v1` | Applications | Project API key | Exactly the pinned OpenAI Agents API route set ([upstream.json](contracts/agents-api/upstream.json): SDK 3.13.0, `agents=v1`). Fields the official types lack live only in `x_agents_core` on Agents and Sessions (`harness`, `model_provider`). Nothing about deployment belongs here. |
 | `/core/v1` | Core Web's server and operator scripts | Core key; Core stores its digest | Everything about operating the deployment: Projects and keys, resource reads and deletion, Session archive, credential issuance (node enrollment tokens, executor credentials), observability, audit, sandbox deployment and nodes. |
-| `/api/v1` | Nodes, Runtime daemons, self-hosted executors | Machine credentials issued through `/core/v1` | Machine connections only; each credential works only on its own routes. |
+| `/api/v1` | Nodes, Runtime daemons, self-hosted executors | Machine credentials: enrollment tokens and executor credentials issued through `/core/v1`; nodes register their own credential with an enrollment token; Core writes daemon credentials into hosted sandboxes | Machine connections only; each credential works only on its own routes. |
 
 - Core Web calls only `/core/v1`, through the Core clients in
   `packages/agents-client` (`AdminClient`, `SandboxAdminClient`,

CONTRIBUTING.md

@@ -51,11 +51,10 @@ Keep administrator target scope separate from caller principals. See
 
 Administrator writes and their audit record share one PostgreSQL transaction.
 Reuse existing resource deletion and serialization code. Cross-Project copying was
-removed. `admin_resource_owners` alone feeds the historical `source:"admin_copy"`
-provenance read; `admin_asset_copies` is retained only because tables are not
-dropped. Unknown historical provenance remains unknown. No secrets or request
-bodies enter logs. The console's fixed actor label (`console`) is only an audit
-display label, never an authorization input.
+removed; only the historical `source:"admin_copy"` provenance read remains, fed by
+`admin_resource_owners`. Unknown historical provenance remains unknown. No secrets
+or request bodies enter logs. The console's fixed actor label (`console`) is only
+an audit display label, never an authorization input.
 
 When requirements conflict, object ownership is unclear, or a design would need
 parallel compatibility paths, raise the issue with a concrete recommendation and
@@ -193,9 +192,9 @@ coverage ledgers and official SDK/raw HTTP tests when changing API behavior.
 Run `make openapi` after handler annotation changes. It reuses the original
 Core-only swaggo v1.16.4 generator, then splits the result by namespace: `/v1`
 into `openapi.yaml`, `/core/v1` into `core.openapi.yaml` and `/api/v1` into
-`runtime.openapi.yaml` (the last two with base path `/`), each keeping only the
-security schemes its operations use. All generated schemas remain free of product
-routes.
+`runtime.openapi.yaml`; the last two use base path `/`, and each document keeps
+only the security schemes its operations use. All generated schemas remain free
+of product routes.
 
 Core changes must retain the independent build and official-client workflow.
 Native adapter changes require their applicable build/check targets and live provider
@@ -780,9 +779,9 @@ A locally unavailable provider dependency keeps hosted admission closed while th
 existing scan waits for repair; administrator recovery remains available, including
 on restart. Database and ownership errors remain failures. Unconfigured hosted
 admission creates no Session state. Derive Runtime bootstrap and daemon WebSocket
-addresses from the saved validated origin, never inbound Host headers. Use the live
-deployment API for selections made after startup; the startup configuration API
-remains a startup snapshot.
+addresses from the saved validated origin, never inbound Host headers. Read the
+current selection from the live deployment API; there is no startup configuration
+read.
 
 Provider, resources and Runtime changes require maintenance, the current generation
 and verified zero retained or pending resources. The Core origin remains unchanged
@@ -1861,9 +1860,9 @@ Nodes and Core come from one distribution; older nodes using the removed
 `/core/v1/sandbox` node paths cannot connect and are replaced through the drained
 upgrade and re-enrollment workflow.
 
-The Web manager offers no manual Core key entry outside sign-in. A console without
-paired management configuration shows setup guidance; direct remote project API
-connections do not silently administer the console's configured deployment.
+The Web manager offers no manual Core key entry outside sign-in, and Web refuses
+to start without its Core key file. It holds no Project API key and never calls
+`/v1`.
 Chinese/English sandbox text, status and diagnostic formatting live in the shared
 `apps/web/src/lib/` locale modules. A persisted explicit language preference wins
 before the first browser language; unrelated product surfaces are outside this
@@ -2237,19 +2236,19 @@ replaced; do not carry obsolete compatibility code forward to satisfy this secti
   written with provenance in the same creation transaction as Session resources.
   Read no credential ciphertext and never recompute sources from current Agents
   or operator defaults. Model/harness sources are independent; provider bundles
-  retain one source. Project reads redact all deployment provider details. Old
-  Sessions expose persisted model/harness with unknown sources and unavailable
-  provider metadata, without backfill. Projection metadata does not alter retry
+  retain one source. The read is Core-key only, under `/core/v1`; `/v1` has no
+  execution-configuration read. Old Sessions expose persisted model/harness with
+  unknown sources and unavailable provider metadata, without backfill. Projection metadata does not alter retry
   identity; retries cannot replace it. Keep this administrator query separate from
   runtime observations and do not touch activity or wake sandboxes. The versioned
   contract is `contracts/agents-api/execution-configuration.md`.
 - Provider input validation uses the adapter-owned rules in `internal/harnessconfig`.
   Keep one internal registry for protocol and token-limit validation; Core owns
   credential environment and endpoint admission policy. These rules are not a
   public discovery API or Runtime registration descriptor. Operation qualification
-  and live readiness retain their existing owners. The Core startup view keeps its
-  basic supported/configured deployment snapshot and accepts no query parameters.
-  Session frozen execution-configuration reads remain a separate administrator read.
+  and live readiness retain their existing owners. There is no startup
+  configuration read; Session frozen execution-configuration reads remain a
+  separate administrator read.
 - Public Agent updates use `POST /v1/agents/{agent_id}` with the same tenant/Beta
   boundary and shared saved-field validation. Preserve omission separately from
   null; only supplied fields replace saved values. Metadata is a separate whole-map
@@ -2352,12 +2351,14 @@ replaced; do not carry obsolete compatibility code forward to satisfy this secti
   and verify supported behavior using the official client. Track current coverage
   in `contracts/agents-api/README.md`; SDK workflow objects are not this contract.
 - Shared supported wire types live in `contracts/agents-api/v1`. `make openapi`
-  separately generates the product spec and `contracts/agents-api/openapi.yaml`;
-  never mix their routes or authentication schemes. CI checks both for drift.
+  writes `openapi.yaml` (`/v1`), `core.openapi.yaml` (`/core/v1`) and
+  `runtime.openapi.yaml` (`/api/v1`); never mix their routes or authentication
+  schemes. Review the generated diffs; contract tests hold `openapi.yaml` to the
+  pinned routes and fields.
 - The standalone service uses `AGENTS_API_DATABASE_URL`. PostgreSQL stores Projects,
   their immutable execution scopes and API-key digests. Keys in the same Project
   resolve to one shared service-account principal and tenant. Project/key writes
-  are managed through deployment-authenticated APIs, not configuration files.
+  go through Core-key `/core/v1` routes, not configuration files.
   Optional `OpenAI-Organization` and `OpenAI-Project` headers must match the key;
   repeated/conflicting values fail authentication. Metadata, forwarded identities
   and product session cookies grant no access. Issue/revoke operations take effect
@@ -3480,7 +3481,7 @@ queue. A failed audit must roll back the write. Internal lifecycle/refresh work
 not acquire public provenance. Retries never replace ownership. Environment uploads
 persist safe request origin before dispatch and record success with the confirmed
 receipt, not the native filesystem call. Never put payloads, paths or secrets in
-audit metadata. Read models are deployment-authenticated `/core/v1` extensions;
-keep `/v1` wire contracts unchanged. See
+audit metadata. Read models are Core-key `/core/v1` routes; keep `/v1` wire
+contracts unchanged. See
 [write-audit.md](contracts/agents-api/write-audit.md) for coverage, retention and
 console integration. Do not confuse key identity with Session creator identity.

contracts/agents-api/harness-selection.md

@@ -40,38 +40,27 @@ adds comma-separated deployment-supported engines, for example
 remains enabled; unknown names fail startup.
 This setting does not install a harness or qualify a native deployment.
 
-Hosted placement uses one provider per deployment. Set `provider` to `docker` or
-`microsandbox` in `AGENTS_API_MANAGED_RUNTIMES_FILE`, with a stable
-`installation_id`, a `maintenance` boolean and one matching backend object.
-For example:
-
-```json
-{
-  "core_url": "http://core:8091/api/v1",
-  "provider": "docker",
-  "installation_id": "11111111-1111-4111-8111-111111111111",
-  "maintenance": false,
-  "docker": {
-    "host": "unix:///var/run/docker.sock",
-    "image": "sha256:<qualified-runtime-image>",
-    "network": "bridge",
-    "seccomp_file": "/private/seccomp.json",
-    "nested_sandbox": true
-  }
-}
-```
+Hosted placement uses one provider per deployment, saved in PostgreSQL. Web or
+`POST /core/v1/sandbox/deployment` with the Core key selects `docker`,
+`microsandbox` or `e2b`, the per-sandbox resources and one immutable Runtime
+release (an E2B template build for E2B); see the
+[deployment configuration](sandbox-deployment.md). Core needs a stable
+`AGENTS_API_SANDBOX_INSTALLATION_ID` for this; the installer generates it. Docker
+and microsandbox sandboxes run on enrolled nodes, whose files hold only host paths
+and an installed copy of that selection. The former
+`AGENTS_API_MANAGED_RUNTIMES_FILE` is rejected at startup.
 
 There is no engine-to-provider routing or mixed-provider configuration. Enabling
 another harness does not choose another image or backend; the selected Runtime
 image must contain and qualify each enabled harness. Capability checks still
-apply. Legacy `default_provider`, `engine_providers` and provider maps are rejected.
+apply.
 
-Before changing provider or backend namespace, restart the original configuration
-with `maintenance: true`, explicitly settle or delete its hosted resources and
-confirm cleanup is complete. Restart the new provider configuration in maintenance
-to validate the switch, then disable maintenance without changing its identity.
-Switching never migrates Sessions or deletes resources automatically. See the
-[deployment procedure](../../services/agents-api/deploy/microsandbox/README.md#change-the-deployment-provider).
+Before changing provider, resources or Runtime, enter maintenance at the current
+generation, explicitly archive retained hosted Sessions and confirm cleanup is
+complete. Then submit the replacement and explicitly resume with the returned
+generation. Switching never migrates Sessions or deletes resources automatically.
+See the
+[deployment procedure](../../services/agents-api/HOSTED-SANDBOX-MANAGER.md#removal-and-maintenance).
 
 For multiple engines, use an exclusive `by_harness` object in the private
 `AGENTS_API_EXECUTION_OPTIONS_FILE`, with one existing adapter-options object per

contracts/agents-api/node-host-history.md

@@ -1,8 +1,8 @@
 # Administrator node host observations
 
-`GET /core/v1/sandbox/nodes/{node_id}?range=1h|6h|24h` requires deployment
-administrator authentication. Core Web forwards it through its authenticated
-server; Project, enrollment and node credentials do not authorize this read.
+`GET /core/v1/sandbox/nodes/{node_id}?range=1h|6h|24h` requires the Core key.
+Core Web forwards it with the Core key after console sign-in; Project, enrollment
+and node credentials do not authorize this read.
 The omitted range defaults to `1h`. Invalid, repeated or unknown query parameters
 return the existing invalid-input response; missing or removed nodes return 404.
 

contracts/agents-api/openapi.yaml

@@ -5360,16 +5360,4 @@ securityDefinitions:
     in: header
     name: Authorization
     type: apiKey
-  DeploymentAdminAuth:
-    in: header
-    name: Authorization
-    type: apiKey
-  NodeAuth:
-    in: header
-    name: Authorization
-    type: apiKey
-  NodeEnrollmentAuth:
-    in: header
-    name: Authorization
-    type: apiKey
 swagger: "2.0"

contracts/agents-api/runtime-history-api.md

@@ -1,6 +1,6 @@
 # Runtime history API
 
-Status: public contract, strict TypeScript client, PostgreSQL history and Core Web
+Status: Core-key contract, strict TypeScript client, PostgreSQL history and Core Web
 History ranges implemented. Core uses its existing database; the execution owner
 samples every 30 seconds by default. API-only processes without an execution worker
 collect only on read; their Session history read returns
@@ -144,7 +144,7 @@ or malformed data reject the entire response with a 502 `invalid_admin_response`
 ## Explicit boundaries
 
 - The routes never sample a live provider, provision compute, or mutate lifecycle.
-- The public contract does not expose a storage backend.
+- The contract does not expose a storage backend.
 - History availability does not imply current Runtime readiness.
 - Current observations and Durable history have separate freshness and retention
   semantics and must remain separately labelled in Web.

contracts/agents-api/runtime-observability-api.md

@@ -1,7 +1,7 @@
 # Runtime observation API
 
 Status: Phase 2 and initial Core Web consumption implemented. The current-snapshot routes, strict
-`packages/agents-client` projection, and generated `openapi.yaml` contract are
+`packages/agents-client` projection, and generated `core.openapi.yaml` contract are
 implemented and consumed by the Dashboard through complete Session/observation
 identity joins. Durable history uses the separate optional
 [Runtime history API](runtime-history-api.md); lifecycle controls remain outside

contracts/agents-api/runtime-observability-design.md

@@ -4,7 +4,7 @@ Status: provider abstraction with Docker and microsandbox sampling, the
 current-snapshot API/client contract, and Core Web Live and capability-gated
 Durable Dashboard sources are implemented. Phase 4 includes the bounded sanitized
 exporter seam, optional OTLP/HTTP transport, execution-owner singleton background
-sampling, PostgreSQL history, public history API, and 1h/6h/24h Web ranges.
+sampling, PostgreSQL history, the Core-key history read, and 1h/6h/24h Web ranges.
 History uses the existing Core database by default. Other provider sources are not implemented.
 Microsandbox idle suspension is a separate durable lifecycle feature; it does
 not consume this telemetry as authority.
@@ -51,7 +51,7 @@ evidence. They must not become execution or lifecycle authority.
 
 | Concern | Authority | Notes |
 | --- | --- | --- |
-| Tenant and Session ownership | Core database | Every public read is tenant-scoped. |
+| Tenant and Session ownership | Core database | Every read is scoped to the tenant of the Project in its `/core/v1` path. |
 | Environment placement | Session configuration and Environment row | `none`, `self_hosted`, or `openai_hosted`. |
 | Observation resource identity | Session ID | One current observation resource exists per tenant-owned Session. |
 | Managed Runtime identity | `runtime_allocations` | Allocation and provider key identify the compute incarnation. |
@@ -258,8 +258,8 @@ Core reuses its PostgreSQL database for bounded recent Runtime history. The
 provider-neutral observation service hands each sanitized periodic result to a
 bounded asynchronous writer. One typed row contains the observation and optional
 measured Session usage snapshot (recorded root Turn snapshots, active Turns
-included, not the public Session usage rule). The public API resolves caller ownership before
-issuing bounded queries; Web never queries storage directly.
+included, not the public Session usage rule). The `/core/v1` read resolves the Project's
+Session before issuing bounded queries; Web never queries storage directly.
 
 External OTLP export remains optional. Each destination has an independent queue,
 so a Collector outage cannot delay local persistence. Neither history nor export

contracts/agents-api/runtime-observability.md

@@ -127,7 +127,7 @@ PostgreSQL database. The execution owner samples every 30 seconds by default,
 using bounded pages, concurrency and source deadlines. Collection never wakes or
 mutates compute. The worker lease is checked during the sweep and before each
 handoff. Only periodic samples populate durable history; current API reads cannot
-inflate cadence coverage. Retention is seven days; public queries span at most
+inflate cadence coverage. Retention is seven days; history reads span at most
 24 hours and have explicit input and output limits.
 
 `AGENTS_API_RUNTIME_HISTORY_FILE` optionally changes sampling and adds OTLP/HTTP

contracts/agents-api/write-audit.md

@@ -9,8 +9,8 @@ replacement for a Session's creator identity.
 Authentication carries the issued key UUID and its Project's tenant/principal.
 Keys in one Project share assets and permissions; provenance records which key
 performed each write. All business keys live in PostgreSQL. Configuration contains
-no business keys or Projects. Console credentials authenticate only management
-operations and are never public API identities. Client headers cannot assert a
+no business keys or Projects. The Core key authenticates only `/core/v1` and is
+never a public API identity. Client headers cannot assert a
 key identity, and display names do not change an ID.
 
 True creation stores ownership in the same transaction as the resource and operation.