@teaflask/assistant 0.3.0 → 0.7.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.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.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

@@ -1,36 +1,18 @@
 import type { AgentSubscriber } from "@ag-ui/client";
+/**
+ * Notice sentences attached to one message, split by whether they are shown
+ * before or after it.
+ */
 export interface AnchoredReceipts {
+    /**
+     * Sentences shown before the message. The package places failure notices
+     * after the message, so this is normally empty.
+     */
     before: string[];
+    /** Sentences shown after the message. */
     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.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.js

@@ -1,21 +1,3 @@
-// The status announcer's ladder, pure of
-// React and of the wire. Chrome does not narrate run state visibly —
-// the actionable thing is its own signal — so this ladder serves only
-// the sr-only live region. Honesty rule: the wire's awaiting_input and
-// parked statuses record lifecycle, not who the run waits on (a subagent
-// park ships the same "parked" as a HITL pause), so "waiting" is claimed
-// only while an actionable decision actually exists; a pause with no
-// pending decision is the machine's time (delegated children are
-// running, or the execution driver is answering) and reads "working".
-// Terminal states map to null: transient status disappears at settle,
-// and the durable "Worked for …" story belongs to the settled fold
-// headline (core/run-folds.ts).
-/**
- * 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 function announcedStatusOf(status, decisionsPending) {
     if (status === "queued" || status === "working") {
         return "working";
@@ -25,17 +7,6 @@ export function announcedStatusOf(status, decisionsPending) {
     }
     return 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 function runReadsAsWorking(status, decisionsPending) {
     return announcedStatusOf(status, decisionsPending) === "working";
 }
-//# sourceMappingURL=run-status.js.map

package/dist/core/segment-timing.d.ts

@@ -1,33 +1,36 @@
-/** One transcript block's observed server timing: the earliest and latest
- *  emit-side timestamp seen for its id. Either half may be null — old
- *  histories carry no timestamps, and an open block has no settle yet. */
+/**
+ * When a message or tool call started and ended, by the server's clock in
+ * milliseconds since the Unix epoch.
+ */
 export interface BlockTiming {
+    /** The earliest server timestamp seen for it, or null when unknown. */
     startedAtMs: number | null;
+    /**
+     * The latest server timestamp seen for it, or null when unknown. Equals
+     * startedAtMs until its end arrives.
+     */
     settledAtMs: number | null;
 }
-/** The typed unknown-vs-measured distinction: `measured` under 1000 ms is
- *  the sub-second case (render "<1s", never "0s"); `unknown` means the
- *  evidence does not exist and the UI hides the duration entirely. */
+/**
+ * A duration that is either unknown (hide it) or measured in milliseconds;
+ * render a measured value under 1000 as "<1s" rather than "0s".
+ */
 export type SegmentDuration = {
     kind: "unknown";
 } | {
     kind: "measured";
     durationMs: number;
 };
-/** The settled fold reduction: earliest observed start to latest observed
- *  settle across the members. Members without evidence contribute nothing;
- *  a fold with no timestamped member is unknown. A settle counts as a start
- *  bound too — a block observed only at its settle is still inside. */
+/**
+ * How long the given blocks took together, from the earliest to the latest
+ * server timestamp among them, or unknown when none has a timestamp.
+ */
 export declare function settledFoldDurationOf(members: readonly BlockTiming[]): SegmentDuration;
-/** The house duration vocabulary for every duration surface: "12s",
- *  "3m 04s", "1h 07m", with the sub-second floor "<1s" — "0s" is not in the
- *  register. The subagent roster's settledDurationLabelOf delegates here. */
 export declare function durationLabelOf(durationMs: number): string;
-/** The active fold's elapsed time: the persisted server start to the
- *  caller's "now"; with no persisted start there is none — unknown, never a
- *  mount-relative stopwatch. CAUTION: a client `Date.now()` as `nowMs` is a
- *  cross-clock-domain subtraction carrying the device's full offset from the
- *  server. No widget chrome consumes this; reach for it only with
- *  a server-derived `nowMs`, or where the surface accepts the skew. */
+/**
+ * Time elapsed from the earliest server timestamp among the given blocks to
+ * `nowMs` (milliseconds since the Unix epoch), or unknown when none has a
+ * timestamp. Passing Date.now() includes any difference between the device
+ * clock and the server clock.
+ */
 export declare function activeFoldElapsedOf(members: readonly BlockTiming[], nowMs: number): SegmentDuration;
-//# sourceMappingURL=segment-timing.d.ts.map

package/dist/core/segment-timing.js

@@ -1,13 +1,4 @@
-// The duration contract, pure of React and of the wire. Two laws:
-// a fold's duration reduces over its MEMBER blocks' emit-side server
-// timestamps — earliest start, latest settle — never turn-level evidence;
-// and "unknown" and "sub-second" are DIFFERENT states held apart by type, so
-// no consumer renders "Worked for 0s" (docs/transcript-rows-and-folds.md).
 const UNKNOWN = { kind: "unknown" };
-/** The settled fold reduction: earliest observed start to latest observed
- *  settle across the members. Members without evidence contribute nothing;
- *  a fold with no timestamped member is unknown. A settle counts as a start
- *  bound too — a block observed only at its settle is still inside. */
 export function settledFoldDurationOf(members) {
     let earliest = null;
     let latest = null;
@@ -23,13 +14,8 @@ export function settledFoldDurationOf(members) {
     if (earliest === null || latest === null) {
         return UNKNOWN;
     }
-    // A single flush can stamp a whole coalesced batch with one instant:
-    // that is a MEASURED zero — a real sub-second span — never unknown.
     return { kind: "measured", durationMs: Math.max(0, latest - earliest) };
 }
-/** The house duration vocabulary for every duration surface: "12s",
- *  "3m 04s", "1h 07m", with the sub-second floor "<1s" — "0s" is not in the
- *  register. The subagent roster's settledDurationLabelOf delegates here. */
 export function durationLabelOf(durationMs) {
     if (durationMs < 1_000) {
         return "<1s";
@@ -45,12 +31,6 @@ export function durationLabelOf(durationMs) {
     const hours = Math.floor(totalMinutes / 60);
     return `${String(hours)}h ${String(totalMinutes % 60).padStart(2, "0")}m`;
 }
-/** The active fold's elapsed time: the persisted server start to the
- *  caller's "now"; with no persisted start there is none — unknown, never a
- *  mount-relative stopwatch. CAUTION: a client `Date.now()` as `nowMs` is a
- *  cross-clock-domain subtraction carrying the device's full offset from the
- *  server. No widget chrome consumes this; reach for it only with
- *  a server-derived `nowMs`, or where the surface accepts the skew. */
 export function activeFoldElapsedOf(members, nowMs) {
     let earliest = null;
     for (const member of members) {
@@ -65,4 +45,3 @@ export function activeFoldElapsedOf(members, nowMs) {
     }
     return { kind: "measured", durationMs: Math.max(0, nowMs - earliest) };
 }
-//# sourceMappingURL=segment-timing.js.map

package/dist/core/settle-refresh.js

@@ -1,15 +1,4 @@
-// A settled run means the thread's REST truth moved (busy flag, turn
-// statuses, maybe the title). Full replays settle every historical run in
-// a burst, so the re-read waits out the burst.
 export const SETTLE_REFRESH_DELAY_MS = 400;
-/**
- * The settle re-read's debounce: every settled run re-arms one timer, and
- * the re-read fires once the burst has been quiet for
- * SETTLE_REFRESH_DELAY_MS. What a settle refreshes is the owner's
- * (`onSettle`): the widget store re-reads the thread, the history list and
- * the funding gate; the playground hook re-reads the thread and
- * invalidates its thread-list query. The timing policy lives here, once.
- */
 export class SettleRefreshScheduler {
     onSettle;
     timer = null;
@@ -33,4 +22,3 @@ export class SettleRefreshScheduler {
         }
     }
 }
-//# sourceMappingURL=settle-refresh.js.map