@peasant-labs/fairtrade 0.0.2 → 0.0.3

package/dist/lib/types/transcript/wire-types.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Sender role of a turn. schema/develop/types.go:425-430.
+ * @typedef {'user' | 'assistant' | 'tool' | 'system'} Role
+ */
+/** Canonical Role values, in schema order. @type {readonly Role[]} */
+export const ROLES: readonly Role[];
+/**
+ * Classification of a single transcript entry. schema/develop/types.go:464-472.
+ * `thinking` (468) is a first-class entry type: a standalone thinking entry is
+ * its own `entryType=thinking` turn, rendered from `turn.content`.
+ * @typedef {'text' | 'tool_use' | 'tool_result' | 'thinking' | 'system' | 'error' | 'result'} EntryType
+ */
+/** Canonical EntryType values, in schema order. @type {readonly EntryType[]} */
+export const ENTRY_TYPES: readonly EntryType[];
+/**
+ * Tool-call classification, ACP-aligned. schema/develop/types.go:336-346.
+ * The mockup's demo tool kinds map onto these canonical kinds: bash→execute,
+ * grep→search, task→other (subagent), webfetch→fetch.
+ * @typedef {'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'other'} ToolCallKind
+ */
+/** Canonical ToolCallKind values, in schema order. @type {readonly ToolCallKind[]} */
+export const TOOL_CALL_KINDS: readonly ToolCallKind[];
+/**
+ * Why a turn (or session) ended. schema/develop/types.go:383-389.
+ * @typedef {'end_turn' | 'cancelled' | 'max_tokens' | 'max_turn_requests' | 'refusal'} StopReason
+ */
+/** Canonical StopReason values, in schema order. @type {readonly StopReason[]} */
+export const STOP_REASONS: readonly StopReason[];
+/**
+ * Heuristic resolution status of a session. schema/develop/types.go:193-195.
+ * @typedef {'resolved' | 'partial' | 'failed'} SessionOutcome
+ */
+/** Canonical SessionOutcome values, in schema order. @type {readonly SessionOutcome[]} */
+export const SESSION_OUTCOMES: readonly SessionOutcome[];
+/**
+ * The coding tool / AI-assisted environment that produced the session.
+ * bestiary.Harness (the ingestion-supported set peasant emits). The string
+ * union is the wire contract; bestiary may know a superset, so consumers MUST
+ * tolerate an unknown harness string (degrade, never throw).
+ * @typedef {'claude-code' | 'gemini-cli' | 'codex' | 'opencode' | 'cursor' | 'antigravity' | (string & {})} Harness
+ */
+/** Canonical Harness values peasant ingests, in display order. @type {readonly Harness[]} */
+export const HARNESSES: readonly Harness[];
+/**
+ * Sender role of a turn. schema/develop/types.go:425-430.
+ */
+export type Role = "user" | "assistant" | "tool" | "system";
+/**
+ * Classification of a single transcript entry. schema/develop/types.go:464-472.
+ * `thinking` (468) is a first-class entry type: a standalone thinking entry is
+ * its own `entryType=thinking` turn, rendered from `turn.content`.
+ */
+export type EntryType = "text" | "tool_use" | "tool_result" | "thinking" | "system" | "error" | "result";
+/**
+ * Tool-call classification, ACP-aligned. schema/develop/types.go:336-346.
+ * The mockup's demo tool kinds map onto these canonical kinds: bash→execute,
+ * grep→search, task→other (subagent), webfetch→fetch.
+ */
+export type ToolCallKind = "read" | "edit" | "delete" | "move" | "search" | "execute" | "think" | "fetch" | "other";
+/**
+ * Why a turn (or session) ended. schema/develop/types.go:383-389.
+ */
+export type StopReason = "end_turn" | "cancelled" | "max_tokens" | "max_turn_requests" | "refusal";
+/**
+ * Heuristic resolution status of a session. schema/develop/types.go:193-195.
+ */
+export type SessionOutcome = "resolved" | "partial" | "failed";
+/**
+ * The coding tool / AI-assisted environment that produced the session.
+ * bestiary.Harness (the ingestion-supported set peasant emits). The string
+ * union is the wire contract; bestiary may know a superset, so consumers MUST
+ * tolerate an unknown harness string (degrade, never throw).
+ */
+export type Harness = "claude-code" | "gemini-cli" | "codex" | "opencode" | "cursor" | "antigravity" | (string & {});
+/**
+ * A single tool call inside a turn. schema/develop/local_api.go:69-79.
+ *
+ * `arguments` and `result` are JSON-ENCODED STRINGS on the wire. The adapter is
+ * the SOLE site that `JSON.parse`s them; components receive the parsed,
+ * preview-cooked `ToolCallVM` (see view-model.js), never these raw strings.
+ */
+export type ToolCallDetail = {
+    id: string;
+    name: string;
+    /**
+     * JSON-encoded string (parse in the adapter only)
+     */
+    arguments: string;
+    /**
+     * JSON-encoded string (parse in the adapter only)
+     */
+    result: string;
+    /**
+     * ms; absent when not measured
+     */
+    durationMs?: number;
+    /**
+     * process exit code, when applicable
+     */
+    exitCode?: number;
+    /**
+     * target path for file-oriented tools
+     */
+    filePath?: string;
+    /**
+     * true when the call failed
+     */
+    isError?: boolean;
+    /**
+     * ACP-aligned classification; may be omitted
+     */
+    toolKind?: ToolCallKind;
+};
+/**
+ * One turn with full content, as folded server-side. schema/develop/local_api.go:50-66.
+ *
+ * `content` already contains any folded thinking text (the server only
+ * suppresses a redundant depth=1 thinking/text sibling whose parent already
+ * carries the text). Components render thinking from `turn.content`.
+ *
+ * `parentIndex` is present on the Go wire but OMITTED by the drifted TS shape;
+ * consumers MUST NOT depend on it (the graph keys nesting off `depth`). Typed
+ * here as optional-and-nullable for fidelity only.
+ */
+export type TurnDetail = {
+    index: number;
+    role: Role;
+    /**
+     * folded text (incl. thinking) for this turn
+     */
+    content: string;
+    /**
+     * omitempty on the wire
+     */
+    toolCalls?: ToolCallDetail[];
+    /**
+     * RFC3339 (Go time.Time marshals to a string)
+     */
+    timestamp: string;
+    /**
+     * subagent nesting depth (0 = top level)
+     */
+    depth: number;
+    /**
+     * DO NOT rely on this — use `depth`. May be absent or null.
+     */
+    parentIndex?: number | null;
+    agentName?: string;
+    /**
+     * enrichment, propagated from session_entries
+     */
+    entryType?: EntryType;
+    hasThinking?: boolean;
+    stopReason?: StopReason | null;
+    tokensIn?: number | null;
+    tokensOut?: number | null;
+};
+/**
+ * Lightweight reference to a child (subagent) session. schema/develop/local_api.go:153-157.
+ */
+export type ChildSessionRef = {
+    id: string;
+    /**
+     * RFC3339
+     */
+    startTime: string;
+    project?: string;
+};
+/**
+ * Deterministic per-session quality signals for the "How this session went"
+ * self-assessment card. schema/develop/local_api.go:131-150. All numeric fields
+ * are nullable so a consumer can distinguish "not computed" (absent/null) from a
+ * real zero before applying threshold bands.
+ */
+export type SessionScorecard = {
+    m2TokenOutcomeRatio?: number | null;
+    m5ContextUtilizationPct?: number | null;
+    m6OutputSurvivalPct?: number | null;
+    retryTokensWasted?: number | null;
+    totalTokens?: number | null;
+    costTotalUsd?: number | null;
+    specQualityScore?: number | null;
+    signalDensity?: number | null;
+    m7SpecHasExamples?: boolean | null;
+    m7SpecHasConstraints?: boolean | null;
+    m4ConsecutiveErrorMax?: number | null;
+    withinSessionReverts?: number | null;
+    /**
+     * echoes the session outcome for band triggers
+     */
+    outcome?: SessionOutcome;
+};
+/**
+ * A single git commit linked to a session. schema/develop/metadata.go:89-96.
+ * Lives on GitContext.Commits in metadata.json (v4+); absent from the
+ * session_detail payload. Reaches components only after the adapter cooks it
+ * into `vm.session.git.commits`.
+ */
+export type CommitInfo = {
+    /**
+     * commit SHA-1 (full or abbreviated)
+     */
+    hash: string;
+    /**
+     * first line of the commit message
+     */
+    message: string;
+    authorName: string;
+    authorEmail: string;
+    /**
+     * committer date, Unix millis
+     */
+    commitTime: number;
+    /**
+     * author date, Unix millis
+     */
+    authorTime: number;
+};
+/**
+ * Git repository state captured for a session. schema/develop/metadata.go:99-105.
+ * This is the NESTED shape the drifted TS `@peasant-labs/types` exposes and the
+ * shape the mockup fixtures / TB's sample-session hand-populate. It is NOT on
+ * the real Go session_detail wire (which carries only flat gitBranch/gitRemote).
+ * The adapter tolerates this shape too (see `TranscriptWireInput`).
+ */
+export type GitContext = {
+    branch?: string | null;
+    remote?: string | null;
+    worktree?: string | null;
+    tracking?: string | null;
+    /**
+     * produced during this session (v4+)
+     */
+    commits?: CommitInfo[];
+};
+/**
+ * Wire format for an annotation. schema/develop/annotation.go:46-66. Fetched
+ * separately from the payload (WS `annotations` / GET /api/v1/annotations?
+ * session_id=) and passed to the adapter alongside the payload.
+ * `targetEntryEndIndex` is half-open: the range is [targetEntryIndex, end).
+ */
+export type AnnotationSummary = {
+    id: string;
+    targetKind: string;
+    targetSessionId?: string;
+    targetEntryIndex?: number;
+    /**
+     * half-open [start, end)
+     */
+    targetEntryEndIndex?: number;
+    targetAnnotationId?: string;
+    targetProjectHash?: string;
+    isPrimary: boolean;
+    annotatorKind: string;
+    annotatorName: string;
+    typeId: string;
+    typeName: string;
+    value: string;
+    confidence?: number;
+    reason?: string;
+    provenance?: object;
+    contentHash?: string;
+    /**
+     * Unix millis
+     */
+    createdAt: number;
+    supersededBy?: string;
+};
+/**
+ * The full single-session detail payload. schema/develop/local_api.go:92-123.
+ * This is the actual local WebSocket `session_detail` wire body. Note: it
+ * carries FLAT `gitBranch` / `gitRemote` (strings) and NO `gitContext` / commits
+ * (local_api.go:111-112). Turns are already folded server-side.
+ */
+export type SessionDetailPayload = {
+    /**
+     * embedded push-contract version (advisory; omitempty)
+     */
+    schemaVersion?: string;
+    id: string;
+    harness: Harness;
+    /**
+     * RFC3339
+     */
+    startTime: string;
+    /**
+     * RFC3339
+     */
+    endTime: string;
+    durationMins: number;
+    totalTokens: number;
+    tokensIn: number;
+    tokensOut: number;
+    turnCount: number;
+    toolCallCount: number;
+    turns: TurnDetail[];
+    source?: string;
+    status?: string;
+    project?: string;
+    model?: string;
+    workingDirectory?: string;
+    /**
+     * FLAT string on the Go wire (NOT gitContext)
+     */
+    gitBranch?: string;
+    /**
+     * FLAT string on the Go wire (NOT gitContext)
+     */
+    gitRemote?: string;
+    childSessions?: ChildSessionRef[];
+    outcome?: SessionOutcome;
+    scorecard?: SessionScorecard | null;
+};
+/**
+ * The transcript adapter's input type. It is the canonical `SessionDetailPayload`
+ * WIDENED with the nested `gitContext?` so the one adapter compiles against BOTH
+ * runtime shapes — the Go wire (flat gitBranch/gitRemote) AND the drifted TS
+ * `@peasant-labs/types` shape (gitContext? only) — and normalizes whichever is
+ * present into the cooked, optional `vm.session.git`. This widening is the ONLY
+ * place both git shapes coexist; it MUST NOT leak past the adapter into any
+ * component prop contract.
+ */
+export type TranscriptWireInput = SessionDetailPayload & {
+    gitContext?: GitContext;
+};