feat(switchyard-protocol): add common utility to hydrate Metadata from headers

[messiaen]

Summary

Extracts the correlation Metadata type from envelope.rs into a dedicated
metadata module and gives it a Metadata::from_headers constructor that
normalizes the harness-specific HTTP headers emitted by Claude Code, Codex,
NeMo Relay, Dynamo, OpenCode, and OpenAI-style clients into a single neutral
correlation/routing envelope.

Changes

• New metadata module (crates/libsy-protocol/src/metadata.rs): moves
  Metadata out of envelope.rs, re-exported from lib.rs. envelope.rs now
  imports it rather than defining it.
• Expanded Metadata: adds agent-lineage fields (parent_agent_id,
  is_subagent, agent_kind, agent_role, task_kind, turn_id,
  session_final) alongside the existing session/agent/task/correlation fields.
• Metadata::from_headers: case-insensitive header normalization with a
  documented precedence order — explicit x-switchyard-* overrides win,
  followed by each harness's native headers. Handles subagent inference from
  parent/child lineage headers (with an explicit x-switchyard-is-subagent
  override), Codex structured turn metadata (JSON), and Claude Code / OpenCode
  parent-session inference.
• Named header constants: all wire header names are defined as *_HEADER
  constants grouped by originating harness.

Tests

12 unit tests covering Codex child/root metadata, Claude Code agent lineage and
parent inference, Relay/Dynamo correlation, OpenCode parent-session scoping,
session_final parsing, and case-insensitive lookup.

Checklist

• One class per file; filename = snake_case of the primary class.
• New public symbols exported from switchyard/__init__.py.__all__ if intended for downstream use.
• Unit tests added for new components / bug fixes.
• README / --help updated if customer-facing surface changed.
• Commits signed off (Signed-off-by: Your Name <email>) per the DCO.

Notes for reviewers

Anything reviewers should pay extra attention to — risky paths, follow-up tickets, intentional trade-offs.

Summary by CodeRabbit

• New Features

  • Added standardized metadata extraction from HTTP headers.
  • Added support for session, agent, task, turn, correlation, and subagent information.
  • Added recognition of multiple provider-specific header formats, including JSON turn metadata.
  • Added case-insensitive header handling and support for explicit metadata overrides.

• Bug Fixes

  • Improved consistency when determining parent sessions, subagent status, and final-session state across supported integrations.

[coderabbitai]

Walkthrough

The protocol crate adds a shared public Metadata type, normalizes correlation headers from multiple integrations, parses Codex turn metadata, tests provider-specific mappings, and updates request/response envelopes to use the shared type.

Changes

Metadata protocol integration

Layer / File(s)	Summary
Metadata model and parsing helpers crates/libsy-protocol/src/metadata.rs	Defines public metadata fields, Codex turn metadata deserialization, and header lookup, normalization, boolean parsing, and option-selection helpers.
Header normalization and validation crates/libsy-protocol/src/metadata.rs	Implements Metadata::from_headers with override precedence, lineage inference, field selection, and provider-specific unit tests.
Public protocol wiring crates/libsy-protocol/src/lib.rs, crates/libsy-protocol/src/envelope.rs	Exposes the metadata module and updates request and response envelopes to reference the shared Metadata type.

Estimated code review effort: 4 (Complex) | ~45 minutes

Poem

I’m a bunny with headers tucked tight,
Mapping each session through day and night.
Codex and Claude hop into line,
Correlations sparkle, neat and fine.
One shared envelope—what a delightful design!

🚥 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 matches the main change: adding a shared utility to build Metadata from headers.
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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/libsy-protocol/src/envelope.rs`:
- Line 7: Update the imports in the envelope module to publicly re-export
Metadata, preserving the existing libsy_protocol::envelope::Metadata path while
retaining the existing LlmRequest and LlmResponse imports.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0a0b7e41-3310-4b49-9b1d-2019733eb95f

📥 Commits

Reviewing files that changed from the base of the PR and between 8b8dad8 and d3bde40.

📒 Files selected for processing (3)

• crates/libsy-protocol/src/envelope.rs
• crates/libsy-protocol/src/lib.rs
• crates/libsy-protocol/src/metadata.rs

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Preserve the existing envelope::Metadata public path.

The private import removes libsy_protocol::envelope::Metadata, breaking consumers using the previous public path. Re-export the relocated type here.

Proposed compatibility fix

-use crate::{LlmRequest, LlmResponse, Metadata};
+use crate::{LlmRequest, LlmResponse};
+pub use crate::Metadata;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	use crate::{LlmRequest, LlmResponse, Metadata};
	use crate::{LlmRequest, LlmResponse};
	pub use crate::Metadata;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/libsy-protocol/src/envelope.rs` at line 7, Update the imports in the
envelope module to publicly re-export Metadata, preserving the existing
libsy_protocol::envelope::Metadata path while retaining the existing LlmRequest
and LlmResponse imports.