pi-chassis 0.0.0-stage → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+All notable changes to pi-chassis (published under an earlier name up to 0.3.0) are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html); see [Versioning](README.md#versioning) for what counts as a breaking change here.
+
+## [Unreleased]
+
+## [0.7.1] - 2026-10-23
+
+### Changed
+
+- README: the install commands no longer pin a version or a tag, and the advice to pin is gone.
+
+## [0.7.0] - 2026-10-23
+
+### Changed
+
+- **Breaking:** the shared `globalThis` keys are now `Symbol.for("pi-chassis/<name>")`: `registry`, `pending`, `pendingToolRows`, `brand`, `icons`, `providers`, `diff`, `original-root` and `original-render`. The plain message types set is now `globalThis[Symbol.for("pi-chassis/plainMessageTypes")]`. A package that talks to chassis through globals must update the keys.
+- **Breaking:** the session entry types are now `chassis-mode`, `chassis-plan-context` and `chassis-git`. Sessions written with the old names no longer restore their mode or their git reports.
+
+### Removed
+
+- **Breaking:** the fallbacks for the old environment variables, the migration of the old settings file, the old command aliases and the compatibility package for the old name.
+
+## [0.6.1] - 2026-10-21
+
+### Changed
+
+- Documentation only: the 0.6.0 changelog entry and `docs/status-widgets.md` no longer name the package the AWS widget moved to. No code change.
+
+## [0.6.0] - 2026-10-15
+
+### Added
+
+- `docs/status-widgets.md`: recipes for building a status widget from what you already have, an environment variable, a file another tool keeps current, a count with detail lines, a linked line, another extension's `setStatus` line, and a value that needs a command (run from a palette action, never on a timer). Each recipe was type-checked against the real API and run through the sidebar renderer. It also lists the rules that keep a status widget safe.
+
+### Removed
+
+- **Breaking:** the built-in AWS widget is gone. It moved to a separate package. Anything that relied on it must change:
+  - The sidebar and footer no longer show an AWS row unless a package supplies one.
+  - The `pi-chassis/aws` export is removed. `registerCredentialProcessResolver`, `resolveAwsContext`, `resolveRegion`, `parseAwsConfig`, `accountFromAccessKeyId`, `roleTone`, `awsExpiresIn`, `formatRemaining`, `formatAwsStatus`, `EXPIRY_SOON_MS`, `SESSION_EXPIRY_VAR` and the types `AwsContext`, `CredentialProcessCall`, `CredentialProcessResult` and `CredentialProcessResolver` have no replacement in pi-chassis. The shared registry key for credential process resolvers is no longer read.
+  - `/widgets disable aws` and an `aws` entry in `disabledWidgets` do nothing now. The entry is harmless.
+  - The event `aws-status:refresh` and the variable `PI_AWS_SESSION_EXPIRATION` are no longer read by pi-chassis. A package that registers its own `aws` widget keeps using them.
+  - The icon table loses `widgetAws` and `widgetAwsFooter`.
+  - To get the same row, write one with the recipes in `docs/status-widgets.md`.
+
+### Changed
+
+- `docs/widgets.md` now says where `onDetailClick` works: only in fullscreen mode with the split sidebar. In regular mode, and in the pop-up sidebar that stands in for the split one, clicks do not reach the widget, so anything the user must reach by clicking needs a second way, such as a palette action.
+
+## [0.5.1] - 2026-10-14
+
+### Changed
+
+- The README is now a short overview with links, and the detail lives in `docs/` (usage, git workflows, widgets, tool rows, the diff view API, branding, provider status, how the sidebar works, development). `docs/` is part of the published package, so the docs match the installed version. The README sections that other packages refer to by name moved: "Adding a widget" and "Adding a widget without depending on pi-chassis" are in `docs/widgets.md`, "Tool rows for your extension's tools" is in `docs/tool-rows.md`.
+
+## [0.5.0] - 2026-10-14
+
+### Added
+
+- Detail lines can hold links. A `detail` line may be a list of pieces, each a string or a `{ text, url }` link (the new `DetailLine` and `DetailLink` types, exported from `pi-chassis/client` and `pi-chassis/api`). chassis builds the link itself, and only from a plain https URL (no user name, whitespace or control characters, at most 2048 characters). It shows the label alone when the terminal cannot show links, when the URL is refused, or when the label is empty once cleaned. Text is still stripped of every escape sequence, so a link written into a string, or one that arrives inside a ticket summary or an incident title, never becomes a link. Until now a widget could not show a link in the sidebar at all, because chassis strips escape sequences from widget text.
+
+## [0.4.0] - 2026-10-14
+
+### Changed
+
+- **Breaking:** the package is now named **pi-chassis**. Install `npm:pi-chassis` and import `pi-chassis/client` (and the other exports). The commands are `/chassis` and `/chassis-resume-last`, the settings file is `~/.pi/agent/chassis.json`, the environment variables are `PI_CHASSIS_ICONS` and `PI_CHASSIS_STATE`, and the brand line reads `chassis X.Y.Z`.
+- **Breaking:** requires pi 1.2 (`>=1.2.0 <1.3.0`). pi 1.1.0 no longer installs cleanly. The sidebar layout, prompt bars and thinking peek were checked against pi 1.2.0. Plan mode's read-only reminder now also reaches runs another extension starts with a custom message, which pi 1.2 passes through `before_agent_start`.
+
+## [0.3.0] - 2026-10-08
+
+### Added
+
+- Tool rows for other extensions' tools: `registerToolRows(specs)` in `pi-chassis/client` (and `registerToolRows` plus `toolRowsVersion` on the shared registry on `globalThis` for a package that does not depend on pi-chassis) has chassis draw a tool's calls as one-line rows with an icon, title, description, outcome and an expanded view. Specs are `ToolRowSpec` (`icon`, `title`, `describe`, `summarize`, `expand`), exported as types from `pi-chassis/client`. Everything a spec returns is sanitized, a spec that throws falls back to the tool's own renderer, registration works in any load order and returns a function that removes it, and chassis's rows for pi's built-in tools cannot be overridden. `registerToolRows(specs, { id })` takes an optional owner id: registering again with the same id replaces that registrant's earlier rows, so a package that registers on every `session_start` or after /reload does not pile up groups. Entries need a string `title` and function `describe` and `summarize` (and `expand`, if given) or they are skipped. A spec that throws while a call's arguments or output are still arriving is retried on the next frame; one that fails on three finished calls is skipped for new calls, which then use the tool's own renderers and shell. This is a new capability, not a change to `apiVersion`: check `toolRowsVersion`.
+- `register(pi, spec, ctx?)` on the registry, and `registerWidget(pi, spec, ctx?)` in `pi-chassis/client`, take an optional `ctx`. A widget registered from inside a `session_start` handler passes the handler's `ctx` so its first `update` and its timer start at once.
+- README: how a package without a dependency on pi-chassis registers a widget (including a sidebar section whose detail lines open the full text on click) and tool rows through `globalThis` alone.
+
+### Removed
+
+- **Breaking for the old memory extension's users:** chassis no longer draws the `memory_write`, `memory_update`, `memory_forget` and `memory_search` tools with its own rows, and no longer treats the `memory-recall` message type as a plain row. A memory extension now registers its own rows (`registerToolRows`) and its message type (the shared plain message types set); until it does, those tools use pi's default rendering and `memory-recall` notices get chassis's panel and bar. The `toolMemory` icon is removed from `pi-chassis/icons`.
+
+## [0.2.1] - 2026-10-08
+
+### Changed
+
+- pi-chassis describes itself as a workbench for pi (an interface, git workflows and a widget platform) instead of an OpenCode-style TUI, in the README and the npm description. OpenCode is credited as the inspiration for the interface.
+
+## [0.2.0] - 2026-10-08
+
+### Changed
+
+- **Breaking:** the package exports (`pi-chassis/client`, `api`, `brand`, `icons`, `provider`, `aws`) now resolve to compiled JavaScript in `dist/` with type declarations, instead of the `.ts` sources. A package that depends on pi-chassis can now import it from plain `node --test` and type-check it with `tsc`; before, Node refused to strip types from files under `node_modules`. Deep imports of `pi-chassis/extensions/...` paths are not part of the API and may stop working. pi still loads chassis's own extensions from the `.ts` sources, so nothing changes for users of the TUI.
+
+## [0.1.1] - 2026-10-08
+
+### Security
+
+- Releases are published by CI with npm trusted publishing (OIDC) and carry a provenance attestation. No npm token is stored in the repository.
+
+## [0.1.0] - 2026-10-08
+
+First public release.
+
+### Added
+
+- OpenCode-style TUI for pi: home screen, right sidebar, one-line footer, prompt row with the mode and model, `ctrl+x` leader keys and a `ctrl+p` command palette.
+- Build and Plan modes. Plan mode turns off edit and write and limits bash to a read-only allow-list (a guardrail, not a sandbox).
+- Tool rows for pi's built-in tools, drawn through `pi.registerToolRenderer`, with live bash output, expandable results, diffs for edit and numbered lines for write.
+- Thinking peek, turn telemetry and a finish alert (terminal bell and window title mark).
+- Git diff view (`/diff`): changes and branch views, hunks, mouse support, and an API for other extensions (`openDiff`, `openChanges`, `addDiffAction`).
+- Git commands: `/commit` (drafts the message from the diff), `/push`, `/merge`, `/pr` (drafts the title and description, opens it with `gh` or `glab`) and `/git`. Each reports its outcome and a fresh repository status to the model on its next turn.
+- Widget API (`pi-chassis/client`) for status rows and sidebar sections, with built-in widgets for containers, AWS, MCP, TODO.md, session todos and subagents.
+- Replaceable brand layer (`pi-chassis/brand`): name, mark, colours, startup art and surface shades.
+- Plain and Nerd Font icon sets (`/chassis icons`).
+- Sanitizing of untrusted text (file contents, tool output, git and forge output, session names, widget text) before it reaches the terminal.
+
+[Unreleased]: https://github.com/one24-ai/pi-chassis/compare/v0.7.1...HEAD
+[0.7.1]: https://github.com/one24-ai/pi-chassis/compare/v0.7.0...v0.7.1
+[0.7.0]: https://github.com/one24-ai/pi-chassis/releases/tag/v0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Koncir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
+# pi-chassis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A workbench for [pi](https://pi.dev): a sidebar, a home screen, Build and Plan modes, a git diff view, git commands that draft commit messages and pull requests, and a small API for widgets, tool rows and branding. The brand (name, mark, colours, startup art) is a replaceable layer: see [Branding](docs/branding.md).
+
+Requires pi 1.2 and Node.js 22.19 or later.
+
+## Install
+
+```bash
+pi install npm:pi-chassis                        # from npm, the latest release
+pi install git:github.com/one24-ai/pi-chassis   # from git, the main branch
+pi install /path/to/pi-chassis                  # a local checkout
+```
+
+`pi update` moves to the latest release; the [changelog](CHANGELOG.md) says what changed.
+
+pi-chassis replaces pi's header, footer and editor, so it does not combine with another package that replaces any of them (pi-open-tui is one): keep only one such package in `packages`.
+
+## Documentation
+
+Using it:
+
+- [Using pi-chassis](docs/usage.md): the features in detail, keys, subagents, icons and themes
+- [Git workflows](docs/git.md): `/commit`, `/push`, `/merge`, `/pr`, `/git` and the diff view
+
+Building on it:
+
+- [Adding a widget](docs/widgets.md), with or without a dependency on pi-chassis
+- [Status widgets from what you already have](docs/status-widgets.md): recipes for an environment variable, a file, a count, a link and a palette action
+- [Tool rows for your extension's tools](docs/tool-rows.md)
+- [Diff view API](docs/diff-api.md)
+- [Branding](docs/branding.md)
+- [Provider status](docs/provider-status.md)
+
+Working on pi-chassis:
+
+- [How the sidebar works](docs/internals.md)
+- [Development](docs/development.md) and [RELEASING.md](RELEASING.md)
+
+## Versioning
+
+pi-chassis follows [Semantic Versioning](https://semver.org). The public API is:
+
+- the exports in `package.json` (`pi-chassis/client`, `api`, `brand`, `icons`, `provider`) and the types they export,
+- the slash commands, their arguments and the `ctrl+x` and `ctrl+p` keys,
+- the settings it stores in `~/.pi/agent/chassis.json`.
+
+A change that breaks one of those is a major version, a new feature is a minor version, and a fix is a patch. Before 1.0.0, a breaking change bumps the minor version instead (0.1 to 0.2). Each release supports one pi minor version, declared in `peerDependencies`; supporting a new pi minor is a minor release of pi-chassis. Every change is listed in [CHANGELOG.md](CHANGELOG.md); how a release is cut is in [RELEASING.md](RELEASING.md).
+
+## Credits
+
+The interface is inspired by [OpenCode](https://opencode.ai). The thinking peek and turn telemetry are adapted from [pi-open-tui](https://github.com/OldSuns/pi-open-tui). The plan-mode bash allowlist started from pi's plan-mode example. See `THIRD_PARTY_NOTICES`.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,30 @@
+pi-chassis includes code adapted from the following projects.
+
+== pi-open-tui (extensions/chassis/peek.ts, extensions/chassis/telemetry.ts) ==
+https://github.com/OldSuns/pi-open-tui
+
+MIT License
+
+Copyright (c) 2026 pi-open-tui contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+== pi-coding-agent plan-mode example (extensions/chassis/readonly-command.ts, the first version of the bash allow-list) ==
+https://github.com/earendil-works/pi
+License: MIT

package/dist/chassis/alert.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Finish alert: when a long run ends, or a run that has been going for a while stops to ask you
+ * something, ring the terminal bell and put a mark in the window title, so you notice from another
+ * window or tab.
+ *
+ * It uses only two terminal standards and no OS commands: BEL (0x07) and the OSC 0 title. What the
+ * terminal does with them is its own setting (a taskbar flash, a tab badge, a sound, or nothing).
+ * Runs shorter than the threshold stay quiet, and `/chassis alert off` switches it off.
+ *
+ * The setting lives in the same state file as the disabled widgets (`alert`: `{ enabled, seconds }`).
+ */
+export declare const DEFAULT_ALERT_SECONDS = 30;
+export interface AlertSettings {
+    enabled: boolean;
+    /** Runs shorter than this stay quiet. */
+    seconds: number;
+}
+export declare function defaultAlert(): AlertSettings;
+/** Settings from the state file; anything missing or malformed falls back to the default. */
+export declare function loadAlert(path?: string): AlertSettings;
+/** Save into the state file, keeping its other keys. Best effort, like the widget list. */
+export declare function saveAlert(s: AlertSettings, path?: string): void;
+/** Why the agent stopped. */
+export type AlertReason = "finished" | "failed" | "waiting";
+/**
+ * Whether to alert: on, and the run has lasted the threshold. A shorter run is one you are
+ * watching. This holds for a finish, a failure and a stop that waits for you alike.
+ */
+export declare function shouldAlert(s: AlertSettings, durationMs: number | undefined): boolean;
+/** The mark put in front of the title. */
+export declare const TITLE_MARK: Record<AlertReason, string>;
+/** Title while alerting: the mark in front of pi's own title. */
+export declare function alertTitle(reason: AlertReason, title: string): string;
+export interface AlertOutput {
+    /** Raw write to the terminal. */
+    write(data: string): void;
+    setTitle(title: string): void;
+}
+/** Ring the bell and mark the title. */
+export declare function alert(out: AlertOutput, reason: AlertReason, title: string): void;
+/**
+ * How a run ended, from the last assistant message's stop reason in an agent_end message list. An
+ * abort means you pressed esc, so you are there and nothing should ring.
+ */
+export declare function runOutcome(messages: readonly unknown[] | undefined): "finished" | "failed" | "aborted";
+/** The title pi itself sets when there is no session name: "π - <folder>". Used to clear the mark. */
+export declare function plainTitle(cwd: string, sessionName?: string): string;
+/** "off", "on", or a number of seconds ("30", "30s", "2m"); undefined when it is none of these. */
+export declare function parseAlertArg(arg: string): Partial<AlertSettings> | undefined;
+export declare function describeAlert(s: AlertSettings): string;

package/dist/chassis/alert.js

@@ -0,0 +1,107 @@
+/**
+ * Finish alert: when a long run ends, or a run that has been going for a while stops to ask you
+ * something, ring the terminal bell and put a mark in the window title, so you notice from another
+ * window or tab.
+ *
+ * It uses only two terminal standards and no OS commands: BEL (0x07) and the OSC 0 title. What the
+ * terminal does with them is its own setting (a taskbar flash, a tab badge, a sound, or nothing).
+ * Runs shorter than the threshold stay quiet, and `/chassis alert off` switches it off.
+ *
+ * The setting lives in the same state file as the disabled widgets (`alert`: `{ enabled, seconds }`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { statePath } from "./api.js";
+export const DEFAULT_ALERT_SECONDS = 30;
+const MAX_SECONDS = 24 * 60 * 60;
+const BEL = "\x07";
+export function defaultAlert() {
+    return { enabled: true, seconds: DEFAULT_ALERT_SECONDS };
+}
+/** Settings from the state file; anything missing or malformed falls back to the default. */
+export function loadAlert(path = statePath()) {
+    const out = defaultAlert();
+    try {
+        const a = JSON.parse(readFileSync(path, "utf8"))?.alert;
+        if (typeof a?.enabled === "boolean")
+            out.enabled = a.enabled;
+        if (typeof a?.seconds === "number" && Number.isFinite(a.seconds) && a.seconds >= 0 && a.seconds <= MAX_SECONDS)
+            out.seconds = a.seconds;
+    }
+    catch {
+        // no file yet, or unreadable: defaults
+    }
+    return out;
+}
+/** Save into the state file, keeping its other keys. Best effort, like the widget list. */
+export function saveAlert(s, path = statePath()) {
+    try {
+        let data = {};
+        if (existsSync(path)) {
+            try {
+                data = JSON.parse(readFileSync(path, "utf8")) ?? {};
+            }
+            catch {
+                data = {};
+            }
+        }
+        data.alert = { enabled: s.enabled, seconds: s.seconds };
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
+    }
+    catch {
+        // the in-memory setting still applies for this run
+    }
+}
+/**
+ * Whether to alert: on, and the run has lasted the threshold. A shorter run is one you are
+ * watching. This holds for a finish, a failure and a stop that waits for you alike.
+ */
+export function shouldAlert(s, durationMs) {
+    return s.enabled && durationMs !== undefined && durationMs >= s.seconds * 1000;
+}
+/** The mark put in front of the title. */
+export const TITLE_MARK = { finished: "✓", failed: "✗", waiting: "?" };
+/** Title while alerting: the mark in front of pi's own title. */
+export function alertTitle(reason, title) {
+    return `${TITLE_MARK[reason]} ${title}`;
+}
+/** Ring the bell and mark the title. */
+export function alert(out, reason, title) {
+    out.write(BEL);
+    out.setTitle(alertTitle(reason, title));
+}
+/**
+ * How a run ended, from the last assistant message's stop reason in an agent_end message list. An
+ * abort means you pressed esc, so you are there and nothing should ring.
+ */
+export function runOutcome(messages) {
+    for (let i = (messages?.length ?? 0) - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role !== "assistant")
+            continue;
+        return m.stopReason === "error" ? "failed" : m.stopReason === "aborted" ? "aborted" : "finished";
+    }
+    return "finished";
+}
+/** The title pi itself sets when there is no session name: "π - <folder>". Used to clear the mark. */
+export function plainTitle(cwd, sessionName) {
+    const folder = cwd.split(/[\\/]/).filter(Boolean).pop() ?? cwd;
+    return sessionName ? `π - ${sessionName} - ${folder}` : `π - ${folder}`;
+}
+/** "off", "on", or a number of seconds ("30", "30s", "2m"); undefined when it is none of these. */
+export function parseAlertArg(arg) {
+    const a = arg.trim().toLowerCase();
+    if (a === "on")
+        return { enabled: true };
+    if (a === "off")
+        return { enabled: false };
+    const m = a.match(/^(\d+(?:\.\d+)?)\s*(s|m)?$/);
+    if (!m)
+        return undefined;
+    const seconds = Number(m[1]) * (m[2] === "m" ? 60 : 1);
+    return seconds <= MAX_SECONDS ? { enabled: true, seconds } : undefined;
+}
+export function describeAlert(s) {
+    return s.enabled ? `finish alert on (runs over ${s.seconds}s)` : "finish alert off";
+}