[Automated] Draft docs (kagent): feat: wake session quiescence workers after task settlement

[github-actions]

kagent-dev/kagent#3074 — feat: wake session quiescence workers after task settlement

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

What changes for users: After a task settlement commits, local controller workers now wake immediately to pause or suspend the Session Actor. Missed wake-ups still recover through KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL, which defaults to 1m; blocked work and database errors retry within one second.

What the docs now say: The operational considerations page now explains session quiescence recovery, when KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL matters, and how to set the variable through controller.env.

Not verified: No cluster; the configuration is unrun.

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

• Code PR: feat: wake session quiescence workers after task settlement kagent#3074
• Code issue: [FEATURE] Wake session quiescence workers in memory after task settlement kagent#3040
• Product: kagent (upstream) -> kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-alpha10.
• Category: scoped-edit / pr
• Possibly incomplete: feat: configure database polling and skip unchanged MCP writes kagent#3038 also worked issue #3040, which feat: wake session quiescence workers after task settlement kagent#3074 closes; the dossier for #3074 did not include #3038, so this draft documents only the wake-up and recovery behavior shown here.

Plan, and what changed it

• Planned: Add the session quiescence recovery behavior to the operations page that already covers controller replicas, PostgreSQL, idle Sessions, and snapshot availability.
• Learned: upgrade-from-0x.md is migration-specific, while operational-considerations.md owns the affected production behavior; the target pages and dossier diff showed this.
• Did: Documented the behavior in operational-considerations.md, left upgrade-from-0x.md unchanged, and wrote a feature release-note proposal.

Why a documentation change is necessary

The pull request changes how kagent finds settled Session work: local workers wake after a committed settlement, while periodic scans become missed-wake-up recovery. The operational considerations page already tells operators how controller replicas and PostgreSQL affect production behavior, but it did not explain the recovery interval or what happens after a missed signal. Without the update, an operator could tune the interval as though it controlled ordinary settlement latency rather than only recovery.

What changed on disk

docs-site/content/kagent/1.x/operations/operational-considerations.md - added Tune session quiescence recovery, with the wake-up behavior, recovery interval, retry boundary, and controller.env example.

How to verify this change

1. Install or upgrade kagent with the controller.env example from the page, setting KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL to 30s.
2. Run kubectl get deployment -n kagent kagent-controller -o yaml and confirm that the controller container has KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL: 30s.
3. Set the value to 0s and restart the controller. The pod logs should include KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL must be positive, and the controller should not start.

What was not verified

The configuration was not applied to a cluster, so the YAML example and verification commands are unrun.

How the pages were chosen (triage report)

Feature clusters

These clusters look incomplete. Each names a pull request this run never saw, so documenting the cluster as it stands may describe half a feature — the classic failure is a guide telling a reader to set a field that a later change gave a default. Read the absent pull request before drafting:

Cluster	Missing	What it is	Why it matters
c4	kagent-dev/kagent#3038	feat: configure database polling and skip unchanged MCP writes (merged)	also worked issue #3040, which kagent-dev/kagent#3074 closes

Draft a documentation change

kagent-dev/kagent#3074 — feat: wake session quiescence workers after task settlement

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Code issue: [FEATURE] Wake session quiescence workers in memory after task settlement kagent#3040
• Summary (read from the body): Each API replica currently polls PostgreSQL every second for idle sessions. This PR wakes the local quiescence workers through a buffered channel after task settlement commits, so normal pause/suspend stays prompt while idle recovery scans default to once a minute.
• 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/architecture/runtime-and-lifecycle.md
  • docs/env.md
  • go/core/internal/service/session/quiescence.go
  • go/core/internal/service/session/workflow.go
  • go/core/internal/service/taskstore/service.go
  • go/core/pkg/app/app.go
  • ...and 1 more

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

[kristin-kronstain-brown]

Closing: kagent-dev/kagent#3074 changes how the controller schedules its internal quiescence workers, and pause and suspend behave the same for users. The new KAGENT_SESSION_QUIESCENCE_POLL_INTERVAL recovery setting is listed in the generated environment variable reference, so no guide page needs to change.