feat: add an egress policy translator for embedded controllers

docs/architecture/README.md

@@ -14,6 +14,7 @@ the agent processes.
 | `Harness`                     | Kubernetes (`api.kagent.dev/v1alpha3`)       | Runtime implementation, workload, credentials, capacity, and snapshot policy |
 | `AgentTemplate`               | Kubernetes (`api.kagent.dev/v1alpha3`)       | Portable agent behavior: model, prompt, tools, skills, and plugins            |
 | `SandboxTemplate` | Kubernetes (`api.kagent.dev/v1alpha3`) | Tools image, environment, and preparation policy for standalone sandboxes |
+| `EgressPolicy` | Kubernetes (`api.kagent.dev/v1alpha3`) | Additional HTTP(S) origins and gateway credentials selected by Agents and SandboxTemplates |
 | prepared revision             | PostgreSQL and ate-api                   | Immutable compiled runtime input and its Substrate ActorTemplate              |
 | `Session`               | PostgreSQL, exposed by gRPC              | Stable conversation identity and runtime lifecycle                                      |
 | `Sandbox` | PostgreSQL, exposed by gRPC and MCP | Owner-scoped scratch environment with process/file access and expiration |
@@ -95,6 +96,8 @@ cleanup. Session lifecycle workers independently pause/suspend idle Actors.
 
 ## Documents
 
+- [Egress policies](egress-policies.md)
+- [Runtime credential injection](credential-injection.md)
 - [Configuration and compilation](configuration-and-compilation.md)
 - [Runtime and lifecycle](runtime-and-lifecycle.md)
 - [Client lifecycle retries](../lifecycle-retries.md)

docs/architecture/configuration-and-compilation.md

@@ -172,9 +172,11 @@ revision. AgentTemplate is shared context with no runtime status. Child template
 references are resolved under the root Agent's Harness; they do not require
 separate Agents or matching Harness references.
 
-A failed compile or apply leaves the previous successful revision available.
-Sessions pin a prepared revision, so later template edits do not mutate a
-running session.
+A failed compile or apply retains the previous successful revision, which
+remains available for fresh Sessions during pending or failed edits. Initial
+creation requires a successful revision. Existing Sessions and creation retries
+keep their pinned revision. Explicit egress grants use current policies
+independently of runtime preparation.
 
 Harness compilers only translate inputs. The controller and Substrate adapter own
 application and readiness. The central entry points are
@@ -391,7 +393,8 @@ no synthetic Kubernetes object is created for an inline template.
 
 Create a session with `kagent agent session create --agent assistant -n kagent`.
 The gRPC create request and ScheduledRun target one `agent` resource reference.
-The controller selects that Agent's latest successful revision. Deleting an Agent
+The store selects that Agent's latest successful revision, including while an
+edit is pending or failed. Deleting an Agent
 retires its definition; sessions and checkpoints retain their pinned revisions.
 Recreating the same name creates a new identity and cannot inherit the old
 Agent's last successful revision.

docs/architecture/credential-injection.md

@@ -1,16 +1,21 @@
 # Runtime credential injection
 
-Kagent requires Substrate **v0.4.0-alpha1**. The compiler turns ModelConfig API
-keys and Secret-backed RemoteMCPServer headers into destination-scoped egress
-bindings. Substrate's gateway fetches the referenced Kubernetes Secret and
+Kagent requires Substrate **v0.5.0-alpha2**. The runtime compiler turns
+ModelConfig API keys and Secret-backed RemoteMCPServer headers into pinned
+destination-scoped bindings. Independently, EgressPolicy admission supplies
+additional live bindings. Substrate's gateway fetches the referenced Kubernetes Secret and
 replaces the outgoing HTTP header when the request carries a placeholder. SDKs
 receive an inert placeholder where they require an API key; real credentials never enter compiled environments,
 runtime configuration, or revision provenance.
 
-Bindings are persisted with the prepared revision and installed before a
-session becomes ready, including retries and checkpoint forks. Secret names,
-keys, destinations, and headers affect revision identity. Secret values and
-Secret UIDs do not. Rotation is handled by the gateway; its credential cache can
+Inferred integration bindings are persisted with the prepared revision; their
+Secret names, keys, destinations, and headers affect revision identity. Explicit
+EgressPolicy bindings are resolved from current policies and update live actors
+without changing that revision. Conflicts hold new grants and report the
+independent [EgressPoliciesApplied condition](egress-policies.md#preparation-and-lifecycle);
+they do not block runtime compilation. Both are installed before execution, including
+creation retries, resume, and checkpoint forks. Secret values and Secret UIDs
+do not affect revision identity. Rotation is handled by the gateway; its credential cache can
 take up to five minutes to refresh, without recompiling or restarting an agent.
 
 ## Installation
@@ -58,24 +63,48 @@ overrides of these variables are rejected.
 | RemoteMCPServer Secret-backed header | Configured header; Secret contains its full value |
 
 Provider endpoint overrides determine the allowed HTTP(S) origin. Egress rules
-match its scheme, DNS name, and port; credential bindings remain scoped to the
-hostname and header. Different credentials for the same hostname and header
-are rejected, including conflicts between models, memory embeddings, and MCP
-servers. Use distinct DNS names for
-origins requiring different credentials. IP-address destinations are unsupported
-by Substrate egress policies.
+and credential bindings both match its scheme, DNS name, and port. Different
+credentials for the same origin and header are rejected, including conflicts
+between models, memory embeddings, MCP servers, and explicit policies. Distinct
+ports on the same DNS name can use different credentials. IP-address destinations
+are unsupported by Substrate egress policies.
+
+The v1alpha3 revision format stores full origins. It assumes a clean installation;
+previously persisted hostname-only credential bindings are rejected rather than
+reinterpreted across every port on that host.
 
 Harness and SandboxTemplate environment entries accept only literal `value`
 strings, including empty strings. Configure Secret-backed credentials on
-ModelConfig or RemoteMCPServer for gateway injection.
+ModelConfig, RemoteMCPServer, or [EgressPolicy](egress-policies.md) for gateway injection.
 
 AWS IAM signing keys, Google service-account keys, and OAuth client credentials
 require mechanisms beyond static header injection and are rejected rather than
 serialized into runtimes.
 Caller-token passthrough retains its existing behavior. A passthrough model
-cannot share a hostname with static gateway credentials, which would override
+cannot share an origin with static gateway credentials, which would override
 the caller's authentication.
 
+## Controller credential extension
+
+Embedded controllers can set `app.Options.EgressPolicyTranslator` to add credential
+references for eligible model and MCP destinations before client rendering. See
+[PolicyTranslator](../../go/core/pkg/egressext/policy.go) for the contract. Core
+validates and pins the bindings, then renders client placeholders.
+
+MCP Secret bindings can coexist with extension bindings on different headers.
+Literal or ConfigMap MCP headers prevent additions at their origin. Model
+requirements restrict the header and prefix. An extension binding that conflicts
+with a model or MCP binding in the draft fails compilation. A later EgressPolicy
+conflict does not block compilation. Pinned integration bindings take precedence,
+and admission holds the new grants and reports
+[EgressPoliciesApplied](egress-policies.md#preparation-and-lifecycle).
+EgressPolicy-only destinations are outside the draft.
+
+References require a registered Substrate provider and use
+`ate-secret://<provider>/<path>`, with a lowercase DNS provider, no port, and at
+least two nonempty, unescaped path segments. Clients must send the bound header
+to trigger injection. Keyless Gemini support remains a follow-up.
+
 ## Deferred API fields
 
 The source retains commented declarations for Harness and SandboxTemplate