@surprisal/pi-hyperchart

Pi extension, run manager, agent executor, terminal UI, React inspector, and bundled Hyperchart skill.

Install in Pi

Run from your shell:

pi install npm:@surprisal/pi-hyperchart

Start Pi after the install, or restart an existing Pi process. The package declares:

• extensions/hyperchart.ts;
• skills/hyperchart/.

It requires Node.js 22.19 or newer and the exact matching version of @surprisal/hyperchart. Pi host libraries remain optional peers supplied by Pi's extension loader. On filesystem-backed Node.js installations, detached runners receive absolute module entries from the active Pi process and therefore use that same Pi installation rather than a separately resolved copy. Compiled Bun Pi binaries do not expose their embedded host modules as files and are not currently supported for detached runners.

Start a chart

Place a chart in .pi/hypercharts/name.chart.ts, then run:

/hyperchart run name          # asynchronous
/hyperchart run name --wait   # synchronous

The TUI stays compact: it shows active states and path-aware percentage progress. Run /hyperchart to select recent runs; Enter opens the selected run in the full localhost browser inspector. Map actions held behind a concurrency limit appear as waiting; only admitted work appears as running and can expose an active session. Agent cards show declared role/toolset names and their resolved model/tool allowlists; the selected state's run-specific Runtime section shows the actual launch plan plus transcript/current-tool polling and steering. Run metadata and every agent system context distinguish the owning repository/project directory from the isolated branch action workspace; the latter is not an implicit repository checkout.

The consolidated tool runs the same TypeScript/source-lint preflight for inspect and run. Fresh runs default to branch main; existing single-branch runs can infer their only head, while multi-branch run inspection/view/resume requires an explicit selector. Safe run-target actions accept either runDir or runId and reject conflicts; respond keeps exact (runId, branchId, seqId) identity. See the canonical Pi tool API.

Asynchronous runs inject only a compact terminal boundary notice into the exact originating Pi session/workDir. An active owned user gate defers terminal delivery without receipting it. The extension never answers a gate automatically: hidden context tells the model to call respond only when the current prompt actually answers the displayed question; unrelated requests leave it open. --wait/wait: true waits for terminal status or a user boundary and returns bounded identifiers/status only. Gate response identities remain exact; bounded prompt/option labels carry original/omitted character counts and are separate from exact option values. Structured user gates carry a bounded recursive, non-executable output contract; if any identity or contract cannot remain sufficient within its caps, delivery fails closed and directs the operator to the browser inspector. Terminal-notification delivery uses at-least-once semantics. Durable terminal request IDs and recoverable claims prevent permanent suppression after crash. The host may redeliver the same terminal notification after a crash between delivery and confirmation. Treat each terminal requestId idempotently; user gates instead use exact (runId, branchId, seqId) coordinates.

Pi agent tool

The consolidated hyperchart tool supports bounded responses only. Full definitions, schemas, runtime snapshots, visit histories, and transcripts never enter Pi tool results/session JSONL; action: "view" is the sole full inspection surface and returns exactly { "url": string }. Deprecated verbose: true inspection calls are rejected.

Supported actions:

• action: "list"
• action: "inspect"
• action: "run"
• action: "run_inspect"
• action: "view" — open the localhost inspector and return its URL; pass open: false to return the URL only
• action: "branches"
• action: "fork"
• action: "rewind"
• action: "stop"
• action: "respond"

Application entry points

Import	Purpose
@surprisal/pi-hyperchart	same in-process command API as /command
@surprisal/pi-hyperchart/command	in-process /hyperchart request event
@surprisal/pi-hyperchart/pi-host	Pi host adapter: summary-only session lists plus on-demand full chart definitions (including launch metadata) and inspector runs; exposes originating Pi session for new runs
@surprisal/pi-hyperchart/react	inspector, graph, run strip, launch dialog, UI providers
@surprisal/pi-hyperchart/react/styles.css	required React stylesheet
@surprisal/pi-hyperchart/package.json	package metadata and Pi manifest

Bundled documentation

The published package includes docs/, runnable examples/, and the architecture diagram. The bundled skill links to these local, version-matched files so an agent does not need network access for authoring, tool schemas, or recovery guidance.

Documentation

• Pi extension
• Pi API and agent tools
• React API
• Run your first chart
• Recovery and safety
• React and host integration

MIT · experimental 0.6.0

Named branches

The consolidated hyperchart tool accepts branchId, non-empty unique branchIds, or omission for run. Omission starts fresh main or infers an existing run's only durable branch; multi-branch resume requires an explicit selector. Start main, fork durable heads, then resume with branchId or branchIds to execute the fixed set concurrently in one detached runner with a separate Pi executor per branch. Run inspection and view also infer only a single unambiguous branch; response, steering, and rewind select one explicit branchId. action: "branches" lists heads and action: "fork" creates a head without selecting or starting it. Rewind preserves all history and downstream files. status.json v2 persists stable branchIds, and session state is stored under collision-resistant sessions/<sanitized-branch-prefix>-<hash>/... paths.