@pi-unipi/unipi 3.0.0-alpha.21 → 3.0.0-alpha.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +193 -158
  3. package/package.json +21 -21
  4. package/packages/ask-user/README.md +82 -39
  5. package/packages/ask-user/index.ts +17 -2
  6. package/packages/ask-user/package.json +2 -2
  7. package/packages/ask-user/tools.ts +40 -6
  8. package/packages/autocomplete/README.md +46 -21
  9. package/packages/autocomplete/package.json +1 -1
  10. package/packages/background-tasks/README.md +69 -67
  11. package/packages/background-tasks/package.json +2 -2
  12. package/packages/btw/README.md +59 -13
  13. package/packages/btw/package.json +2 -2
  14. package/packages/compactor/README.md +78 -61
  15. package/packages/compactor/package.json +3 -3
  16. package/packages/core/README.md +98 -94
  17. package/packages/core/package.json +1 -1
  18. package/packages/footer/README.md +73 -116
  19. package/packages/footer/package.json +3 -3
  20. package/packages/fusion/README.md +83 -150
  21. package/packages/fusion/package.json +4 -4
  22. package/packages/info-screen/README.md +81 -69
  23. package/packages/info-screen/package.json +2 -2
  24. package/packages/input-shortcuts/README.md +47 -47
  25. package/packages/input-shortcuts/package.json +2 -2
  26. package/packages/kanboard/README.md +98 -182
  27. package/packages/kanboard/package.json +7 -7
  28. package/packages/long-horizon/README.md +98 -16
  29. package/packages/long-horizon/package.json +2 -2
  30. package/packages/long-horizon/src/gate.ts +9 -0
  31. package/packages/mcp/README.md +74 -62
  32. package/packages/mcp/package.json +2 -2
  33. package/packages/memory/README.md +93 -118
  34. package/packages/memory/package.json +3 -3
  35. package/packages/notify/README.md +85 -120
  36. package/packages/notify/package.json +2 -2
  37. package/packages/skill-registry/README.md +78 -44
  38. package/packages/skill-registry/package.json +2 -2
  39. package/packages/subagents/README.md +77 -31
  40. package/packages/subagents/package.json +3 -3
  41. package/packages/unipi/bundled.js +1210 -1099
  42. package/packages/updater/README.md +53 -55
  43. package/packages/updater/package.json +2 -2
  44. package/packages/utility/README.md +87 -78
  45. package/packages/utility/package.json +2 -2
  46. package/packages/utility/src/index.ts +12 -4
  47. package/packages/utility/src/render/delegated.ts +3 -0
  48. package/packages/utility/src/render/harness.ts +11 -2
  49. package/packages/utility/src/render/images.ts +51 -0
  50. package/packages/utility/src/render/reply-bg.ts +30 -2
  51. package/packages/utility/src/render/simple.ts +3 -0
  52. package/packages/utility/src/render/spacing.ts +13 -1
  53. package/packages/utility/src/settings.ts +2 -2
  54. package/packages/watchdog/README.md +66 -41
  55. package/packages/watchdog/package.json +3 -3
  56. package/packages/web-api/README.md +78 -126
  57. package/packages/web-api/package.json +2 -2
  58. package/packages/workflow/README.md +80 -103
  59. package/packages/workflow/package.json +2 -2
@@ -1,147 +1,104 @@
1
- # @pi-unipi/footer
1
+ # Footer
2
2
 
3
- Persistent status bar at the bottom of the terminal. Shows live stats from all Unipi packages — compactor tokens saved, memory count, MCP status, Ralph loops, workflow state, kanboard tasks, notifications.
3
+ Show live session stats and the state of every UniPi package at the bottom of the terminal.
4
4
 
5
- Subscribes to events from every package and renders segments using Pi's `setFooter` + `setWidget` APIs. Responsive layout adjusts to terminal width, with a secondary row for narrow terminals.
5
+ `@pi-unipi/footer` · part of [UniPi](../../README.md)
6
6
 
7
- ## Glance Footer (new in 2.12)
7
+ ![Glance footer: a framed input box with the branch, model and a session stats line](../../docs/assets/screenshots/glance-footer.png)
8
8
 
9
- An experimental input surface, on by default and toggleable in `/unipi:settings` (Footer) → **Glance mode**:
9
+ ## What it does
10
10
 
11
+ - Puts a frame around the input box. This is **glance mode**, and it is on by default.
12
+ - Shows a stats line below the input. It shows turns, steps, model time and tool time. It also shows average time to first token (TTFT), tokens per second, compactions and cache hit rate.
13
+ - Shows a line above the input with counts of background tasks: running, stopped, failed and done.
14
+ - Shows a status line with segments from each package when glance mode is off. This is the **classic** footer.
15
+ - Lets you select a preset, separator, icon style and color mode, and turn each segment on or off.
16
+
17
+ ## Quick start
18
+
19
+ UniPi installs this package:
20
+
21
+ ```bash
22
+ pi install npm:@pi-unipi/unipi
11
23
  ```
12
- ╭─ 󰚩 UNIPI │ feat/footer-default-v2 │ ───────────────────────────╮
13
- │ Type your prompt here... │
14
- ╰─ 󰉋 unipi ────────────────────── 42%/1.0M │ GLM-5.3 │ thinking:high ─╯
15
- 2 turn · 20 steps | 00:12:14 · tool 00:02 | 20ms avg ttft · 120 tok/s | 90% cache hit
24
+
25
+ To install this package alone:
26
+
27
+ ```bash
28
+ pi install npm:@pi-unipi/footer
16
29
  ```
17
30
 
18
- - **Top border:** animated lolcat-gradient UNIPI brand + git branch (turns rainbow-frame animated while thinking is max/xhigh)
19
- - **Bottom border:** workspace · context %/window · model · thinking level
20
- - **Session strip:** turns/steps, wall + tool wall time, average TTFT, tok/s, cache hit % — colored per stat, honest across restarts (derived from persisted session timestamps when live hooks are unavailable; provider-reported `usage.output` anchors token counts whenever present)
21
- - **Process line (new in 2.13):** centered one-liner directly above the frame while background work is in flight — `● 3 running ● 1 stopped ● 1 failed ● 2 done` — green ● running, yellow ● stopped (killed), red ● failed, gray ● done. Covers every task type (shell jobs, delegates, fusion workflows) via direct registry reads; zero-count buckets are omitted and the line hides when idle. Counts reset per session.
22
- - The classic segment status line is suppressed while glance mode is on; toggle it back for the classic footer
31
+ The footer starts with the session. Open `/unipi:settings` → **Footer** to change it.
23
32
 
24
33
  ## Commands
25
34
 
26
- | Command | Description |
27
- |---------|-------------|
28
- | `/unipi:footer` | Toggle footer on/off |
29
- | `/unipi:footer on` / `/unipi:footer off` | Enable/disable explicitly |
30
- | `/unipi:settings` | Hub — preset, separator, zone separator, icon style, glance mode, per-segment toggles (Footer group) |
31
- | `/unipi:footer-help` | Show footer segment guide |
35
+ | Command | What it does |
36
+ |---|---|
37
+ | `/unipi:footer` | Turns the footer on or off. |
38
+ | `/unipi:footer on` | Turns the footer on. |
39
+ | `/unipi:footer off` | Turns the footer off. |
40
+ | `/unipi:footer-help` | Shows each active segment with its icon, label and description. |
32
41
 
33
- ## Special Triggers
42
+ ## The glance frame
34
43
 
35
- Footer subscribes to events from every Unipi package:
44
+ The glance frame has three parts:
36
45
 
37
- | Group | Events | Segments |
38
- |-------|--------|----------|
39
- | core | Pi SDK | model, thinking, path, git, context_pct, cost, tokens, session |
40
- | compactor | Pi session data | compactions — `cmp 4× 39k→13k · 3m` (count, tokens before → after, time since the last; hidden until the first) |
41
- | memory | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` | project_count, total_count, consolidations |
42
- | mcp | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` | servers_total, servers_active, tools_total |
43
- | ralph | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` | active_loops, total_iterations, loop_status |
44
- | workflow | `WORKFLOW_START`/`END` | current_command, sandbox_level, command_duration |
45
- | kanboard | Direct registry read | docs_count, tasks_done, tasks_total, task_pct |
46
- | notify | `NOTIFICATION_SENT` | platforms_enabled, last_sent |
46
+ - **Top border.** The UNIPI brand, the long-horizon mode, the git branch, and the plan and permission mode. The brand shows a moving rainbow. The frame also shows the rainbow when the thinking level is `xhigh` or `max`.
47
+ - **Bottom border.** The workspace name, context use and window size, the model and the thinking level. With a [Fusion](../fusion/README.md) pair, it shows the lead and the sidekick. It also shows Kanboard claims.
48
+ - **Stats line.** The line below the input. A part stays hidden until it has data. For example, compactions show only after the first compaction.
47
49
 
48
- Footer works even if packages load after it — late-arriving events update the cache.
50
+ The background-task line reads the [Background Tasks](../background-tasks/README.md) registry. It shows nothing when no task exists.
51
+
52
+ Set **Glance mode** to off to get the classic status line.
49
53
 
50
54
  ## Presets
51
55
 
52
- | Preset | Description |
53
- |--------|-------------|
54
- | `default` | Glance-era: UNIPI brand, model, thinking, directory, git \| context/tokens, tps, cost, clock |
55
- | `classic` | The pre-2.12 balanced layout: model, api, tools, git \| tps, context, cost + compactor + memory + ralph |
56
- | `minimal` | Essentials only: path, git, context |
57
- | `compact` | Core + key stats: model, git, cost, context |
58
- | `full` | Everything from all groups |
59
- | `ascii` | Core segments with ASCII icons |
60
-
61
- ## Segment Groups
62
-
63
- | Group | Default | Data Source |
64
- |-------|---------|-------------|
65
- | **core** | ON | Pi SDK (ctx.sessionManager, footerData) |
66
- | **compactor** | ON | Live Pi session data; last-compaction event |
67
- | **memory** | ON | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` events |
68
- | **mcp** | ON | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` events |
69
- | **ralph** | ON | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` events |
70
- | **workflow** | ON | `WORKFLOW_START`/`END` events |
71
- | **kanboard** | ON | Kanboard registry (direct read) |
72
- | **notify** | OFF | `NOTIFICATION_SENT` event |
73
- | **status_ext** | ON | `footerData.getExtensionStatuses()` |
74
-
75
- ## Configurables
76
-
77
- Settings in `~/.pi/agent/settings.json` under `unipi.footer`:
78
-
79
- ```json
80
- {
81
- "unipi": {
82
- "footer": {
83
- "enabled": true,
84
- "preset": "default",
85
- "glanceMode": true,
86
- "separator": "powerline-thin",
87
- "iconStyle": "nerd",
88
- "colorMode": "auto",
89
- "groups": {
90
- "compactor": {
91
- "show": true,
92
- "segments": {
93
- "compactions": true
94
- }
95
- }
96
- }
97
- }
98
- }
99
- }
100
- ```
56
+ A preset selects the segments of the classic status line.
101
57
 
102
- ### Separator Styles
58
+ | Preset | Segments |
59
+ |---|---|
60
+ | `default` | brand, mode, model, directory, git, context, compactions, tokens, TPS, cost, clock, duration |
61
+ | `classic` | mode, model, API state, tool count, git, TPS, context, cost, compactions, memory, command, loop status, extensions |
62
+ | `minimal` | mode, model, git, context, clock |
63
+ | `compact` | mode, model, git, TPS, context, cost, clock, duration |
64
+ | `full` | all groups, with a second row |
65
+ | `ascii` | the same segments as `compact` |
103
66
 
104
- | Style | Look |
105
- |-------|------|
106
- | `powerline` | Thick powerline arrows |
107
- | `powerline-thin` | Thin powerline arrows (default) |
108
- | `slash` | / |
109
- | `pipe` | \| |
110
- | `dot` | Middle dot |
111
- | `ascii` | > < |
67
+ The hub list also shows `dense`, `devops` and `zen`. These names have no preset definition, so the footer uses `default` for them. To select `compact`, `full` or `ascii`, edit the settings file.
112
68
 
113
- ### Icon Styles
69
+ ## Settings
114
70
 
115
- | Style | Description |
116
- |-------|-------------|
117
- | `nerd` | Nerd Font glyphs (auto-detected) |
118
- | `emoji` | Unicode symbols (works on most terminals) |
119
- | `text` | Plain text labels (works everywhere). Glance frame drops the robot glyph: `UNIPI │ branch:main`, `workspace:unipi` |
71
+ Open `/unipi:settings` → **Footer**. The file is `~/.unipi/config/footer/config.json`. A project file at `.unipi/config/footer/config.json` overrides it.
120
72
 
121
- When `iconStyle` is not set, footer auto-detects Nerd Font support and defaults to `nerd` if available, `emoji` otherwise.
73
+ | Key | Default | What it does |
74
+ |---|---|---|
75
+ | `enabled` | `true` | Turns the footer on or off. |
76
+ | `glanceMode` | `true` | Uses the glance frame around the input. |
77
+ | `preset` | `default` | Selects the segments of the classic status line. |
78
+ | `showFullLabels` | `false` | Shows full labels in place of short labels. |
79
+ | `separator` | `powerline-thin` | Segment divider: `powerline`, `powerline-thin`, `slash`, `pipe`, `dot`, `ascii`. |
80
+ | `zoneSeparator` | `│` | Divider between the left, center and right zones. |
81
+ | `iconStyle` | `nerd` | Icon set: `nerd` (needs a Nerd Font), `emoji` or `text`. |
82
+ | `colorMode` | `auto` | `auto`, `truecolor`, `256` or `none`. |
83
+ | `groups.<group>.show` | `true` (`notify`: `false`) | Shows or hides a segment group. |
84
+ | `groups.<group>.segments.<id>` | per segment | Shows or hides one segment. |
122
85
 
123
- ### Color Mode
86
+ `colorMode: auto` uses 24-bit color where the terminal supports it. It uses 256 colors in terminals such as Apple Terminal. It uses no color when the `NO_COLOR` environment variable exists.
124
87
 
125
- | Mode | Description |
126
- |------|-------------|
127
- | `auto` | Detect terminal support from environment (default) |
128
- | `truecolor` | Force 24-bit ANSI color |
129
- | `256` | Force xterm-256 color fallback |
130
- | `none` | Disable footer color escapes |
88
+ The hub **Color mode** list shows `mono`. The footer does not know this value and uses `auto`. Use `none` in the file to turn off color.
131
89
 
132
- `auto` uses truecolor where supported and downgrades to xterm-256 colors for terminals such as Apple Terminal that do not reliably render 24-bit color escapes.
90
+ For the full list of segments and icons, refer to [Footer customization](../../FOOTER_CUSTOMIZATION.md).
133
91
 
134
- ### Responsive Layout
92
+ ## How it works
135
93
 
136
- ```
137
- Wide terminal (>120 cols):
138
- model | thinking | path | git | context | compactions | cost | project_count
94
+ The footer listens to UniPi events on the [event bus](../../docs/architecture/event-bus.md). Examples are `MEMORY_STORED`, `MCP_SERVER_STARTED`, `RALPH_LOOP_START`, `WORKFLOW_START`, `COMPACTOR_COMPACTED` and `NOTIFICATION_SENT`. It keeps the last data of each event. Thus a package that loads after the footer still shows its data.
139
95
 
140
- Narrow terminal (<120 cols):
141
- Row 1: model | thinking | path | git | context | cost
142
- Row 2: compactions | project_count | ralph | workflow
143
- ```
96
+ Some segments read data directly: the Pi session, the Kanboard registry and the Info Screen cache. The footer draws again each second.
97
+
98
+ The classic status line puts segments that do not fit into a second row.
144
99
 
145
- ## License
100
+ ## See also
146
101
 
147
- MIT
102
+ - [Footer customization](../../FOOTER_CUSTOMIZATION.md)
103
+ - [Info Screen](../info-screen/README.md)
104
+ - [Settings reference](../../docs/reference/settings.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/footer",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -32,8 +32,8 @@
32
32
  "access": "public"
33
33
  },
34
34
  "dependencies": {
35
- "@pi-unipi/core": "3.0.0-alpha.21",
36
- "@pi-unipi/background-tasks": "3.0.0-alpha.21"
35
+ "@pi-unipi/core": "3.0.0-alpha.22",
36
+ "@pi-unipi/background-tasks": "3.0.0-alpha.22"
37
37
  },
38
38
  "peerDependencies": {
39
39
  "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -1,165 +1,98 @@
1
- # @pi-unipi/fusion
1
+ # Fusion
2
2
 
3
- Local Fusion for UniPi: a Devin-inspired lead + persistent sidekick pair, a
4
- curated model preset, and a keyboard-first picker (`/unipi:model`). It uses
5
- pi's extension and RPC APIs natively.
3
+ Fusion pairs a strong lead model with a lower-cost sidekick model, so the lead
4
+ plans and the sidekick does the routine work.
6
5
 
7
- ## `/unipi:model` — the picker
6
+ `@pi-unipi/fusion` · part of [UniPi](../../README.md)
8
7
 
9
- ```
10
- ╭ Model ───────────────────────────────────────────────────────────────╮
11
- │/ Type to search │
12
- │───────────────────────────────────────────────────────────────────────│
13
- │❭ Fusion ← ▰▰▰▱▱ → Medium Lead Fable… ▾ │
14
- │· GLM-5.3 Flash ✱ ▰▰▰▰▰ Max │
15
- │· openrouter · deepseek/deepseek-v4.1-flash ▰▰▱▱▱ High │
16
- │ ↓ more below │
17
- │ │
18
- │ ━━━━━●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
19
- │ Input Cached input Output Sidekick input │
20
- │ $10 / 1M $0.25 / 1M $50 / 1M $0.2 / 1M │
21
- │ Sidekick cached input Sidekick output │
22
- │ $0.02 / 1M $1.2 / 1M │
23
- │ Model key openrouter/deepseek/deepseek-v4.1-flash │
24
- │ │
25
- │ ✱ New ✱ Promotion ✱ Beta · Pairs frontier intelligence with cost-efficient execution │
26
- │↑↓ select · tab lead · ←→ lead effort · space → side · ↵ confirm · esc │
27
- ╰───────────────────────────────────────────────────────────────────────╯
28
- ```
8
+ ## What it does
29
9
 
30
- - **Row order**: the active selection pinned first, then the Fusion row (when a
31
- pair is configured), then recent (≤5, MRU), then the preset models, then
32
- **every other available model** — the catalogue is never hidden; the preset
33
- only controls ordering. When a single model is selected its row lights up
34
- with `✓`; when Fusion is selected the selection lives on the Fusion row and
35
- plain rows stay unmarked.
36
- - **`←`/`→`** steps the highlighted row's effort (pi thinking level:
37
- off → minimal → low → medium → high → xhigh → max) and it is **remembered per
38
- model**. The five-cell bar fills with `▰` and uses `▱` for remaining levels.
39
- The Fusion row keeps its own lead/sidekick efforts, so adjusting Fusion never
40
- rewrites a model's standalone level.
41
- - **`tab`** on the Fusion row cycles focus: effort → lead → sidekick
42
- (`shift+tab` reverses). Focused columns open an inline dropdown over the
43
- preset lists; `↵` applies, `esc` collapses.
44
- - **`space`** on the Fusion row toggles which side `←`/`→` adjusts: lead
45
- effort (default) ↔ sidekick effort. The row shows both levels (`Lead … ▸High`,
46
- `Sidekick … Low` — `▸` marks the side `←`/`→` moves) and the hint line names
47
- the target. A changed sidekick effort reaches a running sidekick over rpc
48
- (`set_thinking_level`) and lands in the spawn args for the next process.
49
- - **Price panel**: the highlighted model's blended price is marked on a
50
- logarithmic red→orange→yellow→green→cyan→blue→violet slider. Fusion shows
51
- `Input`, `Cached input`, `Output`, `Sidekick input`, `Sidekick cached input`,
52
- and `Sidekick output`, and the exact registry key of the highlighted row is
53
- spelled out (`Model key openrouter/deepseek/deepseek-v4.1-flash`; both the
54
- lead and sidekick keys on the Fusion row).
55
- - **Name column & provider**: the name column sizes itself to the widest row
56
- label (minimum 24 columns) up to the terminal width, and the effort control
57
- stays right-anchored — so wide terminals show full names. A row only gets a
58
- dim `provider · ` prefix when its display name is ambiguous: it contains a
59
- `/` (`deepseek/deepseek-v4.1-flash` reads like a key) or the same friendly
60
- name is offered by more than one provider. Unique names stay clean, and the
61
- prefix is never truncated.
62
- - **Confirm** applies: `pi.setModel`, `pi.setThinkingLevel(effort)`, updates
63
- MRU + persisted active selection, and shows `Fusion · Lead ◆ Sidekick` in
64
- the footer. Switching the model through pi's own `/model`/Ctrl+P drops
65
- Fusion mode.
66
- - Because pi intercepts `/model` inside its editor before extensions run, the
67
- command cannot be replaced — instead typing `/model` pins `/unipi:model`
68
- as the **first autocomplete suggestion**.
69
- - Fast Mode is not implemented because pi has no equivalent capability.
70
-
71
- Hand-edited preset badge metadata renders `✱` as New, Promotion, or Beta:
10
+ - Gives `/unipi:model`, a keyboard model picker. It shows all available models,
11
+ their prices and a thinking level for each model.
12
+ - Lets you select one model, or a Fusion pair of a lead and a sidekick.
13
+ - Runs one persistent sidekick for each lead session. The sidekick is a child Pi
14
+ process. Its context and shells stay between handoffs.
15
+ - Tells the lead to give work to the sidekick. In each turn, the first direct
16
+ `edit` or `write` of the lead gets a reminder. Each 4 non-trivial `bash`
17
+ calls of the lead also get a reminder.
18
+ - Shows the estimated savings of the sidekick in `/unipi:fusion-stats`.
72
19
 
73
- ```json
74
- {"badges": {"provider/model": "new"}}
75
- ```
20
+ ## Quick start
76
21
 
77
- ## `/unipi:settings → Fusion → "Edit fusion presets…"` — curation
22
+ 1. Install UniPi: `pi install npm:@pi-unipi/unipi`. You can also install this
23
+ package alone: `pi install npm:@pi-unipi/fusion`.
24
+ 2. Open `/unipi:settings`. Select "Edit fusion presets…". Mark the lead and
25
+ sidekick models.
26
+ 3. Type `/unipi:model`. Select the Fusion row. Push `Enter`.
27
+ 4. Give the agent a task. The lead calls the `sidekick` tool.
78
28
 
79
- Two-column checklist over every available model:
29
+ ## Commands
80
30
 
81
- ```
82
- ╭ Fusion preset ───────────────────────────────────────────────────────╮
83
- │Fusion preset · 2 lead · 2 sidekick · writes to global │
84
- │Search: (type to filter) │
85
- │ L S model │
86
- │ › [x] [ ] provider/lead │
87
- │ [ ] [x] provider/sidekick │
88
- │↑↓ select · ←→ column · space toggle sidekick · Enter save · esc cancel │
89
- ╰───────────────────────────────────────────────────────────────────────╯
90
- ```
31
+ | Command | What it does |
32
+ |---|---|
33
+ | `/unipi:model` | Opens the model picker. When you type `/model`, the picker is the first suggestion. |
34
+ | `/unipi:fusion-stats` | Shows sidekick tokens, costs, savings, handoffs and runtime state. |
35
+
36
+ ## Picker keys
37
+
38
+ | Key | What it does |
39
+ |---|---|
40
+ | Up, Down | Moves the selection. |
41
+ | Typing | Filters the models. |
42
+ | Left, Right | Changes the thinking level of the selected row. Fusion keeps the level for each model. |
43
+ | `Tab`, `Shift+Tab` | On the Fusion row, moves the focus: effort, lead, sidekick. |
44
+ | `Space` | On the Fusion row, selects lead effort or sidekick effort. |
45
+ | `Enter` | Applies the selection. |
46
+ | `Alt+Enter` | Saves the selected row as the startup model. |
47
+ | `Esc` | Closes the picker. |
48
+
49
+ If you change the model with Pi's own `/model` or `Ctrl+P`, Fusion mode stops.
50
+
51
+ ## Agent tools
91
52
 
92
- - `←`/`→` (or `tab`) switches the L/S column, `space` toggles membership,
93
- `Enter` saves & closes, `esc` cancels, and typing filters. Selected models
94
- float to the top so the curated set is always visible.
95
- - Defaults are not edited here: confirming a Fusion pair in `/unipi:model`
96
- records it as the preset default.
97
-
98
- Any model key in the registry is allowed — there is no OAuth/subscription gate.
99
-
100
- ## Persistent sidekick
101
-
102
- Confirming a Fusion pair selects the lead for the session. The `sidekick` tool
103
- runs one lazy-spawned child pi per lead session; its session file is persisted
104
- at `~/.unipi/state/fusion/sidekick/<lead-session-id>.jsonl`. Context and shells
105
- persist across handoffs. The sidekick's context compacts independently of the
106
- lead's (it is its own pi session). `sidekick({message, block:true})` waits by
107
- default; `block:false` returns immediately and delivers a
108
- `<subagent_completion_notification>`. Calling it while busy steers the same
109
- handoff. A handoff whose lead turn has ended — started with `block:false`,
110
- abandoned by a user message, or timed out — still wakes the lead with that same
111
- completion notification when its report lands, exactly once. Background tasks
112
- keep that handoff open through their completion
113
- notification and any follow-up turn, so the report is not released at an
114
- intermediate checkpoint. If a prompt arrives while the child is processing,
115
- Fusion retries it once with pi's `followUp` streaming behavior. Sidekick work
116
- renders as ordinary tool activity — handoff ids, `agent_id`, and
117
- `read_subagent` protocol text never reach the terminal. Sidekick steps draw in
118
- the active render style — mcode rows in simple, `◆` + guttered output in
119
- advanced, pi's own finished-call card (its exported `ToolExecutionComponent` +
120
- per-tool defs) in regular — each line marked as sidekick-origin by a `▏` rail
121
- on the custom-message background. Consecutive steps join into one rail block
122
- with no blank separator; in simple mode a run of tool steps draws the same
123
- `├…├…└` tree the lead's tools get, and prose steps stay `●`-anchored inside
124
- the block. While the sidekick works and the lead's turn is over, an animated
125
- `sidekick working` line above the editor shows the live tool count and elapsed
126
- time until the report lands.
127
- `read_subagent({agent_id?, block?, timeout?})` reads or waits for a handoff.
128
-
129
- The child receives `UNIPI_FUSION_CHILD=1` and `UNIPI_SUBAGENT_CHILD=1`; the
130
- Fusion extension guard prevents child processes from registering Fusion tools,
131
- commands, or lead policy.
132
-
133
- The lead gets the persistent delegation policy through `before_agent_start`,
134
- and the first direct `edit`/`write` receives a one-time delegation nudge.
135
- `/unipi:fusion-stats` reports sidekick tokens, costs at sidekick and lead
136
- rates, estimated savings, handoff count, and runtime state. The footer shows
137
- savings above `$0.005`.
138
-
139
- ## Storage
53
+ | Tool | What it does |
54
+ |---|---|
55
+ | `sidekick` | Gives a message to the sidekick. `block: true` (default) waits for the report. `block: false` returns now. The report comes later as a completion notice. |
56
+ | `read_subagent` | Reads or waits for a sidekick handoff. |
57
+
58
+ A call to `sidekick` while the sidekick works sends the message as an
59
+ interrupt. It does not start a second sidekick.
60
+
61
+ ## Settings
62
+
63
+ Namespace `fusion`. Open it with `/unipi:settings`.
64
+
65
+ | Key | Default | What it does |
66
+ |---|---|---|
67
+ | `startup.model` | empty | Model that Pi opens with. Empty uses Pi's default. Global only. |
68
+ | `startup.thinking` | not set | Thinking level that Pi opens with. Global only. |
69
+ | `default.lead` | empty | Lead model when you confirm the Fusion row with no change. |
70
+ | `default.sidekick` | empty | Sidekick model for the same case. |
71
+
72
+ The preset file holds the model lists, levels, recent models and badges:
73
+
74
+ - Global: `~/.unipi/config/fusion/preset.json`
75
+ - Project: `<project>/.unipi/fusion-preset.json`. Its lists replace the global
76
+ lists. Its objects merge with the global objects.
77
+
78
+ Add a `prices` object to the preset file when a provider gives no prices:
140
79
 
141
80
  ```json
142
- // ~/.unipi/config/fusion/preset.json (global)
143
- // <cwd>/.unipi/fusion-preset.json (project override; lists replace, objects merge)
144
- {
145
- "schema_version": 1,
146
- "lead": ["provider/lead"],
147
- "sidekick": ["provider/sidekick"],
148
- "default": {"lead": "provider/lead", "sidekick": "provider/sidekick"},
149
- "effort": {"provider/sidekick": "high"},
150
- "badges": {"provider/sidekick": "new"},
151
- "prices": {"provider/sidekick": {"input": 0.2, "cachedInput": 0.02, "output": 1.2}},
152
- "recent": ["provider/lead"],
153
- "active": {"kind": "fusion", "lead": "provider/lead", "sidekick": "provider/sidekick"}
154
- }
81
+ {"prices": {"provider/model": {"input": 0.2, "cachedInput": 0.02, "output": 1.2}}}
155
82
  ```
156
83
 
157
- `prices` is an optional manual override for models whose provider reports no pricing.
84
+ ## How it works
85
+
86
+ The sidekick session file is
87
+ `~/.unipi/workspace/<id>/sessions/<sid>/fusion/sidekick/<lead-session-id>.jsonl`.
88
+ The sidekick compacts its own context. The child gets `UNIPI_FUSION_CHILD=1` and
89
+ `UNIPI_SUBAGENT_CHILD=1`, so it does not load Fusion tools or commands.
90
+
91
+ Read [Delegation](../../docs/architecture/delegation.md) for the lead and
92
+ sidekick flow.
158
93
 
159
- ## Status
94
+ ## See also
160
95
 
161
- - [x] Preset store, project layering, curation UI, autocomplete boost
162
- - [x] Picker effort bars, price slider, price panel, badges, legend
163
- - [x] Persistent sidekick runtime, blocking/non-blocking tools, steering,
164
- progress, completion card, session isolation
165
- - [x] Lead policy, first-edit nudge, savings estimate, footer and stats command
96
+ - [Subagents](../subagents/README.md)
97
+ - [Prefix cache](../../docs/architecture/prefix-cache.md)
98
+ - [Commands reference](../../docs/reference/commands.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/fusion",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Devin-style model picker, fusion presets (lead + sidekick), and Local Fusion runtime for UniPi",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",
@@ -32,9 +32,9 @@
32
32
  "access": "public"
33
33
  },
34
34
  "dependencies": {
35
- "@pi-unipi/core": "3.0.0-alpha.21",
36
- "@pi-unipi/subagents": "3.0.0-alpha.21",
37
- "@pi-unipi/utility": "3.0.0-alpha.21"
35
+ "@pi-unipi/core": "3.0.0-alpha.22",
36
+ "@pi-unipi/subagents": "3.0.0-alpha.22",
37
+ "@pi-unipi/utility": "3.0.0-alpha.22"
38
38
  },
39
39
  "peerDependencies": {
40
40
  "@earendil-works/pi-ai": "^0.87.1",