RFC 0001: Mutable Terminal History and Reading Anchors

Field

Value

Status

Draft

Author

HelloWorldU

Created

2026-07-31

Abstract

This RFC frames a protocol for identified, mutable content in terminal-owned history, allowing applications to update logical blocks while terminals preserve native scrollback and stable reading positions.

Background

AI agents bring ongoing, dynamic interactions to terminal interfaces: content is generated, revised, and finalized throughout a session. Applications manage that content as logical units with identity and lifecycle, while traditional terminal interaction primarily expresses character output and screen operations. The gap is between the application’s content model and what it can communicate to the terminal, not simply between two redraw strategies.

Traditional cursor-oriented terminal control lets applications edit the active presentation, but generally does not give rows already committed to terminal-owned scrollback stable application-addressable identity. Related systems provide structure or identity for narrower models, but the bounded prior-art review has not identified among its surveyed mechanisms a contract that combines mutable historical Blocks with native terminal history and reading-anchor preservation. Differential redraw cannot generally reach anonymous rows already in scrollback, while destructive clear- and-replay can erase history, duplicate content, or move the user’s reading position.

Historical updates and disrupted reading positions are concrete consequences of this gap. The proposed contract lets applications express content identity, lifecycle, and revision while terminals own presentation and native behavior. This RFC focuses that broader motivation on mutable terminal history and reading anchors through the goals below; it does not attempt to cover every dynamic TUI requirement.

Goals

The project explores whether a terminal protocol can provide all three of these properties together:

  1. Preserve terminal-owned scrollback and the native terminal capabilities built around it.

  2. Update or reflow dynamic content after it has left the active screen.

  3. Keep the user’s reading position anchored to logical content when output continues or content above it changes.

Responsibility Boundaries

The protocol separates three responsibilities:

  1. Content (TUI-owned): The TUI identifies logical blocks, controls their lifecycle, and decides when their content changes.

  2. Execution (terminal-owned): The terminal stores and lays out history, realizes content changes, and preserves terminal-native capabilities and the user’s reading position.

  3. Info (shared): The protocol carries semantic changes between the TUI and terminal and specifies their observable effects without exposing cursor movement, physical rows, or redraw algorithms to the TUI.

A block’s lifecycle is independent of its physical location. A block may remain mutable after its rendered rows have entered scrollback, and entering scrollback does not implicitly finalize it.

Minimal Protocol Model

The initial model has two core primitives:

  1. Block: an identified logical unit of content whose lifecycle is controlled by the TUI and whose presentation is controlled by the terminal.

  2. Operation: a semantic change to one or more blocks. The TUI expresses the intended change; the terminal decides how to apply and render it.

Operations describe changes to blocks, not terminal rendering instructions. For example, a user action inside a TUI may result in a block operation, while terminal-native scrolling, selection, and copying remain entirely within the terminal.

The terminal may use block identity to preserve a reading anchor across an operation, but an anchor is not exposed as a separate primitive in this initial model. Detailed Operation semantics and content-representation requirements are maintained in the living protocol drafts below. The current experimental wire mapping is also defined there and remains a non-normative draft.

Protocol Semantics

Detailed observable semantics are consolidated in the living Operation Semantics document:

  • Append introduces a Block; its initial semantics are defined.

  • Update replaces the content of an existing mutable Block; its initial semantics are defined.

  • Extend adds text at the exact current logical tail of a mutable Block; its initial semantics are defined.

  • ReplaceSuffix replaces a non-empty suffix of a mutable text/plain Block; its initial semantics are defined.

  • Seal finalizes a Block; its initial semantics are defined.

Protocol activation is governed by the living Capability Negotiation document. A TUI enables Block Operations only after the current terminal connection positively confirms complete support for a mutually understood protocol version.

Block identity and mutation authority are scoped by the living Protocol Context Semantics document. Each Block is addressed by its Context ID and Block ID; establishing and closing a Context are protocol control exchanges rather than Block Operations.

Any concrete encoding must satisfy the living Wire Format Requirements, including explicit framing, safe coexistence with ordinary terminal traffic, ordered application, payload integrity, failure recovery, and bidirectional capability negotiation.

The living Logical Wire Message Model maps those semantics onto a common envelope and finite Capability, Context, Block Operation, and error-reporting message kinds. It also defines closed per-version schemas and explicit extension paths.

The living Concrete Message Schemas map each logical message kind to its required envelope and body fields without adding new Block semantics.

The initial machine-readable failure categories and their reporting paths are defined by the living Error Codes document.

The initial logical Message serialization is UTF-8 JSON as defined by the living JSON Serialization document. The initial bidirectional carrier and message boundaries are defined by the living OSC Carrier and Framing document.

Block snapshots follow the living Content Representation requirements: content is self-contained and declarative, uses one explicitly typed and negotiated representation, and defines how terminal-native capabilities apply to its logical content.

The living Terminal-Native Behavior document defines how Block changes interact with terminal-owned reading, reflow, selection, search, content metadata, and active input state.