fix(tracing): link spawned sub-agent Langfuse traces to their parent turn

[M3gA-Mind]

A spawned sub-agent's real work landed as a separate Langfuse trace (e.g. …:bgdeliver-…) whose metadata had run_id/parent_run_id/root_run_id all null, so it was not linked to the parent turn — you couldn't navigate from the opaque spawn span to the sub-agent's detail.

Root cause: trace metadata is built from TraceContext, which carried no run-lineage fields, so trace_config_from_context never emitted them. But every journalled AgentObservation already carries the tinyagents RunContext lineage, and a single push_observations export is exactly one run's observation stream.

Fix: add run_id/parent_run_id/root_run_id to TraceContext; at journal export derive the lineage from the run's own observations (trace_ctx_with_run_lineage) and stamp it into the trace metadata. Sub-agent traces now point back at the spawning turn (parent_run_id/root_run_id), so Langfuse can thread them as a trace tree. Top-level turns get run_id with no parent. Added unit tests for the stamping + derivation.

Note: cargo check --lib can't complete in this environment (pre-existing whisper-rs-sys C++ build failure, unrelated); change verified statically.

Closes #4657

Summary by CodeRabbit

• New Features

  • Added run lineage metadata to traces, helping connect related sub-agent activity back to its parent and overall root run.
  • Trace details now include identifiers for the current run, parent run, and root run when available.

• Bug Fixes

  • Improved trace metadata propagation so lineage information is preserved for spawned sub-traces.
  • Top-level runs now avoid setting parent lineage when none exists.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2148de72-3b49-4cef-b62c-19db76863584

📥 Commits

Reviewing files that changed from the base of the PR and between c38d4c9 and 12b59dc.

📒 Files selected for processing (2)

• src/openhuman/agent/progress_tracing.rs
• src/openhuman/agent/progress_tracing/langfuse.rs

---

📝 Walkthrough

Walkthrough

TraceContext is extended with optional run_id, parent_run_id, and root_run_id fields plus a with_run_lineage builder method. The Langfuse module derives these lineage values from journal observations and stamps them into trace metadata during push_observations, with accompanying unit tests.

Changes

Run Lineage Metadata

Layer / File(s)	Summary
TraceContext lineage fields and constructor src/openhuman/agent/progress_tracing.rs	Adds run_id, parent_run_id, root_run_id optional fields to TraceContext, defaults them to None in new, and introduces with_run_lineage(...) to set them fluently.
Langfuse lineage derivation and export src/openhuman/agent/progress_tracing/langfuse.rs	Adds trace_ctx_with_run_lineage to derive lineage from the first observation, extends trace_config_from_context to stamp lineage into trace metadata, wires enrichment into push_observations, and adds tests for top-level, sub-agent, and empty-observation scenarios.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
    participant PushObservations as push_observations
    participant LineageHelper as trace_ctx_with_run_lineage
    participant ConfigBuilder as trace_config_from_context
    participant Langfuse as LangfuseTraceConfig

    PushObservations->>LineageHelper: derive lineage from first observation
    LineageHelper-->>PushObservations: enriched TraceContext
    PushObservations->>ConfigBuilder: build config with enriched context
    ConfigBuilder->>Langfuse: stamp run_id/parent_run_id/root_run_id into metadata

Loading

Possibly related issues

• [observability] Sub-agent internal steps not traced to Langfuse — delegated runs are opaque single spans #4657: Adds run-lineage metadata and Langfuse propagation to link spawned sub-agent traces, addressing correlated child trace needs.

Possibly related PRs

• tinyhumansai/openhuman#4562: Both PRs modify the same push_observations/trace_config_from_context logic in langfuse.rs for building trace metadata from TraceContext.

Suggested labels: rust-core, bug

Poem

A rabbit hops through spawned-off trees,
Tracing lineage with graceful ease,
run_id, parent, root all tied,
No orphaned trace left aside,
Metadata hops along for the ride! 🐰🔗

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: linking spawned sub-agent Langfuse traces to their parent turn.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 12b59dc748

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Propagate lineage on the live-span export path

This enrichment only runs for journal exports. In the autonomous/bgdeliver path I inspected, run_autonomous attaches the bridge with source: "autonomous" but runs under AgentTurnOrigin::Cli (src/openhuman/agent/task_dispatcher/executor.rs:173-205), while request→journal registration is limited to AgentTurnOrigin::WebChat (src/openhuman/tinyagents/mod.rs:727-734). That makes shadow_compare_journal_projection return None and the bridge falls back to export_run_trace/push_spans (src/openhuman/channels/providers/web/progress_bridge.rs:1420-1444), where these new lineage fields are never stamped. Those ...:bgdeliver... traces therefore remain unlinked unless lineage is also propagated into the live-span path or autonomous runs get journal-exported.

Useful? React with 👍 / 👎.