Use Platform agent-runtime as Maestro's durable run ledger

[haasonsaas]

From the Maestro/platform integration review using gh on 2026-04-22.

Reviewed heads:

• ae6e88a
• evalops/platform@7b003938349939052f90ae41241599993a7c06c9

Problem

Maestro has rich local/session telemetry and hosted session state, while Platform has agentruntime.v1 durable runs with steps, checkpoints, waits, costs, leases, and run events. Platform tracks the generic primitive in evalops/platform#671, but Maestro does not yet have a concrete adoption issue for using that ledger.

Scope

• Add an optional Platform agent-runtime client/config path beside the existing Platform client helpers.
• When enabled, create or attach an AgentRun for each Maestro session/run using stable workspace/team/session identifiers.
• Record turn lifecycle as AgentRunStep and checkpoint records, including model/provider, tool calls, token/cost data, and failure state.
• Map approval pauses and human-in-the-loop decisions to WaitRun / ResumeRun without blocking local-only operation.
• Correlate AgentRun IDs onto emitted maestro.* CloudEvents, meter payloads, audit context, and headless protocol output where relevant.
• Preserve TUI/web/headless behavior when Platform agent-runtime is unavailable.

Acceptance Criteria

• A Platform-backed smoke path can start a Maestro session, record at least one turn step plus cost/checkpoint data, pause/resume on an approval wait, and complete or fail the AgentRun.
• Local/offline Maestro sessions continue to work with no Platform env vars.
• Docs/env examples explain the feature flag and identity/correlation fields.
• Tests cover the disabled path, mocked Platform success path, and Platform unavailable/fallback behavior.

Related: evalops/platform#671, evalops/platform#765, evalops/platform#762, evalops/platform#763.

---

Runtime Parity / Conformance Links

• Define Rust core runtime parity contract for hosted Maestro #84 — Rust core runtime parity decision for hosted Maestro.
• Add headless runtime conformance suite for Rust parity #85 — headless runtime conformance suite that should gate Rust-hosted runner parity.

Use #85 as the protocol-level acceptance bar: lifecycle, subscribe/events/messages/heartbeat/disconnect, viewer/controller roles, permission request/response, utility operations, workspace-root enforcement, cursor replay/reset, and drain/resume behavior should match across the current TypeScript web/headless bridge and the target Rust runtime.

[haasonsaas]

Cross-linking from the integration tracker:

• Platform runtime primitive: evalops/platform#671
• Platform-side Maestro worker adapter: evalops/platform#780
• Event contract/publisher/subscribers: evalops/platform#762, Publish Maestro telemetry as typed CloudEvents onto platform's event bus #49, evalops/platform#763
• Approval waits and policy decisions that should record into the runtime ledger: Route Maestro approvals, sandbox, and firewall decisions through Platform policy services #73
• Tool and prompt/skill metadata that should be attached to run steps: Consume Platform-governed MCP skill endpoints as Maestro tool sources #74, Close the Platform prompt and skill learning loop in Maestro #75

Implementation note: this issue is the Maestro-side client/ledger adoption. evalops/platform#780 is the reciprocal Platform-side worker adapter.

[haasonsaas]

Cross-linking from the hosted remote-server review:

• Tracking: harden Maestro remote servers for hosted runtimes #76 is now the Maestro-side tracker for hardening remote/headless servers before/alongside Platform runtime adoption.
• Bind headless remote sessions to explicit workspace sandboxes #77 should land before this issue records hosted runs broadly, so AgentRun linkage has a real workspace/sandbox boundary instead of process.cwd().
• Make headless runtime fleet-safe across Maestro web replicas #78 affects how Platform run leases map to Maestro runtime ownership when more than one web replica is active.
• Use verified principals for hosted remote session scope and authorization #79 affects the workspace_id / actor_id / subject fields this issue should attach to AgentRun records.
• Bring Maestro Helm and runtime image up to hosted remote-server requirements #80 covers the chart/runtime preconditions needed for a deployed ledger-backed remote server.

In short: this issue remains the durable-ledger adoption work; #76 is the remote-server safety envelope around it.

[haasonsaas]

PR is up at #164 for the first Platform agent-runtime ledger slice.

This adds the agentruntime.v1.AgentRuntimeService Connect catalog entries, an enum-backed Maestro session trigger builder, and a fail-open client helper so we can start recording sessions into the durable Platform run ledger without flipping local/offline behavior yet.

[haasonsaas]

Provenance follow-up for #164: the matching source-of-truth PR is evalops/maestro-internal#1479. The public PR body now links it so require-internal-pr can pass.

[haasonsaas]

#164 merged green, with matching source-of-truth internal PR evalops/maestro-internal#1479 also merged.

This completes the first client/config slice for using Platform agent-runtime.v1 as Maestro's durable run ledger: Connect catalog entries, enum-backed Maestro session trigger builder, and fail-open ledger recording helper. Follow-on work can now wire the helper into actual session lifecycle points.

[haasonsaas]

PR is up at #168.

This first ledger-adoption slice records hosted headless session creation through the existing Platform AgentRuntime client when configured, carries hosted runner/workspace/model/session metadata, stores the returned AgentRun id on the hosted runner context, and keeps connection-create from double-recording a session trigger.

Local checks passed: focused web/platform tests, focused Biome, npm run build, and git diff --check.

[haasonsaas]

Update: the source-of-truth internal PR is now up at evalops/maestro-internal#1481, and the public mirror PR #168 has been updated with that provenance link.

Both PRs have auto-merge enabled. Local validation is green on both the public and internal worktrees: focused web/platform tests, focused Biome, npm run build, and diff whitespace checks.

[haasonsaas]

First durable-ledger slice merged via public #168 and internal evalops/maestro-internal#1481.

What landed:

• hosted headless session creation now records a Platform AgentRun trigger when agent-runtime config is present
• hosted runner metadata carries the returned Platform run id for correlation
• connection bootstrap avoids duplicate trigger records
• CI fix hardened shell runner cwd/PWD handling after the full Maestro suites caught a runner startup-script edge case

All public/internal checks passed before merge. This does not close #72 yet; turn-step/checkpoint/cost/wait-resume mapping remain the next ledger slices.

[haasonsaas]

Stale triage (2026-07-19): progress exists (src/platform/agent-runtime-client.ts, ledger bridge docs/smoke) but full durable run ledger adoption incomplete — see deeper slice #170. Pending: feature-flagged end-to-end AgentRun/step/wait path with offline fallback. Keep.