Spec — AI agent step trace

Consumer principal: surfaces que executam *gents*(Kortex agent mode, Kode platform, Bot autonomous flows). Hosts inline tool cards (mcp-tool-invocation.kmd) e thinking blocks (thinking-state.kmd) per step. Implementation ticket pra web side: services/ai/ai#117 (já aberto).

Princípios

1. *lan prerender*— quando agent expõe plan upfront (planand-execute), render todos os steps imediatamente; statuses populam during execution.
2. *inear flow + branching opcional*— vertical list default; branching gesture cria forks.
3. *tep is self-contained*— cada step encapsula tool call + thinking + result + duration.
4. *eplayable*— qualquer ponto da trace é pointin-time reconstructable.

R1 — Anatomia

Vertical step list:

┌──────────────────────────────────────┐
│ ✓ 1 · Search documentation           │
│       Duration: 1.2s                 │
│       ▸ tools.search('Koder Stack')  │
├──────────────────────────────────────┤
│ ✓ 2 · Read top result                │
│       Duration: 0.4s                 │
│       ▸ tools.fetch_url(...)         │
├──────────────────────────────────────┤
│ ⚙ 3 · Synthesize answer              │
│       (running…)                     │
├──────────────────────────────────────┤
│ ⏳ 4 · Format response                │
│       (waiting)                      │
└──────────────────────────────────────┘

Per step:

Tap step header → expand body (R3).

R2 — Status states

Transitions:

pending → running → done | error | skipped
running → paused (manual) → running | error

R3 — Step body (expanded)

┌──────────────────────────────────────┐
│ ✓ 1 · Search documentation           │
│       Duration: 1.2s                 │
├──────────────────────────────────────┤
│ ▼ Thinking (cross-link #107)         │
│   "I need to find recent docs about  │
│    Koder Stack architecture..."      │
├──────────────────────────────────────┤
│ ▼ Tool call (cross-link #100)        │
│   [mcp-tool-card: tools.search]      │
├──────────────────────────────────────┤
│ ▼ Result                             │
│   Found 5 results...                 │
└──────────────────────────────────────┘

Sub-blocks expandable independent:

• *hinking*— reasoning trace via thinking-state.kmd (#107).
• *ool call*— MCP tool card via mcp-tool-invocation.kmd (#100).
• *esult*— text or content array (per chat-message-bubble.kmd R5 renderers).

R4 — Plan pre-render

When agent supports planandexecute pattern, expose plan via gateway:

{
  "agent_run": {
    "id": "...",
    "plan": [
      {"id": "1", "title": "Search documentation", "tool_hint": "tools.search"},
      {"id": "2", "title": "Read top result", "tool_hint": "tools.fetch_url"},
      {"id": "3", "title": "Synthesize answer"},
      {"id": "4", "title": "Format response"}
    ],
    "current_step_id": "3",
    "status": "running"
  }
}

Client renders all 4 steps immediately with statuses (1+2 done, 3 running, 4 pending). User sees "we're 75% through" visually.

Plans MAY mutate at runtime (agent addsremoves steps mid-run); client renders new steps with smooth insertion animation per `themesmotion.kmd` R9 spring.

R5 — Replay / time-travel

Each step has unique id + timestamp + sequence number. Trace exportable as OpenTelemetry-compatible spans via services/ai/trace/.

Replay UI:

• Pause/Play controls at bottom of trace.
• Scrubber: drag to specific step → UI rewinds to that pointintime (subsequent steps gray out as "future").
• Branching: at any past step, "Fork from here" creates new conversation/agentrun starting fresh from that state. Crosslink chat-message-bubble.kmd R3.2 Branch action.

R6 — Branching

Forking semantics:

• Selecting "Fork from here" at step N: clone state up to step N; new agent run begins with step N+1 (or user prompt-injection).
• Forks tracked in conversation history (conversation-history.kmd #115) as separate entries with parent reference.
• Visual: forks shown as tree below original trace; user can navigate between branches.

R7 — Surface bindings

R8 — Acessibilidade

• Step list: <ol> (semanticamente ordered).
• Status icons: aria-label per state ("Done", "Running", "Waiting", etc.).
• Step body: <details><summary> em Web; equivalente em Flutter/Compose.
• Live region: aria-live="polite" announces step state changes ("Step 3 done").
• Keyboard: Tab cycle, Enter expands, arrow keys navigate replay scrubber.
• Reduced-motion: skip insertion animation; smooth scrubbing replaced by stepped jumps.

R9 — Multi-tenant + persistência

• Agent run + steps scoped per (koder_user_id, workspace_id, conversation_id, run_id).
• Tool calls em steps respeitam permissions per mcp-permission-prompt.kmd.
• Forks: parentrunid link mantido crossfork; cascade delete per `identitydata-retention.kmd`.
• Audit log: every step transition emit event pra services/foundation/audit/.

R10 — i18n

R11 — Per-preset variation

T-suite

• *1*Mount: render trace com 4 steps; statuses iniciais corretos.
• *2*Transitions: emit step state events → assert UI atualiza per R2.
• *3*Expand step: tap header → body visible com thinking + tool call + result sub-blocks.
• *4*Plan pre-render: receive plan with 4 steps → all 4 rendered immediately.
• *5*Plan mutation: agent adds step 5 mid-run → smooth insertion (spring).
• *6*Replay scrubber: drag to step 2 → steps 3+4 gray out; UI shows state at step 2.
• *7*Fork: tap "Fork from here" at step 2 → new conversation entry created with parentrunid link.
• *8*Pause/resume: tap pause → step running → paused; tap resume → continues.
• *9*Error retry: step error → retry button → step re-runs.
• *10*OpenTelemetry export: trace export produces valid OTLP spans (validation via opentelemetry-cli).
• *11*A11y: screen reader announces step transitions; keyboard nav functional.
• *1*Cross-tenant: run from workspace A não visible em workspace B.
• *2*Multitool permissions: step com tool denied via `mcppermission-prompt.kmd` → step skipped; trace marks "Skipped (permission denied)".

Cross-link

• Companion: mcp-tool-invocation.kmd, thinking-state.kmd, chat-message-bubble.kmd (bubble host trace as content item), conversation-history.kmd (fork tracking)
• Backend: services/ai/agents/, services/ai/trace/ (OpenTelemetry export)
• Impl ticket web: services/ai/ai/backlog/pending/117-web-agent-run-step-replay.md
• Policies: multi-tenant-by-default.kmd, identity-data-retention.kmd
• Motion: themes/motion.kmd R9 spring (insertion animation)
• Refs: LangChain agent observability, fuselabcreative agent UX 2026