pi-focus-mode 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+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.

package/README.md

@@ -0,0 +1,203 @@
+# pi-focus-mode
+
+Show timing, token, cache, cost, and tool-use statistics for each Pi exchange.
+Each run of thinking and tool calls between pieces of assistant text starts folded
+as one process line, even when it spans assistant messages or turns. The line shows
+thinking and tool counts as `◈ n` and `⚙ m`, plus total wall time, or the current
+block and its live time while streaming. In the running exchange, a tool call that
+has streamed but not yet started shows as `⚙ <tool> queued`. A call whose exchange
+settled, or was restored, without a result shows `no result` in its title and no
+live activity. At the next fold level, each block has a one-line title in stream order, with dim `├` and `└` guides under its process line and `│` continuing through rows with later siblings.
+While an exchange streams, assistant text stays visible. After it settles, an
+exchange with a process and a trailing answer folds its processes and earlier
+assistant text into one dim progress line at the first progress item. Opening that
+line shows the process lines and earlier text beneath it, grouped by dim tree guides;
+the trailing answer stays visible without a guide. Its `1 note` or `N notes` segment
+counts interim text items and is omitted when there are none. An exchange without a
+process or a trailing answer keeps its existing rows.
+Tool titles show the argument, status, duration, and result line count. Thinking
+titles show the trace's last complete sentence, or `Thinking` until one completes.
+With `summaryModel` configured, a short model headline takes its place when ready;
+the leading `≈` marks it as a summary. A failed or timed-out request returns to
+the sentence fallback, on screen and in the saved entry, even after an earlier
+model headline; it gives one warning per session.
+The headline is shortened first to make room for duration and stats.
+Titles also show elapsed time, thinking tokens and rate while streaming; a `~` marks
+token estimates when the provider has not reported reasoning usage. Settled titles
+show duration and word count. Opening a block keeps its title and shows Pi's native
+output below it, two columns beneath its tree guide; a thinking block shows Pi's full trace
+there, regardless of Pi's hide-thinking setting. Process lines, settled progress lines,
+and block titles use the active Pi theme's dim color and italic style, except the line
+selected by the transcript cursor, which uses the theme's accent color and stays
+italic. Picker text and exchange card rows use the same dim italic style; the picker
+border stays upright. Visible assistant text and opened native content keep Pi's own
+styling.
+
+Press `ctrl+alt+f` to toggle the latest process between its line and block titles.
+Press `ctrl+alt+e` to toggle the latest exchange's progress line after it settles;
+while it streams, the shortcut opens or folds all its processes. Press
+`ctrl+alt+s` to open the picker; use Up/Down and Enter to toggle an exchange,
+process, or block, and Escape to close it. The exchange row toggles settled progress
+or the streaming processes. The picker marks open items; opening a block also opens
+its process, while folding that block leaves the process open. These controls change
+only the display. In fullscreen mode, left click a process line, progress line, or
+block title to toggle it. Option+left-click a progress or process line toggles that
+row and its direct children; on a block title it behaves like a plain click. A terminal
+that swallows Option+click, for example to move the cursor, sends a plain click.
+Hovering one of these rows brightens its text and puts it
+on the theme's selection background, from the title after its tree guide to the right edge;
+opened native output is not highlighted. The highlight follows the pointer across fold rows,
+assistant text and the exchange card; it can stay on a row after the pointer
+moves straight to Pi's own rows (a user message, the editor), until the pointer
+next crosses the transcript. Terminal multiplexers that Pi runs in button-motion
+mode (tmux, screen, zellij) send no hover events, so there is no highlight there.
+
+An experimental transcript cursor is available with `cursorMode: true`. Press
+`ctrl+alt+g` to enter it, Up/Down to move through progress and process lines and the
+block titles of open processes, Enter to toggle the highlighted item, and Escape to
+return to the editor. The selected title also appears in the status line, since
+regular terminal scrollback can leave the highlighted line above the viewport.
+Fullscreen Pi exposes scrolling by line, but its extension UI does not expose the
+selected transcript row's position; the cursor therefore cannot scroll to it.
+
+An **exchange** is one uninterrupted work span from a submitted prompt until Pi has
+nothing left to do automatically. A **turn** is one model response plus the tools it
+invokes, so an exchange can contain several turns. The status line shows the current
+or most recent exchange. Exchange and session cards are summary-only and show one
+line when their content fits; at narrower widths Pi wraps the text without
+truncating its numbers. The exchange line contains its duration, finish time when
+the record has `endedAt`, and model, separated by `·`; its metrics follow the model
+in parentheses after one space, separated by `·`. It does not include an exchange
+number. The finish time uses the runtime default locale and local time zone in
+24-hour `HH:MM:SS` style, with the date when that local date is not today. Records
+saved by version 0.1.0 without `endedAt` omit the finish time. The session line keeps
+its turn and exchange counts and follows the same model and metrics layout. Metrics
+show input and output tokens, cache reads as `cache R` with `/ W written` when cache writes are
+nonzero (or `cache W written` when there are writes but no reads), waiting time only
+when nonzero, and total cost at the end even when it is `$0`. Cards omit turns,
+prompts, tools, thinking, and total-token details. Block titles carry individual
+timing and count details.
+
+Tool time is the union of tool spans, not their sum, so parallel calls are not counted
+twice. Model time is estimated as turn wall time minus tool time. Output throughput is
+calculated per turn, while cumulative cost and token fields use Pi's reported usage.
+Run `/exstats` to append a cumulative session card. Exchange entries retain block
+durations, status, counts, and headlines outside model context. A model headline
+that arrives after its exchange settles is saved in a separate, unrendered
+`exchange-stats-headline` entry holding only the block id, headline and source, and
+restore applies the latest one. On resume, reload,
+or a branch switch, the extension rebuilds fold state from the active session
+branch without sending historical thinking to the headline model. Older entries
+without block statistics still show their card; their thinking titles use `—` for
+unknown duration.
+
+## External contract
+
+Pi must emit its documented session, agent, turn, tool, and UI-prompt lifecycle events.
+Display wrappers are installed at `session_start` and released at `session_shutdown`;
+loading the extension without a session leaves Pi's component prototypes unchanged.
+Overlapping extension instances share the wrappers until the last session releases them.
+A tool row renders with the session that received its tool call id. An assistant
+message renders with the session that received a message with its timestamp; when
+several sessions did, with the one whose received thinking or tool calls match the
+message. Sessions whose messages share a timestamp and identical content, or a
+component built before any session received its message, use the latest session.
+Tool folding uses Pi's `ToolExecutionComponent.render` interface from version 0.87.1.
+Thinking folding uses `AssistantMessageComponent.updateContent` and Pi's
+`message_update` events. Its clock starts at the first thinking delta and stops
+at `thinking_end`, the first following non-thinking event, or message end,
+whichever comes first. Streamed snapshots of one assistant message must retain
+the same Pi message timestamp for the local clock to follow them.
+Assistant messages should include usage and cost fields when the provider supports
+them. Model headlines use Pi's configured provider; no separate endpoint is needed.
+
+## If the contract is unmet
+
+Missing usage fields are reported as zero for exchange totals; the extension does
+not invent exchange token or cost data. Thinking estimates are explicitly marked
+with `~`.
+Missing lifecycle events produce an incomplete or absent span. When UI status is
+unavailable, status updates are skipped. If custom-entry persistence is unavailable,
+the live status can still update and the agent turn continues. If Pi no longer
+provides the tool render interface, a single warning is shown and tool rows use
+Pi's native renderer; exchange stats continue.
+If Pi no longer provides the assistant content interface, a single warning is
+shown and thinking uses Pi's native rendering.
+
+The timings are measured locally, then saved in exchange entries. They do not
+claim provider-side queue time, exclusive model compute time, or billing beyond
+the usage object Pi received.
+
+## Compatibility
+
+Uninstall `pi-exchange-stats` before installing `pi-focus-mode`; both packages
+must not be loaded together. The published `pi-exchange-stats@0.1.0` had no
+settings or environment variables, so no settings migration is needed. Existing
+sessions remain readable through their `exchange-stats` and
+`exchange-stats-headline` entries. The `/exstats` command and `exchange` status
+key stay unchanged.
+
+## Settings
+
+The optional `focus-mode.json` file in Pi's agent directory configures
+`processKey`, `exchangeKey`, and `pickerKey`. Their defaults are `ctrl+alt+f`,
+`ctrl+alt+e`, and `ctrl+alt+s`. The experimental `cursorKey` defaults to
+`ctrl+alt+g`. Each key value must be a modified Pi key such as
+`ctrl+alt+x` or `alt+enter`; an invalid value uses its default and produces one warning.
+The matching environment variables are `PI_FOCUS_MODE_PROCESS_KEY`,
+`PI_FOCUS_MODE_EXCHANGE_KEY`, `PI_FOCUS_MODE_PICKER_KEY`, and
+`PI_FOCUS_MODE_CURSOR_KEY`. Set `cursorMode` to the boolean `true` in the same
+file, or set `PI_FOCUS_MODE_CURSOR_MODE=true`, to register the cursor shortcut.
+It is off by default. A project's `.pi/focus-mode.json` is not read for the keys
+or `cursorMode`, even in a trusted project.
+
+Set `summaryModel` to a `provider/modelId` registered in Pi's model registry.
+It is off by default. Put it in `<agentDir>/focus-mode.json`, or in a trusted
+project's `.pi/focus-mode.json`. For example:
+
+```json
+{ "summaryModel": "my-provider/my-headline-model" }
+```
+
+`PI_FOCUS_MODE_SUMMARY_MODEL` overrides the file setting. While thinking
+streams, the extension sends at most the last 1,500 trace characters after about
+400 new tokens or six seconds, and once more when the block ends. Requests use
+reasoning off and a 32 token output cap. The model call never delays the turn or
+the trace; with the setting absent or an unknown model, titles use the trace
+sentence.
+
+The summary model must honor Pi's reasoning `off` level. Set
+`thinkingLevelMap.off` in that model's Pi `models.json` entry to the provider's
+own value for disabling thinking. For a provider that uses `none`, for example:
+
+```json
+{ "thinkingLevelMap": { "off": "none" } }
+```
+
+Without it, a model may spend the 32 token cap reasoning and return no headline.
+
+For a development install, do not load this package from a path whose
+`node_modules` contains its own `@earendil-works/pi-*` packages. That path makes
+the display patch land on those private component classes rather than the classes
+used by the running Pi. Stage the built package files outside such a tree, or
+`npm pack` this package and install the tarball with
+`pi install npm:pi-focus-mode@file:/absolute/path/to/pi-focus-mode-0.1.0.tgz`.
+
+## Install and verify
+
+```sh
+pi install npm:pi-focus-mode
+```
+
+Submit a prompt that makes at least one tool call and produces thinking. While it
+streams, check that process lines update and assistant text remains visible. After Pi
+settles, check that one progress line covers the work before the final answer; open it
+to see process lines and interim text grouped beneath it with tree guides, while the
+final answer stays unmarked. Check that exchanges without a process or a trailing
+answer stay unfolded. Check that the exchange card uses one line when it fits and
+wraps without truncating numbers at narrower widths, with metrics in parentheses,
+cost last and no expanded detail. Open a process to see individual block timings
+and counts. Run `/exstats` and confirm the session card keeps its turn and exchange
+counts, with metrics in parentheses and following the same metrics rules. To check
+parallel-tool accounting, run two overlapping tools and confirm their union is not
+larger than the exchange wall time.