[github-actions]

[kagent-dev/kagent#3358 + kagent-dev/kagent#3409](kagent-dev/kagent#3358 and kagent-dev/kagent#3409) — feat(auth): support human and machine principals; remove public suspend and resume controls

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

No code-path rule covers 23 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/a2a-gateway.md
• docs/architecture/oidc-proxy-authentication.md
• go/api/gen/kagent/config/v1/config.pb.go
• go/core/internal/grpcserver/interceptors.go
• go/core/internal/httpserver/auth/authn.go
• go/core/internal/httpserver/auth/proxy_authn.go
• ...and 17 more

What changes for users: Machine callers can authenticate to the kagent API with Kubernetes ServiceAccount tokens when config.server.auth.serviceAccount.authority is set. Public Session suspend/resume RPCs and UI controls are removed; the Session stays READY while its Actor gives back capacity between turns and wakes on the next message.

What the docs now say: The Identity page now explains opaque Principal.ID values, service-account TokenReview authentication, and runtime RuntimeBinding scoping. The UI, architecture, and core concepts pages no longer describe public Session suspend/resume controls and now state that conversation lifecycle is platform-managed.

Not verified: No cluster actions were run; the configuration is unrun, and internal links are unchecked.

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

• Code PR: feat(auth): support human and machine principals kagent#3358 and refactor(session)!: remove public suspend and resume controls kagent#3409
• Code issue: none linked
• Product: kagent (upstream) -> kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-rc1.
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add the new service-account authentication surface and remove or correct public Session suspend/resume documentation.
• Learned: examples/agent-substrate.md still uses sessionId for CheckpointService calls and Actor naming, not for the removed Session suspend/resume RPCs.
• Did: Updated the identity, UI, architecture, and reused core-concepts prose; left the Agent Substrate example commands unchanged.

Why a documentation change is necessary

kagent-dev/kagent#3358 adds config.server.auth.serviceAccount.authority and a shared Principal.ID model for human, machine, and runtime callers. The Identity page already documents controller authentication, but did not mention service-account TokenReview authentication or the opaque principal IDs that the UI now labels as creator IDs. kagent-dev/kagent#3409 removes public Session suspend/resume RPCs and UI controls, while the architecture page and a reused core-concepts snippet still listed those controls as kagent-native Session operations.

What changed on disk

• docs-site/content/kagent/1.x/about/substrate-runtime/identity.md - Documents opaque Principal.ID values, service-account TokenReview authentication, corrected trusted-proxy expiry behavior, and RuntimeBinding scoping.
• docs-site/content/kagent/1.x/observability/launch-ui.md - Explains that the UI has no conversation suspend/resume controls and shows opaque creator IDs.
• docs-site/content/kagent/1.x/about/architecture/kagent.md - Removes public Session suspend/resume from the kagent control-plane operation list.
• docs-site/assets/kagent-docs/snippets/about/core-concepts-session-authorization.md - Removes public Session suspend/resume from the reused core-concepts authorization split.

How to verify this change

1. Install kagent with service-account authentication enabled.

   cat > kagent-values.yaml <<EOF
   config:
     server:
       grpcReflection: true
       auth:
         serviceAccount:
           authority: kubernetes
   EOF
   
   cat > kagent-config.yaml <<EOF
   install:
     kagent:
       valuesFiles: [kagent-values.yaml]
   EOF
   
   kagent --config kagent-config.yaml install --namespace kagent

2. Run kubectl get clusterrole kagent-kagent-invocation-auth -o yaml and confirm that the role grants create on authentication.k8s.io tokenreviews. Run kubectl get clusterrolebinding kagent-kagent-invocation-auth -o yaml and confirm that the binding points at the controller ServiceAccount.
3. Run grpcurl -plaintext localhost:8083 list kagent.api.v1.SessionService and confirm that the service lists Session create, read, rename, delete, and share RPCs, but not SuspendSession or ResumeSession.
4. Open the UI for an agent conversation and confirm that the conversation page does not show Suspend or Resume controls and that creator fields are labeled as creator IDs.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false for both items.

Suggested text:

• Machine callers can authenticate to kagent with Kubernetes ServiceAccount tokens by setting config.server.auth.serviceAccount.authority. The controller verifies those tokens with the TokenReview API for the kagent-invocation audience and uses an opaque Principal.ID.
• Public Session suspend/resume RPCs and UI controls are removed. Agent runtime quiescence keeps Sessions READY, and the next interaction wakes the Actor automatically. Explicit suspend/resume controls remain for Sandboxes.

What was not verified

• The configuration was not applied to a cluster, so every command in this diff is unrun.
• cluster-facts.md was used only as an API-surface reference; no configuration was applied.
• Internal links are unchecked because Hugo was not run.
• UI screenshots were not refreshed.

How the pages were chosen (triage report)

Feature clusters

These pull requests document one feature between them:

Cluster	Pull requests	Product	Why grouped
c2	kagent-dev/kagent#3358, kagent-dev/kagent#3409	kagent	the same author merged both within 24 hours, they change the same source file, and both are drafted into docs-site/content/kagent/1.x/observability/launch-ui.md, so this looks like one change split across pull requests and separate drafts would conflict

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• feat(auth): add gateway Actor JWT credentials kagent#3359 and refactor(session)!: remove public suspend and resume controls kagent#3409 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• refactor(session)!: remove public suspend and resume controls kagent#3409 and core: support cross-namespace ModelConfig and RemoteMCPServer with allowedNamespaces kagent#3382 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there
• feat(auth): support human and machine principals kagent#3358 and feat(auth): add gateway Actor JWT credentials kagent#3359 are a stacked pair (one depends on the other), which is a delivery detail rather than a shared feature

Draft a documentation change

kagent-dev/kagent#3358 — feat(auth): support human and machine principals

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Scheduled execution needs an authenticated caller even when no user is present. This PR gives human, service-account, and Substrate Actor callers a common opaque Principal.ID, replacing the separate user and agent identity fields.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 23 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/a2a-gateway.md
  • docs/architecture/oidc-proxy-authentication.md
  • go/api/gen/kagent/config/v1/config.pb.go
  • go/core/internal/grpcserver/interceptors.go
  • go/core/internal/httpserver/auth/authn.go
  • go/core/internal/httpserver/auth/proxy_authn.go
  • ...and 17 more

kagent-dev/kagent#3409 — refactor(session)!: remove public suspend and resume controls

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): Agent runtime lifecycle is already platform-managed. This removes the public Session suspend/resume RPCs, UI controls, and chat resume plumbing. Automatic quiescence keeps the Session READY, and the next interaction wakes the Actor through Substrate ingress.
• Not tested: a cluster was used only to dry-run the YAML manifests the draft added; prose, inline field paths and commands are unrun
• No rule covers 9 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/runtime-and-lifecycle.md
  • docs/lifecycle-retries.md
  • go/api/gen/kagent/api/v1/sessions.pb.go
  • go/api/gen/kagent/api/v1/sessions_grpc.pb.go
  • go/core/internal/grpcserver/policy.go
  • go/core/internal/grpcserver/session.go
  • ...and 3 more

Draft branch: pr-tracker-draft-kagent-3358-plus1

[Rachael-Graham]

Folded into #672.