@teaflask/assistant 0.3.0 → 0.6.0

package/dist/core/question-drafts.js

@@ -1,48 +1,9 @@
-// The question-set draft store: where a member's in-progress
-// answers to a builtin.ask_questions pause live while they page through
-// the panel. OUTSIDE every component on purpose — the suspension pager
-// remounts the presented surface by decision identity, the transcript
-// remounts on every reconnect nonce, and the playground remounts its
-// whole transcript on send/retry — so a draft held in component state
-// dies at exactly the moments a member is most likely to be mid-answer.
-// Keyed by interrupt id (one pause = one question set) and question id
-// beneath it, so two sets can never bleed into each other and the pager
-// key's isolation guarantee survives without the key eating the draft.
-//
-// LIFETIME (ruled here, not inferred): created lazily on the first
-// mutation; kept across navigation, remount, reconnect and a failed
-// submit; cleared by the owner only on present-and-settled evidence (the
-// member's own successful submit or cancel, or a published card for the
-// same interrupt that reads answered/stale) — never on mere absence,
-// because a reconnect publishes an empty entry list before the replay
-// refills it; cleared wholesale on a thread switch. IN-MEMORY ONLY: a
-// page reload loses unsent drafts. That is a decision, not a gap — a
-// pause can be voided from another tab by a new message, and persisted
-// drafts would resurrect stale text against a superseded set.
-//
-// ACTIVE CHOICE is explicit: an option OR the custom row, never a hidden
-// "typed text wins" rule. Selecting an option keeps the custom text (the
-// member may come back to it); typing in the custom row makes it active.
-//
-// Deliberately import-free and React-free: every draft law (explicit
-// active choice, cursor in the draft, release only on explicit clear)
-// reads the same on every surface because there is one store — exported
-// on @teaflask/assistant/transcript for the playground.
-/** The per-answer transport bound the server enforces (QuestionAnswer.text
- *  maxLength on the serving contract — pinned equal by the monorepo's
- *  contract-parity test). The panel says so beside the row instead of
- *  clipping: no silent truncation. Measured here in UTF-16 units
- *  (String.length) while the server counts code points — an astral
- *  character costs two here and one there, so this side is the stricter
- *  or equal one and a text that passes the panel never fails the door. */
 export const MAX_ANSWER_TEXT_CHARS = 1900;
 const EMPTY_ANSWER = { active: null, customText: "" };
 const EMPTY_SET = { cursor: 0, answers: new Map() };
 export class QuestionDraftStore {
     drafts = new Map();
     listeners = new Set();
-    // Arrow fields on purpose: get/subscribe travel unbound into
-    // useSyncExternalStore.
     get = (interruptId) => {
         return this.drafts.get(interruptId) ?? EMPTY_SET;
     };
@@ -52,8 +13,6 @@ export class QuestionDraftStore {
             this.listeners.delete(listener);
         };
     };
-    /** True when the member has entered anything for this set — what the
-     *  panel's Cancel consults before asking "Discard answers?". */
     hasContent(interruptId) {
         const draft = this.drafts.get(interruptId);
         if (draft === undefined) {
@@ -78,12 +37,6 @@ export class QuestionDraftStore {
             active: { kind: "custom" },
         }));
     }
-    /** Typing makes the custom row the active choice — the one implicit
-     *  switch, and it is the member's own keystroke. The text is written
-     *  as the door will accept it: pasted control characters are
-     *  normalized here (see normalizeCustomText), so the panel's posture —
-     *  every per-answer rule the door enforces is kept in view before the
-     *  POST — holds for the control rule as it does for the length bound. */
     setCustomText(interruptId, questionId, text) {
         this.updateAnswer(interruptId, questionId, (answer) => ({
             ...answer,
@@ -139,10 +92,6 @@ function sameChoice(a, b) {
     }
     return a.kind === "option" && b.kind === "option" ? a.text === b.text : true;
 }
-/** The text one question's draft answers with, or null while it has no
- *  usable answer: an active option is its text; the custom row counts
- *  only with non-blank text (submitted verbatim — trimming is for the
- *  emptiness test alone, never the payload). */
 function answerTextOf(draft) {
     const active = draft?.active ?? null;
     if (active === null || draft === undefined) {
@@ -153,8 +102,6 @@ function answerTextOf(draft) {
     }
     return draft.customText.trim() === "" ? null : draft.customText;
 }
-/** The complete answer set in question order, or null while any
- *  question is unanswered — the panel's Submit gate and its POST body. */
 export function answersOf(questions, draft) {
     const answers = [];
     for (const question of questions) {
@@ -166,28 +113,14 @@ export function answersOf(questions, draft) {
     }
     return answers;
 }
-/** The door refuses C0 control characters other than tab, newline and
- *  carriage return (a transport rule that bounds the escaped worst case).
- *  A textarea only normalizes CRLF, and real pastes carry the rest: Word
- *  and Google Docs emit a vertical tab (U+000B) for a soft line break,
- *  some PDF viewers a form feed (U+000C) for a page break. Those two ARE
- *  line breaks to the member, so they become newlines — the break
- *  survives unchanged in meaning; the others (NUL, BEL, BS, ESC, …) carry
- *  no text and are dropped. Never a truncation: every printable character
- *  stays exactly where it was. */
 function normalizeCustomText(text) {
     return text
         .replace(/[\u000b\u000c]/g, "\n")
         .replace(/[\u0000-\u0008\u000e-\u001f]/g, "");
 }
-/** The index of the first question still without a usable answer, or -1
- *  when the set is complete — what the footer names when Submit is gated,
- *  and where a continue from the last question jumps to. */
 export function firstUnansweredIndexOf(questions, draft) {
     return questions.findIndex((question) => answerTextOf(draft.answers.get(question.id)) === null);
 }
-/** The ids whose custom text exceeds the transport bound — the panel
- *  says so beside the row instead of clipping (no silent truncation). */
 export function overLimitOf(questions, draft, maxChars) {
     const over = [];
     for (const question of questions) {
@@ -200,4 +133,3 @@ export function overLimitOf(questions, draft, maxChars) {
     }
     return over;
 }
-//# sourceMappingURL=question-drafts.js.map

package/dist/core/question-receipt.d.ts

@@ -1,10 +1,5 @@
 import type { AnsweredQuestions } from "./elicitation-cards.js";
 import { type QuestionModel } from "./elicitation-pickers.js";
-/** A settled question set as the transcript states it: the questions
- *  and the member's answers (verbatim, line breaks kept). A cancelled set
- *  is NOT a receipt — nothing was answered, and the dismissed fact is
- *  the panel footer's to state (the meta-receipt rule), never a
- *  transcript row's. */
 export interface SettledQuestionsReceipt {
     questions: readonly QuestionModel[];
     answers: readonly {
@@ -12,23 +7,5 @@ export interface SettledQuestionsReceipt {
         text: string;
     }[];
 }
-/** The receipt for a card this tab saw settle: the member's own answers
- *  when the store stamped them, else the plain answered fact per
- *  question (a set another client answered — the text never reached this
- *  tab; the row's tool result is the durable record). Null for a
- *  cancelled set: no receipt renders for a dismissal. */
 export declare function settledQuestionsReceiptOfCard(questions: readonly QuestionModel[], answered: AnsweredQuestions | null): SettledQuestionsReceipt | null;
-/**
- * Recover a settled question set from a durable ask_user tool row:
- * the stored arguments must narrow to a question set AND the
- * result must be the tool's ANSWERED return — `{answers: [{id, text}]}` —
- * for the row to collapse into a receipt. A cancelled return
- * (`{cancelled: true}`) is a settled decision with no answers: the row
- * keeps its own state and no prose renders for it (the meta-receipt rule:
- * the dismissed fact is the panel footer's, in shelf-less hosts). A failure
- * envelope, the chat fallback, or an unrelated tool's questions-shaped
- * arguments never become one. Tool identity is checked first; the
- * projection routes, it never guesses.
- */
 export declare function settledQuestionsReceiptOf(toolName: string, argsText: string, resultText: string | undefined): SettledQuestionsReceipt | null;
-//# sourceMappingURL=question-receipt.d.ts.map

package/dist/core/question-receipt.js

@@ -1,27 +1,10 @@
 import { askQuestionsActionOf, } from "./elicitation-pickers.js";
-/** The receipt for a card this tab saw settle: the member's own answers
- *  when the store stamped them, else the plain answered fact per
- *  question (a set another client answered — the text never reached this
- *  tab; the row's tool result is the durable record). Null for a
- *  cancelled set: no receipt renders for a dismissal. */
 export function settledQuestionsReceiptOfCard(questions, answered) {
     if (answered !== null && answered.kind === "cancelled") {
         return null;
     }
     return { questions, answers: answered === null ? [] : answered.answers };
 }
-/**
- * Recover a settled question set from a durable ask_user tool row:
- * the stored arguments must narrow to a question set AND the
- * result must be the tool's ANSWERED return — `{answers: [{id, text}]}` —
- * for the row to collapse into a receipt. A cancelled return
- * (`{cancelled: true}`) is a settled decision with no answers: the row
- * keeps its own state and no prose renders for it (the meta-receipt rule:
- * the dismissed fact is the panel footer's, in shelf-less hosts). A failure
- * envelope, the chat fallback, or an unrelated tool's questions-shaped
- * arguments never become one. Tool identity is checked first; the
- * projection routes, it never guesses.
- */
 export function settledQuestionsReceiptOf(toolName, argsText, resultText) {
     if (toolName !== "ask_user" ||
         resultText === undefined ||
@@ -70,4 +53,3 @@ function _recordOf(text) {
     }
     return parsed;
 }
-//# sourceMappingURL=question-receipt.js.map

package/dist/core/reasoning-copy.d.ts

@@ -1,3 +1,2 @@
 export declare const REASONING_STREAMING_LABEL = "Thinking\u2026";
 export declare const REASONING_SETTLED_LABEL = "Thought about it";
-//# sourceMappingURL=reasoning-copy.d.ts.map

package/dist/core/reasoning-copy.js

@@ -1,10 +1,2 @@
-// The reasoning step's two state labels, in core so both consumers read
-// ONE spelling: components/reasoning-row.tsx renders them on the row,
-// and core/run-folds.ts's liveFoldHeadlineOf names a collapsed live
-// fold's latest step with them. Components import core, never the
-// reverse — hoisting the strings here is what lets the pure headline
-// derivation say exactly what the row says without a core→component
-// import.
 export const REASONING_STREAMING_LABEL = "Thinking…";
 export const REASONING_SETTLED_LABEL = "Thought about it";
-//# sourceMappingURL=reasoning-copy.js.map

package/dist/core/receipt-anchors.d.ts

@@ -3,34 +3,7 @@ export interface AnchoredReceipts {
     before: string[];
     after: string[];
 }
-/**
- * Narrow a receipt-carrying CUSTOM event's wire value (any by contract).
- * Malformed payloads return null and are ignored — the contract's
- * "clients MUST ignore events and fields they do not recognize".
- */
 export declare function receiptOf(value: unknown): string | null;
-/**
- * Idempotent anchor merge: every connection replays the stream from its
- * boundary (and StrictMode aborts and reruns the first connection), so the
- * same receipt can be anchored more than once per mount. Merging by content
- * keeps replays from stuttering the rows.
- */
 export declare function withReceiptAnchored(previous: ReadonlyMap<string, AnchoredReceipts>, messageId: string, position: keyof AnchoredReceipts, receipts: string[]): ReadonlyMap<string, AnchoredReceipts>;
-/**
- * A defensive copy for seeding transcript state from the resume store:
- * entries that do not hold well-formed receipts are dropped rather than
- * rendered (or crashed on). The store is in-memory today, so every entry
- * it holds passed the payload narrower — this seam is where any future
- * persisted form of the store must degrade gracefully instead of wedging
- * the resume path: a dropped receipt reappears on the next full replay.
- */
 export declare function wellFormedReceiptAnchorsOf(stored: ReadonlyMap<string, AnchoredReceipts>): ReadonlyMap<string, AnchoredReceipts>;
-/**
- * Anchors each of one marker's receipts: the marker and its run's
- * terminal are written in one commit, so the terminal is always the very
- * next event — the live RUN_ERROR for turn_failed, demoted to a quiet
- * RUN_FINISHED on replay — and the receipt flushes to a row after that
- * run's last message on either one.
- */
 export declare function receiptMarkerRecorder(eventName: string, onReceiptAnchored: (runId: string, messageId: string, position: keyof AnchoredReceipts, receipts: string[]) => void): AgentSubscriber;
-//# sourceMappingURL=receipt-anchors.d.ts.map

package/dist/core/receipt-anchors.js

@@ -1,16 +1,4 @@
-// The string-receipt anchor family ({ receipt: string }, pinned per-marker by
-// tests/contract-parity): the marker and its run's terminal are written in
-// one commit, the receipt never becomes a message, and the row renders after
-// the run's last message. The package's one consumer is turn_failed (the
-// turn_voided row was deleted with the meta-receipts); the dashboard binds
-// turn_failed and turn_stopped through ./transcript, so ReceiptPayload pins
-// all three.
 import { WIRE_SENTENCE_MAX_CHARS } from "./wire-sentence-cap.js";
-/**
- * Narrow a receipt-carrying CUSTOM event's wire value (any by contract).
- * Malformed payloads return null and are ignored — the contract's
- * "clients MUST ignore events and fields they do not recognize".
- */
 export function receiptOf(value) {
     if (typeof value !== "object" || value === null) {
         return null;
@@ -21,16 +9,8 @@ export function receiptOf(value) {
     }
     return payload.receipt.slice(0, WIRE_SENTENCE_MAX_CHARS);
 }
-/**
- * Idempotent anchor merge: every connection replays the stream from its
- * boundary (and StrictMode aborts and reruns the first connection), so the
- * same receipt can be anchored more than once per mount. Merging by content
- * keeps replays from stuttering the rows.
- */
 export function withReceiptAnchored(previous, messageId, position, receipts) {
     const anchored = previous.get(messageId) ?? { before: [], after: [] };
-    // Unique within the batch too: a flush can carry the same receipt
-    // twice when two connections' deliveries pooled before it.
     const fresh = [...new Set(receipts)].filter((receipt) => !anchored[position].includes(receipt));
     if (fresh.length === 0) {
         return previous;
@@ -42,18 +22,8 @@ export function withReceiptAnchored(previous, messageId, position, receipts) {
     });
     return next;
 }
-/**
- * A defensive copy for seeding transcript state from the resume store:
- * entries that do not hold well-formed receipts are dropped rather than
- * rendered (or crashed on). The store is in-memory today, so every entry
- * it holds passed the payload narrower — this seam is where any future
- * persisted form of the store must degrade gracefully instead of wedging
- * the resume path: a dropped receipt reappears on the next full replay.
- */
 export function wellFormedReceiptAnchorsOf(stored) {
     const seeded = new Map();
-    // The narrowing deliberately distrusts the map's own types: this seam
-    // is what turns a stale shape into missing rows instead of a crash.
     const entries = stored;
     for (const [messageId, anchored] of entries) {
         const before = _wellFormedReceiptsAt(anchored, "before");
@@ -64,21 +34,10 @@ export function wellFormedReceiptAnchorsOf(stored) {
     }
     return seeded;
 }
-/**
- * Anchors each of one marker's receipts: the marker and its run's
- * terminal are written in one commit, so the terminal is always the very
- * next event — the live RUN_ERROR for turn_failed, demoted to a quiet
- * RUN_FINISHED on replay — and the receipt flushes to a row after that
- * run's last message on either one.
- */
 export function receiptMarkerRecorder(eventName, onReceiptAnchored) {
     let pendingReceipts = [];
     let currentRunId = null;
     let newestMessageId = null;
-    // One flush for both terminals: a failed run's live ending is
-    // RUN_ERROR, and replay demotes it to a quiet RUN_FINISHED — the
-    // turn_failed receipt must flush on either, or a live failure would
-    // anchor nothing until the next reload.
     const flush = () => {
         if (pendingReceipts.length === 0 ||
             newestMessageId === null ||
@@ -89,19 +48,12 @@ export function receiptMarkerRecorder(eventName, onReceiptAnchored) {
         pendingReceipts = [];
     };
     return {
-        // One agent can be connected more than once (StrictMode detaches
-        // the first run terminal-free and starts over): receipts a dead
-        // connection collected but never flushed must not ride into the
-        // replacement's flush, or the replay's own copy doubles them.
         onRunInitialized() {
             pendingReceipts = [];
             currentRunId = null;
             newestMessageId = null;
         },
         onRunStartedEvent({ event }) {
-            // The server-named run id: the receipt's identity rides the run
-            // it marked, so re-deliveries anchor once no matter where each
-            // connection's message list has drifted to at flush time.
             currentRunId = event.runId;
         },
         onCustomEvent({ event }) {
@@ -134,4 +86,3 @@ function _wellFormedReceiptsAt(anchored, position) {
     }
     return receipts.filter((receipt) => typeof receipt === "string" && receipt !== "");
 }
-//# sourceMappingURL=receipt-anchors.js.map

package/dist/core/run-folds.d.ts

@@ -1,10 +1,6 @@
 import { type SegmentDuration } from "./segment-timing.js";
 import { type AssistantTextRow, type MarkerBoundaries, type ReasoningRow, type ToolCallRow, type TranscriptBlock, type TranscriptRow } from "./transcript-rows.js";
 export type RunFoldMember = ReasoningRow | ToolCallRow | AssistantTextRow;
-/** The fold's steps in transcript order: tool calls verbatim, narration
- *  verbatim at its own position, and each CONTIGUOUS run of reasoning rows
- *  merged into one thinking block at the run's position — adjacent deltas
- *  read as one thought; thinking after a tool call stays below it. */
 export type RunFoldStep = {
     kind: "reasoning";
     view: ReasoningRow;
@@ -17,74 +13,24 @@ export type RunFoldStep = {
 };
 export interface RunFoldRow {
     kind: "run-fold";
-    /** Derived from the first WORK member (reasoning or tool call, never
-     *  narration), so stable across the running→settled flip AND episode
-     *  unification: a settled episode's key equals the key of the live cluster
-     *  it starts with, so a surviving fold's <details> never remounts
-     *  mid-conversation (TVC-014 element identity; TVC-084 key continuity). */
     key: string;
-    /** The raw member rows — liveness and pending-decision derivations
-     *  read these, and each work member still carries its own timing. */
     members: readonly RunFoldMember[];
     steps: readonly RunFoldStep[];
-    /** This fold's own span, reduced over its members' timing evidence —
-     *  unknown when no member carries any (an old history), never zero. */
     duration: SegmentDuration;
 }
-/** Reasoning is structurally excluded from the folded list: it only ever
- *  renders inside a run fold. */
 export type FoldedTranscriptRow = Exclude<TranscriptRow, ReasoningRow> | RunFoldRow;
 export interface RunFoldsOptions {
-    /** True while the newest turn is non-terminal (queued, working,
-     *  awaiting_input, parked — isTerminalTurnStatus's complement): the
-     *  trailing turn then keeps the per-cluster live folding so nothing
-     *  moves mid-turn and no intermediate paragraph is prematurely read as
-     *  the final answer. Settled turns always unify into episodes. */
     openTailTurn?: boolean;
-    /** The tail turn's start index, pre-computed by the caller: foldedBlocksOf
-     *  derives it ONCE over the whole flat list and hands each segment its
-     *  clamped offset, so a mid-open-turn boundary never prematurely
-     *  episode-folds the open turn. Outranks openTailTurn; clamped to the list. */
     tailStart?: number;
 }
-/** Fold the projected rows. Rows before the tail turn (and the whole list
- *  once the newest turn settles) fold as completed episodes; the open tail
- *  turn — from the last user or subagent-delivery row on — keeps the live
- *  per-cluster folding. */
 export declare function runFoldsOf(rows: readonly TranscriptRow[], options?: RunFoldsOptions): FoldedTranscriptRow[];
-/** A row either turn-boundary scan may read: the projection's raw rows or
- *  the fold pass's display rows. The union keeps the boundary kinds below as
- *  checked literals — a renamed row kind fails the build here. */
 type TurnBoundaryRow = TranscriptRow | FoldedTranscriptRow;
-/** A block whose rows the declared-start scan counts: the projection's
- *  TranscriptBlock and the fold pass's own FoldedBlock both qualify. */
 interface CountableBlock {
     messageId: string;
     rows: readonly TurnBoundaryRow[];
 }
-/**
- * Where the current turn starts, as a flat index into `rows`: the LAST
- * boundary of either kind — the newest row the tail scan recognizes or the
- * newest declared turn-start block — whichever is later. `null` blocks
- * means only the row scan applies. The fold pass and the row list's
- * placement hold both read this spelling, so the two windows never disagree.
- */
 export declare function currentTurnStartOf(rows: readonly TurnBoundaryRow[], blocks: readonly CountableBlock[] | null, turnStartIds?: ReadonlySet<string>): number;
-/** The settled fold headline. The duration is the member-relevant cost —
- *  never a step count (TVC-011) — and the register is honest about its
- *  evidence: a measured sub-second span reads "<1s", never "Worked for 0s";
- *  an unknown span degrades to the neutral "Worked", never an invented
- *  duration (docs/replay-metadata-contract.md, "Unknown vs sub-second"). */
 export declare function settledFoldHeadlineOf(duration: SegmentDuration): string;
-/**
- * A COLLAPSED live fold's headline: the latest step's own label, so the
- * member tracks the work without expanding (the expanded fold keeps the
- * generic "Working…"). Each label is the one the step's own row wears: a
- * tool call reads toolRowHeadlineOf on its OWN state, a reasoning step the
- * ReasoningRow labels; narration is skipped (prose is not a work step); no
- * usable step → "Working…". Returned RAW: the renderer (FoldHeadline)
- * truncates for display and carries this text as its wrapper's title.
- */
 export declare function liveFoldHeadlineOf(steps: readonly RunFoldStep[]): string;
 export interface FoldedBlock {
     messageId: string;
@@ -92,12 +38,6 @@ export interface FoldedBlock {
 }
 export declare function foldedBlocksOf(blocks: readonly TranscriptBlock[], options?: Omit<RunFoldsOptions, "tailStart"> & {
     markerBoundaries?: MarkerBoundaries;
-    /** Message ids that BEGIN a turn without a user message — the
-     *  machine-initiated delivery turns. A host that draws its own delivery
-     *  marker (agent mode rides the delivery anchors in EMPTY, so no row is
-     *  projected) must hand the turn starts in here, or the open tail window
-     *  falls back to the previous member turn's user row. */
     turnStartIds?: ReadonlySet<string>;
 }): FoldedBlock[];
 export {};
-//# sourceMappingURL=run-folds.d.ts.map

package/dist/core/run-folds.js

@@ -1,21 +1,7 @@
-// Run folds: the pure grouping pass between the
-// row projection and the rendered transcript. Open turn: consecutive
-// reasoning/tool rows are one fold, and any other row splits at its exact
-// position. Settled turn: each work span unifies around its LAST maximal
-// prose run, which stays outside — collapse the work, never the answer.
-// Structural only: position and row kinds decide, never content and never
-// which views a tool row resolves — a view is inspected at its
-// own row inside the fold. Each fold's duration reduces over ITS OWN
-// members' server timing. The premises in full:
-// docs/transcript-rows-and-folds.md, "Fold premises".
 import { REASONING_SETTLED_LABEL, REASONING_STREAMING_LABEL, } from "./reasoning-copy.js";
 import { durationLabelOf, settledFoldDurationOf, } from "./segment-timing.js";
 import { toolRowHeadlineOf } from "./tool-call-display.js";
 import { EMPTY_MARKER_BOUNDARIES, } from "./transcript-rows.js";
-/** Fold the projected rows. Rows before the tail turn (and the whole list
- *  once the newest turn settles) fold as completed episodes; the open tail
- *  turn — from the last user or subagent-delivery row on — keeps the live
- *  per-cluster folding. */
 export function runFoldsOf(rows, options = {}) {
     const folded = [];
     const tailStart = options.tailStart !== undefined
@@ -27,10 +13,6 @@ export function runFoldsOf(rows, options = {}) {
     _pushClusterFolds(rows.slice(tailStart), folded);
     return folded;
 }
-/** The open tail turn starts at the last turn-boundary row — a user message
- *  or a subagent delivery (the projection's severance scan's two kinds). A
- *  list with neither (a bare fixture) is one turn, as is a child transcript,
- *  whose only boundary is its opening brief at index 0. */
 function _tailTurnStartOf(rows) {
     for (let index = rows.length - 1; index >= 0; index -= 1) {
         const kind = rows[index].kind;
@@ -41,9 +23,6 @@ function _tailTurnStartOf(rows) {
     return 0;
 }
 const NO_TURN_START_IDS = new Set();
-/** The newest DECLARED turn start, in flat coordinates over the blocks'
- *  rows — a declared turn-start block marks the boundary at the position
- *  its rows occupy (or would occupy, for a row-less block). */
 function _declaredTurnStartOf(blocks, turnStartIds) {
     let declaredTurnStart = 0;
     let flatIndex = 0;
@@ -55,28 +34,12 @@ function _declaredTurnStartOf(blocks, turnStartIds) {
     }
     return declaredTurnStart;
 }
-/**
- * Where the current turn starts, as a flat index into `rows`: the LAST
- * boundary of either kind — the newest row the tail scan recognizes or the
- * newest declared turn-start block — whichever is later. `null` blocks
- * means only the row scan applies. The fold pass and the row list's
- * placement hold both read this spelling, so the two windows never disagree.
- */
 export function currentTurnStartOf(rows, blocks, turnStartIds = NO_TURN_START_IDS) {
     return Math.max(_declaredTurnStartOf(blocks ?? [], turnStartIds), _tailTurnStartOf(rows));
 }
-/** Completed-episode folding. Within each span between hard
- *  boundaries, the LAST maximal run of prose rows stays top-level — the
- *  turn's last words. Everything before it is ONE episode fold, keyed on
- *  its first work member (the live cluster it started as, so the settled
- *  <details> is the same element); work rows after it (the cut-off tail)
- *  are one trailing fold, so a stopped/failed turn never buries all its
- *  prose. No work row → nothing folds; no prose → the span folds whole.
- *  Position alone decides. */
 function _pushEpisodeFolds(rows, folded) {
     let pending = [];
     const flush = () => {
-        // The last maximal prose run: [proseStart, proseEnd] inclusive.
         let proseEnd = -1;
         for (let index = pending.length - 1; index >= 0; index -= 1) {
             if (pending[index].kind === "assistant-text") {
@@ -89,20 +52,15 @@ function _pushEpisodeFolds(rows, folded) {
             pending[proseStart - 1].kind === "assistant-text") {
             proseStart -= 1;
         }
-        // Before the run: one episode fold. Maximality guarantees the prefix
-        // is empty or ends on a work row, so the fold has its anchor.
         if (proseStart > 0) {
             folded.push(_foldOf(pending.slice(0, proseStart)));
         }
         else if (proseEnd < 0 && pending.length > 0) {
-            // No prose anywhere: the whole span folds.
             folded.push(_foldOf(pending));
         }
-        // The run itself, top-level.
         for (let index = Math.max(proseStart, 0); index <= proseEnd; index += 1) {
             folded.push(pending[index]);
         }
-        // After the run: work only (maximality again) — the cut-off tail.
         if (proseEnd >= 0 && proseEnd + 1 < pending.length) {
             folded.push(_foldOf(pending.slice(proseEnd + 1)));
         }
@@ -120,9 +78,6 @@ function _pushEpisodeFolds(rows, folded) {
     }
     flush();
 }
-/** Live per-cluster folding: consecutive reasoning/tool rows
- *  are one fold; ANY other row — prose included — splits at its exact
- *  transcript position, so the open turn reads in true chronology. */
 function _pushClusterFolds(rows, folded) {
     let members = [];
     const flush = () => {
@@ -146,26 +101,12 @@ function _pushClusterFolds(rows, folded) {
     }
     flush();
 }
-/** The settled fold headline. The duration is the member-relevant cost —
- *  never a step count (TVC-011) — and the register is honest about its
- *  evidence: a measured sub-second span reads "<1s", never "Worked for 0s";
- *  an unknown span degrades to the neutral "Worked", never an invented
- *  duration (docs/replay-metadata-contract.md, "Unknown vs sub-second"). */
 export function settledFoldHeadlineOf(duration) {
     if (duration.kind === "unknown") {
         return "Worked";
     }
     return `Worked for ${durationLabelOf(duration.durationMs)}`;
 }
-/**
- * A COLLAPSED live fold's headline: the latest step's own label, so the
- * member tracks the work without expanding (the expanded fold keeps the
- * generic "Working…"). Each label is the one the step's own row wears: a
- * tool call reads toolRowHeadlineOf on its OWN state, a reasoning step the
- * ReasoningRow labels; narration is skipped (prose is not a work step); no
- * usable step → "Working…". Returned RAW: the renderer (FoldHeadline)
- * truncates for display and carries this text as its wrapper's title.
- */
 export function liveFoldHeadlineOf(steps) {
     for (let index = steps.length - 1; index >= 0; index -= 1) {
         const step = steps[index];
@@ -192,8 +133,6 @@ function _foldOf(members) {
             timings.push(member.timing);
         }
     }
-    // Both fold passes construct a fold only around at least one work row,
-    // so the anchor always exists; the fallback merely satisfies the type.
     const anchor = members.find((member) => member.kind !== "assistant-text") ?? members[0];
     return {
         kind: "run-fold",
@@ -203,21 +142,11 @@ function _foldOf(members) {
         duration: settledFoldDurationOf(timings),
     };
 }
-export function foldedBlocksOf(blocks, 
-// tailStart is Omit-ed on purpose: it is the offset THIS function
-// computes and hands down per segment — accepting it here would
-// type-check and silently do nothing.
-options = {}) {
+export function foldedBlocksOf(blocks, options = {}) {
     const boundaries = options.markerBoundaries ?? EMPTY_MARKER_BOUNDARIES;
     const turnStartIds = options.turnStartIds ?? NO_TURN_START_IDS;
-    // Flatten, remembering each row's block by its key (keys are unique
-    // across the projection: message ids, `${messageId}:${toolCallId}`,
-    // marker keys, `subagents:` group keys).
     const flat = [];
     const blockIndexByKey = new Map();
-    // Segment cuts in flat coordinates: a before-boundary cuts ahead of its
-    // block's rows, an after-boundary behind them. 0 and length are cuts by
-    // construction.
     const cuts = new Set([0]);
     for (const [index, block] of blocks.entries()) {
         if (boundaries.before.has(block.messageId)) {
@@ -232,8 +161,6 @@ options = {}) {
         }
     }
     cuts.add(flat.length);
-    // The open tail turn starts where the current turn starts (the row
-    // scan or the declared start, whichever is later in the flat order).
     const tailStart = options.openTailTurn
         ? currentTurnStartOf(flat, blocks, turnStartIds)
         : flat.length;
@@ -249,8 +176,6 @@ options = {}) {
         });
         for (const row of folded) {
             const firstKey = row.kind === "run-fold" ? row.members[0].key : row.key;
-            // The key map covers every input row; a fold's first member is one
-            // of them. The fallback merely satisfies the type.
             const blockIndex = blockIndexByKey.get(firstKey) ?? 0;
             foldedBlocks[blockIndex].rows.push(row);
         }
@@ -284,4 +209,3 @@ function _stepsInTranscriptOrder(members) {
     }
     return steps;
 }
-//# sourceMappingURL=run-folds.js.map

package/dist/core/run-status.d.ts

@@ -1,22 +1,4 @@
 import type { TurnStatus } from "../contract/threads.js";
-/** The two states the announcer can honestly claim. */
 export type AnnouncedStatus = "working" | "waiting";
-/**
- * Map the newest turn's wire status, plus the one fact the status enum
- * cannot carry — whether a member-actionable decision is live — onto the
- * announcer's register. `decisionsPending` comes from the decision
- * surfaces themselves (the cards), never inferred from what rendered.
- */
 export declare function announcedStatusOf(status: TurnStatus | null, decisionsPending: boolean): AnnouncedStatus | null;
-/**
- * The VISIBLE liveness register: whether the run reads as the
- * machine's time — the fold headline's "Working…", the tool rows'
- * running-vs-pending projection, the jump affordance's live treatment.
- * One function with the announcer, on purpose: the fold used to derive
- * liveness from the REST-only queued/working status (never advanced by
- * a stream event), so an approved live pause read "Worked for <1s" above
- * a running tool row while the sr-only region honestly said "working".
- * Parity is now by construction — the two registers cannot disagree.
- */
 export declare function runReadsAsWorking(status: TurnStatus | null, decisionsPending: boolean): boolean;
-//# sourceMappingURL=run-status.d.ts.map