docs(agent-workflows): redesign trace continuation

[mmabrouk]

Context

Issue #5097 proposes joining the multiple HTTP requests behind one approval- or client-tool-resumed assistant turn into one OpenTelemetry trace.

The original design correctly found that the SDK already accepts inbound W3C traceparent, but its Small estimate omitted several current-system constraints: the browser still needs the response span id, request preparation replaces candidate transport headers, message usage is overwritten on each resume, and both trace-query paths cache a found trace as immutable even while later continuation spans are still being ingested.

This draft re-audits the proposal against current main and turns it into an implementation-ready complexity assessment. It changes documentation only.

Changes

• Add a current v2 design with the full approval and client-tool continuation flow.
• Keep spanId and traceparent as transport-owned protocol context instead of persistent UI-message metadata.
• Use the stable assistant message id from merged PR fix(sdk): echo the continuation message id so playground turns continue in place #5088 as the transport context-map key.
• Define a chained trace shape: each resume is a child of the previous request span.
• Define cumulative per-turn usage rules, including the ACP {input:0, output:0, total:~62k} guard.
• Identify scoped, bounded growing-trace cache refresh as mandatory; a single invalidation can race asynchronous ingestion and cache a partial trace.
• Cover streaming, 406 batch fallback, approvals, denials, client-tool success/failure, sequential gates, regeneration, and failure behavior.
• Separate guaranteed continuity after a page reload into an explicit durability slice.
• Mark the 2026-07-06 proposal as historical and update workspace status.

Complexity conclusion

• Same mounted-session continuation: Medium, approximately 3–5 engineering days across SDK metadata, frontend transport, usage aggregation, trace-cache lifecycle, tests, and live QA.
• Guaranteed continuation after server-only hydration/page reload: an additional Medium, approximately 2–4 engineering days across durable session records, restoration, and compatibility tests.

Tests / notes

• pnpm exec prettier --check for the new v2 design, complexity plan, and rewritten status: passed.
• git diff --check: passed.
• Pre-commit secret scanning: passed.
• No product code changed.

Decisions requested

1. Is one trace for same-mount approval and client-tool resumes sufficient for the first implementation?
2. Or must one logical turn remain one trace after a page reload/server-only hydration? If required, the durability slice belongs in release scope rather than being treated as an edge case.
3. Is root-request latency acceptable for the first slice, given that cumulative usage is corrected in the UI but root-span cumulative metrics are not recomputed after late ingest?

What to review

• Start with trace-continuation-v2.md for the contract and end-to-end flow.
• Then review trace-continuation-complexity.md for slices, risks, test matrix, estimates, and rollout order.

Related to #5097.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 24, 2026 6:38pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5db786c7-7129-4c01-bb5a-ddca8fe7644f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/approval-resume-trace-continuation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

This draft needs two product calls before implementation:

1. Is same-mounted-session continuity the first release boundary, or must a parked turn keep one trace across page reload/server-only hydration?
2. Is request-1 latency acceptable while the message chip aggregates usage across all continuation requests?

Please also challenge the transport ownership decision: spanId is captured and stripped as protocol context, while only stable traceId and cumulative usage reach the persisted UI message.