aryx/HANDOVER.md

Rich run timeline handover

This change implements the backend half of the Rich run timeline roadmap item and leaves the actual timeline UI/UX for the next agent.

What is done

• Persisted structured run history on every SessionRecord
• Added a shared run/timeline domain model for durable per-run metadata and ordered timeline events
• Started a new run record whenever sendSessionMessage(...) kicks off a turn
• Grouped streamed assistant output into a single timeline message event keyed by messageId
• Persisted timeline updates during agent activity, message streaming, completion, and failure
• Added explicit handoff source metadata so the future UI can draw source/target handoff edges
• Added a live run-updated session event so the renderer can receive timeline changes incrementally without waiting for a full workspace refresh
• Kept duplicate-session behavior simple and safe: duplicated sessions copy transcript/tooling config but start with runs: []

Important files

• src/shared/domain/runTimeline.ts
  • New shared types and helpers:
    • SessionRunRecord
    • RunTimelineEventRecord
    • createSessionRunRecord(...)
    • appendRunActivityEvent(...)
    • upsertRunMessageEvent(...)
    • completeSessionRunRecord(...)
    • failSessionRunRecord(...)
• src/shared/domain/session.ts
  • SessionRecord now includes runs: SessionRunRecord[]
• src/main/persistence/workspaceRepository.ts
  • Normalizes persisted session.runs
• src/main/EryxAppService.ts
  • Creates and updates run records during turn execution
  • Emits live run-updated session events
• src/shared/domain/event.ts
  • Added session event kind run-updated
  • Added optional run payload on SessionEventRecord
• src/renderer/lib/sessionWorkspace.ts
  • Applies run-updated events by replacing/inserting the full run snapshot
• src/shared/contracts/sidecar.ts
  • AgentActivityEvent now carries optional sourceAgentId / sourceAgentName
• sidecar/src/Eryx.AgentHost/Contracts/ProtocolModels.cs
  • C# DTO mirror for the new handoff source fields
• sidecar/src/Eryx.AgentHost/Services/CopilotWorkflowRunner.cs
  • Handoff activity now includes the active/source agent when available

Backend contract

Session shape

Every session now has:

runs: SessionRunRecord[]

Runs are stored newest-first.

SessionRunRecord

Key fields:

• id
• requestId
• projectId
• projectPath
• workspaceKind
• patternId
• patternName
• patternMode
• triggerMessageId
• startedAt
• completedAt?
• status
• agents
• events

agents is the per-run lane metadata the UI should use for lane headers / agent grouping.

RunTimelineEventRecord

Event kinds:

• run-started
• thinking
• handoff
• tool-call
• message
• run-completed
• run-failed

Useful payload fields:

• occurredAt
• updatedAt?
• status
• agentId / agentName
• sourceAgentId / sourceAgentName
• targetAgentId / targetAgentName
• toolName
• messageId
• content
• error

Live update event

The renderer now receives:

{
  sessionId: string;
  kind: 'run-updated';
  occurredAt: string;
  run: SessionRunRecord;
}

This is a full run snapshot, not a delta patch. The reducer already replaces/upserts the run for the selected session.

Current runtime behavior

Run start

sendSessionMessage(...) now:

1. appends the user message
2. creates a new SessionRunRecord
3. persists the workspace
4. starts the turn

The initial run contains a run-started event pointing at triggerMessageId.

Thinking / handoff / tool activity

Agent activity events now append timeline entries:

• thinking
• handoff
• tool-call

For handoffs, the backend now stores both source and target when the source agent is known.

Streamed assistant output

Message streaming is grouped into one message event per messageId.

During streaming:

• the existing message event is updated in place
• status stays running
• content holds the latest snapshot
• updatedAt advances

On completion:

• the same event becomes status: 'completed'
• final content is persisted

Run completion / failure

Successful runs append run-completed.

Failed runs append run-failed and also mark any still-running message events as errored.

Notes for the UI/UX agent

You do not need new IPC or backend endpoints for the first timeline UI pass.

Use:

• session.runs for initial render / reload
• live run-updated session events for in-flight changes

Suggested UI plan:

1. Replace or reframe the current agent-activity tiles around the run model instead of mixing unrelated tiles together.
2. Show runs newest-first in the side panel.
3. Inside a run, render a vertical timeline ordered by events[].
4. Use agents[] to build per-agent lanes or grouped headers.
5. Render message events as the coherent answer step for streamed assistant output.
6. Use messageId and triggerMessageId for jump-to-message actions.
7. Use agentId, sourceAgentId, and targetAgentId for jump-to-agent / handoff visuals.

UX-specific suggestions

• run-started: compact start card linked to the triggering user message
• thinking: lightweight state card or inline badge in the agent lane
• handoff: directional edge/card from source -> target
• tool-call: small tool chip/card with tool name and agent
• message: the main rich output card; this is the item that should expand/collapse cleanly
• run-completed / run-failed: footer-style terminal state card

Known limitations / open questions

• There is no dedicated persisted completed activity event. Final assistant output plus run-completed is the canonical completion signal for now.
• Tool results are not persisted yet; only tool invocation metadata is stored.
• Pattern version metadata is not persisted yet; only patternId, patternName, and patternMode are captured.
• Duplicate sessions intentionally start with empty run history. If product wants copied traces later, that needs an explicit decision.
• Live run-updated events currently send the full run snapshot each time. That keeps the reducer simple; optimize later only if payload size becomes a problem.

Frontend implementation (completed)

The UI has been implemented with the following files:

• src/renderer/lib/runTimelineFormatting.ts — formatting helpers for timestamps, durations, event labels, and a thinking-event collapsing algorithm
• src/renderer/components/RunTimeline.tsx — the main timeline UI component with collapsible run cards, vertical timeline connector lines, event icons, and jump-to-message support
• src/renderer/components/ActivityPanel.tsx — updated to include a Timeline section between Agents and Tools
• src/renderer/App.tsx — wired onJumpToMessage callback that scrolls to the target message with a temporary highlight ring
• src/renderer/components/ChatPane.tsx — added data-message-id attributes on message elements for DOM-based scroll targeting
• tests/renderer/runTimelineFormatting.test.ts — unit tests for all formatting helpers

UI features

• Collapsible run cards — newest first, auto-expanded for the latest run, with pattern name and live status badge
• Vertical timeline — ordered event list with connector lines and per-kind icons (Brain for thinking, ArrowRight for handoff, Wrench for tool-call, MessageSquare for message, etc.)
• Thinking collapse — consecutive thinking events from the same agent are collapsed into a single "×N" row
• Message preview — message events show a truncated content preview
• Jump to message — clicking a message or run-started event scrolls the ChatPane to the corresponding message with a brief indigo highlight ring
• Agent badges — multi-agent runs show agent lane badges at the top of the expanded timeline
• Duration footer — completed runs show total wall-clock duration
• Status animations — running events pulse, completed events show green checks, failed events show red alerts

Validation completed

• bun run typecheck
• bun test (81 tests, 0 failures)
• bun run sidecar:test (55 tests, 0 failures)
• bun run build