@vibefield/rosetta-room 0.0.0-stage → 0.1.0

package/dist/lib/transcript/turns.js

@@ -0,0 +1,576 @@
+import { ledgerLines, runSummary } from "./ledger.js";
+import { withinPromptCluster } from "./sittings.js";
+import { canonicalText, citationLabel, noticeText, stampSpan, } from "./vocabulary.js";
+function mediaShortName(mediaType, name) {
+    if (mediaType !== null && mediaType !== "") {
+        const subtype = mediaType.split("/").at(-1) ?? mediaType;
+        return subtype.replace(/^x-/, "").toUpperCase();
+    }
+    const extension = name === null ? null : /\.([A-Za-z0-9]{1,5})$/.exec(name);
+    if (extension === null)
+        return null;
+    const upper = extension[1].toUpperCase();
+    return upper === "JPG" ? "JPEG" : upper;
+}
+function caption(width, height, type) {
+    const size = width !== null && height !== null ? `${width}×${height}` : null;
+    return [size, type].filter((piece) => piece !== null).join(" · ");
+}
+function factFromRef(ref) {
+    const name = ref.name;
+    const type = mediaShortName(ref.media_type, name);
+    return {
+        key: ref.id,
+        kind: ref.kind,
+        name,
+        mediaType: ref.media_type,
+        byteLen: ref.byte_len,
+        width: ref.dimensions?.width ?? null,
+        height: ref.dimensions?.height ?? null,
+        missing: ref.source.type !== "asset",
+        ref,
+        caption: caption(ref.dimensions?.width ?? null, ref.dimensions?.height ?? null, type),
+    };
+}
+/** Native wrappers and image grammar belong to adapters, never the renderer. */
+export function readAttachments(text, refs) {
+    return { text: text?.trim() ? text : null, attachments: refs.map(factFromRef) };
+}
+/** Exact canonical Unicode-scalar spans, converted once to JS string offsets.
+ * Missing images retain their link; undocumented numbering stays plain text. */
+export function attachmentMentions(text, attachments) {
+    if (!attachments.some(fact => fact.ref?.message_ranges?.length))
+        return [];
+    const offsets = [0];
+    let offset = 0;
+    for (const char of text) {
+        offset += char.length;
+        offsets.push(offset);
+    }
+    const mentions = [];
+    for (const target of attachments) {
+        if (target.kind !== "image")
+            continue;
+        for (const range of target.ref?.message_ranges ?? []) {
+            if (!Number.isInteger(range.start) || !Number.isInteger(range.end) || range.start < 0 || range.end <= range.start || range.end >= offsets.length)
+                continue;
+            mentions.push({ start: offsets[range.start], end: offsets[range.end], target });
+        }
+    }
+    mentions.sort((a, b) => a.start - b.start);
+    return mentions.filter((mention, index) => !mentions.some((other, otherIndex) => index !== otherIndex && other.start < mention.end && mention.start < other.end));
+}
+/* ── the prompt ──────────────────────────────────────────────────────────── */
+// A local command as the reader typed it: one line, a leading slash, a name.
+const LOCAL_COMMAND = /^\/[A-Za-z][\w:.-]*(?:\s+\S.*)?$/;
+function looksLocalCommand(text) {
+    if (text === null)
+        return false;
+    const trimmed = text.trim();
+    return !trimmed.includes("\n") && LOCAL_COMMAND.test(trimmed);
+}
+/** Project a normalized setting value into the two words the reader needs.
+ * Diagnostics deliberately fail this predicate and retain the generic command
+ * treatment, so compact presentation never conceals a rejected command. */
+export function localSetting(command, output) {
+    if (command === null || output === null)
+        return null;
+    const value = output.trim();
+    if (value === "" || value.includes("\n") || value.length > 96)
+        return null;
+    const name = command.trim().split(/\s+/, 1)[0]?.toLowerCase();
+    if (name === "/effort") {
+        return /^[a-z][\w-]*$/i.test(value)
+            ? { kind: "effort", label: "Effort", value }
+            : null;
+    }
+    if (name === "/model") {
+        return /^(?:set|invalid|unknown|error|failed|usage)\b/i.test(value)
+            ? null
+            : { kind: "model", label: "Model", value };
+    }
+    return null;
+}
+function opensTurn(row, options) {
+    if (row.body.type === "user")
+        return true;
+    if (row.body.type === "collaboration" &&
+        options.sharedCollaborationSessionIds?.has(row.session_id) === true) {
+        return false;
+    }
+    return row.body.type === "collaboration" &&
+        (row.group.kind === "human_turn" || row.group.kind === "parent_invocation");
+}
+function isAgentAuthored(row) {
+    switch (row.body.type) {
+        case "agent":
+        case "thinking":
+        case "tool_use":
+            return true;
+        case "summary":
+            return row.body.purpose !== "compaction";
+        case "collaboration":
+        case "user":
+        case "notice":
+            return false;
+    }
+}
+/** Every usage record in the reply, summed. A record sits on exactly one row
+ * (a response's usage on its first projectable row, a multi-step message's
+ * steps each on their own), and the six buckets are mutually exclusive
+ * (ARCHITECTURE §4.1.3), so the sum is the reply's total and the heads add up
+ * to the same figure as every aggregate. */
+function reportedTokens(rows) {
+    let total = 0;
+    let reported = false;
+    for (const row of rows) {
+        const parts = [
+            row.usage.input,
+            row.usage.output,
+            row.usage.cache_read,
+            row.usage.cache_write,
+            row.usage.cache_write_1h,
+            row.usage.thinking,
+        ];
+        if (parts.every((value) => value === null || value === undefined))
+            continue;
+        reported = true;
+        total += parts.reduce((sum, value) => sum + (value ?? 0), 0);
+    }
+    return reported ? total : null;
+}
+/** A record whose prompt was recorded but whose output never was: its price
+ * is a lower bound (a streamed reply that never got its final usage record). */
+function outputUnrecorded(row) {
+    const usage = row.usage;
+    const prompt = [usage.input, usage.cache_read, usage.cache_write, usage.cache_write_1h];
+    return prompt.some((value) => value !== null && value !== undefined)
+        && (usage.output === null || usage.output === undefined);
+}
+/** The reply's list-price cost from each row's read-time `cost`. Partial when
+ * any usage-bearing row could not be priced or its output was never recorded;
+ * null when no row carried usage. */
+function reportedCost(rows) {
+    let microUsd = null;
+    let partial = false;
+    let reported = false;
+    for (const row of rows) {
+        const cost = row.cost;
+        if (cost === undefined || cost === null)
+            continue;
+        reported = true;
+        if (cost.status === "priced") {
+            microUsd = (microUsd ?? 0) + cost.micro_usd;
+            if (outputUnrecorded(row))
+                partial = true;
+        }
+        else
+            partial = true;
+    }
+    return reported ? { microUsd, partial } : null;
+}
+function buildPrompt(row, outputRow) {
+    const body = row.body;
+    const collaboration = body.type === "collaboration" ? body.event : null;
+    const rawText = body.type === "user" && body.text !== null
+        ? canonicalText(body.text)
+        : collaboration?.body !== null && collaboration?.body !== undefined
+            ? canonicalText(collaboration.body)
+            : (collaboration?.summary ?? null);
+    const refs = body.type === "user" ? body.attachments : [];
+    const { text, attachments } = readAttachments(rawText, refs);
+    const isCommand = body.type === "user" && attachments.length === 0 && looksLocalCommand(text);
+    const output = outputRow !== null && outputRow.body.type === "notice"
+        ? canonicalText(outputRow.body.notice.type === "command_output"
+            ? outputRow.body.notice.output
+            : { type: "inline", text: "" })
+        : null;
+    const command = isCommand && text !== null ? text.trim() : null;
+    const commandOutput = output === null || output === "" ? null : output;
+    return {
+        key: row.timeline_id,
+        row,
+        rows: outputRow === null ? [row] : [row, outputRow],
+        at: row.at,
+        text,
+        attachments,
+        isCommand,
+        command,
+        commandOutput,
+        commandOutputRow: outputRow,
+        setting: localSetting(command, commandOutput),
+        fromParent: row.group.kind === "parent_invocation",
+        machine: collaboration === null
+            ? null
+            : {
+                label: collaboration.kind === "assignment"
+                    ? "Assignment"
+                    : collaboration.channel === "coordinator"
+                        ? "Coordinator follow-up"
+                        : collaboration.channel === "peer"
+                            ? "Peer message"
+                            : "Team message",
+                sender: collaboration.sender,
+            },
+    };
+}
+function thinkingSegment(row, nextAtOf) {
+    if (row.body.type !== "thinking")
+        return null;
+    const text = canonicalText(row.body.text);
+    if (text.trim() === "")
+        return null;
+    const next = nextAtOf(row);
+    return {
+        kind: "thinking",
+        key: row.timeline_id,
+        row,
+        at: row.at,
+        text,
+        spanMs: row.at !== null && next !== null && next > row.at ? next - row.at : null,
+    };
+}
+function markerSegment(row) {
+    if (row.body.type !== "notice")
+        return null;
+    const notice = row.body.notice;
+    return {
+        kind: "marker",
+        key: row.timeline_id,
+        row,
+        at: row.at,
+        notice,
+        text: noticeText(notice),
+        tone: notice.type === "runtime_error" ||
+            (notice.type === "async_task" && ["failed", "denied", "timed_out"].includes(notice.status))
+            ? "failed"
+            : "plain",
+    };
+}
+function summarySegment(row) {
+    if (row.body.type !== "summary")
+        return null;
+    const text = canonicalText(row.body.text);
+    if (text.trim() === "")
+        return null;
+    return {
+        kind: "summary",
+        key: row.timeline_id,
+        row,
+        at: row.at,
+        purpose: row.body.purpose,
+        text,
+    };
+}
+function runOther(member) {
+    switch (member.kind) {
+        case "line":
+            return null;
+        case "thinking":
+            return { kind: "thinking", row: member.row };
+        case "marker":
+            return { kind: "marker", row: member.row, failed: member.tone === "failed" };
+        case "summary":
+            return { kind: "summary", row: member.row };
+    }
+}
+/** Combine only a direct native parent/child pair. Reversed timestamps are
+ * common after compaction; proximity to `/compact` is not evidence of a link.
+ * A page or sitting boundary leaves each record independently drawable. */
+function compactionPairs(rows, cutBefore) {
+    const pairs = new Map();
+    // index runs from 1 below rows.length, so index - 1 and index are rows.
+    const rowAt = (index) => rows[index];
+    for (let index = 1; index < rows.length; index += 1) {
+        const previous = rowAt(index - 1);
+        const current = rowAt(index);
+        if (cutBefore.has(current.timeline_id) || previous.session_id !== current.session_id
+            || current.ordinal !== previous.ordinal + 1)
+            continue;
+        const summary = previous.body.type === "summary" ? previous : current;
+        const boundary = summary === previous ? current : previous;
+        if (summary.body.type !== "summary" || summary.body.purpose !== "compaction"
+            || boundary.body.type !== "notice" || boundary.body.notice.type !== "compaction"
+            || boundary.native_id === null || summary.parent_native_id !== boundary.native_id
+            || pairs.has(summary.timeline_id) || pairs.has(boundary.timeline_id))
+            continue;
+        const pair = [previous, current];
+        pairs.set(summary.timeline_id, pair);
+        pairs.set(boundary.timeline_id, pair);
+    }
+    return pairs;
+}
+/**
+ * The reply's segments. R-1: speech is the boundary — a prose row or a team
+ * message closes the run, and everything between two of them (tool rows,
+ * thoughts, notices, summaries) is ONE run, in order. Even a lone tool line
+ * gets the run's summary fold. A lone thought stays a `thinking` segment,
+ * a lone notice a `marker`. A run that holds only notices and summaries has
+ * no sentence to close to, so its members stand as
+ * their own segments. Compaction recaps (and their paired boundary) stay
+ * outside activity folds. A sitting boundary (`cutBefore`) also closes a run,
+ * so no run straddles a pill.
+ */
+function buildSegments(rows, nextAtOf, context, cutBefore) {
+    const segments = [];
+    const pairs = compactionPairs(rows, cutBefore);
+    let members = [];
+    let runRows = [];
+    let tools = [];
+    const flushTools = () => {
+        if (tools.length === 0)
+            return;
+        for (const line of ledgerLines(tools, context)) {
+            members.push({ kind: "line", key: line.key, line });
+        }
+        tools = [];
+    };
+    const flushRun = () => {
+        flushTools();
+        if (members.length === 0)
+            return;
+        const folds = members.some((member) => member.kind === "line" || member.kind === "thinking");
+        if (!folds || (members.length === 1 && members[0].kind !== "line")) {
+            // R-2: a lone thought stays a thinking segment, and notices or
+            // summaries with nothing to fold around stand as their own markers.
+            for (const member of members)
+                if (member.kind !== "line")
+                    segments.push(member);
+        }
+        else {
+            const lines = members.flatMap((member) => (member.kind === "line" ? [member.line] : []));
+            const others = members.flatMap((member) => {
+                const other = runOther(member);
+                return other === null ? [] : [other];
+            });
+            segments.push({
+                kind: "ledger",
+                key: runRows[0].timeline_id,
+                at: firstStamp(runRows),
+                rows: runRows,
+                lines,
+                members,
+                summary: runSummary(lines, others),
+            });
+        }
+        members = [];
+        runRows = [];
+    };
+    for (const row of rows) {
+        if (cutBefore.has(row.timeline_id))
+            flushRun();
+        switch (row.body.type) {
+            case "tool_use":
+                if (row.body.tool.action.type === "question") {
+                    // A question to the reader, and their answer, is speech (R-1): it
+                    // closes the run before it and stands alone, open, as §04 draws it.
+                    flushRun();
+                    tools.push(row);
+                    runRows.push(row);
+                    flushRun();
+                    continue;
+                }
+                tools.push(row);
+                runRows.push(row);
+                continue;
+            case "thinking": {
+                const segment = thinkingSegment(row, nextAtOf);
+                if (segment === null)
+                    continue;
+                flushTools();
+                members.push(segment);
+                runRows.push(row);
+                continue;
+            }
+            case "notice": {
+                if (pairs.has(row.timeline_id)) {
+                    flushRun();
+                    continue;
+                }
+                const segment = markerSegment(row);
+                if (segment === null)
+                    continue;
+                flushTools();
+                members.push(segment);
+                runRows.push(row);
+                continue;
+            }
+            case "summary": {
+                if (row.body.purpose === "compaction") {
+                    flushRun();
+                    const paired = pairs.get(row.timeline_id) ?? [row];
+                    segments.push({
+                        kind: "compaction",
+                        key: row.timeline_id,
+                        row,
+                        rows: paired,
+                        at: firstStamp(paired),
+                        text: row.body.text,
+                    });
+                    continue;
+                }
+                const segment = summarySegment(row);
+                if (segment === null)
+                    continue;
+                flushTools();
+                members.push(segment);
+                runRows.push(row);
+                continue;
+            }
+            case "agent": {
+                const text = row.body.text === null ? null : canonicalText(row.body.text);
+                const { text: prose, attachments } = readAttachments(text, row.body.attachments);
+                // A blank agent row said nothing, so it closes nothing (R-1).
+                if (prose === null && attachments.length === 0 && row.body.citations.length === 0)
+                    continue;
+                flushRun();
+                segments.push({
+                    kind: "prose",
+                    key: row.timeline_id,
+                    row,
+                    at: row.at,
+                    text: prose,
+                    attachments,
+                    citations: row.body.citations,
+                    citationLabels: row.body.citations.map(citationLabel),
+                });
+                continue;
+            }
+            case "collaboration":
+                flushRun();
+                segments.push({
+                    kind: "collaboration",
+                    key: row.timeline_id,
+                    row,
+                    at: row.at,
+                    event: row.body.event,
+                });
+                continue;
+            case "user":
+                // Unreachable: a user row always opens its own turn.
+                continue;
+        }
+    }
+    flushRun();
+    return segments;
+}
+/**
+ * Fold an ordered timeline into turns. Pure: no clock, no IO. The rows behind
+ * every prompt, segment and ledger line stay reachable, so the anchors, the
+ * focus landing and the live watermark all keep working off `timeline_id` and
+ * `ordinal` exactly as they do today.
+ */
+export function documentTurns(rows, options = {}) {
+    const context = options.context ?? {};
+    // The next stamped row, for a reasoning segment's span.
+    const nextAt = new Map();
+    // index and ahead both stay below rows.length.
+    const rowAt = (index) => rows[index];
+    for (let index = 0; index < rows.length; index += 1) {
+        let found = null;
+        for (let ahead = index + 1; ahead < rows.length; ahead += 1) {
+            if (rowAt(ahead).at !== null) {
+                found = rowAt(ahead).at;
+                break;
+            }
+        }
+        nextAt.set(rowAt(index).timeline_id, found);
+    }
+    const nextAtOf = (row) => nextAt.get(row.timeline_id) ?? null;
+    // Group the rows into turns, absorbing a command prompt's `command_output`
+    // notice as we go — the pair is one object, decided by adjacency and nothing
+    // else, so the notice never also draws as a marker.
+    const groups = [];
+    for (const row of rows) {
+        if (opensTurn(row, options)) {
+            groups.push({ prompt: row, output: null, body: [] });
+            continue;
+        }
+        const current = groups.at(-1);
+        if (current === undefined) {
+            groups.push({ prompt: null, output: null, body: [row] });
+            continue;
+        }
+        const promptRow = current.prompt;
+        if (promptRow !== null &&
+            !options.cutBefore?.has(row.timeline_id) &&
+            current.output === null &&
+            current.body.length === 0 &&
+            row.body.type === "notice" &&
+            row.body.notice.type === "command_output" &&
+            looksLocalCommand(promptRow.body.type === "user" && promptRow.body.text !== null
+                ? canonicalText(promptRow.body.text)
+                : null)) {
+            current.output = row;
+            continue;
+        }
+        current.body.push(row);
+    }
+    const turns = [];
+    let previousPromptAt = null;
+    let previousHadReply = true;
+    let previousWasHumanSetting = false;
+    for (const group of groups) {
+        const promptRow = group.prompt;
+        const outputRow = group.output;
+        const body = group.body;
+        const prompt = promptRow === null ? null : buildPrompt(promptRow, outputRow);
+        const segments = buildSegments(body, nextAtOf, context, options.cutBefore ?? new Set());
+        const agentRows = body.filter(isAgentAuthored);
+        const head = agentRows.length === 0
+            ? null
+            : {
+                model: agentRows.find((row) => row.model !== null)?.model ?? null,
+                effort: agentRows.find((row) => row.effort !== null)?.effort ?? null,
+                tokens: reportedTokens(agentRows),
+                cost: reportedCost(agentRows),
+                startedAt: firstStamp(body),
+                endedAt: lastStamp(body),
+                spanMs: stampSpan(body),
+            };
+        const headIndex = Math.max(0, segments.findIndex((segment) => segment.kind !== "marker" && segment.kind !== "compaction"));
+        const at = promptRow?.at ?? firstStamp(body);
+        const clusteredWithPrevious = prompt !== null &&
+            prompt.setting !== null &&
+            !prompt.fromParent &&
+            previousWasHumanSetting &&
+            !previousHadReply &&
+            withinPromptCluster(previousPromptAt, prompt.at);
+        const allRows = [
+            ...(prompt === null ? [] : prompt.rows),
+            ...body,
+        ];
+        turns.push({
+            key: prompt?.key ?? allRows[0]?.timeline_id ?? `turn-${turns.length}`,
+            prompt,
+            head,
+            segments,
+            headIndex,
+            rows: allRows,
+            at,
+            clusteredWithPrevious,
+        });
+        if (prompt !== null) {
+            previousPromptAt = prompt.at;
+            previousHadReply = agentRows.length > 0;
+            previousWasHumanSetting = prompt.setting !== null && !prompt.fromParent;
+        }
+    }
+    return turns;
+}
+function firstStamp(rows) {
+    for (const row of rows)
+        if (row.at !== null)
+            return row.at;
+    return null;
+}
+function lastStamp(rows) {
+    // index walks rows from its last index down to 0.
+    const rowAt = (index) => rows[index];
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+        const at = rowAt(index).at;
+        if (at !== null)
+            return at;
+    }
+    return null;
+}

package/dist/lib/transcript/use-transcript-opening.d.ts

@@ -0,0 +1,12 @@
+import type { TimelineLayout } from "./use-transcript-tail.js";
+/** The selected session owns this hook (its column is keyed by session id).
+ * Mount and measure the real document under a stationary loading surface.
+ * Readiness comes from the snapshot and initial team reads; two render frames
+ * let preview measurement, disclosure layout and scroll placement finish.
+ * There is no minimum spinner time and image downloads never block reading. */
+export declare function useTranscriptOpening(snapshotReady: boolean, seeking: boolean): {
+    visible: boolean;
+    onLayout: (layout: TimelineLayout) => void;
+    continueReading: () => void;
+    waitingForTeam: boolean;
+};

package/dist/lib/transcript/use-transcript-opening.js

@@ -0,0 +1,31 @@
+import { useCallback, useLayoutEffect, useState } from "react";
+/** The selected session owns this hook (its column is keyed by session id).
+ * Mount and measure the real document under a stationary loading surface.
+ * Readiness comes from the snapshot and initial team reads; two render frames
+ * let preview measurement, disclosure layout and scroll placement finish.
+ * There is no minimum spinner time and image downloads never block reading. */
+export function useTranscriptOpening(snapshotReady, seeking) {
+    const [layoutReady, setLayoutReady] = useState(false);
+    const [revealed, setRevealed] = useState(false);
+    const [readAvailable, setReadAvailable] = useState(false);
+    const visible = !snapshotReady || !revealed;
+    const onLayout = useCallback((layout) => {
+        setLayoutReady(layout.ready && layout.initialReady !== false);
+    }, []);
+    const continueReading = useCallback(() => setReadAvailable(true), []);
+    useLayoutEffect(() => {
+        if (!snapshotReady) {
+            setRevealed(false);
+            setReadAvailable(false);
+            return;
+        }
+        // Once readable, roster changes and ordinary reconnects stay inline.
+        if (revealed || seeking || (!layoutReady && !readAvailable))
+            return;
+        let frame = requestAnimationFrame(() => {
+            frame = requestAnimationFrame(() => setRevealed(true));
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [snapshotReady, layoutReady, revealed, seeking, readAvailable]);
+    return { visible, onLayout, continueReading, waitingForTeam: snapshotReady && !layoutReady };
+}

package/dist/lib/transcript/use-transcript-tail.d.ts

@@ -0,0 +1,25 @@
+import type { TimelineEntry } from "@vibefield/rosetta-protocol";
+export interface TimelineLayout {
+    readonly sessionId: string;
+    readonly rows: readonly TimelineEntry[];
+    /** Full observed boundary histories establish arrival baselines even while
+     * older entries remain outside the displayed parent window. */
+    readonly observedRows?: readonly TimelineEntry[];
+    readonly ready: boolean;
+    /** First covered chronology is complete, or failed with an inline retry.
+     * Later team roster changes must not hide an already readable document. */
+    readonly initialReady?: boolean;
+    readonly readySessionIds: readonly string[];
+    readonly elementForRow: (row: TimelineEntry) => HTMLElement | null;
+    /** Ownership/coalescing in the displayed chronology may differ from the source page. */
+    readonly elementForAnchor?: (timelineId: string) => HTMLElement | null;
+}
+export declare function useTranscriptTail(scrollerRef: {
+    current: HTMLElement | null;
+}, sessionId: string | null, enabled: boolean, seeking: boolean, opening?: boolean): {
+    onLayout: (next: TimelineLayout) => void;
+    pause: () => void | undefined;
+    latest: () => void | undefined;
+    away: boolean;
+    unseen: number;
+};