[github-actions]

kagent-dev/kagent#3263 — feat: support gateway token passthrough for embedded controllers

Docs versions: 1.x (first shipped in v1.0.0-alpha17)

No code-path rule covers 4 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/credential-injection.md
• go/core/internal/controller/reconciler.go
• go/core/pkg/app/app.go
• go/core/pkg/egresspolicy/egresspolicy.go

What changes for users: Embedded kagent controllers can register app.Options.EgressPolicyCompilers so tokenPassthrough clients send the kagent-credential-injected placeholder to the runtime while the egress gateway binds the caller token. With any compiler registered, each passthrough target must have a credential header, and compiler or validation failure denies Actor egress until retry.

What the docs now say: The Egress control page now explains the gateway-bound caller-token path, including the exact origin/header/prefix target, compiler ordering, failure behavior, and conflicts with Secret credentials or non-passthrough clients. The About model providers page now distinguishes the default runtime-forwarded token path from embedded deployments that bind the token at the gateway.

Not verified: No cluster; the configuration and embedded-controller compiler path are unrun.

How kagent-3263 was drafted, and what was not verified

• Code PR: feat: support gateway token passthrough for embedded controllers kagent#3263
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha17
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Document gateway token passthrough beside the egress policy and credential-injection behavior.
• Learned: docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md already owns policy generation and credential injection, while about-model-providers.md already states the default tokenPassthrough path.
• Did: Added a caller-token passthrough subsection to Egress control and clarified the default provider-token paragraph in About model providers.

Why a documentation change is necessary

The pull request adds app.Options.EgressPolicyCompilers and records tokenPassthrough clients as gateway targets with an origin, header, and prefix. The existing docs described credential injection and tokenPassthrough, but only the default path where the runtime forwards the caller token. Readers embedding kagent could not tell that compiler-registered deployments bind the token at the gateway, require every target to be bound, and deny Actor egress after compiler validation failure.

What changed on disk

• docs-site/content/kagent/1.x/about/substrate-runtime/networking-and-egress.md: Added Caller-token passthrough through the gateway.
• docs-site/content/kagent/1.x/setup/model-providers/about-model-providers.md: Clarified that the default provider path forwards the caller token from the runtime, while embedded controllers can bind it at the gateway.

How to verify this change

1. Cannot be verified from the diff alone: the dossier does not include a runnable embedded-controller sample or manifest for app.Options.EgressPolicyCompilers.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false. Suggested note: kagent now lets embedding controllers register egress policy compilers that bind tokenPassthrough credentials at the Agent Substrate egress gateway. In embedded deployments, runtimes can send the kagent-credential-injected placeholder while the gateway applies the caller token, and kagent denies Actor egress when compiler validation fails.

What was not verified

The embedded-controller compiler path was not run.

How the pages were chosen (triage report)

Draft a documentation change

kagent-dev/kagent#3263 — feat: support gateway token passthrough for embedded controllers

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Lets an embedding controller deliver tokenPassthrough credentials at the egress gateway, through app.Options.EgressPolicyCompilers. Builds on #3177 and #3257.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 4 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/credential-injection.md
  • go/core/internal/controller/reconciler.go
  • go/core/pkg/app/app.go
  • go/core/pkg/egresspolicy/egresspolicy.go

Draft branch: pr-tracker-draft-kagent-3263