Specification · RFC
RFC-0010: View-Only Workspace TUI
Version: 0.6.0 | Status: normative | Phase: stable Owners: @Zihua Wu
1. Summary
Section titled “1. Summary”[RFC-0010:C-SUMMARY] Summary (Informative)
Section titled “[RFC-0010:C-SUMMARY] Summary (Informative) ”This RFC defines a workspace-scoped terminal interface for observing InferLab definitions, active CLI work, serving state, records, metrics, logs, and operator journal context without moving execution authority into the interface. It complements the workspace authority in RFC-0002, the runtime workflows in RFC-0003, and the record and scratchpad authorities in RFC-0005.
Scope: This version covers one automatically discovered or explicitly selected workspace, four read-only views, contextual detail, global and local search over a complete record catalog, producer-published operation observations, one fixed display-refresh cadence with a lower-frequency declared-workspace observation, bounded and fair active observation, responsive keyboard navigation, and transition from a running operation to its referenced record. It does not cover cross-workspace aggregation, experiment comparison or trend analysis, arbitrary JSON browsing, framework-specific dashboards, remote log synchronization, a general query language, plugins, or any lifecycle or experiment action.
Rationale: Operators currently need several commands and files to understand what a workspace contains, what is running, and what recently completed. A persistent view makes those existing facts navigable while preserving the CLI and records as the execution and evidence authorities. Keeping the complete catalog navigable while scheduling expensive, slowly changing declared facts less often lets long-lived workspaces remain usable without creating another index or authority.
Since: v0.1.0
2. Specification
Section titled “2. Specification”[RFC-0010:C-SCOPE] Workspace And View-Only Scope (Normative)
Section titled “[RFC-0010:C-SCOPE] Workspace And View-Only Scope (Normative) ”The public CLI MUST provide tui as a view-only terminal interface.
The global --workspace <dir> selection governed by RFC-0002:C-WORKSPACE-AUTHORITY MUST select the one workspace observed by tui. When --workspace is omitted, tui MUST use the same upward discovery from the current directory as other workspace-scoped commands.
The interface MUST observe exactly one workspace. It MUST display the canonical workspace root and MUST NOT provide a workspace switcher, recent-workspace registry, or cross-workspace aggregation.
The interface MUST NOT start or stop a server, launch an Eval or Bench, execute a recipe, build an image, install a toolchain, edit a definition or scratchpad, repair or clean state, download a dataset, synchronize remote logs, reset a prefix cache, or otherwise initiate an InferLab workflow. Search results and object selections MUST navigate only.
The interface MAY actively observe process state, readiness, Prometheus-compatible server metrics, and GPU telemetry. Each such observation MUST be bounded. It MUST use an observation command or endpoint and MUST NOT request process lifecycle, configuration, repair, cleanup, or other workflow effects. Incidental access logging and telemetry accounting performed by the observed system do not make an observation an InferLab workflow action.
The tui invocation itself MUST NOT be published as a workspace operation. Exiting normally, on an error, or after interruption MUST leave workspace state unchanged and MUST restore the terminal for ordinary shell use.
Rationale: All actual work remains explicit in a separate CLI invocation, while bounded probes answer whether already-running resources remain healthy. Reusing standard discovery preserves one workspace-selection contract and prevents the observer from becoming a second workspace manager.
Since: v0.1.0
[RFC-0010:C-READ-MODEL] Views, Authorities, And Detail (Normative)
Section titled “[RFC-0010:C-READ-MODEL] Views, Authorities, And Detail (Normative) ”The interface MUST provide top-level Overview, Operations, Records, and Workspace views.
Overview MUST show the workspace revision and dirty state, active operations, running or abnormal servers, and recent top-level records. It MUST prioritize failed, stale, and unavailable objects. It MUST NOT expand the complete workspace catalog or keep full logs, GPU telemetry, server metrics, or resolved configuration permanently visible.
Operations MUST show concurrent workspace-scoped CLI invocations and retained stale operation observations. Records MUST retain every currently available top-level workflow record in one continuously navigable catalog. Records MUST NOT apply a recent-record cutoff or partition the catalog into operator-managed pages. Viewport position MUST NOT restrict the records available to navigation or search. Records MUST show explicit child-record references beneath their parent rather than flattening child records or deriving hierarchy from record identifiers. A parent whose child references are collapsed MUST indicate that it has child references. A child reference whose record is available MUST be selectable and MUST present that record’s detail; a child reference whose record cannot be read MUST remain beneath its parent as unavailable. Workspace MUST show the declared models, stacks, servers, Evals, Benches, workload suites, recipes, images, and external images governed by RFC-0002:C-WORKSPACE-AUTHORITY.
A selected object MUST have a contextual detail surface. That surface MUST show the facts available for the selected kind, including referenced logs, metrics, topology, child records, and scratchpad entries when they apply. Logs MUST be associated through explicit operation or record references. The interface MUST NOT infer log ownership from filenames.
A selected Bench definition MUST distinguish request, linear-session, and agentic-replay sources. Its detail MUST present only applicable facts from the source identity, prompt authority, population, load, and prefix-sharing declarations governed by RFC-0004:C-BENCH-REQUEST-SOURCES, RFC-0004:C-BENCH-LINEAR-SESSIONS, RFC-0004:C-BENCH-PROMPT-AUTHORITY, RFC-0004:C-BENCH-PREFIX-GEOMETRY, and RFC-0004:C-BENCH-AGENTIC-TRACE-REPLAY; it MUST NOT expand absent or unrelated configuration.
A selected Bench record MUST present its recorded terminal outcome, including pass, skip, failure, and capture outcomes when those facts exist, and MUST distinguish its recorded source kind. Request-source detail MUST present recorded request population, prompt authority, prefix-cache reset, and prompt-token reconciliation evidence when present. Linear-session detail MUST present the separate warmup and profiling session and request counts, reconciliation outcomes, and failed-session outcome and diagnostic when present, with meanings governed by RFC-0005:C-BENCH-LINEAR-SESSION-EVIDENCE. Agentic-replay detail MUST present catalog and source identity and acquisition outcome; native run and scenario identity; submission validity and reasons; warmup counts, outcome, and profiling handoff; profiling, source-trace, runtime-conversation, transport-request, cache-bust, context-overflow, and ordinary-failure counts; branch and join counters; unavailable dimensions; and the terminal case outcome when present, with meanings governed by RFC-0005:C-BENCH-AGENTIC-TRACE-EVIDENCE. Source-specific raw artifacts MUST remain references rather than being copied into the TUI. A historical or unsupported record without a source tag or required source evidence MUST remain navigable and MUST identify that source detail as unavailable for its record schema; the interface MUST NOT infer a source kind from other fields.
A selected Bench record that contains metrics MUST provide a metric comparison surface reachable from its detail. The surface MUST use the following mapping for the stable metrics governed by RFC-0004:C-MEASUREMENTS and the request-SLO metrics governed by RFC-0004:C-BENCH-SLO:
request_throughput,output_throughput, andtotal_token_throughputuse labels “Request throughput”, “Output-token throughput”, and “Total-token throughput”, familyTHROUGHPUT, and unitsreq/s,tok/s, andtok/s, respectively.- The
<statistic>_prompt_tokensfamily uses the statistic label, familyINPUT · OBSERVED, and unittok. - The
<statistic>_request_latency_ms,<statistic>_ttft_ms, and<statistic>_tpot_msfamilies use the statistic label, familiesLATENCY · REQUEST,LATENCY · TTFT, andLATENCY · TPOT, respectively, and unitms. prompt_cache_read_ratiouses label “Prompt cache read ratio”, familyCACHE, and unit%.acceptance_lengthandacceptance_rateuse labels “Acceptance length” and “Acceptance rate”, familySPECULATION, and unitstokand%, respectively.good_request_ratioandgoodputuse labels “Good request ratio” and “Goodput”, familySLO, and units%andreq/s, respectively.
For this mapping, <statistic> means mean, p50, p90, p95, p99, min, max, or stddev; its displayed label MUST be Mean, P50, P90, P95, P99, Min, Max, or Stddev, respectively. Ratio values recorded on the inclusive zero-to-one scale MUST be displayed as percentages. An unknown recorded metric MUST remain available under OTHER with its recorded name unchanged and no invented unit.
Every displayed fact MUST retain its authority as declared, recorded, ephemeral, or observed. Declared facts MUST retain the workspace revision, dirty state, and source identity governed by RFC-0002:C-WORKSPACE-AUTHORITY. Stale and unavailable MUST remain observation-state qualifiers rather than evidence authorities. The interface MUST NOT copy a live observation into a record, reinterpret an existing record outcome, reconstruct resolved execution facts from definitions, or treat an operation observation as execution evidence.
Recorded execution facts and artifacts MUST continue to follow RFC-0005:C-EVIDENCE. Scratchpad text and record references MUST continue to follow RFC-0005:C-SCRATCHPAD-JOURNAL.
Rationale: Four product-oriented views answer what exists, what is happening, and what happened without exposing storage nouns as navigation. Source-aware Bench detail makes newly supported request, session, and agentic workflows distinguishable without turning the TUI into raw JSON browsing or another execution authority. A complete scrolling catalog and typed search preserve access to old evidence as history grows without introducing an operator-visible paging workflow. Explicit source labels and record references prevent a convenient display from creating a second authority for configuration, execution, or evidence.
Since: v0.1.0
[RFC-0010:C-OPERATIONS] Workspace Operation Observation (Normative)
Section titled “[RFC-0010:C-OPERATIONS] Workspace Operation Observation (Normative) ”After discovering a workspace, every public workspace-scoped CLI invocation except tui and web MUST publish one ephemeral operation observation for the remainder of that invocation. Dry runs and run invocations are operations. Commands that do not belong to a workspace are not operations of the observed workspace.
If a producer cannot establish or update its required observation, the invocation MUST fail under the operation-observation error code rather than silently continue without it. A failed update MUST NOT leave an earlier snapshot visible as live.
Each concurrently executing invocation MUST own a distinct observation. Its producer identity MUST include host identity, boot identity, process identifier, and process start time.
An operation observation MUST be a versioned JSON document under .inferlab/runtime/observations/. It MUST identify its producer and schema version, producer identity, command identity, start time, last-update time, current phase, and current item position when the operation has one. It MAY carry explicit log references, the latest readiness failure, and a contended lock reference.
A record-producing operation MUST publish its record reference once the record is allocated and before the next potentially blocking operation. It MUST retain that reference in every subsequent observation update through removal.
Phase, item, readiness-failure, lock, record-reference, and log-reference facts that also appear in operator progress MUST project the same current state governed by RFC-0001:C-OPERATOR-PROGRESS. Successful observation publication MUST NOT suppress or alter the workflow’s stdout result, stderr progress, or terminal diagnostic.
An operation observation MUST supplement rather than replace an in-progress record governed by RFC-0005:C-EVIDENCE. It MUST NOT duplicate the record’s resolved configuration, lifecycle state, runtime evidence, normalized metrics, or outcomes. Updates MUST replace the document atomically from a reader’s perspective.
A malformed document or unsupported observation schema MUST affect only that operation. The TUI MUST present it as unavailable and incompatible, including the producer and schema version when those envelope facts are readable. It MUST NOT partially interpret the document as another version or fail the remaining refresh.
A consumer on the producer host and boot MUST validate the PID and process start time. A mismatch MUST make the operation stale. A matching host with a different boot identity MUST make the operation stale because the producer cannot have survived that reboot. An observation from another host MUST be unavailable unless a bounded observation path validates that remote producer identity; it MUST NOT be declared stale merely because the local process table lacks the PID.
A producer MUST remove its own observation on normal completion, including a handled failure. An abruptly terminated producer MAY leave its observation in place. This version MUST NOT automatically expire or delete such a residual observation.
A producer MUST NOT delay command completion so an operation crosses a refresh interval. Multiple operations with the same command identity MUST remain independently visible when they overlap.
When a selected operation disappears and its referenced record remains available, the detail surface MUST transition to the record’s current state. When the operation disappears without an available referenced record, the detail surface MUST retain the last observation as stale and MUST NOT infer an outcome.
Rationale: Records are created before state-affecting workflow commands and remain authoritative for resolved intent, lifecycle, runtime evidence, and outcomes. The operation observation fills the narrower gap for invocation and phase facts, including pre-record work, dry runs, commands without records, and current progress shown in another terminal. Host- and boot-scoped identity prevents local PID reuse or shared-workspace access from fabricating liveness.
Since: v0.1.0
[RFC-0010:C-REFRESH] Refresh And Observation State (Normative)
Section titled “[RFC-0010:C-REFRESH] Refresh And Observation State (Normative) ”The interface MUST schedule display refresh automatically on one fixed interval. The default interval MUST be one second. --refresh-interval <duration> MUST allow a positive invocation-scoped override. The override MUST NOT change workspace definitions, local bindings, or records.
Operations, record-directory membership, non-finalized records, and journal change detection MUST be scheduled on every display refresh. Workspace revision and dirty state and the declared workspace definitions MUST be observed at startup. Those declared-workspace sources MUST thereafter be scheduled automatically at an interval equal to the greater of the configured display-refresh interval and sixty seconds.
A source that is not scheduled for the current generation MUST retain its last value and observation time. It MUST NOT become stale solely because it was not scheduled. A source that is checked and found unchanged has a successful current observation. The r key MUST request one immediate read-only refresh that schedules every source, including the declared-workspace sources.
Each refresh MUST publish one coherent display generation after the reads and bounded probes scheduled for that generation complete. The last complete generation MUST remain available while the next refresh is in progress. Refresh work MUST NOT prevent keyboard input, navigation, search, q exit, or terminal restoration.
A refresh still in progress MUST NOT overlap with another refresh. Ticks missed by an in-progress refresh MUST be coalesced rather than queued.
The persistent interface chrome MUST present one display-refresh indicator owned by the display-refresh schedule rather than by any workspace, record, operation, or active-observation source. Before the first complete generation, the indicator MUST show that the interface is waiting. After a complete generation, while the monotonic elapsed time since that generation became available to the interface is less than two configured display-refresh intervals, the indicator MUST present the configured automatic cadence without a changing generation age. Once that elapsed time reaches two configured intervals without another complete generation, the indicator MUST present the elapsed time since the last complete generation until a later generation completes. The display-refresh indicator MUST NOT change merely because a refresh is in progress.
The display-refresh indicator’s elapsed time MUST begin when a complete generation becomes available to the interface. The elapsed time MUST use a monotonic clock. It MUST NOT use a source observation timestamp or wall-clock time. Object-level observation state, last-success time, and data age MUST remain attached to the object they describe and MUST NOT replace the display-refresh indicator.
Every process-state observation initiated from a server record whose recorded status is running is an eligible active-server observation. All eligible active-server observations attempted in one display generation MUST share one elapsed wall-clock deadline one second after that observation phase begins. Each attempt MUST be bounded by the then-remaining interval and MUST NOT delay the generation beyond the shared deadline. Exhausting that deadline MUST stop further active-server observation attempts in that generation.
An eligible server skipped because the shared deadline is exhausted MUST retain its previous observation value and observation time. Its displayed data age MUST continue to advance against the presentation time. It MUST NOT become stale solely because it was skipped. An eligible server with no successful observation since interface startup MUST remain unavailable until an observation succeeds. Scheduling across generations MUST prevent an earlier slow server from indefinitely starving another eligible server.
Failure to read or probe one object MUST NOT fail observations of other objects or terminate the interface. Each object with active observations MUST show its observation time.
An object whose scheduled observation succeeds MUST be live. An object whose scheduled observation fails after an earlier success MUST be stale. A stale object MUST retain the last successful value and MUST show the failure, last-success time, and data age. An object that has not succeeded since interface startup MUST be unavailable and MUST NOT present a fabricated value. A later successful observation MUST return the object to live.
A stale or unavailable active observation MUST NOT change the status or content of declared workspace facts or recorded evidence displayed for the same object.
An immediate refresh requested with r MUST obey the same non-overlap, shared active-observation deadline, failure-isolation, responsiveness, and authority rules as an automatic refresh.
Rationale: One display cadence remains predictable for live operator state, while revision, dirty state, and fully validated definitions change slowly and can require substantially more source work than runtime observations. Retaining their explicit observation time and providing an immediate manual refresh make the lower frequency visible rather than silently presenting it as current. A stable healthy indicator reports the configured schedule instead of animating a sawtooth age, while a monotonic overdue age changes only when a complete generation is genuinely delayed. One shared elapsed deadline keeps a collection of unreachable servers from extending a generation once per object, and fair scheduling preserves eventual visibility without introducing a concurrent probe service.
Since: v0.1.0
[RFC-0010:C-NAVIGATION] Responsive Navigation And Search (Normative)
Section titled “[RFC-0010:C-NAVIGATION] Responsive Navigation And Search (Normative) ”A wide terminal MUST present an object list and selected detail together. A narrow terminal MUST present one at a time, with Enter opening detail and Esc returning to the list. Below the supported minimum dimensions, the interface MUST show the required and current dimensions rather than render unreadable tables.
The number keys 1, 2, 3, and 4 MUST select Overview, Operations, Records, and Workspace respectively. Tab and the arrow keys MUST move focus or selection. Enter MUST navigate into the selected object. Esc MUST close the current overlay or return from detail. q MUST exit. In Records, → on a collapsed parent MUST expand its child references and otherwise MUST open detail; ← on an expanded parent or one of its children MUST collapse them and select the parent, and otherwise MUST return from detail. In Overview and Records, f MUST cycle the visible status filter through all objects, objects needing attention (failed, stale, or unavailable), and running objects, and the interface MUST show the active filter and the count of objects under each status. Outside text entry, t MUST switch between the dark and light palettes for the rest of the session without changing any observed fact.
When a selected object remains in the resulting visible list after refresh, the interface MUST preserve that selection by object identity even if insertion, removal, sorting, or ranking changes its list position. This applies equally to a selected child record beneath an expanded parent.
Ctrl+K MUST open a global Find surface over operations, every top-level record in the current catalog, the workspace catalog, and scratchpad entries. Results MUST be grouped or labeled by kind and authority and MUST include enough context to distinguish similarly named objects. Selecting a result MUST navigate to its object detail and MUST NOT execute an action.
Global Find MUST search these typed fields:
- for an operation: command identity, phase, current item, and record reference;
- for a top-level record: record identifier, workflow kind, selected definition identifiers, selected case, status, and error summary;
- for a workspace definition: definition kind, identifier, and displayed relationship labels;
- for a scratchpad entry: topic, author, text, and record references.
/ MUST search or filter the current list. In a selected local log, / MUST search that log on demand. The interface MUST NOT globally scan all logs.
Text matching MUST be case-insensitive. Exact and prefix matches MUST rank ahead of fuzzy matches. This version MUST NOT expose a query-language grammar. Status and scope restrictions MUST use visible filters.
Global Find MUST NOT search raw record JSON, environment values, raw artifact contents, or unreferenced files. It MUST update from the same refreshed read model as the visible views. It MUST NOT present an independently stale result set. Viewport position MUST NOT restrict the records searched.
This version does not define mouse input, configurable keymaps, a command palette, or a persistent search index.
Rationale: Two responsive layouts keep the console usable without multiplying page-specific UI states. Identity-stable selection prevents a refresh from silently moving the operator to another record as a complete catalog changes. A navigation-only Find solves real workspace scale and long identifiers, while bounded typed search avoids turning the interface into a database browser or hidden action surface.
Since: v0.1.0