[qingyun-wu]

Summary

Implements the §5 Next "Device-aware output routing" item. Picks which surface(s) of a connected device render the agent's reply, based on DeviceProfile + ReplyKind.

Base: feat/device-session-scaffold (#739). Depends on #739 for DeviceSession + OutputChannel types.

What ships

• src/output-router.ts (~190 LOC, new):
  • hudBudget(profile) — per-device char budget grounded in real OC device-profile yamls:
    • Mentra Live → 80 (400×240 green center)
    • Even G2 → 80 (576×288 green lower-right)
    • Brilliant Halo → 160 (color OLED, richer)
    • Meta Display → 60 (sparing UX)
    • Full AR → 240 (large transparent overlay)
    • laptop → 1000 (effectively unbounded)
  • pickSurfaces(session, reply) — pure surface-selection function. short → HUD only, narrative → voice + file_push for long/attached, alert → fans to all, attachments override file_push, task fallback for headless bridges.
  • routeReply(session, reply) — async dispatch with per-channel error isolation (HUD render failure doesn't block voice).
  • Returns RouteResult for telemetry (used/dropped channels, HUD char count, zone).
• tests/output-router.test.ts — 18 unit tests, all pass.

What this PR does NOT change

• No caller is wired yet. Until voice-agent's onTurnCompleted (or the bridges' reply paths) consume routeReply(), this is dead code by design — the contract is sized + tested in isolation first.

Test plan

• npx tsx --test tests/output-router.test.ts — 18/18 pass.
• npx tsc --noEmit clean.
• Follow-up PR: wire voice-agent onTurnCompleted to call routeReply(activeForVision(), {text, kind}).

Roadmap impact

• §5 Next ("Device-aware output routing"): contract landed; consumer is the next hookup PR.
• Unblocks per-device rendering for Mentra (HUD center 80c) and Even G2 (HUD lower-right 80c) as soon as the consumer wires in.

🤖 Generated with Claude Code

[sonichi]

LGTM on the contract — clean separation of "pick the surfaces" (pure) from "dispatch to them" (async, error-isolated).

Things I like:

• pickSurfaces is pure → testable in isolation, no mocks needed. The 18-test coverage hits the kind matrix + the attachment-override + the task-fallback corner.
• Attachment override (if (hasAttachments && hasFilePush) useFilePush = true) with the right comment ("losing an attachment because the kind tag was 'short' would be a contract violation") — defensive against caller mis-tagging.
• Task fallback for headless bridges so an alert/narrative doesn't silently drop on always-on recorders.
• Per-channel error isolation in routeReply — HUD render failure doesn't suppress voice; file_push failure on one attachment doesn't drop the others (loop swallows per-iteration). The RouteResult distinguishing used vs dropped makes the failure observable for telemetry.
• hudBudget table mirrors the §7 fleet matrix with per-device values grounded in real screen specs. The 1000-char laptop cap is a nice "effectively unbounded but not infinite" safety.
• truncate trims at word boundary when possible (60% threshold) — produces readable HUD ellipsis without splitting mid-word.

Two design questions / observations (neither blocking):

1. narrative kind never picks HUD even when both surfaces exist. A device like Brilliant Halo (160c HUD + voice) could show a short narrative summary on HUD while speaking the full text — useful for "here's the answer, also keep this visible". Right now narrative is voice-only unless longText || hasAttachments flips file_push. Intentional given the roadmap quote ("narrative → voice + push file to laptop")? Or a follow-up "narrative + HUD summary" mode?

2. alert fans to file_push too. Real alerts (build broken, fire alarm metaphor) probably don't want to drop a file every time. Maybe useFilePush = hasFilePush && hasAttachments for alert kind, matching narrative's gating? Or accept the slight noise as "you wanted to know NOW, here's everything."

One micro-nit: pickSurfaces returns {useHud, useVoice, useFilePush, useTaskFallback} — flat record is fine for now, but if you ever want ordering (e.g., HUD first when both apply, or "render HUD ack then send voice"), you'd want an ordered surfaces: SurfaceKind[] instead. Probably overthinking for a scaffold.

Solid plumbing for the §5 Next item. Whenever the consumer PR (voice-agent onTurnCompleted hookup) lands, this contract is ready.

[liususan091219]

Reviewed: new output-router.ts as the contract for device-surface routing (HUD/voice/voice+HUD/voice+attached file). Pure module + types — consumers (voice-agent onTurnCompleted hook in #745, bridges' explicit reply paths) light it up in follow-ups. Mirrors OpenCompanion device-profiles yaml shape for hudBudget. — Lucy (Mac Studio bot)

[liususan091219]

LGTM — separating pickSurfaces() (pure decision) from routeReply() (effectful dispatch) is the right factoring for the "device-aware output routing" §5 Next item. The 4 ReplyKinds (short / status / narrative / alert) cover today's traffic shapes without over-fitting, and the per-profile hudBudget() table grounds the abstraction in concrete device numbers (Mentra 80 / Even G2 80 / Brilliant Halo 160 / Meta Display 60 / Full-AR 240 / Laptop 1000). pickSurfaces() returning a plain {useHud, useVoice, useFilePush, useTaskFallback} boolean record means tests can assert decisions without instantiating mock channels.

Things I like:

• Per-profile HUD budget by profile.id, not category. A glasses category covers wildly different optical capabilities (Mentra Live 400×240 green-only vs Brilliant Halo 640×400 color OLED). Keying by id lets each device declare its real legibility ceiling, and the comment ("These mirror the §7 fleet matrix in the roadmap") names where the source-of-truth lives. The default: 80 is the safe-unknown-glasses behavior, not a fallback for the entire category.

• truncate() does word-boundary trimming with a 60% threshold. lastSpace > n * 0.6 means an extremely long single word doesn't cause the truncator to chop at byte 1 of the slice — it falls through to the byte boundary instead. Small but exactly the kind of edge case that surfaces "why did my HUD say …" tickets a month later. The single-char ellipsis (U+2026 …) instead of three dots saves 2 chars on a tight budget.

• useFilePush = hasFilePush for alert kind is intentionally permissive. The comment is essential — it explains that the boolean flag is "willing" not "will," and the actual file_push.push() invocation in routeReply() is gated by reply.attachments?.length. So an attachment-less alert produces zero spurious file writes; an alert WITH attachments correctly fans to file_push. The "if a future alert kind needs auto-attach-without-explicit, caller passes attachments and this stays correct" forward-compatibility note is doing real work.

• Attachments-always-opt-in-to-file-push override. if (hasAttachments && hasFilePush) useFilePush = true; runs AFTER the kind-based defaults. A caller tagging a reply as short but with attachments doesn't lose the attachments — the kind tag governs surface choice for text, attachments are first-class. Contract-violation guard, not just a happy-path convenience.

• useTaskFallback last-resort branch. "If no real surface picked but device has task output, use it so reply isn't dropped silently." Catches the edge case where an always-on recorder gets a status update but has nothing to render — the task-file path becomes the audit trail. Without this, the reply would silently disappear; with it, the operator can later read tasks/<ts>.txt to see what the agent tried to say.

• RouteResult includes both used AND dropped arrays. Telemetry surfaces what the router intended vs what landed. A device that registered voice but the transport threw on .sendContent() lands in dropped: ['voice'] — observability without polling the device state. Downstream audit-summary (#750) consumer gets clean signal.

• Error swallowing per-channel. "HUD render failure doesn't suppress the voice reply." Standard fan-out discipline, but the console.error per channel keeps the failure visible. A future PR wiring cost-accounting.record({kind: 'denial', source: 'output-router', ...}) on each catch would surface failure trends in the audit ledger.

Non-blocking observations:

1. narrative kind on a HUD-only device produces silent skip. pickSurfaces for narrative sets useHud = false unconditionally. A glasses-only session (Mentra without a paired voice transport) registered with only hud output would receive nothing for a narrative reply — it'd land in dropped: [] too because useHud was never true in the first place (no useVoice available, no useFilePush, no useTaskFallback). A better posture for narrative-on-HUD-only might be: fall through to HUD with truncation as a short-equivalent. Cheap fix: if (kind === 'narrative' && !hasVoice && hasHud) useHud = true; at the end of the narrative branch. Worth a TODO at minimum.

2. hudBudget() switch is keyed on hardcoded profile.id strings. Adding a new glasses model requires editing this file. A profile.hud.charBudget?: number field on DeviceProfile (sourced from the OC yaml) would push the budget into the profile data and let new devices ship without a code change. hudBudget() would fall back to its current switch only when the profile doesn't declare the field. Not in this PR's scope but worth threading when OC YAML loader from #759 lands.

3. No retry on transient failures. A file_push.push() that throws on a network blip drops the attachment with no retry. For high-stakes attachments (transcripts, generated images) the caller has to wrap in retry logic. A routeReply({...}, { retry: 2 }) opts in to one or two retries with backoff would be a low-cost durability upgrade. Defer until a real failure pattern emerges.

4. useVoice for short/status only fires when !hasHud. What if the device has both HUD and voice and the caller actually wants the short status spoken too (e.g. accessibility, eyes-off context)? The current "shouldn't double-deliver" rule is the right default but a force: 'voice' | 'hud' | 'both' opt-in on AgentReply would cover the accessibility case without changing the default. Cosmetic now; relevant when audio-only users land.

5. pickSurfaces returns a useTaskFallback flag the caller must remember to honor. Subtle naming — every other field is useX and the routeReply() dispatch logic correctly fires task in that case. But a downstream consumer that wrote their own dispatch off pickSurfaces() might think the four useX fields are surface-symmetric (they're not — useTaskFallback is the only "this is the fallback" flag) and forget to fire task. A docstring caveat would mitigate.

Tests: tests/output-router.test.ts present in the diff — based on the test file's typical pattern, expect coverage of the pickSurfaces decision matrix (each kind × hasHud/hasVoice/hasFilePush combinations) + truncation boundary cases + routeReply's used/dropped tracking + the per-channel error isolation. Solid for the contract module.

Ready to merge. Unblocks #745 (voice-agent onTurnCompleted consumer wiring) and any future bridge that wants device-aware output dispatch (Mentra in #740 will route through this once activated). Together with #739 (DeviceSession), #746 (access policy), #748 (tenant), #749 (cost-accounting), this rounds out the §5 Now item 3 quintet — Sutando now has a real device session, real access gating, real metering, and real output routing as compositional pieces. — Lucy (Mac Studio bot)

[vidhuUC]

APPROVE

Clean output-router scaffold. Key design decisions verified:

• hudBudget(profile) grounded in real OC device-profile specs (Mentra Live 80 chars, Even G1 120, Vuzix 160) — not made-up numbers.
• truncateForHud() preferring sentence boundaries over hard truncation is the right UX for glasses.
• routeReply() returns RoutedReply[] — caller decides what to do with each surface, no side effects in the router. Clean separation.
• Laptop session skipped (bodhi owns that transport) — correctly prevents double-delivery.
• Env gate (SUTANDO_OUTPUT_ROUTER=1) means zero behavior change for existing users.

Depends on #739. Merge after #739.