Add minimal and max wait time to both control plane and Python SDK

[pocesar]

Summary

Most of the time you'll have an external service paired with the agent node Kubernetes deployment: Redis, a vector DB, the postgres connector itself.
Allows some time to pass before starting to teardown everything

Proposed solution

The idea follows the maxSigtermDelay and minSigtermDelay: https://github.com/GoogleCloudPlatform/cloud-sql-proxy-operator/blob/main/docs/api.md#authproxycontainerspec

When receiving a shutdown event (SIGTERM, SIGINT, etc) either on the control plane itself (a re-deployment or a new version being deployed) or on agents deployments, wait for at least n seconds before fanning out the shutdown signals to in-flight reasoners. And similarly, when an agent (using the python SDK here), it shouldn't kill the process straight away and should wait n < kill < m. A Kubernetes lifecycle.stopSignal: SIGHUP could also be used to differentiate from a hard SIGTERM.

Additionally a /shutdown internal endpoint could be exposed so Kubernetes lifecycle.preStop.httpGet.path: /shutdown could be used natively to start winding down

Alternatives considered

Right now, using a lifecyle.preStop.sleep with a obscene high number until it get SIGTERM'd. Some agent reasoners can take 4 minutes to complete, and 90% of the time it gets killed anyway.
The drawback is that new deployments take just as much to be live

Additional context

[AbirAbbas]

Triage

Classification: feature ✓
Suggested labels: enhancement

Likely affected files:

• ./reasoners/webhook_router.py (matched: out, reasoners, reasoners)
• ./reasoners/models.py (matched: reasoners, reasoners)
• ./reasoners/init.py (matched: reasoners, reasoners)
• ./reasoners/conversational.py (matched: reasoners, reasoners)
• ./reasoners/helpers.py (matched: reasoners, reasoners)

---

Triage by github-buddy

[AbirAbbas]

Partly shipped in v0.1.137, and the rest is in one PR.

The max side is in: Python, Go and TypeScript agents drain in-flight reasoners on SIGTERM/SIGINT under AGENTFIELD_SHUTDOWN_TIMEOUT (default 30s; accepts 30, 30s, 5m), then cancel with a 5s settlement and report a terminal cancelled. Python and Go expose POST /shutdown. On the control plane, dispatch to a draining node is held rather than 503'd, the orphan reap is deferred by AGENTFIELD_AGENT_DRAIN_GRACE, and af server drains on SIGTERM. The shipped Helm chart now sets terminationGracePeriodSeconds on every pod.

#1030 adds the min side for the control plane: AGENTFIELD_SHUTDOWN_MIN_DELAY (default 0 = today's behaviour) keeps serving for that long after SIGTERM before the listener closes — the standard endpoint-propagation floor — with a readiness route that flips to 503 immediately while liveness stays green. The chart defaults to 5s and raises the control plane's terminationGracePeriodSeconds to 60. It also rewrites docs/deploying-on-kubernetes.md into one tuning recipe with actual numbers (terminationGracePeriodSeconds, SHUTDOWN_TIMEOUT, SHUTDOWN_MIN_DELAY, drain grace, restart grace, preStop).

Two things from the proposal I'm deliberately not doing:

• A min delay on the agent side: functionally identical to the preStop.sleep you already run, and the control plane holds dispatch the moment the agent notifies, so nothing new arrives in that window anyway.
• GET /shutdown for preStop.httpGet: that puts a process-killing side effect behind an unauthenticated GET on the agent's own port, where a mis-pointed probe or an in-cluster crawler can trigger it. preStop: {sleep: {seconds: 5}} (on by default since k8s 1.30, GA in 1.32) plus the delays above gets you the same effect. If you're pinned below 1.30 and need it, say so and I'll do it behind an explicit opt-in.

lifecycle.stopSignal: SIGHUP — nothing consumes the distinction today; happy to hear a concrete use.