feat(temporal): opt-in continue-as-new for long-lived agent workflows

[danielmillerp]

Why

Long-lived chat/session agents (e.g. the Emu/FDD researcher) run as a single Temporal workflow that stays open indefinitely. Their event history grows until it hits Temporal's ~50k-event / 50MB limit and the workflow stalls — this is the root cause behind "chats die / state outgrows the 2MB payload" (P0 for EY).

This PR adds an opt-in continue-as-new path so a session can stay open forever by recycling its history, plus the discipline of keeping messages/state outside workflow state so they survive the recycle.

Two orthogonal levers: continue-as-new bounds history size; the chain-wide WORKFLOW_EXECUTION_TIMEOUT_SECONDS bounds wall-clock lifetime. continue-as-new does not extend the execution timeout — raise that knob too to keep workflows long-lived.

SDK — BaseWorkflow helpers (opt-in)

• should_continue_as_new() — recycle decision: Temporal's is_continue_as_new_suggested() or a configurable WORKFLOW_MAX_HISTORY_LENGTH threshold.
• drain_and_continue_as_new() — waits all_handlers_finished (so an in-flight turn isn't lost/duplicated at the boundary), then continue_as_new.
• run_until_complete() — drop-in replacement for the usual wait_condition(timeout=None) tail. Gated once behind workflow.patched() so in-flight pre-patch workflows keep the old behaviour and don't hit a non-determinism error on replay.
• conversation_from_messages() — rebuild the conversation from the adk.messages ledger after a recycle (messages live in adk.messages, not workflow state).

Config (default OFF — existing agents unaffected)

• WORKFLOW_CONTINUE_AS_NEW_ENABLED (bool)
• WORKFLOW_MAX_HISTORY_LENGTH (int | None)

Examples

All 13 long-lived Temporal tutorial agents adopt run_until_complete:

• Message-based chat (010, 050, 060, 070, 080, 100, 120) — rebuild conversation from adk.messages.
• Harness/session — persist non-message state to adk.state and re-hydrate on recycle: opaque session handles for claude-sdk (090), claude-code (140), codex (150); rich ModelMessage history for pydantic-ai (110, via ModelMessagesTypeAdapter); langgraph (130) rebuilds from the ledger.
• 000 (no per-turn state) just swaps the wait.

Every adk.state / adk.messages round-trip is guarded by the enabled flag, so the default path is byte-for-byte unchanged.

Verification

• New unit tests for the recycle decision logic — tests/lib/core/temporal/test_base_workflow_continue_as_new.py (5 passing).
• Full tests/lib/core/temporal suite: 8 passed, no regressions.
• py_compile + ruff clean across all 16 changed files.

Follow-ups (not in this PR)

• Replay/integration test of drain_and_continue_as_new against a Temporal test server.
• Validate the pattern (drain + patch + chain-timeout) with the Temporal team before enabling in production.
• Optional platform-level "transparent for all agents" variant (SDK owns the run loop) — deferred per discussion.

🤖 Generated with Claude Code

Greptile Summary

This PR adds opt-in continue-as-new support for long-running Temporal agent workflows. The main changes are:

• BaseWorkflow helpers for recycle decisions, handler draining, and continued-run detection.
• Conversation rehydration from adk.messages after workflow history is recycled.
• adk.state persistence for agents with opaque session handles or non-text model history.
• Tutorial workflow updates to use the new run_until_complete path.
• New environment flags and tests for continue-as-new behavior.

Confidence Score: 4/5

The continue-as-new support is mostly contained and opt-in, but the conversation restore path needs attention before relying on recycled workflows.

The main implementation and tests cover the recycle decision logic, and the remaining issue is localized to message pagination during conversation rehydration.

src/agentex/lib/core/temporal/workflows/workflow.py

T-Rex Logs

What T-Rex did

• Reproduced zero-based pagination behavior by running a focused script against the real BaseWorkflow.conversation_from_messages implementation with a fake continued workflow run and a fake adk.messages.list that only returns ledger messages for page 0; the fake messages client logged HTTP 200 OK for page_number=1 as the first and only restore request, proving page 0 was skipped; the restored conversation was empty despite two text ledger messages existing on page 0, and the script failed with an assertion that the first requested page should be 0.
• T-Rex ran the requested verification, but its local artifact references were not uploaded.
• Before and after guard-state runs show progress: before the guard exercise exits with code 1 due to missing run_until_complete and legacy wait_condition lines, after the guard exercise exits with code 0 and per-file run_until_complete lines plus guarded adk.state calls, and supplemental codex-focused logs show attempted focused test execution with blockers such as uv: not found and No module named pytest.

_{Ran code and verified through T-Rex}

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
src/agentex/lib/core/temporal/workflows/workflow.py:244-251
**Use zero-based pages**

The messages SDK's offset pagination is zero-based, but this restore loop starts at `1`. When a workflow continues as new, chats with 200 or fewer ledger messages fetch the empty second page and restore an empty conversation. Longer chats drop the first 200 messages from model context. Please start from page 0, or otherwise match the messages API page base, before rebuilding the conversation.

_{Reviews (8): Last reviewed commit: "feat(temporal): opt-in continue-as-new f..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​agentex-sdk@​0.13.0 ⏵ 0.14.0	+1
	pypi/​agentex-client@​0.13.0 ⏵ 0.15.0	+1		+1

View full report

[greptile-apps]

Use zero-based pages

The messages SDK's offset pagination is zero-based, but this restore loop starts at 1. When a workflow continues as new, chats with 200 or fewer ledger messages fetch the empty second page and restore an empty conversation. Longer chats drop the first 200 messages from model context. Please start from page 0, or otherwise match the messages API page base, before rebuilding the conversation.

Artifacts

Repro: focused BaseWorkflow zero-based pagination script

• Contains supporting evidence from the run (text/x-python; charset=utf-8).

Stack trace captured during the T-Rex run

• Keeps the raw stack trace available without making the summary code-heavy.

_{Ran code and verified through T-Rex}

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agentex/lib/core/temporal/workflows/workflow.py
Line: 244-251

Comment:
**Use zero-based pages**

The messages SDK's offset pagination is zero-based, but this restore loop starts at `1`. When a workflow continues as new, chats with 200 or fewer ledger messages fetch the empty second page and restore an empty conversation. Longer chats drop the first 200 messages from model context. Please start from page 0, or otherwise match the messages API page base, before rebuilding the conversation.

How can I resolve this? If you propose a fix, please make it concise.