Skip to content

[Automated] Draft docs (kagent): fix(adk): default overlapSize to 0 when compactionInterval is set (+1 related) - #735

Open
github-actions[bot] wants to merge 1 commit into
mainfrom
pr-tracker-draft-kagent-3574-plus1
Open

github-actions[bot] wants to merge 1 commit into
mainfrom
pr-tracker-draft-kagent-3574-plus1

Conversation

@github-actions

@github-actions github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

The target's own content scan fails where the base build passed (docs-theme-extras markdown-leaks / built-html-integrity):

  • markdown-leaks.spec.ts > markdown-leaks: rendered HTML scan > no leaked markdown across built HTML pages

[kagent-dev/kagent#3574 and kagent-dev/kagent#3593](kagent-dev/kagent#3574 and kagent-dev/kagent#3593) — Harness compaction default and recovery telemetry

Docs versions: main

No code-path rule covers 1 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:

  • python/packages/kagent-adk/src/kagent/adk/types.py

What changes for users: A Harness with spec.kagent.compaction.compactionInterval and no overlapSize now runs with an overlap of 0 instead of failing Python runtime requests. Operators also get controller telemetry for session quiescence and push delivery claims, split by kagent_worker_trigger, plus an info log when a recovery scan finds work.

What the docs now say: The Metrics page now lists the new session quiescence and push delivery counters, explains the kagent_worker_trigger values, and gives a Prometheus query for timer-driven recovery discoveries. The compaction pages already said overlapSize is optional, so #3574 needed no page edit.

How kagent-3574 was drafted

Plan, and what changed it

  • Planned: Correct the compaction docs for overlapSize and document the new recovery telemetry.
  • Learned: agents/context-management.md and agents/declarative-agents.md already describe overlapSize as optional, and the #3574 diff restores that documented behavior; observability/metrics.md is the page that lists controller Prometheus metrics.
  • Did: Updated observability/metrics.md for #3593 and wrote no page change for #3574.

Why a documentation change is necessary

No page change is necessary for #3574 because the existing compaction docs already tell readers that overlapSize is optional and only requires compactionInterval when set. The code change makes the runtime match that documented contract by defaulting the runtime overlap to 0 when only compactionInterval is set.

#3593 adds user-visible controller metrics and a recovery discovery log message. The Metrics page lists controller Prometheus metrics and example Prometheus queries, but did not mention kagent_session_quiescence_claimed_total, kagent_push_delivery_claimed_total, or the kagent_worker_trigger label, so operators could not discover how to inspect recovery activity from the published docs.

How to verify this change

  1. Enable the controller metrics endpoint by following the Metrics page, then make sure Prometheus scrapes the kagent-controller-metrics job.
  2. Let a recovery timer claim pending session work, then run increase(kagent_session_quiescence_claimed_total{kagent_worker_trigger="recovery"}[1h]) in Prometheus. The query shows the number of timer-driven session quiescence discoveries in the last hour.
  3. Read the controller log with kubectl logs -n kagent deployment/kagent-controller | grep "recovery scan found work". When a recovery scan finds work, the line includes operation, recovery_interval_seconds, and either session_id or registration_id.

Proposed release note

markers.notes_placeable is false for both items, so no proposed-release-note.md was written. Reviewer-use text:

  • Fixes Harness compaction with compactionInterval and no overlapSize; kagent now defaults the runtime overlap to 0 instead of letting Python ADK requests fail.
  • Adds controller telemetry for session quiescence and push delivery recovery. The new counters are split by kagent.worker.trigger, and recovery discoveries also write the recovery scan found work info log.

Files in this pull request

  • docs-site/content/kagent/main/observability/metrics.md
How the pages were chosen (triage report)

Feature clusters

These pull requests document one feature between them:

Cluster Pull requests Product Why grouped
c1 kagent-dev/kagent#3574, kagent-dev/kagent#3593 kagent both are drafted into docs-site/content/kagent/main/agents/agent-harness.md, the only page a code-path rule names for one of them, so separate pull requests 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:

Draft a documentation change

kagent-dev/kagent#3574 — fix(adk): default overlapSize to 0 when compactionInterval is set

  • Product: kagent (upstream) → kagent-dev/website
  • Docs version: main
  • Code issue: [BUG] Harness compactionInterval without overlapSize is accepted but fails every request kagent#3573
  • Summary (read from the body): A Harness with compactionInterval but no overlapSize passes CRD validation, but the Python runtime then fails every request: google-adk's EventsCompactionConfig requires compaction_interval and overlap_size together. The Go runtime already treats an unset overlap as 0.
  • 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 1 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:
    • python/packages/kagent-adk/src/kagent/adk/types.py

kagent-dev/kagent#3593 — feat(telemetry): expose session and push recovery activity

  • Product: kagent (upstream) → kagent-dev/website
  • Docs version: main
  • Summary (read from the body): Periodic recovery scans currently discover pending work silently, making it difficult to assess whether longer recovery intervals delay session suspension or push notifications.
  • Not tested: no cluster was available, so every command in this diff is 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:
    • go/core/internal/service/session/push_notifications.go
    • go/core/internal/service/session/quiescence.go
    • go/core/internal/service/session/worker_metrics.go
    • go/core/internal/service/session/workflow.go
    • go/core/pkg/app/app.go
    • python/packages/kagent-core/src/kagent/core/telemetry/_conv.py
    • ...and 3 more

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

…hen compactionInterval is set (+1 related)

Signed-off-by: GitHub Action <action@github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant