CodeNomad/dev-docs/TRANSCRIPT.md

19 KiB

Transcript rendering

Message content visibility and presets, token lines, tool renderers, native session lifecycle signals and transcript re-projection.

Agent conventions

  • Transcript watch marks retain a unique view lease under the captured backend attachment and the session's native location, project and instance generation. Scalar bindings preserve that lease across catalogue hydration; hiding, session clearing and owner revocation release its visibility and memory protection. Each cleanup releases only its own lease, including after same-ID reattachment. Mounted session and child views reacquire the current attachment reactively. The acyclic visibility leaf receives authority from these producers; projection gates and the transcript LRU share its current-lease check.

  • Mermaid fences (mermaid/mmd) use only @mermaid-js/tiny, loaded on demand and excluded from PWA precaching. lib/markdown.ts publishes a per-render token/encoded-source/completeness sidecar from actual fenced tokens alongside cached HTML; raw HTML cannot supply that provenance. markdown-mermaid.tsx consumes the sidecar and retains source for unfinished or display-truncated fences and while streaming. Source/diagram choices remain local to the Markdown owner; copy/wrap keep the native source. mermaid-renderer.ts serializes bounded renders in one opaque allow-scripts iframe with network-disabled CSP; returned SVGs are image documents rather than host HTML. Keep 50,000-character/500-edge input limits, a 2M-character SVG ceiling and the initialization/render deadlines, including late-import fencing. MermaidDiagram is shared with .mmd file previews; invalid/unsupported/oversized content keeps an actionable source fallback. Regression coverage: tests/browser/mermaid.test.ts.

  • Partial live projections preserve omitted resident message runs beside their preceding shared row, with leading history before the snapshot and pending optimistic sends at the tail. Shared rows follow the incoming native order. A prompt delivered from the session inbox takes the position the native message page owns: the SDK's session.inbox.delivered moves the prompt's row to the reducer's tail, so a delivery that relocates a row which is not the reducer's last owes an authoritative page read — invalidated and finished like a settlement read, shared with any in-flight read and superseded only by a newer admitted execution, and published through the instance layer's frame gates (active session, latest window) exactly as live events' projections are. The outstanding read is a retirement barrier, and a verified reconnect carries the demand: after the seeded page lands, the repair resumes immediately instead of trailing behind the quiet reconciliation. No client-side ordering state survives the delivery: the reducer itself is healed, so reconnect seeding and authoritative replacement carry the corrected order. HTTP pages can contain later steps whose events are still in transit; message IDs and wall-clock timestamps remain identity/display data rather than transcript sort keys.

  • Deferred media producers emit a reference only when the canonical server parser admits its encoded identities, positions and complete path. Refused or unencodable references retain the original URI. Media reads pin the published workspace occurrence and service connection across session, message and physical ownership revalidation, including undo and digest checks. One 30-second budget covers the whole request; the decompressed native response envelope is bounded to 16 MiB before parsing, and embedded URIs to 8 MiB before decoding. Responses contain only signature-verified passive raster bytes; client close suppresses further writes.

  • The message-content popup and Chat settings share components/transcript-visibility.ts and the semantic icons from components/message-content-icons.ts; tool presentation metadata lives independently of renderers in components/tool-call/tool-presentation.ts. Popup styles live in styles/components/transcript-filters.css. Popup rows show a requested state at once and keep it until the save carrying it settles. Each save re-renders the transcript, so a drag sweep (dev-docs/UI_CONVENTIONS.md) saves its rows once, on release (afterSweep). Saves run in order, each built from the preferences the previous one returned; a batch of rows is sealed as it joins the queue, so a later click never jumps ahead of a preset change nor rides along with a sweep still held.

  • Transcript presets are Nothing (hides every row, including all tools), Minimal, Balanced and Everything (TRANSCRIPT_PRESETS); saved Detailed choices load as Custom with their effective tool column. Chat settings shows the four as buttons; the popup shows the same choice as a native select under its title, where a disabled Custom entry appears only after a manual row change. Escape closes an open list before the popup. Preset names and descriptions are localized in every locale; covered by tests/browser/transcript-presets.test.ts.

  • Status Tokens are independent of message token visibility. The non-interactive renderStatus slot keeps the session input/output/cost chips in the header in both states; collapsed they form one ellipsized line, expanded they include reasoning and wrap beside the heading. Expanded content holds descendant-inclusive totals below the header. Keep the layout in styles/panels/status-tokens.css.

  • Message token disclosures keep one row in both states: collapsed shows the input/output/cost summary chips on a single ellipsized line; expanded swaps the same row to all six chips beside the chevron, which wrap onto further lines when narrow instead of truncating (expansion exists to read every value). Messages and Status share components/usage-metric-chips.tsx and styles/components/usage-metrics.css; message row geometry lives in styles/messaging/message-usage.css.

  • Tool-result images retain native state.content and render through the shared components/tool-call/output-images.tsx surface, including MCP and specialized tools. Keep image bytes out of text projections (copy/search/speech); image styles live in styles/messaging/tool-call/images.css.

  • Remote blob images accept only signature-verified PNG, JPEG, GIF, WebP, AVIF, BMP and ICO, with their canonical passive MIME type (lib/passive-image.ts). Inline data images use plain fetch with credentials omitted and the same byte gate; reject externally supplied blob references. Refuse SVG, HTML, unknown formats and non-image attachments through the existing unavailable presentation; never expose an openable link for them. Remote blob image interactions suppress opening as a document (including linked images, middle clicks, dragging and context menus); direct navigation to an admitted blob remains passive by its verified format and MIME. Never convert an active remote response into a UI-origin blob document. Server response CSP protects server URLs; blob documents use their creator's origin, so verified bytes and canonical MIME govern their admission. Local image sources and their server CSP stay unchanged.

  • Transcript pages carry large tool images by reference: the UI's native message list reads (lib/sdk-manager.ts) and history windows (fetchHistoryWindow) send the x-codenomad-media: deferred opt-in (server/src/opencode/session-media-contract.ts), and the server replaces each tool image data URI over INLINE_MEDIA_LIMIT (32 KiB) with a /api/workspaces/<id>/session-media/<session>/<message>/<part>/<index>/<sha256> path (opencode/session-media.ts). Mounted tool images, matching Markdown images and attachments select backendOf(instanceId) through lib/media-source.ts. Local sources retain their exact strings and deferred-path joining contract. Remote owned session-media routes load through the selected backend's authenticated fetch into a blob URL; other same-origin HTTP sources use plain fetch with credentials omitted, and public external HTTP images retain their direct URL. Credential-bearing HTTP URLs are rejected for remote media. Attachment authority and the resource lifetime fence admission and every response/body await; replacement, unmount and revocation release blob URLs and clear displayed sources. Missing backends leave media unavailable. routes/session-media.ts serves the bytes of the owned session's native message, pinned by the digest and refused at or after an undo boundary, as an immutable sandboxed image. Single-message reads (session.message.get: pruning revisions, previews), live events, user attachments and requests without the opt-in stay whole, so revisions hash native content.

  • Markdown images of local file paths (C:/…, file://, absolute or relative POSIX paths) cannot load in the renderer. lib/markdown.ts renders them as their alt text in a span.markdown-local-image, and components/markdown.tsx swaps the label for an <img> with the source of a completed tool image of the same path already in the session's loaded messages (lib/markdown-local-images.ts: the image's file name or its single-image tool's filePath; Windows paths compare case-insensitively, a relative path must match one known path's end). Only blocks containing such a label read and track the session's tool parts, and only matched image sources acquire mounted media resources. Never fetch local paths through a backend route for this; an unmatched path keeps its alt text.

  • Remote media resolves session-media paths through the owning backend's relay and admits same-origin absolute URLs only inside that owner's namespace. Namespace comparisons use the root origin and path; the media request retains its relay authority query and header. Absolute data and public HTTP sources retain their own URL resolution and passive-image admission rules.

  • Sanitized remote HTML images with /, ./ or ../ sources become the existing local-image labels before insertion into the reading DOM. Markdown cache modes include this owner policy; aside answers and workspace Markdown pass their instance identity. Local HTML image sources retain their exact strings.

  • Code Mode reads native metadata.toolCalls in tool-call/renderers/execute-data.ts; keep call-list styling in styles/messaging/tool-call/execute.css, with native image/output ownership in the shared tool shell.

  • Native websearch text is parsed conservatively by tool-call/renderers/websearch-data.ts; unknown/oversized responses use the shared raw renderer. Recognized provider-consent Forms retain the generic schema/answer path, with layout in styles/messaging/tool-call/websearch.css.

  • Session lifecycle features use OpenCode V2's published signals: one session.execution.{succeeded,failed,interrupted} per busy period (lib/native-execution-events.ts) and session.retry.scheduled for provider backoff. The schema-declared session.idle/session.status are never published; never wire a feature only to them. A terminal event is a hint until session.active confirms settlement, which alone announces "A session finished", only for root sessions ending in success, failure or an inactivity stop. Transcript reducers retire at settlement, deferred while prompts stay parked in their inbox or a user shell or unsettled tool call still needs reconciling there. A tool part still streaming (rendered "pending") once a settlement drained has lost its called transition: session.tool.success reduces solely from the running status (a later failed can still settle it). Symmetrically, admission drops a session.tool.called whose newest matching part already holds a terminal status: the reducer would overwrite the settled state wholesale (flipping completed tool images back to "running" until a settlement read healed them), while a legitimate re-call is always preceded by a fresh session.tool.input.started part that becomes the reducer's match. The SDK reducer already answers a terminal event whose transcript holds a streaming or running tool by invalidating and re-reading messages, but that refresh is dropped while the stream is not connected and never publishes its result; the terminal event therefore finishes the read itself (finishOpenCodeDataEvent: one message.sync that shares the SDK's in-flight read when connected and starts it when not) and projects the reconciled page, which keeps the display window's membership. Only a newer admitted execution suppresses that publication — same-round activity such as a late terminal tool event must not leave the repair unpublished. Non-event settlement evidence finishes the same read through the same fence: the liveness activity read observing that a run the UI still believed working has settled (observeNonEventSettlement, reported by session-api), and an authoritative inbox sync that drops an item the reducer admitted (a delivery or cancellation without events, whose user message may never be admitted either). A tool still streaming or running in a finished round once a later session.step.started reduced (reconcileStrandedRoundTools, hooked after both the direct emit and the queued replay, where the scan runs at the task boundary between replay chunks) lost its terminal event mid-execution: the loop feeds every tool result back before it continues, so waiting for the settlement read would keep its spinner live through later rounds (and a quickly following execution would suppress that repair). That reconcile and every settlement read share one in-flight reconciliation per transcript (settlementReadPending); covered by opencode-data-settlement.test.ts. Token/cost lines (components/message-usage.tsx) appear once per agent message: the row of an assistant message's final text (the one carrying "delete tools and reasoning") renders, once that message has native usage, the sum (sumMessageUsage) of its own usage and of every message holding a tool or reasoning part that cleanup selects (technicalCleanupParts). Reuse that selection rather than a separate projection. The line renders inside the content row, so it never shifts <Index> items or splits a technical group (whose Delete needs two tools); tool-only steps get no line. A message whose text is followed by tools also counts in the next message's line, as its tools belong to that selection. Sums cover the loaded transcript window only, like cleanup. Capture real streams with scripts/test-session-lifecycle-native.mjs.

  • Native transcript events reduce only through stores/opencode-data.ts (never add another partial-part reducer), which publishes bounded snapshots through hydrateMessages (message-v2/instance-store.ts); these per-event re-projections must not invalidate unchanged messages: hydrateMessages reuses the resident MessageRecord object whenever content, explicit timestamps and prompt-display metadata are unchanged, and an identical whole snapshot returns before any store write or session-revision bump. Part/info comparisons use allocation-free structural equality (partDataEqual), never JSON.stringify. The SDK reduce mutates rows in place, so reference identity can never prove a session unchanged — never add a reference-anchored projection skip. A session's reducer is replaced (authoritative resync after an overflow, rotation failure or reconnect; pruning invalidation) only through replaceTranscriptEntry, which bumps the transcript's entryRevision; reactive readers of the reducer, such as the inbox behind queued badges (getOpenCodeSessionInbox), track it so they rebind instead of keeping the disposed reducer's last state (opencode-inbox-rebinding.test.ts, tests/browser/session-rendering.test.ts).

  • Event-driven projections coalesce to the frame level through stores/opencode-projection-frame.ts: events still reduce synchronously and in order, but the projection into the message store runs at most once per animation frame per session, always from the reducer's newest state (a bounded timer while the window is hidden, since hidden windows pause animation frames; environments without a frame scheduler keep the previous synchronous projection). Store readers lag at most one frame. Session selection writes (writeSessionSelection) and visibility transitions flush pending pages; transcript eviction and instance teardown cancel them; destructive events (session.deleted, session.inbox.cancelled, session.revert.committed) and forced authoritative publications still project synchronously and subsume the pending frame. Projections and stream invalidation gate on watched transcripts — the active session plus any child session whose task renderer keeps its transcript visible (stores/session-transcript-visibility.ts): watched children project streamed steps like the active session instead of dropping their loaded page per event, while an event admitted while its session was watched but no longer watched at frame time invalidates the loaded page so the next activation reads authoritatively. Covered by opencode-projection-frame.test.ts, session-child-transcript-watch.test.ts and tests/browser/streaming-projection.test.ts.

  • Reducer page reads (the SDK's message.sync through the message.list proxy in createDataEntry) flush buffered compaction text, snapshot the session's live rows, fetch, flush again and answer with the page merged against that snapshot (stores/opencode-data-read-merge.ts), so buffered text is reduced exactly once: the page is the base and keeps its cursor, a live row new or changed since the snapshot keeps its live version (a row changed only in its root time.completed, which SDK step boundaries stamp, takes the page's version) except for its identified content parts, such as tool calls, left unchanged since the snapshot, which take the page's version so progress on one tool never hides authority for another, and rows created during the fetch and absent from the page ride along newest-first. Only events that remove or replace content (invalidatesFetchedPage: deletion, revert commit, inbox cancellation, compaction start/end/failure) restart the read; streamed text, reasoning, tool progress, compaction text and new rows merge, so a continuously streaming session completes its read in one fetch. Live versions are reconciled by the native full-text endings and the SDK's end-of-round refresh. A first latest-window load (loadMessages with no resident rows and no stored window) merges its 200-row page the same way and commits it while live revisions advance, then, unless the session is known idle, seeds a session reducer that holds no rows with the page's newest 20 rows, the SDK's own page size, without another read (seedOpenCodeSessionMessages), because the reducer applies streamed events only to messages it holds. Reloads and history windows keep the revision checks. Covered by opencode-data-trailing-read.test.ts, opencode-data-read-merge.test.ts and session-api-running-open.test.ts.

  • Shared speech byte/MediaSource transport lives in lib/audio-utils.ts; playback ownership and cancellation stay with its callers.

  • Speech keeps one active hook owner by callback identity. Identity changes and disposal cancel that owner's work and audio; delayed capabilities and synthesis responses are fenced by request version. Audio completion resets only the owner of that audio instance, including when multiple mounted views share a content identity. tests/browser/speech-lifecycle.test.ts covers recycled tool cards and playback cancellation.