PXI Terminal UI#

The PXI terminal UI is an Ink-based React interface for the pxi executable in js/packages/phoenix-cli. It provides an interactive chat session against the PXI server-agent endpoint — rendering a streaming conversation transcript, inline tool call progress, and a live "thinking" indicator — entirely in the terminal. 1

Key source files (all under js/packages/phoenix-cli/src/pxi/):

App Structure and State#

PxiApp is the root component. It holds four pieces of state — messages, draft, status ("idle" | "streaming"), and error — and drives PxiChatClient to stream assistant replies. 1

Top-level layout:

PxiApp
├── PxiBanner — ASCII PXI wordmark (blueBright raised faces, gray shading)
├── status line — endpoint / model / session
├── Transcript — all conversation turns (color-coded "You" vs "PXI")
│ └── MessageParts — per-message: Text → Markdown, tool parts → InlineToolProgress
├── ThinkingIndicator — animated "PXI is thinking…" (250 ms frames, shown while streaming)
└── InputPrompt — single-line draft with block cursor; hints below the border

Keyboard bindings 1:

When the user presses Esc mid-stream, the current assistant message is frozen with any completed parts kept intact and an [Interrupted by user before completion.] text suffix appended. 1

Tool Call Rendering#

Each tool part in a message renders as InlineToolProgress. The original implementation showed a single opaque [tool] bash Complete line; PR #14093 replaced it with a structured layout. 2 3

Layout of a tool row#

  <state> <icon> <toolName> · <previewText> (<statusSuffix>)
      <detailLines …> (dimmed)
      <errorLines …> (red)

State glyph — rendered by ToolStateIndicator: 3

The spinner is ToolSpinner: a setInterval at 250 ms cycles through ten braille frames (⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏). 3

Spacing#

Consecutive tool calls stack compactly — marginTop/marginBottom are set to 0 when the adjacent part is also a tool call, and 1 at the boundary with text content. 3

Quiet tools#

load_skill and read_skill_resource collapse on completion to a single dim line, e.g. ✓ Loaded skill datasets, instead of a full tool row. 3

Tool Presentation Registry (toolPresentation.ts)#

toolPresentation.ts is a pure derivation layer — no side effects, no imports beyond ToolProgressState. It mirrors the web UI's per-tool registry in app/src/components/agent/ToolPart.tsx (which cannot be imported from this package). 3

ToolPresentation type#

type ToolPresentation = {
  icon: string; // terminal-safe single-width BMP unicode
  previewText: string; // one-line summary; empty until derivable
  detailLines: string[]; // dimmed lines (e.g. bash command excerpt)
  errorLines: string[]; // red lines (e.g. stderr)
  statusSuffix?: string; // appended to header, e.g. "exit 1"
  isQuiet: boolean; // collapse to single dim line when complete
  quietLabel?: string; // text for the collapsed line
};

3

Per-tool icons and bespoke presenters#

3

Clamping strategy#

All raw payload text is inspected after being clamped to MAX_SOURCE_LENGTH = 1000 characters, keeping the per-snapshot re-render O(1) even for large payloads. previewText is collapsed to a single line and truncated at 120 chars with …; detail lines are each capped at 200 chars. 3

getToolPresentation({ toolName, state, input, output, errorText }) is the single public entry point. toolProgress.ts calls it and spreads the result directly onto the ToolProgress object. 3

Tests and Extension Points#

Test files (under js/packages/phoenix-cli/test/): 3 1

• pxiApp.test.tsx — Ink component tests; covers spinner rendering, bash-failure display, quiet-skill collapse, and the old black-box behavior regression.
• pxiToolPresentation.test.ts — 28 unit cases: streaming-partial inputs, per-tool previews, truncation/clamping, exit-code handling, and malformed inputs that must never throw.
• pxiClient.test.ts, pxiMarkdown.test.ts, pxiOptions.test.ts, pxiPreflight.test.ts — coverage for the remaining modules.

Adding a new tool presenter: Register a ToolPresenter function in the TOOL_PRESENTERS map in toolPresentation.ts. The function receives { state, input, output, errorText } and returns a Partial<ToolPresentation>. Raw JSON is never printed — always derive display text from named input fields. 3