@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,30 +1,89 @@
1
- # @pi-unipi/info-screen
1
+ # Info Screen
2
2
 
3
- Dashboard overlay that shows what's running. Displays module status, registered tools, custom data groups, and load times in a tabbed interface.
3
+ See the modules, tools and extensions that Pi loads, and your token use, in one dashboard.
4
4
 
5
- Every Unipi module registers itself via `MODULE_READY` events. Info-screen picks these up and builds a live dashboard. Other packages add their own data groups — ralph shows active loops, memory shows counts, compactor shows token savings.
5
+ `@pi-unipi/info-screen` · part of [UniPi](../../README.md)
6
+
7
+ ## What it does
8
+
9
+ - Opens a dashboard overlay with one tab for each data group.
10
+ - Shows five core groups: **Overview**, **Usage**, **Tools**, **Extensions** and **Skills**.
11
+ - Shows groups from other packages, for example MCP, Memory, Compactor, Web API, Updater and Input Shortcuts.
12
+ - Opens at startup and closes after 2 seconds by default.
13
+ - Opens at once with cached data. Each group then loads its new data in the background.
14
+
15
+ ## Quick start
16
+
17
+ UniPi installs this package:
18
+
19
+ ```bash
20
+ pi install npm:@pi-unipi/unipi
21
+ ```
22
+
23
+ To install this package alone:
24
+
25
+ ```bash
26
+ pi install npm:@pi-unipi/info-screen
27
+ ```
28
+
29
+ Run `/unipi:info` to open the dashboard.
6
30
 
7
31
  ## Commands
8
32
 
9
- | Command | Description |
10
- |---------|-------------|
11
- | `/unipi:info` | Show info screen dashboard |
12
- | `/unipi:settings` | Configure info display (groups, stats, visibility — Info Screen group) |
33
+ | Command | What it does |
34
+ |---|---|
35
+ | `/unipi:info` | Opens the dashboard. |
13
36
 
14
- ## Special Triggers
37
+ ## Dashboard keys
15
38
 
16
- Info-screen listens for `MODULE_READY` events from `@pi-unipi/core`. When a module loads, info-screen adds it to the modules group automatically. No registration needed for basic module tracking.
39
+ | Key | What it does |
40
+ |---|---|
41
+ | `←` / `→` or `h` / `l` | Goes to the previous or next tab. |
42
+ | `↑` / `↓` or `k` / `j` | Scrolls the tab. |
43
+ | `g` / `G` | Goes to the top or the bottom. |
44
+ | `r` | Loads the active group again. |
45
+ | `R` | Loads all groups again. |
46
+ | `q` / `Esc` | Closes the dashboard. |
17
47
 
18
- Packages that want custom data groups use the registry API:
48
+ The startup dashboard does not take keyboard input. You can type your first prompt while it shows. It closes after `bootTimeoutMs`. If another overlay opens on top of it, it waits for that overlay to close.
19
49
 
20
- ```typescript
21
- import { infoRegistry } from "@pi-unipi/info-screen";
50
+ ## Core groups
51
+
52
+ | Group | What it shows |
53
+ |---|---|
54
+ | Overview | Pi version, working directory, active modules, session uptime and total load time. |
55
+ | Usage | Tokens today, this week and this month. Cost today and for all time. Top model for each period. Session count. |
56
+ | Tools | Total tools, built-in tools and registered tools. |
57
+ | Extensions | Loaded Pi extensions. |
58
+ | Skills | Loaded skills. |
59
+
60
+ The Usage group reads the session files in `~/.pi/agent/sessions/`.
61
+
62
+ ## Settings
63
+
64
+ Open `/unipi:settings` → **Info Screen**. The file is `~/.unipi/config/info-screen/config.json`.
22
65
 
23
- infoRegistry.registerGroup({
66
+ | Key | Default | What it does |
67
+ |---|---|---|
68
+ | `bootMode` | `auto-close` | `on` shows the dashboard at startup until you close it. `auto-close` closes it after `bootTimeoutMs`. `off` does not show it. |
69
+ | `bootTimeoutMs` | `2000` | Time before the startup dashboard closes, in milliseconds. |
70
+ | `groups.<id>.show` | `true` | Shows or hides a group. |
71
+ | `groups.<id>.stats.<stat>` | `true` | Shows or hides one stat in a group. |
72
+
73
+ The startup dashboard opens only when Pi starts. It does not open when you resume or start a session.
74
+
75
+ The hub also has a **Group order** page that writes `groupOrder`. In this version, the dashboard does not read `groupOrder`. The groups use their `priority` order.
76
+
77
+ ## Add a group from a package
78
+
79
+ A package can add its own tab. Use the registry on `globalThis.__unipi_info_registry`, or import `infoRegistry` from `@pi-unipi/info-screen`.
80
+
81
+ ```typescript
82
+ globalThis.__unipi_info_registry?.registerGroup({
24
83
  id: "my-module",
25
84
  name: "My Module",
26
85
  icon: "📦",
27
- priority: 60,
86
+ priority: 60, // lower numbers come first
28
87
  config: {
29
88
  showByDefault: true,
30
89
  stats: [
@@ -39,63 +98,16 @@ infoRegistry.registerGroup({
39
98
  });
40
99
  ```
41
100
 
42
- The footer package reads info-screen data for its extension status segment.
43
-
44
- ## Registry API
101
+ The registry has these methods: `registerGroup`, `getAllGroups`, `getGroup`, `getCachedData`, `getGroupData`, `refreshGroup`, `refreshAll`, `subscribeAll`, `getVisibleStats` and `invalidateCache`.
45
102
 
46
- | Method | Description |
47
- |--------|-------------|
48
- | `registerGroup(group)` | Register an info group |
49
- | `unregisterGroup(id)` | Remove a group |
50
- | `getGroups()` | Get visible groups (sorted by priority) |
51
- | `getAllGroups()` | Get all groups (including hidden) |
52
- | `getGroupData(id)` | Get data for a group (cached) |
53
- | `updateGroupData(id, data)` | Manually update group data |
54
- | `getVisibleStats(id)` | Get enabled stats for a group |
55
- | `invalidateCache(id)` | Invalidate cached data |
103
+ ## How it works
56
104
 
57
- The registry is a singleton, also available globally via `globalThis.__unipi_info_registry`.
58
-
59
- ### Load Tracking
60
-
61
- ```typescript
62
- import { startLoadTracking, recordLoadTime, finishLoadTracking, recordModuleStart } from "@pi-unipi/info-screen";
63
-
64
- startLoadTracking();
65
- recordModuleStart("@pi-unipi/memory");
66
- // ... module loads ...
67
- recordLoadTime("@pi-unipi/memory", "module", 150);
68
- finishLoadTracking();
69
- ```
70
-
71
- ## Configurables
72
-
73
- Settings in pi `settings.json`:
74
-
75
- ```json
76
- {
77
- "unipi": {
78
- "infoScreen": {
79
- "bootMode": "auto-close",
80
- "bootTimeoutMs": 2000,
81
- "groups": {
82
- "modules": { "show": true },
83
- "ralph": { "show": true },
84
- "memory": { "show": false }
85
- },
86
- "groupOrder": ["modules", "ralph", "subagents"]
87
- }
88
- }
89
- }
90
- ```
105
+ Each UniPi module emits `MODULE_READY` on the [event bus](../../docs/architecture/event-bus.md) when it loads. The Info Screen collects these events for 150 ms and then updates the Overview and Tools groups one time. It loads data only while the dashboard shows.
91
106
 
92
- | Setting | Default | What It Does |
93
- |---------|---------|--------------|
94
- | `bootMode` | `"auto-close"` | `"on"` keeps the dashboard up until dismissed, `"auto-close"` closes it after `bootTimeoutMs`, `"off"` never shows it |
95
- | `bootTimeoutMs` | 2000 | Auto-close delay, in ms. Any keypress cancels it. Ignored unless `bootMode` is `"auto-close"` |
96
- | `groups.{id}.show` | true | Toggle group visibility |
97
- | `groupOrder` | priority sort | Custom group ordering |
107
+ The [Footer](../footer/README.md) reads the cached Memory group data from this registry.
98
108
 
99
- ## License
109
+ ## See also
100
110
 
101
- MIT
111
+ - [Footer](../footer/README.md)
112
+ - [Event bus](../../docs/architecture/event-bus.md)
113
+ - [Settings reference](../../docs/reference/settings.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/info-screen",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Dashboard and module registry for Unipi — configurable info overlay with tabbed groups",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -32,7 +32,7 @@
32
32
  "access": "public"
33
33
  },
34
34
  "dependencies": {
35
- "@pi-unipi/core": "3.0.0-alpha.21"
35
+ "@pi-unipi/core": "3.0.0-alpha.22"
36
36
  },
37
37
  "peerDependencies": {
38
38
  "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -1,67 +1,67 @@
1
- # @pi-unipi/input-shortcuts
1
+ # Input Shortcuts
2
2
 
3
- Keyboard shortcuts for Pi's input box. Stash and restore text, undo/redo, copy the last response, push the editor text to the kanboard backlog, and tab insertion — all via a vim-style chord overlay triggered by `ALT+S`.
3
+ Input Shortcuts adds editor keys to stash text, undo edits, copy the last reply and capture a kanboard task.
4
4
 
5
- Press `ALT+S`, a small overlay appears with key hints. Press a key, the action runs. The overlay closes automatically after selecting an action, on `ESC`, or on an unknown key.
5
+ `@pi-unipi/input-shortcuts` · part of [UniPi](../../README.md)
6
6
 
7
- ## Shortcuts
8
-
9
- | Chord | Action | Description |
10
- |-------|--------|-------------|
11
- | `ALT+S → S` | Stash/Restore | Save input to the stash register, or restore it |
12
- | `ALT+S → U` | Undo | Step back through editor checkpoints |
13
- | `ALT+S → R` | Redo | Step forward again (an edit invalidates the redo) |
14
- | `ALT+S → A` | Append Stash | Append the stash text to the input (stash kept) |
15
- | `ALT+S → Y` | Copy Last Response | Copy the last assistant response to the system clipboard |
16
- | `ALT+S → K` | Add to Kanboard Backlog | Add the editor text to the project's kanboard backlog as a body-only task (attached file paths in the text are uploaded) |
17
- | `ALT+I` | Tab Insert | Insert literal tab character |
18
-
19
- ## Commands
20
-
21
- | Command | Description |
22
- |---------|-------------|
23
- | `/unipi:settings` | Customize keybindings (Input Shortcuts group) |
7
+ ## What it does
24
8
 
25
- ## Special Triggers
9
+ - `Alt+S` opens a chord overlay. You press one more key to run an action.
10
+ - Stash keeps one piece of editor text, and the stash stays after a restart.
11
+ - Undo and redo step through editor text. History starts at the first keystroke.
12
+ - `Y` copies the last agent reply to the system clipboard.
13
+ - `K` adds the editor text to the kanboard backlog.
14
+ - After Ctrl+C clears the editor, the cleared text stays in the transcript, struck through. `↑` restores it.
26
15
 
27
- Input-shortcuts is a standalone package. It doesn't register with other packages or trigger coexists behavior.
16
+ ## Quick start
28
17
 
29
- Every action shows a brief success or error message in the status bar via `ctx.ui.setStatus()`.
18
+ Input Shortcuts ships in `@pi-unipi/unipi`. To install it alone:
30
19
 
31
- ## How It Works
20
+ ```bash
21
+ pi install npm:@pi-unipi/input-shortcuts
22
+ ```
32
23
 
33
- ### Stash
24
+ 1. Type some text in the editor.
25
+ 2. Press `Alt+S`.
26
+ 3. Press `S` to stash the text. The editor clears.
27
+ 4. Press `Alt+S`, then `S` again to restore the text.
34
28
 
35
- - **Stash register**: 1 register for quick save/restore
36
- - **Persistence**: Saved to `.unipi/config/input-shortcuts.json` (per-project, atomic writes). Files written by older versions (with ten numbered registers 0-9) still load; the register keys are ignored and dropped on the next save.
37
-
38
- ### Undo/Redo
39
-
40
- - Linear checkpoint history, O(1) amortized per record
41
- - A typing burst records the editor text exactly twice — before the first keystroke and after the last (burst closes after 600ms of quiet, and long bursts split every ~2s) — so undo works from the very first keystroke without reading the editor on every keypress
42
- - At most 100 checkpoints / 2M characters in memory (oldest evicted first)
43
- - An edit after an undo invalidates the redo; undoing captures un-flushed typing first
44
- - Not persisted across sessions
29
+ ## Shortcuts
45
30
 
46
- ### Copy Last Response
31
+ | Keys | What it does |
32
+ |---|---|
33
+ | `Alt+S`, then `S` | Stash or restore. With text in the editor, it saves the text and clears the editor. With an empty editor, it restores the stash. |
34
+ | `Alt+S`, then `A` | Adds the stash text to the end of the editor text. The stash stays. |
35
+ | `Alt+S`, then `U` | Undo. |
36
+ | `Alt+S`, then `R` | Redo. An edit after an undo clears the redo steps. |
37
+ | `Alt+S`, then `Y` | Copies the last agent reply to the clipboard. |
38
+ | `Alt+S`, then `K` | Adds the editor text to the kanboard backlog as a task. File paths in the text become attachments. |
39
+ | `Alt+I` | Adds a tab character to the end of the editor text. |
40
+ | `Esc` in the overlay | Closes the overlay. Any other key also closes it. |
47
41
 
48
- Uses pi's own cross-platform `copyToClipboard` (wl-copy / xclip / pbcopy / Windows / WSL / OSC 52 fallbacks) on the text of the last assistant response — the same text pi's `/copy` copies.
42
+ Each action shows a short message in the status bar for 2 seconds. An error message stays for 3 seconds.
49
43
 
50
- ### Kanboard Backlog
44
+ The `K` action needs [Kanboard](../kanboard/README.md) in the same session. If Kanboard is not loaded, the status bar shows `kanboard not loaded`.
51
45
 
52
- The K chord hands the editor text to `globalThis.__unipi_kanboard_api.captureToBacklog()` (registered by `@pi-unipi/kanboard`): the text becomes a body-only Backlog task, and file paths in the text (pasted/dragged files and pasted images, which pi inserts as paths) are attached. Refuses with a status message when kanboard is not loaded or the folder is not onboarded.
46
+ ## Settings
53
47
 
54
- ## Configurables
48
+ Open `/unipi:settings` → Input Shortcuts. The namespace is `input-shortcuts`. The project scope is the default.
55
49
 
56
- Run `/unipi:settings` (Input Shortcuts group) to customize keybindings:
50
+ | Key | Default | What it does |
51
+ |---|---|---|
52
+ | `chordKey` | `alt+s` | Stored chord key. The info screen shows it. |
53
+ | `tabInsertKey` | `alt+i` | Stored tab key. The info screen shows it. |
57
54
 
58
- - **Chord trigger key** — default `alt+s`
59
- - **Tab insert key** — default `alt+i`
55
+ In this release, the shortcuts stay on `Alt+S` and `Alt+I`. The code does not read these two settings when it registers the keys.
60
56
 
61
- Both cycle through available ALT key combinations, excluding known conflicts (`alt+e` = cursorWordRight).
57
+ ## How it works
62
58
 
63
- Config persisted to `~/.unipi/config/input-shortcuts-config.json` (global).
59
+ - **Stash.** The stash file is `.unipi/config/input-shortcuts.json` in the current folder. Input Shortcuts writes it to a temp file first, then renames it.
60
+ - **Undo history.** Input Shortcuts records the editor text two times for each typing burst: before the first key and after the last key. A burst ends after 600 ms with no keys, or after 2 seconds. The history keeps 100 states or 2,000,000 characters at most. The history does not stay after the session ends.
61
+ - **Copy.** `Y` uses the same clipboard function as pi `/copy`.
62
+ - **Ctrl+C.** Input Shortcuts does not change what Ctrl+C does. It only reads the key. The struck-through line is a UI entry, so the model never sees it.
64
63
 
65
- ## License
64
+ ## See also
66
65
 
67
- MIT
66
+ - [Shortcuts reference](../../docs/reference/shortcuts.md)
67
+ - [Kanboard](../kanboard/README.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/input-shortcuts",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Keyboard shortcuts for stash/restore, undo/redo, clipboard, and thinking toggle — chord-based overlay system",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",
@@ -33,7 +33,7 @@
33
33
  "access": "public"
34
34
  },
35
35
  "dependencies": {
36
- "@pi-unipi/core": "3.0.0-alpha.21"
36
+ "@pi-unipi/core": "3.0.0-alpha.22"
37
37
  },
38
38
  "peerDependencies": {
39
39
  "@earendil-works/pi-coding-agent": "^0.87.1",
@@ -1,214 +1,130 @@
1
- # @pi-unipi/kanboard
1
+ # Kanboard
2
2
 
3
- The pi half of **kanboard v3**: a per-project board for deferred work. The
4
- storage, transition rules and web UI live in the Rust binary
5
- ([`crates/kanboard`](../../crates/kanboard) — one writer for every change); this
6
- package is the terminal-side bridge: commands, the `-do` budget, the turn
7
- arbiter's kanboard monitor, hub settings and the `kanboard` skill.
8
- **There is no runner** — the session works board tasks itself; the runner,
9
- queue and strategy labels were removed (see
10
- [`docs/plans/2026-09-30-01a0f095.md`](../../docs/plans/2026-09-30-01a0f095.md)).
3
+ Keep a per-project board of work for later, and let the agent work the tasks when you allow it.
11
4
 
12
- Spec: [`docs/specs/2026-09-24-kanboard-v3-design.md`](../../docs/specs/2026-09-24-kanboard-v3-design.md)
13
- (superseded for the runner/queue/strategy parts).
5
+ `@pi-unipi/kanboard` · part of [UniPi](../../README.md)
14
6
 
15
- ## Commands
7
+ ![Kanboard dashboard: tasks that need you, the next ready task and project health](../../docs/assets/screenshots/kanboard-dashboard.png)
16
8
 
17
- `/unipi:kanboard [open|close|onboard|status|doctor]` — bare lists everything
18
- (display-only, never enters the LLM context):
9
+ ![Kanboard board: lanes from Backlog to Done with task cards](../../docs/assets/screenshots/kanboard-board.png)
19
10
 
20
- | Sub | What it does |
21
- |---|---|
22
- | `open [--host H] [--port N]` | Ensure the daemon (reuse a healthy one, else spawn `serve` detached) and print `http://127.0.0.1:<port>/p/<slug>`. The browser opens only when `openBrowser` is on. |
23
- | `onboard` | `project add` for this workspace and remembers the slug. Idempotent. |
24
- | `close` | Shut down the board daemon — the web UI goes offline until the next `open`. Running tasks are unaffected. |
25
- | `status` | Daemon pid/port, project counts and active claims (session/pid/host/staleness). |
26
- | `doctor` | ✓/✗ setup check (binary, daemon health, project, summary agent, bind, claims) as a display-only message. |
11
+ ## What it does
27
12
 
28
- The other three commands are separate slash commands:
13
+ - Keeps tasks in lanes: Backlog, Todo, In Progress, In Review, Blocked, Done, Cancelled and Archived.
14
+ - Opens a web board for each project. The board updates when the agent or the CLI changes a task.
15
+ - Lets you add a task from the prompt with no agent turn.
16
+ - Lets the agent work tasks only within a budget that you give it, or in autowork.
17
+ - Asks the agent to continue a task that it started and did not finish.
18
+ - Stores tasks as markdown files. The Rust binary `unipi-kanboard` writes all changes. Refer to [the crate README](../../crates/kanboard/README.md).
29
19
 
30
- | Command | What it does |
31
- |---|---|
32
- | `/unipi:kanboard-add [-p 1-5] [--after ID] [--status backlog\|todo] <title>` | Capture a task — no agent turn. Lines below the title are the body; existing file paths pasted there are attached. `-p` maps 1 none · 2 low · 3 medium · 4 high · 5 urgent. |
33
- | `/unipi:kanboard-do <request>` | Reveal the skill and hand the request to the agent with a **budget**: `doTasks` task slots (each `start` uses one) and `doWrites` board writes (add, edit, link, order, move backlog↔todo, note on tasks you don't hold). Always free: reads, and `finish`, `move <ID> blocked --comment` and `note` on tasks this session started. Budgets persist across turns until spent; `-do` tops up without stacking, `off` revokes. Children never write. |
34
- | `/unipi:kanboard-autowork start\|stop` | `start` turns autowork on: the session works every ready task one at a time, in any mode it chooses, with no budget limits. `stop` turns the offers off (never aborts the current turn). |
35
-
36
- The old `add`/`work`/`stop` subcommands and bare-text capture now just point at
37
- these commands.
38
-
39
- ## Continuation: the turn arbiter's monitor
40
-
41
- There is no runner loop. When a run settles, `src/monitor.ts` — a nudge
42
- provider on core's turn arbiter (`agent_before_settle`) — proposes at most one
43
- continuation:
44
-
45
- - **Claims (priority 50):** a task this session started is still In Progress →
46
- `↻ UNI-30 still In Progress — continue, or finish/block it (n/5)`.
47
- - **Autowork-next (priority 40):** autowork on, no open claims, a ready task
48
- exists → `↻ next ready: UNI-33 <title> …`; nothing ready → an
49
- `autowork done` notice, then autowork turns itself off.
50
-
51
- The monitor defers to a **long-horizon owner** (priority 100), to **pending
52
- events** and to **wait sources** (a running bg wake, a busy sidekick, a
53
- background subagent). It **disarms** on an aborted/errored run (Esc never gets
54
- talked over) and when a goal stops paused/budget with claims open (notice
55
- only). Runaway guards: 2 nudged runs with zero tool calls → `⚠ stalled`, a
56
- hard cap of 5 nudges per task, a question heuristic (the agent asked the user
57
- something → notice, no nudge), and in autowork the same stall rule plus a
58
- 3-offers-per-task cap. After an Esc, a later prompt that names a claimed id
59
- re-arms the monitor.
60
-
61
- **Children are read-only.** Sidekicks and subagents may read the board; every
62
- write is refused with "board writes are the lead's job — report this to the
63
- lead". Reminders are silent there too.
64
-
65
- **Session identity & lifecycle.** On every lead `session_start` the session id
66
- becomes `UNIPI_KANBOARD_SESSION = pi-<pi session id>` (stable across `-c`/`-r`)
67
- and `UNIPI_KANBOARD_PID` the process pid. At startup stale claims whose pid died
68
- are reaped (`session lost: …`), and tasks released that way get a one-time
69
- notice ("UNI-30 was released when the last run ended — ask me to re-start it").
70
- On `session_shutdown` this session's open claims are released to Todo with
71
- `released: session ended mid-task (<session>)` (actor system — the agent actor
72
- cannot release).
73
-
74
- ## Settings (hub section "Kanboard")
75
-
76
- | Setting | Default | Notes |
77
- |---|---|---|
78
- | `chainGate` | `in_review` | `done` waits for a finished dependency |
79
- | `idleMin` | `10` | Passed to `serve --idle-min` |
80
- | `port` | `0` | Passed to `serve --port` (0 = OS-assigned) |
81
- | `archiveAfterDays` | `0` | > 0 → `archive-sweep --after-days N` on session start (fire and forget) |
82
- | `openBrowser` | `false` | Open the board in a browser on `open` |
83
- | `requireAuth` | `false` | Also require the access token on 127.0.0.1 (remote always does) |
84
- | `keepToken` | `false` | Reuse `<home>/token` across daemon restarts |
85
- | `maxSessions` | `2` | Distinct sessions holding in-progress tasks per project (`UNIPI_KANBOARD_MAX_SESSIONS`) |
86
- | `turnAddLimit` | `20` | `add` calls allowed per turn (0 = unlimited) — the runaway guard, applies in autowork too |
87
- | `reminders` | `true` | R1: steer on the first file-changing call while a mentioned task is still Todo (text only, never blocks; silent in child sessions) |
88
- | `doTasks` | `5` | Task slots a `/unipi:kanboard-do` grants (each `start` costs one) |
89
- | `doWrites` | `10` | Board writes a `/unipi:kanboard-do` grants; a stored `doCredits` migrates into this |
90
- | *actions* | | `Open board…`, `Stop daemon`, `Summary agent command…`, `Rotate access token` |
91
-
92
- `Summary agent command…` writes through `settings set agent-command` and
93
- `Rotate access token` runs `rotate-token` — both are **user-only** (actor=agent
94
- is refused), as are `settings set` calls generally. `settings show` is read-only.
95
-
96
- ## Binary resolution
97
-
98
- 1. `UNIPI_KANBOARD_BIN` (explicit path)
99
- 2. `@pi-unipi/kanboard-<platform>-<arch>/bin/unipi-kanboard[.exe]` (K4 ships these)
100
- 3. the dev build `<repo>/crates/kanboard/target/{release,debug}/unipi-kanboard`
101
-
102
- Nothing found → every command reports
103
- `kanboard binary unavailable for <platform>-<arch>` and does nothing else.
104
-
105
- **Agent bash env:** pi has no extension-level mechanism to add env vars to the
106
- `bash` tool (only replacing bash via `registerTool` + `BashToolOptions`, which
107
- would change tool schemas mid-session and break the prefix cache — spec principle
108
- 4 forbids that). So the task prompt and the skill pass `--actor agent --project
109
- <slug>` explicitly and call the binary by absolute path.
110
-
111
- ## Skill
112
-
113
- `skills/kanboard/SKILL.md` describes the CLI, the lanes, who may move what, and
114
- the rules agents must follow. It is a normal pi skill (jev skill-judging can
115
- reveal it on intent), and `/unipi:kanboard-do` force-reveals it by emitting
116
- `unipi:skills:reveal`, which utility turns into the usual append-only reveal
117
- message — the system prompt is never touched.
118
-
119
- ## Platforms and packaging
120
-
121
- | Platform | npm package | Rust target | Notes |
122
- |---|---|---|---|
123
- | Linux x64 | `@pi-unipi/kanboard-linux-x64` | `x86_64-unknown-linux-musl` | static-pie, 3.9 MB |
124
- | Linux arm64 | `@pi-unipi/kanboard-linux-arm64` | `aarch64-unknown-linux-musl` | static |
125
- | macOS arm64 | `@pi-unipi/kanboard-darwin-arm64` | `aarch64-apple-darwin` | |
126
- | macOS x64 | `@pi-unipi/kanboard-darwin-x64` | `x86_64-apple-darwin` | cross-built from macos-14 |
127
- | Windows x64 | `@pi-unipi/kanboard-win32-x64` | `x86_64-pc-windows-msvc` | |
128
-
129
- They are **optional dependencies** of this package (`os`/`cpu` gated), so `npm install`
130
- pulls exactly one. `.github/workflows/kanboard-binaries.yml` builds them (tests +
131
- clippy on native targets, release build per target, artifact per platform) and, on
132
- a `v*` tag, attaches the binaries to the GitHub release. Publishing to npm:
20
+ ## Quick start
21
+
22
+ UniPi installs this package:
133
23
 
134
24
  ```bash
135
- npm run publish:kanboard -- --dry-run # what would ship
136
- npm run publish:kanboard # publishes, or skips loudly
25
+ pi install npm:@pi-unipi/unipi
137
26
  ```
138
27
 
139
- The script **skips any platform package whose `bin/` is empty** (and exits 2), so
140
- an empty platform package can never be published. CI publishes only when an
141
- `NPM_TOKEN` secret exists — this repository has none, so the release job attaches
142
- artifacts and says so.
143
-
144
- Local packaging proof (no registry, no network):
28
+ To install this package alone:
145
29
 
146
30
  ```bash
147
- node scripts/test-kanboard-packaging.mjs
148
- # packs packages/kanboard + the linux-x64 platform package, installs both into a
149
- # temp node_modules, resolves the binary through src/bin.ts and runs --version
31
+ pi install npm:@pi-unipi/kanboard
150
32
  ```
151
33
 
152
- ## Remote access
34
+ npm installs the binary for your platform as an optional package: Linux x64 and arm64, macOS x64 and arm64, and Windows x64.
153
35
 
154
- The daemon binds `127.0.0.1` by default — local only, no token. For access from
155
- another machine either **tunnel** it (nothing to configure):
36
+ 1. Run `/unipi:kanboard onboard` to register the project.
37
+ 2. Run `/unipi:kanboard-add Fix the flaky login test` to add a task.
38
+ 3. Run `/unipi:kanboard open` and open the link that it prints.
39
+ 4. Run `/unipi:kanboard-do work the login tasks` to let the agent work them.
156
40
 
157
- ```bash
158
- ssh -N -L 37473:127.0.0.1:37473 <hostname> # then open http://127.0.0.1:37473
159
- ```
41
+ ## Commands
160
42
 
161
- …or bind a reachable interface, which turns on the **token gate**:
43
+ | Command | What it does |
44
+ |---|---|
45
+ | `/unipi:kanboard` | Lists the commands. |
46
+ | `/unipi:kanboard open [--host H] [--port N]` | Starts the board daemon if it does not run, and prints the board link. |
47
+ | `/unipi:kanboard close` | Stops the board daemon. Tasks in progress do not change. |
48
+ | `/unipi:kanboard onboard` | Registers this project. You can run it again with no effect. |
49
+ | `/unipi:kanboard status` | Shows the daemon and the active claims. |
50
+ | `/unipi:kanboard show [--all]` | Shows the board in the chat. |
51
+ | `/unipi:kanboard doctor` | Examines the setup: binary, daemon, project and bind address. |
52
+ | `/unipi:kanboard-add [-p 1-5] [--after ID] [--status backlog\|todo] <title>` | Adds a task. Lines below the title become the description. A file path in the description becomes an attachment. |
53
+ | `/unipi:kanboard-do <request>` | Gives the request to the agent with a task budget. `off` removes the budget. |
54
+ | `/unipi:kanboard-autowork start\|stop` | `start` lets the agent work all ready tasks, one at a time. `stop` stops the offers of new tasks. |
162
55
 
163
- ```bash
164
- /unipi:kanboard open --host 0.0.0.0 --port 37473 # every interface
165
- /unipi:kanboard open --host tailscale # the tailnet IPv4
166
- ```
56
+ Priority `-p`: 1 none, 2 low, 3 medium, 4 high, 5 urgent.
167
57
 
168
- `--host` and `--port` override the `host`/`port` settings for that invocation
169
- only. `tailscale` resolves through `tailscale ip -4` (clear error when tailscale
170
- is not installed). For a wildcard bind the printed URLs cover the machine
171
- hostname, every non-internal IPv4 and the tailnet address, and a warning says
172
- `board is reachable from the network; anyone with the link can edit it`.
58
+ The output of these commands shows in the chat. It does not go into the model context.
173
59
 
174
- **Token model.** Any non-loopback bind generates a 32-byte token (base64url) and
175
- writes it to `daemon.json` alongside `host`. Every request must carry it:
60
+ ## Task budget
176
61
 
177
- - `?t=<token>` — sets an `HttpOnly; SameSite=Strict` cookie and 303-redirects to
178
- the same URL without the parameter (so the token leaves the address bar),
179
- - the `kb_token` cookie, or
180
- - `Authorization: Bearer <token>`.
62
+ `/unipi:kanboard-do` gives the agent two budgets:
181
63
 
182
- Missing or wrong tokens answer `401` with a page saying to open the link printed
183
- by `/unipi:kanboard open`. `/api/health` stays reachable but returns only
184
- `{ok, version}` (no pid) off-loopback, and POSTs are refused when their `Origin`
185
- does not match the request `Host` (drive-by CSRF), in both modes. Loopback binds
186
- keep no token at all.
64
+ - **Task slots** (`doTasks`, default 5). Each `start` uses one slot.
65
+ - **Board writes** (`doWrites`, default 10). `add`, `edit`, `link`, `order`, a move between Backlog and Todo, and a `note` on a task of another session each use one write.
187
66
 
188
- Changing the binding needs a restart: if a daemon already runs with a different
189
- host/port, `serve` reports `bindingChanged` and `/unipi:kanboard open` stops the
190
- old one and starts the new one (`restarted kanboard on 0.0.0.0:37473`). The
191
- daemon runs no jobs, so nothing is lost.
67
+ Some operations are always free: reads, and `finish`, `move <ID> blocked`, `note` and `attach` on tasks that this session started. The budget stays until the agent uses it. A new `-do` fills the budget again. It does not add to the old budget.
192
68
 
193
- ## Storage
69
+ In autowork, the agent has no budget. It can use any mode, for example goal or ralph.
194
70
 
195
- `~/.unipi/kanboard/` (`UNIPI_KANBOARD_HOME` overrides it): `daemon.json` +
196
- `daemon.lock` for the daemon, and `projects/<slug>/{project.json,board.lock,tasks/*.md,queues/<session>.json}`.
197
- The extension never edits those files — the binary owns them.
71
+ Subagents and sidekicks can read the board, but cannot write to it. The guard tells them to report to the lead.
198
72
 
199
- ## Troubleshooting
73
+ ## Settings
200
74
 
201
- | Symptom | Fix |
202
- |---|---|
203
- | `kanboard binary unavailable for <platform>-<arch>` | No `UNIPI_KANBOARD_BIN`, no platform package and no dev build. Build `crates/kanboard` (`cargo build --release`) or set `UNIPI_KANBOARD_BIN`. |
204
- | The board says *"N task file(s) need repair"* | A file was edited by hand. One bad file no longer blocks the board (it is skipped and reported); run `unipi-kanboard validate --fix`, then `validate`. |
205
- | `UNI-5 is unreadable: … (line N)` | That task's own file is broken — repair it before moving/noting it. |
206
- | The daemon looks stale | `unipi-kanboard status` (pid + liveness), then `/unipi:kanboard close`, `unipi-kanboard stop` (SIGTERM, ≤3s) or the hub's **Stop daemon** action. |
207
- | Nothing is ready | `unipi-kanboard list --ready --json` shows `waitingFor`; a cancelled dependency blocks forever — `link`/`unlink` to re-plan. |
208
- | A board call prompts for permission | Fixed in auto mode: `unipi-kanboard … --actor agent` is allow-listed by the permission gate (ask mode still asks). |
75
+ Open `/unipi:settings` → **Kanboard**. The file is `~/.unipi/config/kanboard/config.json`.
209
76
 
210
- ## Tests
77
+ | Key | Default | What it does |
78
+ |---|---|---|
79
+ | `chainGate` | `in_review` | Status that a dependency must reach before the next task is ready: `in_review` or `done`. The web board uses it. |
80
+ | `idleMin` | `10` | Minutes with no board open before the daemon stops. |
81
+ | `host` | `127.0.0.1` | Bind address. Any other address needs an access token. |
82
+ | `port` | `0` | Daemon port. `0` lets the OS select a port. |
83
+ | `archiveAfterDays` | `0` | Archives done and cancelled tasks after this many days. `0` turns it off. |
84
+ | `retentionDays` | `90` | Moves archived and cancelled tasks to cold storage after this many days. |
85
+ | `openBrowser` | `false` | Opens the board in a browser on `open`. |
86
+ | `requireAuth` | `false` | Asks for the token on `127.0.0.1` too. |
87
+ | `keepToken` | `false` | Uses the same token after a daemon restart. |
88
+ | `maxSessions` | `2` | Number of sessions that can hold In Progress tasks in one project. |
89
+ | `turnAddLimit` | `20` | `add` calls in one turn. `0` means no limit. |
90
+ | `reminders` | `true` | Reminds the agent to `start` a Todo task before it edits files. |
91
+ | `doTasks` | `5` | Task slots that one `-do` gives. |
92
+ | `doWrites` | `10` | Board writes that one `-do` gives. |
93
+
94
+ At session start, Kanboard runs `archive-sweep` when `archiveAfterDays` or `retentionDays` is more than 0.
95
+
96
+ ## How it works
97
+
98
+ Kanboard has no task runner. The agent works each task in your session. When a run ends, a monitor on the [turn arbiter](../../docs/architecture/turn-arbiter.md) can add one message to continue:
99
+
100
+ - **Claims** (priority 50). A task that this session started is still In Progress. The monitor asks the agent to continue, finish or block it.
101
+ - **Next task** (priority 40). Autowork is on and a ready task exists. The monitor offers it. When no task is ready, autowork stops.
102
+
103
+ The monitor waits for a [long-horizon](../../docs/architecture/long-horizon.md) owner (priority 100) and for pending events. It stops after you press `Esc` or a run fails. It also stops after 2 runs with no tool calls, after 5 messages for one task, or after 3 offers of one task in autowork.
104
+
105
+ At session start, Kanboard releases claims of dead processes. At session end, it moves the open claims of this session back to Todo. The next start shows a notice about these tasks.
106
+
107
+ ## Remote access
108
+
109
+ The daemon listens on `127.0.0.1` by default and needs no token. To use the board from another machine, use an SSH tunnel:
211
110
 
212
111
  ```bash
213
- npm test -w packages/kanboard # bin resolution, commands, budget guard, monitor, settings
112
+ ssh -N -L 37473:127.0.0.1:37473 <hostname>
214
113
  ```
114
+
115
+ You can also bind another address, for example `/unipi:kanboard open --host 0.0.0.0 --port 37473` or `--host tailscale`. Then the daemon makes an access token, and the printed link contains it. Anyone with the link can edit the board.
116
+
117
+ ## Troubleshooting
118
+
119
+ | Problem | Fix |
120
+ |---|---|
121
+ | `kanboard binary unavailable for <platform>-<arch>` | Set `UNIPI_KANBOARD_BIN` to the binary path, or build `crates/kanboard` with `cargo build --release`. |
122
+ | The board says that some task files have errors | Run `unipi-kanboard validate --fix`, then `unipi-kanboard validate`. |
123
+ | The daemon does not respond | Run `/unipi:kanboard close`, then `/unipi:kanboard open`. |
124
+ | No task is ready | Run `unipi-kanboard list --ready --json` and read `waitingFor`. A cancelled dependency blocks a task. |
125
+
126
+ ## See also
127
+
128
+ - [Kanboard crate: CLI, daemon and JSON API](../../crates/kanboard/README.md)
129
+ - [Turn arbiter](../../docs/architecture/turn-arbiter.md)
130
+ - [Commands reference](../../docs/reference/commands.md)