AI 原生开放教材

外观

Better Harness（QoderAI）工程手册·英文原文 ↗仓库 ↗

Session notebook trace and outcome projection ​

Status ​

Proposed

Context ​

Harness Inspector projects privacy-filtered host events into a read-only Session Notebook. The retained source can contain prompts, assistant messages, tool-call requests, correlated commits, and partial timing. It does not necessarily retain tool results, a patch snapshot, a final assistant response, or enough evidence to prove that an edit or verification succeeded.

The initial notebook presentation treated the last retained assistant message as the Turn result and independently grouped assistant messages and tool calls for display. That made a visually tidy notebook, but it could move an intermediate assistant message after later tool calls and could present an unfinished sentence as Out. Deriving a diff from the current worktree would be worse: the worktree is mutable, can contain unrelated user changes, and is not session-scoped evidence.

The Inspector and Harness Studio may share a notebook visual grammar, but their authority differs. Inspector presents retained evidence and must remain read-only. Studio owns checkpoint-backed execution and comparison through its existing contracts.

Decision ​

Preserve one canonical Turn event order ​

The session-analysis projection owns the ordered Turn stream. Assistant messages and tool requests enter that stream in observed source order after existing deduplication and privacy filtering. Presentation code may collapse contiguous tool-call runs, but it must not regroup all events by kind or otherwise reconstruct chronology.

An assistant message is promoted from the ordered stream to the terminal response only when it is the final retained event in the Turn. If a later tool request was observed, the Turn is incomplete in retained evidence and the earlier assistant message remains an intermediate response. Missing timestamps remain missing; the projection does not manufacture exact times for assistant messages.

Separate process, response, and outcome ​

Process is an ordered evidence trace:

  • assistant messages render as privacy-filtered, sanitized Markdown;
  • tool calls retain structured identity, operation, status, paths, and observed timing where available;
  • compact grouping is limited to adjacent tool calls and preserves their order.

Assistant response is optional retained prose, not proof of success.

Outcome is an evidence-bounded summary of what the Turn retained. It may include observed edit paths, verification calls, correlated commit statistics, and the terminal assistant response. A code diff appears only when a session-scoped patch or equivalent immutable artifact was captured by the report contract. Until that artifact exists, the notebook states that the patch is unavailable and must not substitute the current worktree diff.

Keep the report boundary bounded and read-only ​

The report model carries explicit response availability and ordered steps into the self-contained Inspector document. This is a private projection contract unless a second external consumer requires versioned public ownership. Existing selection, deep-link, privacy, and redaction boundaries remain authoritative.

Inspector does not gain Continue, Fork, rollback, checkpoint mutation, or replay execution. Studio does not consume Inspector's dialogue projection merely to share the notebook appearance.

Consequences ​

  • A Turn can end with responseStatus: incomplete even when an assistant message was retained earlier.
  • Counts distinguish intermediate assistant responses, tool calls, and total retained process events instead of labeling tool calls as intermediate events.
  • Process views become longer in highly interleaved sessions. The UI may collapse adjacent tool runs and keep Process closed by default, but ordering stays visible when expanded.
  • Existing reports without the new status field remain readable through a conservative compatibility projection.
  • A true code-diff output requires a later capture and schema decision; this ADR explicitly prevents a misleading worktree-derived shortcut.

Validation gates ​

  • Parser tests cover tool -> assistant -> tool order, terminal response promotion, deduplication, truncation, and incomplete Turns.
  • Report-model tests assert ordered steps and explicit response availability.
  • Browser verification checks sanitized Markdown, adjacent tool-run ordering, evidence-bounded Outcome copy, selection/deep links, and desktop/narrow controls.
  • Privacy tests continue to prove that secrets and non-repository paths are not retained in the notebook projection.

Traceability ​