@peasant-labs/fairtrade 0.0.2 → 0.0.3

package/dist/lib/types/transcript/view-model.d.ts

@@ -0,0 +1,563 @@
+/**
+ * Cooked git chrome for the session header. Produced by the adapter from
+ * whichever wire shape is present — flat `gitBranch`/`gitRemote` OR nested
+ * `gitContext` (see TranscriptWireInput in wire-types.js). Absent on the model
+ * ⇒ the git chips are omitted entirely (clean degrade). Every field is optional
+ * because the real Go wire carries only branch + remote today; the rest arrive
+ * only via metadata.json fixtures.
+ *
+ * @typedef {object} SessionGitVM
+ * @property {string} [branch]
+ * @property {string} [remote]
+ * @property {string} [author]              cooked from the drifted gitContext.user (TS shape); absent on the Go-flat wire (render-when-present)
+ * @property {CommitVM[]} [commits]
+ * @property {number} [filesChanged]
+ * @property {number} [insertions]
+ * @property {number} [deletions]
+ */
+/**
+ * A cooked commit for the git chrome / commit chips. Mirrors CommitInfo
+ * (wire-types.js) with display-ready fields. The churn (`adds`/`dels`/`files`)
+ * and `turn` anchor are render-when-present: the canonical Go CommitInfo carries
+ * no churn and commits are not on the session_detail payload (the deferred
+ * backend follow-up), so these light up from fixtures / the drifted TS shape now
+ * and from the wire when that follow-up lands.
+ *
+ * @typedef {object} CommitVM
+ * @property {string} hash
+ * @property {string} shortHash             abbreviated hash for the chip label
+ * @property {string} message               first line
+ * @property {string} [author]
+ * @property {number} [commitTime]          Unix millis
+ * @property {boolean} [session]            true if produced during this session
+ * @property {number} [adds]                insertions for the checkpoint stat (render-when-present)
+ * @property {number} [dels]                deletions for the checkpoint stat (render-when-present)
+ * @property {number} [files]               files changed for the checkpoint stat (render-when-present)
+ * @property {number} [turn]                turn index this checkpoint attaches to (adapter joins commitTime→nearest turn)
+ */
+/**
+ * The cooked session header / meta / outcome / scorecard, plus optional git.
+ * The scorecard is passed through largely as-is (the wire scorecard is already
+ * flat numeric signals); the analytics util derives display BANDS from it
+ * separately (see `scorecardBands` on the analytics block).
+ *
+ * @typedef {object} SessionVM
+ * @property {string} id
+ * @property {import('./wire-types.js').Harness} harness
+ * @property {string} startTime
+ * @property {string} endTime
+ * @property {number} durationMins
+ * @property {number} totalTokens
+ * @property {number} tokensIn
+ * @property {number} tokensOut
+ * @property {number} turnCount
+ * @property {number} toolCallCount
+ * @property {string} [title]               editorial session title/summary (render-when-present; else the consumer derives one from the first prompt). Not a wire field — supplied by a curated consumer.
+ * @property {string} [project]
+ * @property {string} [model]
+ * @property {string} [workingDirectory]
+ * @property {import('./wire-types.js').SessionOutcome} [outcome]
+ * @property {import('./wire-types.js').SessionScorecard | null} [scorecard]
+ * @property {SessionGitVM} [git]           render-when-present; never a wire field
+ */
+/**
+ * A logical grouping for the filters rail, derived from `ToolCallKind`. The
+ * adapter classifies every tool call into exactly one group; counts roll up in
+ * `FilterIndexVM.toolGroupCounts`.
+ * @typedef {'edits' | 'bash' | 'read' | 'search' | 'fetch' | 'tasks' | 'other'} ToolGroup
+ */
+/** Canonical ToolGroup ids, in the filters-rail display order. @type {readonly ToolGroup[]} */
+export const TOOL_GROUPS: readonly ToolGroup[];
+/**
+ * Cooked git chrome for the session header. Produced by the adapter from
+ * whichever wire shape is present — flat `gitBranch`/`gitRemote` OR nested
+ * `gitContext` (see TranscriptWireInput in wire-types.js). Absent on the model
+ * ⇒ the git chips are omitted entirely (clean degrade). Every field is optional
+ * because the real Go wire carries only branch + remote today; the rest arrive
+ * only via metadata.json fixtures.
+ */
+export type SessionGitVM = {
+    branch?: string;
+    remote?: string;
+    /**
+     * cooked from the drifted gitContext.user (TS shape); absent on the Go-flat wire (render-when-present)
+     */
+    author?: string;
+    commits?: CommitVM[];
+    filesChanged?: number;
+    insertions?: number;
+    deletions?: number;
+};
+/**
+ * A cooked commit for the git chrome / commit chips. Mirrors CommitInfo
+ * (wire-types.js) with display-ready fields. The churn (`adds`/`dels`/`files`)
+ * and `turn` anchor are render-when-present: the canonical Go CommitInfo carries
+ * no churn and commits are not on the session_detail payload (the deferred
+ * backend follow-up), so these light up from fixtures / the drifted TS shape now
+ * and from the wire when that follow-up lands.
+ */
+export type CommitVM = {
+    hash: string;
+    /**
+     * abbreviated hash for the chip label
+     */
+    shortHash: string;
+    /**
+     * first line
+     */
+    message: string;
+    author?: string;
+    /**
+     * Unix millis
+     */
+    commitTime?: number;
+    /**
+     * true if produced during this session
+     */
+    session?: boolean;
+    /**
+     * insertions for the checkpoint stat (render-when-present)
+     */
+    adds?: number;
+    /**
+     * deletions for the checkpoint stat (render-when-present)
+     */
+    dels?: number;
+    /**
+     * files changed for the checkpoint stat (render-when-present)
+     */
+    files?: number;
+    /**
+     * turn index this checkpoint attaches to (adapter joins commitTime→nearest turn)
+     */
+    turn?: number;
+};
+/**
+ * The cooked session header / meta / outcome / scorecard, plus optional git.
+ * The scorecard is passed through largely as-is (the wire scorecard is already
+ * flat numeric signals); the analytics util derives display BANDS from it
+ * separately (see `scorecardBands` on the analytics block).
+ */
+export type SessionVM = {
+    id: string;
+    harness: import("./wire-types.js").Harness;
+    startTime: string;
+    endTime: string;
+    durationMins: number;
+    totalTokens: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnCount: number;
+    toolCallCount: number;
+    /**
+     * editorial session title/summary (render-when-present; else the consumer derives one from the first prompt). Not a wire field — supplied by a curated consumer.
+     */
+    title?: string;
+    project?: string;
+    model?: string;
+    workingDirectory?: string;
+    outcome?: import("./wire-types.js").SessionOutcome;
+    scorecard?: import("./wire-types.js").SessionScorecard | null;
+    /**
+     * render-when-present; never a wire field
+     */
+    git?: SessionGitVM;
+};
+/**
+ * A logical grouping for the filters rail, derived from `ToolCallKind`. The
+ * adapter classifies every tool call into exactly one group; counts roll up in
+ * `FilterIndexVM.toolGroupCounts`.
+ */
+export type ToolGroup = "edits" | "bash" | "read" | "search" | "fetch" | "tasks" | "other";
+/**
+ * One line of a rendered diff hunk (cooked from a parsed edit/write result).
+ */
+export type DiffLineVM = {
+    sign: "add" | "del" | "ctx";
+    /**
+     * old-file line number (gutter); absent for adds
+     */
+    oldNo?: string;
+    /**
+     * new-file line number (gutter); absent for dels
+     */
+    newNo?: string;
+    text: string;
+};
+/**
+ * A contiguous diff hunk for one file change.
+ */
+export type DiffHunkVM = {
+    /**
+     * the hunk range header line, when present
+     */
+    header?: string;
+    lines: DiffLineVM[];
+};
+/**
+ * A fully cooked tool call. The adapter has ALREADY parsed the wire
+ * `arguments`/`result` JSON strings into `args`/`output`, derived a one-line
+ * `preview`, classified the `kind`/`group`, and (for edit/write) computed
+ * `diff`. Components render these fields directly — they NEVER JSON.parse.
+ */
+export type ToolCallVM = {
+    id: string;
+    /**
+     * display name (e.g. "Read", "Bash")
+     */
+    name: string;
+    kind: import("./wire-types.js").ToolCallKind;
+    /**
+     * filters-rail grouping
+     */
+    group: ToolGroup;
+    /**
+     * the one-line summary shown collapsed
+     */
+    preview: string;
+    /**
+     * parsed `arguments` (shape varies by tool)
+     */
+    args?: unknown;
+    /**
+     * parsed `result` (shape varies by tool)
+     */
+    output?: unknown;
+    filePath?: string;
+    durationMs?: number;
+    exitCode?: number;
+    isError?: boolean;
+    /**
+     * present for edit/write kinds
+     */
+    diff?: DiffHunkVM[];
+    /**
+     * churn for edit/write
+     */
+    adds?: number;
+    dels?: number;
+};
+/**
+ * Cooked thinking content for a turn. The adapter extracts thinking from the
+ * folded `turn.content` (render-when-present); absent ⇒ no thinking block.
+ */
+export type ThinkingVM = {
+    text: string;
+    /**
+     * precomputed word count for the toggle badge
+     */
+    words?: number;
+};
+/**
+ * One cooked turn. `toolCalls` here are the same `ToolCallVM` objects indexed in
+ * `toolCallsById` (shared identity — index once, reference everywhere).
+ */
+export type TurnVM = {
+    index: number;
+    role: import("./wire-types.js").Role;
+    /**
+     * display label, e.g. "1a" / "2"
+     */
+    label: string;
+    /**
+     * markdown body (thinking already extracted)
+     */
+    content: string;
+    /**
+     * subagent nesting depth (0 = top level)
+     */
+    depth: number;
+    /**
+     * provider/role accent token name (decoration)
+     */
+    accent?: string;
+    /**
+     * subagent name when depth > 0
+     */
+    agentName?: string;
+    thinking?: ThinkingVM;
+    toolCalls: ToolCallVM[];
+    entryType?: import("./wire-types.js").EntryType;
+    stopReason?: import("./wire-types.js").StopReason | null;
+    isError?: boolean;
+    isFinal?: boolean;
+    tokens?: {
+        in: number;
+        out: number;
+    };
+    /**
+     * RFC3339 absolute time (drives commit anchoring); the visible label prefers `time`
+     */
+    timestamp?: string;
+    /**
+     * editorial display time, e.g. "8m ago" (render-when-present; else `timestamp`). Not derivable from the wire (relative to now) — a curated consumer supplies it.
+     */
+    time?: string;
+    /**
+     * editorial absolute time for the hover title (render-when-present; else `timestamp`)
+     */
+    timeTitle?: string;
+    /**
+     * annotations targeting this turn (may be empty)
+     */
+    annotations: AnnotationVM[];
+};
+/**
+ * A cooked annotation, already resolved to the turn it targets. The adapter maps
+ * the wire `AnnotationSummary` half-open entry range onto turn indices.
+ */
+export type AnnotationVM = {
+    id: string;
+    /**
+     * e.g. "error" / "retry" / "revert" / "subagent"
+     */
+    kind: string;
+    /**
+     * target turn index
+     */
+    turn: number;
+    label: string;
+    preview?: string;
+    isPrimary?: boolean;
+};
+/**
+ * One file in the Files tab, with cooked churn. The adapter aggregates per-file
+ * reads/writes/edits/deletes across all tool calls.
+ */
+export type FileEntryVM = {
+    path: string;
+    /**
+     * basename for compact display
+     */
+    leaf: string;
+    reads: number;
+    writes: number;
+    edits: number;
+    deletes: number;
+    /**
+     * total insertions
+     */
+    adds: number;
+    /**
+     * total deletions
+     */
+    dels: number;
+    /**
+     * true if writes + edits > 0
+     */
+    edited: boolean;
+    /**
+     * first turn that touched the file
+     */
+    turn?: number;
+};
+/**
+ * One diff entry in the Diffs tab — a file change with its rendered hunks.
+ */
+export type DiffEntryVM = {
+    path: string;
+    leaf: string;
+    adds: number;
+    dels: number;
+    hunks: DiffHunkVM[];
+    /**
+     * turn the edit happened on
+     */
+    turn?: number;
+    /**
+     * back-reference into toolCallsById
+     */
+    toolCallId?: string;
+};
+/**
+ * One task group for the trace outline / waterfall — a user-prompt boundary plus
+ * its derived per-task summary. The adapter computes boundaries off the turn
+ * stream; the optional analytics util can enrich this further.
+ */
+export type TaskGroupVM = {
+    id: string;
+    /**
+     * 1-based task number
+     */
+    index: number;
+    /**
+     * user content for the task (case preserved)
+     */
+    prompt: string;
+    /**
+     * turns belonging to this task
+     */
+    turnIndices: number[];
+    durationMs?: number;
+    /**
+     * tool-call count in the task
+     */
+    tools?: number;
+    outcome?: "ok" | "error";
+    /**
+     * short error label when outcome === 'error'
+     */
+    error?: string;
+    /**
+     * cooked churn/files summary, e.g. "2 files · +316 −25" (render-when-present)
+     */
+    stat?: string;
+};
+/**
+ * One curated key-moment for the HIGHLIGHTS tab. `vm.highlights` BACKS this tab
+ * directly; the tab must render non-empty from it.
+ */
+export type HighlightVM = {
+    id: string;
+    kind: "request" | "phase" | "error" | "checkpoint" | "final" | (string & {});
+    /**
+     * turn index this highlight points at
+     */
+    turn: number;
+    title: string;
+    sub?: string;
+    /**
+     * semantic icon key (consumer maps to a glyph)
+     */
+    icon?: string;
+    /**
+     * e.g. "+312 −24 · 7 files"
+     */
+    stat?: string;
+    time?: string;
+    tokens?: string;
+    /**
+     * error styling
+     */
+    err?: boolean;
+    /**
+     * e.g. a phase id
+     */
+    tag?: string;
+};
+/**
+ * Precomputed indices the filters rail + search read, so no component recomputes
+ * counts or scans turns. Keyed maps are plain records (turn index / group id →
+ * value) for cheap, stable lookup.
+ */
+export type FilterIndexVM = {
+    /**
+     * tool-group id → count
+     */
+    toolGroupCounts: Record<ToolGroup, number>;
+    /**
+     * turn index → annotations
+     */
+    annotationsByTurn: Record<number, AnnotationVM[]>;
+    /**
+     * semantic-tag ids present
+     */
+    tags: string[];
+    /**
+     * tag id → count
+     */
+    tagCounts: Record<string, number>;
+    totalTurns: number;
+};
+/**
+ * One scorecard axis band — the display verdict the analytics util derives from
+ * the raw `SessionScorecard` numeric signals.
+ */
+export type ScorecardBandVM = {
+    /**
+     * axis id (e.g. token-efficiency)
+     */
+    id: string;
+    label: string;
+    band: "good" | "ok" | "watch" | "bad" | (string & {});
+    /**
+     * formatted headline value
+     */
+    value?: string;
+    /**
+     * single cooked sub-line (the lean analytics shape)
+     */
+    detail?: string;
+    /**
+     * semantic axis-icon key the consumer maps to a glyph (render-when-present)
+     */
+    icon?: string;
+    /**
+     * the per-axis flag LIST (render-when-present; richer than `detail` — a curated/backend nicety)
+     */
+    flags?: string[];
+    /**
+     * trend-vs-median delta (render-when-present)
+     */
+    delta?: {
+        dir: "up" | "down";
+        text: string;
+    };
+};
+/**
+ * One phase spanning a turn range, drawn as a divider in the trace.
+ */
+export type PhaseVM = {
+    id: string;
+    label: string;
+    /**
+     * first turn index (inclusive)
+     */
+    from: number;
+    /**
+     * last turn index (inclusive)
+     */
+    to: number;
+    /**
+     * semantic icon key
+     */
+    icon?: string;
+    /**
+     * error count attributed to the phase
+     */
+    errors?: number;
+};
+/**
+ * The optional analytics block. The adapter accepts a precomputed
+ * `TranscriptAnalytics` (produced separately) OR derives it; when no
+ * analytics are available the WHOLE block is absent and every analytics-fed
+ * surface degrades cleanly. Each field is independently optional.
+ */
+export type TranscriptAnalyticsVM = {
+    phases?: PhaseVM[];
+    scorecardBands?: ScorecardBandVM[];
+    /**
+     * detected patterns (errors/retries/reverts/subagents)
+     */
+    patternAnnotations?: AnnotationVM[];
+    /**
+     * analytics-enriched task grouping
+     */
+    taskGroups?: TaskGroupVM[];
+};
+/**
+ * The cooked transcript view model — the adapter's sole output and every
+ * component's prop contract. `analytics` and the git cluster are the only
+ * render-when-present pieces; everything else is always populated (possibly with
+ * empty arrays) so components never branch on existence for the core surfaces.
+ */
+export type TranscriptViewModel = {
+    session: SessionVM;
+    turns: TurnVM[];
+    /**
+     * parsed once; turns reference the same objects
+     */
+    toolCallsById: Map<string, ToolCallVM>;
+    diffs: DiffEntryVM[];
+    files: FileEntryVM[];
+    tasks: TaskGroupVM[];
+    /**
+     * BACKS the HIGHLIGHTS tab (non-empty when present)
+     */
+    highlights: HighlightVM[];
+    filterIndex: FilterIndexVM;
+    /**
+     * render-when-present
+     */
+    analytics?: TranscriptAnalyticsVM;
+};