Record full Platform AgentRuntime lifecycle for Maestro turns, steps, and waits

[haasonsaas]

Summary

Maestro has an optional Platform AgentRuntime client, but the current integration is still too shallow: it mainly records a session-start trigger and treats Platform failures as non-blocking fallback. The next step is to make Platform's AgentRuntime the durable spine for Maestro turns, steps, waits, resumes, and terminal state while preserving local/offline behavior.

Why it matters

Without this, Platform cannot reliably join Maestro sessions to ToolExecution, approvals, timeline, meter, audit, prompt/skill outcomes, or hosted runner sessions. The event bus can say something happened, but AgentRuntime should answer what run it belonged to, which step it happened inside, whether it paused, and how it resumed.

This is the concrete implementation slice under the broader ledger tracker.

What to build

• Expand the Platform AgentRuntime client from session-start recording into turn/step lifecycle recording.
• Create or attach a stable AgentRun for each Platform-backed Maestro session.
• Record user turn, model turn, tool step, wait, resume, completion, cancellation, and failure states with stable ids.
• Map Maestro approval pauses and human-in-the-loop decisions to Platform wait/resume semantics instead of synthetic chat-only continuation.
• Propagate agent_run_id and agent_run_step_id into Maestro CloudEvents, ToolExecution bridge metadata, meter/audit context, and hosted/headless protocol output where relevant.
• Keep local/offline Maestro behavior unchanged when Platform env/config is absent or disabled.

Acceptance criteria

• A mocked Platform-backed smoke path starts a Maestro session, records at least one turn step, records one tool step, pauses on an approval wait, resumes, and completes/fails the AgentRun.
• Existing local sessions still work without Platform configuration.
• Platform unavailable/malformed responses have explicit fallback behavior and tests.
• Event-bus and ToolExecution payloads carry the same run/step correlation ids.
• Docs/env examples explain the feature flag, failure mode, and identity/correlation fields.

Related: #72, #73, evalops/platform#780, evalops/platform#915, evalops/platform#765.

[haasonsaas]

Update: the AgentRuntime lifecycle spine now has a reviewable internal slice in evalops/maestro-internal#1610.

What landed on the branch:

• Maestro AgentRuntime client wrappers for ClaimNextRun, RecordRunStep, WaitRun, ResumeRun, CompleteRun/FailRun, GetRun, and ListRunEvents.
• A new platform:agentruntime-e2e smoke harness that starts a real Platform AgentRuntime Connect handler and drives a Maestro-session-shaped run through: trigger -> claim lease -> record governed tool step -> approval wait/checkpoint -> resume -> claim again -> complete -> get/list events.
• Unit coverage pinning the Connect paths and request/response normalization.

Local/Platform validation is green:

• npm run test -- test/platform/core-services.test.ts test/platform/agent-runtime-client.test.ts
• MAESTRO_PLATFORM_REPO=/Users/jonathanhaas/Documents/Projects/platform npm run platform:agentruntime-e2e -> validated a live Platform handler run with 13 runtime events
• MAESTRO_PLATFORM_REPO=/Users/jonathanhaas/Documents/Projects/platform npm run platform:timeline-e2e
• npm run test -- test/agent/tool-execution-bridge.test.ts test/platform/maestro-timeline-client.test.ts
• npx tsc -p tsconfig.build.json --noEmit
• npm run lint

Leaving this issue open while #1610 gets CI/review and because the next useful follow-through is wiring these lifecycle helpers into the live Maestro turn/step emission path instead of only the harness/client contract.

[haasonsaas]

Follow-up: #1610 auto-merged after green CI. Bugbot posted two low-severity comments immediately after merge, so I split those into evalops/maestro-internal#1611: reuse the shared response normalizers and preserve retryDelaySeconds: 0 for immediate retry failures, with focused unit coverage plus the AgentRuntime smoke rerun.

[haasonsaas]

Follow-up from public mirror review: evalops/maestro-internal#1615 is open to preserve explicit leaseSeconds: 0 in ClaimNextRun, mirroring the scalar-presence fix already merged in #1611 for retryDelaySeconds: 0. Local validation is green, including the Platform AgentRuntime smoke.

[haasonsaas]

Stale triage (2026-07-19): client scaffolding present; full turn/step/wait lifecycle recording still shallow. Keep as concrete #72 implementation slice.