Add trusted multi-user chat prefixing

[TraderSamwise]

Summary

• parse trusted relay collaboration headers in the metadata server
• prefix agent-bound input only when a shared chat is in multi-user mode
• preserve original user message text with actor/share metadata in chat history
• strip client-provided X-Aimux-* headers before shared relay header injection

Verification

• yarn vitest run src/collaboration.test.ts src/multiplexer/session-runtime-core.test.ts src/metadata-server.test.ts relay/src/sharing.test.ts
• yarn typecheck
• yarn lint
• yarn test
• yarn build

Summary by CodeRabbit

• New Features

  • Multi-party collaboration added with automatic speaker labels in shared chats.
  • Collaboration metadata (participant info, share mode) is now captured in message history.

• Bug Fixes

  • Improved security by stripping untrusted headers when forwarding shared-chat requests.

• Tests

  • Added tests verifying header sanitization, collaboration metadata forwarding, and speaker-prefix behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a24a9ab2-774a-4de4-8f10-2aa479bb7d6c

📥 Commits

Reviewing files that changed from the base of the PR and between fd7f9b9 and 8411575.

📒 Files selected for processing (2)

• src/collaboration.test.ts
• src/collaboration.ts

---

📝 Walkthrough

Walkthrough

This PR adds collaboration types and header-parsing, sanitizes client-supplied x-aimux-* headers in the relay, threads parsed collaboration context into the metadata API and runtime, prefixes agent inputs in multi-user mode, and persists collaboration metadata in session history.

Changes

Multi-user Collaboration with Header Threading and Message Prefixing

Layer / File(s)	Summary
Collaboration module with types and utilities src/collaboration.ts, src/collaboration.test.ts	Defines CollaborationChatMode, CollaborationRole, CollaborationActor, and AgentCollaborationContext types. Exports collaborationContextFromHeaders to extract and parse x-aimux-* headers into typed context, and applyAgentCollaborationPrefix to conditionally prefix message data/parts with speaker names in multi-user mode. Includes internal helpers for header parsing, role/mode normalization, and display name formatting.
Relay header sanitization relay/src/sharing.ts, relay/src/relay-object.ts, relay/src/sharing.test.ts	Adds stripTrustedAimuxHeaders utility to filter out x-aimux-* prefixed headers from client requests, then uses it in shared-chat relay forwarding to prevent trusted headers from being passed through unfiltered to backend services.
Metadata server API integration src/metadata-server.ts, src/metadata-server.test.ts	Imports collaborationContextFromHeaders, extends MetadataServerOptions.lifecycle.writeAgentInput input type to accept optional collaboration field, and extracts collaboration context from request headers in the /agents/input POST handler before forwarding to downstream listeners.
Session message persistence with collaboration metadata src/session-message-history.ts	Extends SessionMessageRecord with optional actor, shareId, and chatMode fields; updates appendSessionMessage input to accept optional collaboration and populates the new record fields when provided.
Runtime integration with message prefixing and storage src/multiplexer/agent-io-methods.ts, src/multiplexer/session-runtime-core.ts, src/multiplexer/session-runtime-core.test.ts, src/multiplexer/dashboard-model.ts	Threads collaboration context through agent I/O methods and session runtime; applies applyAgentCollaborationPrefix to transform message payloads before serialization, persists collaboration metadata in session history, and includes end-to-end test verifying multi-user message prefixing, metadata storage, and round-trip reading via readSessionMessages.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TraderSamwise/aimux#19: Both PRs touch relay/src/relay-object.ts and the relay’s handling/forwarding of X-Aimux-* actor/share headers—main PR sanitizes client-provided x-aimux-* via stripTrustedAimuxHeaders, while the retrieved PR injects trusted actor headers into share-invite flows.
• TraderSamwise/aimux#20: Both PRs modify the shared-chat request preparation path in relay/src/relay-object.ts, and both extend relay/src/sharing.ts helpers used for routing/authorization.
• TraderSamwise/aimux#18: Related to handling of relay-injected x-aimux-* actor/mode headers and earlier sharing helper changes.

Poem

🐰 I hopped through headers bright and spry,

I stripped the sneaky x-aimux lie,
In multi chat I let names reply,
Now messages wear labels high —
Hop, prefix, persist — a carrot-sweet sigh.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add trusted multi-user chat prefixing' accurately summarizes the main feature: adding functionality to prefix messages in multi-user chat scenarios with trusted relay headers.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/multi-user-chat-prefixing

Warning

Tools execution failed with the following error:

Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error)

---

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

[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 `@src/collaboration.ts`:
- Around line 81-83: The headerValue function fails to find mixed-case keys in
plain objects; update header lookup to perform a case-insensitive key search on
the headers object (e.g., find the actual key with Object.keys(headers).find(k
=> k.toLowerCase() === name.toLowerCase())), then read raw = headers[foundKey]
(fall back to headers[name] if needed), and preserve the existing array-handling
logic (Array.isArray(raw) ? raw[0] : raw) so both string and string[] header
values are returned correctly; apply this change inside headerValue to ensure
X-Aimux-Share-Id and other mixed-case keys are found.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 262ee90b-0a8b-465c-ba73-a46977745259

📥 Commits

Reviewing files that changed from the base of the PR and between 98d4205 and fd7f9b9.

📒 Files selected for processing (12)

• relay/src/relay-object.ts
• relay/src/sharing.test.ts
• relay/src/sharing.ts
• src/collaboration.test.ts
• src/collaboration.ts
• src/metadata-server.test.ts
• src/metadata-server.ts
• src/multiplexer/agent-io-methods.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/session-runtime-core.test.ts
• src/multiplexer/session-runtime-core.ts
• src/session-message-history.ts