[Automated] Draft docs (kagent): feat(session): let a session share expire

[github-actions]

kagent-dev/kagent#2987 — feat(session): let a session share expire

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

What changes for users: Clients can set CreateSessionShareRequest.ttl to bound how long a Session share token grants access, and operators can cap requested lifetimes with controller.sessionShareMaxTTL. The default cap is 0, so a share created without ttl remains unbounded as before. An expired token is treated as not found, while the owner can still list and revoke the expired share.

What the docs now say: The Identity page now explains CreateSessionShareRequest.ttl, SessionShare.expiresAt, expired-token behavior, and the operator cap. Operational considerations now lists controller.sessionShareMaxTTL, including the default, cap behavior, and rejected values.

Not verified: No cluster; the configuration and API calls are unrun.

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

• Code PR: feat(session): let a session share expire kagent#2987
• Code issue: none linked
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha8
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add session share lifetime behavior beside the existing Session share and Session expiration docs.
• Learned: The generated Helm and environment-variable references already include controller.sessionShareMaxTTL and KAGENT_SESSION_SHARE_MAX_TTL, while the existing share semantics live on about/substrate-runtime/identity.md.
• Did: Documented the share TTL fields on the Identity page and the operator cap on Operational considerations.

Why a documentation change is necessary

The pull request adds CreateSessionShareRequest.ttl, SessionShare.expiresAt, and the controller.sessionShareMaxTTL Helm value. The Identity page already explains Session shares and revocation, but it did not describe expiring tokens or the returned expiry field. The operational page already explains Session retention settings, so it is the prose page where an operator can learn how to cap share lifetimes.

What changed on disk

• docs-site/content/kagent/1.x/about/substrate-runtime/identity.md: Added share TTL, expiresAt, expired-token behavior, and a link to the operator cap.
• docs-site/content/kagent/1.x/operations/operational-considerations.md: Added controller.sessionShareMaxTTL to the Session expiration settings table.

How to verify this change

1. Install or upgrade kagent with controller.sessionShareMaxTTL set to 72h.
2. Use a client that can call SessionService.CreateSessionShare to create a share without ttl; the response includes share.expiresAt about 72 hours after creation.
3. Create another share with ttl longer than 72h; the request fails with InvalidArgument and says that the share TTL must not exceed 72h.
4. Create a short-lived share and wait until expiresAt; presenting the token returns not found, while ListSessionShares still includes the share for the owner.

Proposed release note

Wrote proposed-release-note.md for this feature.

What was not verified

The configuration was not applied to a cluster, so every command and API call in this diff is unrun.

How the pages were chosen (triage report)

Draft a documentation change

kagent-dev/kagent#2987 — feat(session): let a session share expire

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): A session share's token grants access until the share is revoked or the session is deleted: CreateSessionShareRequest takes no lifetime, and GetSessionShareByTokenHash checks nothing but the hash and the session's state. A client that keeps one share per conversation, for the people the owner lets in, has no way to bound it once the conversation is abandoned. A READ_WRITE share can also rena
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 7 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/env.md
  • go/api/gen/kagent/api/v1alpha1/sessions.pb.go
  • go/core/internal/grpcserver/session.go
  • go/core/internal/service/session/service.go
  • go/core/pkg/app/app.go
  • go/core/pkg/env/session.go
  • ...and 1 more

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

[Rachael-Graham]

Absorbed into #591 (commit 0ef30c0), rewritten against the current page rather than merged — this branch was cut before main's rewrite of operational-considerations.md, so it conflicts with main on its own.

controller.sessionShareMaxTTL confirmed present at v1.0.0-alpha12. The draft added a row to a values table that main's rewrite replaced with prose, so the cap moved into the prose. One fix worth noting: the cross-link pointed at #expire-idle-conversations, which no longer exists — the heading is now Expire idle Sessions. A dead link anchor builds clean, so nothing would have caught it.