2  Pi as a Thin Interactive Client

Part I · The system in action

Tested host: Pi 1.0.4 · Current reviewed reference snapshot: 45a903c · Demo review: 2026-10-22

Pi makes the system usable without becoming its authority boundary. The terminal owns interaction and local sessions; the Bun server owns provider credentials, portable routes, input admission, executable tools, and evidence-producing operations.

2.1 The client/server split

The reviewed path is intentionally asymmetric.

Pi owns Portable server owns
terminal editing and rendering provider client construction and credentials
/model interaction admitted portable model routes
local session files and compaction request parsing and ordered input admission
explicitly loaded UI extensions server tool selection, policy, budgets, and execution
attachment references for the current invocation document/image ingestion and invocation-local asset identities
progress-card presentation the actual search, retrieval, computation, and builder operations
artifact preview/save interaction short-lived artifact creation and integrity metadata

This is a thin-client claim, not a claim that Pi contains no logic. Pi still parses interaction, maintains its session, builds requests, renders streams, and runs trusted client extensions. “Thin” means that application authority is not derived from the terminal or generated prompt text.

2.2 The reviewed launcher

The current launcher is scripts/run-pi.sh. It performs a fixed sequence:

  1. resolve the repository root;
  2. require the pinned Pi executable installed under extensions/pi;
  3. create an isolated, ignored Pi agent directory;
  4. copy the reviewed model registry into that directory;
  5. load exactly five repository extensions;
  6. select the portable-agents provider and reviewed OpenAI route; and
  7. pass --no-tools before any additional user arguments.

The five extensions are:

Extension Client responsibility Authority it does not receive
portable-model-routing.ts keep reviewed model choices on portable-agents routes arbitrary provider or endpoint selection
input-file-attachment.ts encode reviewed local attachments for the current invocation durable file identity or arbitrary file traversal
document-inspection.ts present a bounded local extraction model/tool authority or citation status
presentation-artifact.ts verify, preview, and save a returned artifact permission to build arbitrary server files
server-tool-progress.ts render server progress as expandable cards executable tools or model-context instructions

Every extension is local code with the user’s privileges and must be reviewed as such. Loading it is not equivalent to downloading an untrusted plugin at runtime: paths are fixed by the launcher and are not selected by model output or agent.yaml.

2.3 Why --no-tools matters

Pi includes its own executable tool surface. That is useful in coding sessions but would create a second authority plane in this research workflow. The reviewed launcher disables those tools so generated calls must use the server-owned tool loop.

--no-tools does not sandbox Pi, restrict operating-system permissions, or make extensions inert. It has a narrower, testable meaning: built-in Pi tools are not available to the model in this launched session. The repository extensions still perform their reviewed UI and attachment functions, while executable research capabilities remain behind the server.

A model refusal is not proof of this boundary. Evidence comes from the launch arguments, registered tool surface, server tests, and observed correlated calls.

2.4 Portable model routes

Pi’s registry uses a loopback base URL ending in /v1 and a non-secret placeholder API key. Provider credentials remain in the server process. A route such as:

portable-agents/openai/gpt-5.4

means “send the request to the portable server and let its trusted routing policy select the reviewed provider adapter.” Choosing Pi’s built-in openai/... route directly would bypass server-owned attachments and tools even if the visible model name looked similar.

The routing extension remaps a reviewed built-in Anthropic selection to the corresponding portable-agents/anthropic/... route. An unmapped selection restores a reviewed portable route; if rerouting cannot be completed, the session stops instead of silently falling through to a direct provider. Registry context windows and output limits are client routing metadata, not live capability or account-access evidence.

The reviewed Pi 1.0.4 path uses HTTP POST /v1/responses with JSON or SSE. It does not use the Open Responses WebSocket transport or /v1/responses/compact. Pi performs its own local session compaction. These facts explain client behavior; they do not relax the formal conformance gaps reported in Chapter 19.

2.5 Invocation-local attachments

Typing an attachment reference causes the extension to inspect a supported local regular file, enforce its client-side count and byte limits, and add a standard ordered file/image content part to the current request. The server performs its own authoritative admission.

The reviewed extension supplements Pi’s normal fd-based completion because ignored fixture files do not otherwise appear. It exposes only supported, non-empty regular files from the current working directory and does not recursively enumerate ignored paths.

Attachment identity ends with the invocation. A later turn must resend the file if it needs the bytes again. The conversation may retain extracted statements, but those statements are not equivalent to a trusted retained file, page map, or citation identity. This is why the presentation follow-up can reuse research findings but cannot silently remount the original workbook.

2.6 /inspect-document: a different path

/inspect-document path is a local command, not a prompt asking the model to read a file. The command starts a fixed Bun child, runs the same bounded document-ingestion component, and opens the complete admitted extraction in a read-only viewer.

The viewer:

  • begins at the first line;
  • supports bounded line and page navigation;
  • reports filename, media type, size, digest, extraction mode, page/chunk counts, and warnings;
  • saves only after an explicit command;
  • confirms before replacing an existing extraction; and
  • closes without sending document text to the model.

/inspect-document --save path performs the bounded extraction and save path without opening the interactive viewer. The canonical output name ends in .extracted.md; it does not overwrite the source document.

The command does not establish scientific correctness, universal PDF fidelity, page-perfect citations, or safe publication of the extracted content. It exposes what the reviewed ingestion path produced.

2.7 Progress is presentation, not authority

Long research operations need visible activity without leaking raw arguments or results. The server emits bounded progress summaries with operation identity and lifecycle. The Pi extension renders those summaries as expandable custom cards stored outside model context.

The extension registers no executable tool. A progress card cannot start, approve, retry, or cancel an operation. It also must not expose search queries, source bodies, document text, credentials, or raw provider errors. Resume tests keep cards associated with the correct session and verify that rendering does not duplicate execution.

This user-visible protocol is distinct from OpenTelemetry. Chapter 8 owns progress semantics; Chapter 16 remains blocked until operator telemetry is implemented and tested.

2.8 Artifact verification and saving

The presentation builder returns an artifact descriptor rather than placing arbitrary bytes at a model-supplied path. The descriptor binds an artifact ID, media type, byte count, SHA-256 digest, expiry, and loopback retrieval route.

The Pi artifact extension:

  1. retrieves the short-lived artifact from the loopback server;
  2. verifies the exact byte count and SHA-256 digest;
  3. allows preview without claiming visual quality;
  4. writes the selected local destination with restrictive mode 0600; and
  5. requires confirmation before replacement.

The model cannot supply server paths, local save paths, package names, macros, OLE objects, external relationships, or executable presentation code. Integrity verification proves that the saved bytes match the server descriptor; it does not prove the claims in the deck or compatibility with every presentation suite.

2.9 Sessions, privacy, and retention

PI_CODING_AGENT_DIR separates this workflow from the user’s default Pi configuration and sessions. It is organizational isolation, not an operating-system sandbox. Session records can contain prompts, generated answers, tool summaries, source notes, and local paths. They should remain private even when ignored by Git.

--no-session avoids durable Pi session storage for that run, but also prevents later resumption. Deleting the example directory removes copied registry and local sessions; it does not revoke provider credentials held elsewhere or delete server/provider records. A project directory, terminal scrollback, downloaded artifact, and operating-system logs may have separate retention.

2.10 Demonstration: model-independent inspection

The approved landing-page recording supplies this chapter’s clearest negative capability evidence. It shows a public 16-page paper opened, navigated, and explicitly saved with:

44 chunks
129,145 extracted characters
0 extraction warnings
0 model calls
0 provider calls
0 public-network calls

The displayed extraction digest is part of the recording metadata. The PDF itself is not distributed by the book. Gino Tesei approved visible use because he is an author and the paper is public; article text and publisher formatting are not relicensed.

This recording proves the exact local route and reviewed artifact. It does not prove that every PDF extracts correctly, that the paper’s claims are true, or that an on-screen but unused model contributed to the result.

2.11 Deterministic evidence

The current reference provides three credential-free acceptance commands for the client path:

bun run test:pi
bun run test:pi-progress
bun run test:pi-inspection

They use isolated client directories and synthetic loopback servers. Together they exercise text and stream behavior, tool/usage display, continuation and cancellation, progress ordering and resume isolation, command registration, metadata-only inspection notification, zero provider calls, save behavior, and cleanup. They do not replace manual TUI review for resizing, colors, keyboard ergonomics, or every host terminal.

2.12 Failure modes

  • Direct-provider selection: the visible model works but bypasses the server boundary.
  • Implicit attachment retention: a later turn appears to reuse bytes that no longer have an admitted identity.
  • UI card as evidence: rendered progress is mistaken for proof that an operation completed correctly.
  • Client configuration as capability proof: a registry entry is treated as account availability.
  • Local session as trusted memory: editable display history is treated as an authenticated effect ledger.
  • Artifact digest as semantic review: matching bytes are mistaken for verified claims or visual quality.

2.13 Pattern summary

Keep the interactive client replaceable. Give it enough responsibility to present, attach, inspect, and save, but keep credentials, model routing, input admission, executable capabilities, evidence operations, and policy on the server side of a visible protocol boundary.

2.14 Exercises

  1. Launch Pi without --no-tools. Identify the new authority plane and the evidence needed before accepting it.
  2. Compare an @file turn with /inspect-document file. List every model, provider, and network recipient in each path.
  3. Design a session-retention notice that distinguishes Pi files, provider retention, downloaded artifacts, and server invocation state.
  4. Explain why a model name shown in /model is not evidence that the request used the portable route.
  5. Define the checks required before replacing an existing .pptx file.

2.15 Chapter contract

  • Scope: client/server responsibility, portable model selection, fixed extension loading, invocation-local attachments, progress cards, local inspection, artifact verification, and Pi session privacy.
  • Canonical claims: Pi is an optional interactive client; server authority survives only when routing stays under portable-agents and local executable tools remain disabled.
  • Migration inputs: former client/server material, the Pi 1.0.4 implementation notes, and the approved document-inspection evidence.
  • Evidence gates: deterministic Pi acceptance, exact launcher/extension snapshots, and manually reviewed recordings.
  • Demonstration slots: the approved model-independent inspection recording; the hero supplies the complementary attachment/progress path.
  • Source-claim ledger: client behavior is tied to Pi 1.0.4 and reference snapshot 45a903c; formal protocol status remains separate.
  • Exclusions: provider translation belongs to Chapter 5, protocol lifecycle to Chapter 6, executable tool authority to Chapter 8, and durable state to Chapter 15.