@peasant-labs/fairtrade 0.0.40 → 0.0.41

package/dist/lib/types/ui/transcript/analytics.d.ts

@@ -0,0 +1,213 @@
+/** @typedef {import('./wire-types.js').TurnDetail} TurnDetail */
+/** @typedef {import('./wire-types.js').ToolCallDetail} ToolCallDetail */
+/** @typedef {import('./wire-types.js').SessionScorecard} SessionScorecard */
+/** @typedef {import('./view-model.js').PhaseVM} PhaseVM */
+/** @typedef {import('./view-model.js').ScorecardBandVM} ScorecardBandVM */
+/** @typedef {import('./view-model.js').AnnotationVM} AnnotationVM */
+/** @typedef {import('./view-model.js').TaskGroupVM} TaskGroupVM */
+/** @typedef {import('./view-model.js').TranscriptAnalyticsVM} TranscriptAnalyticsVM */
+/**
+ * A "task" is the span from a top-level user prompt up to (but not including)
+ * the next one — one turn of human↔agent collaboration. The shape is the
+ * canonical `TaskGroup` shape, kept stable for consumer back-compat.
+ * @typedef {object} TaskGroup
+ * @property {number} startIndex          display position of the starting prompt
+ * @property {number} endIndex            display position of the last turn (inclusive)
+ * @property {number} promptEntryIndex    wire entry index of the prompt (anchor)
+ * @property {number} [finalEntryIndex]   wire entry index of the final assistant turn
+ * @property {string} prompt              untruncated user prompt
+ * @property {number} toolCallCount
+ * @property {string[]} filesTouched
+ * @property {number} insertions
+ * @property {number} deletions
+ * @property {number} durationMs
+ * @property {boolean} hasErrors
+ * @property {number} tokens
+ */
+/**
+ * Split a turn list into task groups. Each top-level (depth-0) user turn starts
+ * a new task; depth-1+ user turns are content blocks, NOT boundaries. A session
+ * that starts without a user prompt is a single task spanning everything.
+ * @param {TurnDetail[]} turns
+ * @returns {TaskGroup[]}
+ */
+export function computeTasks(turns: TurnDetail[]): TaskGroup[];
+/**
+ * Per-turn display labels: `"1"`, `"2"` for the prompts that open a task, and
+ * `"2a"`, `"2b"` for the follow-ups within it.
+ * @param {TurnDetail[]} turns
+ * @returns {string[]}
+ */
+export function computeTurnLabels(turns: TurnDetail[]): string[];
+/**
+ * One segment of the proportional task waterfall: a task's share of the total
+ * work time and the cumulative share before it (segments tile back-to-back).
+ * @typedef {object} WaterfallSegment
+ * @property {number} promptEntryIndex
+ * @property {number} offsetPct
+ * @property {number} widthPct
+ * @property {number} durationMs
+ */
+/**
+ * Turn task groups into a relative-duration lane. When the total duration is 0
+ * (untimed transcript) every segment is zero-width at offset 0 — the caller
+ * renders the task list without bars rather than dividing by zero.
+ * @param {TaskGroup[]} tasks
+ * @returns {WaterfallSegment[]}
+ */
+export function buildTaskWaterfall(tasks: TaskGroup[]): WaterfallSegment[];
+/**
+ * Walk a transcript and surface error / retry / revert / subagent moments,
+ * sorted by display position.
+ * @param {TurnDetail[]} turns
+ * @returns {TranscriptAnnotation[]}
+ */
+export function annotateTranscript(turns: TurnDetail[]): TranscriptAnnotation[];
+/** Display label for a phase type, falling back to the raw value. @param {string} type @returns {string} */
+export function phaseLabel(type: string): string;
+/**
+ * Segment a transcript into rendered phases. `from` / `to` are WIRE turn indices
+ * (matching `TurnVM.index`), so a divider component can anchor by them directly.
+ * @param {TurnDetail[]} turns
+ * @returns {PhaseVM[]}
+ */
+export function detectPhases(turns: TurnDetail[]): PhaseVM[];
+/**
+ * Per-metric medians across the user's sessions, each field undefined when the
+ * sample yields no value (so the comparison line degrades rather than fabricate
+ * a baseline). The host supplies the sessions; the viewer never fetches them.
+ * @param {PersonalMedianSession[] | undefined} sessions
+ * @returns {PersonalMedians}
+ */
+export function computePersonalMedians(sessions: PersonalMedianSession[] | undefined): PersonalMedians;
+/**
+ * Derive the three scorecard axis verdict bands (token / prompt / loop
+ * efficiency) from the raw numeric signals. Returns `[]` when the scorecard
+ * carries no usable signal, so the card is omitted cleanly.
+ * @param {SessionScorecard | null | undefined} sc
+ * @param {PersonalMedians} [medians]
+ * @returns {ScorecardBandVM[]}
+ */
+export function assessScorecard(sc: SessionScorecard | null | undefined, medians?: PersonalMedians): ScorecardBandVM[];
+/**
+ * The cooked task groups for a turn list (`computeTasks` mapped onto
+ * `TaskGroupVM`). Exported so the adapter can populate the always-present
+ * `vm.tasks` from the same single computation `computeAnalytics` uses.
+ * @param {TurnDetail[]} turns
+ * @returns {TaskGroupVM[]}
+ */
+export function computeTaskGroups(turns: TurnDetail[]): TaskGroupVM[];
+/**
+ * Compute the cooked single-session analytics block from a (prefiltered) turn
+ * list. Each field is omitted when empty so the block is genuinely
+ * render-when-present. The adapter calls this on demand when no precomputed
+ * analytics is supplied, and reuses the returned `patternAnnotations` /
+ * `taskGroups` so nothing is derived twice.
+ * @param {TurnDetail[]} turns
+ * @param {{ scorecard?: SessionScorecard | null, medians?: PersonalMedians }} [opts]
+ * @returns {TranscriptAnalyticsVM}
+ */
+export function computeAnalytics(turns: TurnDetail[], opts?: {
+    scorecard?: SessionScorecard | null;
+    medians?: PersonalMedians;
+}): TranscriptAnalyticsVM;
+export type TurnDetail = import("./wire-types.js").TurnDetail;
+export type ToolCallDetail = import("./wire-types.js").ToolCallDetail;
+export type SessionScorecard = import("./wire-types.js").SessionScorecard;
+export type PhaseVM = import("./view-model.js").PhaseVM;
+export type ScorecardBandVM = import("./view-model.js").ScorecardBandVM;
+export type AnnotationVM = import("./view-model.js").AnnotationVM;
+export type TaskGroupVM = import("./view-model.js").TaskGroupVM;
+export type TranscriptAnalyticsVM = import("./view-model.js").TranscriptAnalyticsVM;
+/**
+ * A "task" is the span from a top-level user prompt up to (but not including)
+ * the next one — one turn of human↔agent collaboration. The shape is the
+ * canonical `TaskGroup` shape, kept stable for consumer back-compat.
+ */
+export type TaskGroup = {
+    /**
+     * display position of the starting prompt
+     */
+    startIndex: number;
+    /**
+     * display position of the last turn (inclusive)
+     */
+    endIndex: number;
+    /**
+     * wire entry index of the prompt (anchor)
+     */
+    promptEntryIndex: number;
+    /**
+     * wire entry index of the final assistant turn
+     */
+    finalEntryIndex?: number;
+    /**
+     * untruncated user prompt
+     */
+    prompt: string;
+    toolCallCount: number;
+    filesTouched: string[];
+    insertions: number;
+    deletions: number;
+    durationMs: number;
+    hasErrors: boolean;
+    tokens: number;
+};
+/**
+ * One segment of the proportional task waterfall: a task's share of the total
+ * work time and the cumulative share before it (segments tile back-to-back).
+ */
+export type WaterfallSegment = {
+    promptEntryIndex: number;
+    offsetPct: number;
+    widthPct: number;
+    durationMs: number;
+};
+export type FailedAttempt = {
+    tools: string[];
+    turnRange: [number, number];
+};
+export type PersonalMedians = {
+    retryShare?: number;
+    specQualityScore?: number;
+    withinSessionReverts?: number;
+};
+/**
+ * A session sample for personal-median computation — the QualitySession subset
+ * the medians read. Kept structural for consumer back-compat.
+ */
+export type PersonalMedianSession = {
+    totalTokens: number;
+    retryTokensWasted: number;
+    specQualityScore: number;
+    withinSessionReverts: number;
+};
+/**
+ * A client-side detected pattern moment. Canonical `TranscriptAnnotation` shape
+ * kept stable for back-compat re-export.
+ */
+export type TranscriptAnnotation = {
+    /**
+     * display position
+     */
+    turnIndex: number;
+    type: "retry" | "error" | "revert" | "subagent";
+    label: string;
+    severity: "info" | "warning" | "error";
+};
+export type PhaseType = "planning" | "exploration" | "implementation" | "testing" | "error" | "debug" | "retry-loop" | "user-correction" | "recovery" | "abandonment";
+export type PhaseSegment = {
+    type: PhaseType;
+    /**
+     * display position (inclusive)
+     */
+    startTurn: number;
+    /**
+     * display position (inclusive)
+     */
+    endTurn: number;
+    badges: {
+        type: PhaseType;
+        count: number;
+    }[];
+};

package/dist/lib/types/ui/transcript/time.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Is this a real recorded time? A missing, unparseable, zero, epoch or Go zero-time value
+ * ("0001-01-01T00:00:00Z") is unknown: nothing may render it, and no "ago" math runs on it.
+ *
+ * @param {string | null | undefined} iso
+ * @returns {boolean}
+ */
+export function isKnownTime(iso: string | null | undefined): boolean;
+/**
+ * Human-readable relative time: "just now", "3m ago", "2h ago", "4d ago"; past a week it reads as
+ * a date ("oct 14", or "oct 14, 2025" in another year). An unknown time reads as nothing.
+ *
+ * @param {string} iso        an ISO 8601 timestamp
+ * @param {number} [now]      reference "now" in epoch millis (defaults to `Date.now()`; pass explicitly for deterministic tests)
+ * @returns {string}
+ */
+export function formatRelative(iso: string, now?: number): string;
+/**
+ * The one duration format: human and short. "12s", "4m 30s", "4m", "1h 12m", "1h"; under a
+ * second "<1s"; zero, negative or unknown reads as nothing, so a caller hides the figure.
+ *
+ * @param {number | null | undefined} seconds
+ * @returns {string}
+ */
+export function formatDurationSeconds(seconds: number | null | undefined): string;
+/**
+ * A duration in minutes, in the one format: 4.5 -> "4m 30s", 76 -> "1h 16m", 0 -> "".
+ *
+ * @param {number | null | undefined} mins
+ * @returns {string}
+ */
+export function formatDurationMins(mins: number | null | undefined): string;
+/**
+ * A duration in milliseconds: a tool call reads "820ms" or "1.4s" while short, then the one
+ * format ("1m 15s"); zero or unknown reads as nothing.
+ *
+ * @param {number | null | undefined} ms
+ * @returns {string}
+ */
+export function formatDurationMs(ms: number | null | undefined): string;
+/**
+ * "Jan 12, 4:23 PM" — long datetime for tooltips.
+ *
+ * @param {string} iso
+ * @returns {string}
+ */
+export function formatDateLong(iso: string): string;

package/dist/lib/types/ui/transcript/title.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The prompt without a harness's <user_query> wrapper: the user's own text, untouched otherwise.
+ * @param {string | undefined} text
+ * @returns {string}
+ */
+export function unwrapUserQuery(text: string | undefined): string;
+/**
+ * A stored session title, shown as written: the harness's <user_query> wrapper dropped and the
+ * whitespace collapsed, but every word, its case, its dots and an existing trailing "…" kept. For a
+ * title, never `summarizePrompt`, which cuts at the first sentence and recases.
+ * @param {string | undefined} text
+ * @returns {string}
+ */
+export function cleanSessionTitle(text: string | undefined): string;
+/**
+ * The transcript page's title, the one rule the viewer's header and the share card both use: a
+ * curated title (an empty one is kept), else, when the session has no normalized evidence, the
+ * first task's prompt or the first user turn's text, else the session id, else "transcript".
+ * Session titles are often a whole first prompt, so the title is bounded to 160 characters: a
+ * longer one is cut to 159 and "…", never through a surrogate pair.
+ * @param {object} parts
+ * @param {string} [parts.title] curated session title
+ * @param {boolean} [parts.hasNormalizedEvidence] true when a title must not be inferred from a prompt
+ * @param {string} [parts.firstTaskPrompt]
+ * @param {string} [parts.firstUserContent]
+ * @param {string} [parts.id] session id
+ * @returns {string}
+ */
+export function transcriptTitle({ title, hasNormalizedEvidence, firstTaskPrompt, firstUserContent, id }: {
+    title?: string;
+    hasNormalizedEvidence?: boolean;
+    firstTaskPrompt?: string;
+    firstUserContent?: string;
+    id?: string;
+}): string;
+/**
+ * Produce a short, human-readable summary of a raw prompt. Heuristic, in order:
+ *   0. Drop a harness's <user_query> wrapper (cleanSessionTitle's rule).
+ *   1. Strip leading <system-reminder> blocks and leading fenced code blocks.
+ *   2. Pull out a <command-name> (e.g. `/mcp`) if present, keep following prose.
+ *   3. Strip remaining XML-ish tags, collapse whitespace, take the first sentence.
+ *   4. Capitalize the first letter and cap at `limit` chars with `…`.
+ *
+ * @param {string | undefined} raw
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function summarizePrompt(raw: string | undefined, limit?: number): string;
+/**
+ * Last path segment of a project string. `/Users/x/Projects/phaze` → `phaze`.
+ * Falls back to the whole string if there's no separator. Returns `''` when the
+ * input is empty/undefined.
+ *
+ * @param {string | undefined} project
+ * @returns {string}
+ */
+export function projectLabel(project: string | undefined): string;
+/**
+ * Compose the session detail h1.
+ *
+ *   • {project}: {Summary}   — project + meaningful prompt
+ *   • {project}, {shortId}  — project, no usable prompt
+ *   • {shortId} — {Summary}  — no project, but a prompt
+ *   • Session {shortId}      — nothing useful at all
+ *
+ * The full prompt text (or composed title) is returned alongside as a tooltip
+ * string so `<h1 title=…>` can expose the raw prompt on hover.
+ *
+ * @param {object} args
+ * @param {string} args.id
+ * @param {string | undefined} args.project
+ * @param {string | undefined} args.promptContent
+ * @param {number} [args.limit]
+ * @returns {{ title: string, tooltip: string }}
+ */
+export function composeSessionTitle(args: {
+    id: string;
+    project: string | undefined;
+    promptContent: string | undefined;
+    limit?: number;
+}): {
+    title: string;
+    tooltip: string;
+};

package/dist/lib/types/ui/transcript/usage.d.ts

@@ -0,0 +1,19 @@
+/** @param {import('@peasant-labs/schema').TurnDetail[]} turns
+ * @returns {import('./view-model.js').UsageScopeVM[]} */
+export function aggregateUsage(turns: import("@peasant-labs/schema").TurnDetail[]): import("./view-model.js").UsageScopeVM[];
+export const TOKEN_FIELDS: Readonly<{
+    input: "input";
+    output: "output";
+    cacheRead: "cache read";
+    cacheWrite: "cache write";
+    cacheWrite1h: "cache write 1h (subset)";
+    reasoning: "reasoning (subset)";
+    totalTokens: "total tokens";
+}>;
+export const COST_FIELDS: Readonly<{
+    input: "input";
+    output: "output";
+    cacheRead: "cache read";
+    cacheWrite: "cache write";
+    total: "total";
+}>;