@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,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/memory",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Persistent cross-session memory on MemPalace (auto-installed): daemon-routed writes, shared palace with other agents, for Pi coding agent",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -42,8 +42,8 @@
42
42
  "README.md"
43
43
  ],
44
44
  "dependencies": {
45
- "@pi-unipi/core": "3.0.0-alpha.21",
46
- "@pi-unipi/info-screen": "3.0.0-alpha.21",
45
+ "@pi-unipi/core": "3.0.0-alpha.22",
46
+ "@pi-unipi/info-screen": "3.0.0-alpha.22",
47
47
  "js-yaml": "^4.1.0"
48
48
  },
49
49
  "peerDependencies": {
@@ -1,156 +1,121 @@
1
- # @pi-unipi/notify
1
+ # Notify
2
2
 
3
- Push notifications when things happen. Workflow finishes, Ralph loop completes, MCP server errors — notify sends alerts to native OS, Gotify, Telegram, or ntfy.
3
+ Send a notification to your desktop or phone when the agent finishes work or needs an answer.
4
4
 
5
- Configure once, get alerts everywhere. Per-event platform routing lets you send critical errors to Telegram and routine completions to Gotify. Native desktop notifications can also be suppressed while the Pi window is focused.
5
+ `@pi-unipi/notify` · part of [UniPi](../../README.md)
6
6
 
7
- ## Commands
8
-
9
- | Command | Description |
10
- |---------|-------------|
11
- | `/unipi:settings (Notify)` | Platforms setup wizards, test notification, recap model, event matrix |
12
- | `/unipi:notify-event` | Toggle a single event without the TUI (`<event> <on\|off>`) — reports the new value; run `/reload` to re-register listeners |
13
-
14
- ## Special Triggers
7
+ ## What it does
15
8
 
16
- Notify subscribes to Pi lifecycle events and routes notifications based on your config:
9
+ - Sends notifications to four platforms: native OS, [Gotify](https://gotify.net), Telegram and [ntfy](https://ntfy.sh).
10
+ - Sends a notification for each enabled event, for example when a workflow ends or the agent asks a question.
11
+ - Lets you route each event to its own platforms.
12
+ - Gives the agent a `notify_user` tool.
13
+ - Sends a question again every 2 minutes, 3 times at most, until you answer it.
14
+ - Can write a one-line summary of the last agent message with a model of your choice ("recap").
17
15
 
18
- | Event | Default | Description |
19
- |-------|---------|-------------|
20
- | `workflow_end` | On | Workflow command completes |
21
- | `ralph_loop_end` | On | Ralph loop completes |
22
- | `mcp_server_error` | On | MCP server error |
23
- | `agent_end` | Off | Low-level agent run ends (may fire again on retries) |
24
- | `agent_settled` | Off | Agent fully settles after retries, compaction, and queued continuations |
25
- | `memory_consolidated` | Off | Memory auto-saved |
26
- | `session_shutdown` | Off | Session ends |
27
- | `ask_user_prompt` | Off | Agent asked a question and is waiting for an answer |
28
- | `permission_request` | Off | A permission prompt is about to be shown (requires [`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system)) |
16
+ ## Quick start
29
17
 
30
- `ask_user_prompt` and `permission_request` are **blocking** events: while one is unanswered the agent is parked, so notify re-sends it periodically (see [Re-notify unanswered prompts](#re-notify-unanswered-prompts)).
18
+ UniPi installs this package:
31
19
 
32
- Notify registers with the info-screen dashboard, showing enabled platforms and last notification time. The footer subscribes to `NOTIFICATION_SENT` events to display notification stats.
33
-
34
- ## Agent Tool
20
+ ```bash
21
+ pi install npm:@pi-unipi/unipi
22
+ ```
35
23
 
36
- | Tool | Description |
37
- |------|-------------|
38
- | `notify_user` | Send cross-platform notification |
24
+ To install this package alone:
39
25
 
26
+ ```bash
27
+ pi install npm:@pi-unipi/notify
40
28
  ```
41
- notify_user({
42
- title: "Build Failed",
43
- message: "TypeScript compilation failed with 12 errors.",
44
- priority: "high"
45
- })
46
- ```
47
-
48
- An explicit semantic priority overrides configured urgency for that dispatch on platforms that support it: `low`/`normal`/`high` map to Gotify `2`/`5`/`8` and ntfy `2`/`3`/`5`. Native and Telegram have no priority input and ignore it. When omitted, Gotify and ntfy retain their configured numeric priorities.
49
29
 
50
- ## Platforms
30
+ Native OS notifications work with no setup. To add a phone platform:
51
31
 
52
- ### Native OS
32
+ 1. Open `/unipi:settings`.
33
+ 2. Select the **Notify** group.
34
+ 3. Open the page for `gotify`, `telegram` or `ntfy`.
35
+ 4. Set **Enabled** to on.
36
+ 5. Enter the server URL, token, topic or chat ID.
37
+ 6. Select **Send test notification** to make sure that it works.
53
38
 
54
- Desktop notifications via [node-notifier](https://github.com/mikaelbr/node-notifier):
55
- - **Windows:** SnoreToast (no admin required)
56
- - **macOS:** terminal-notifier
57
- - **Linux:** notify-send / libnotify
39
+ For Telegram, get a bot token from @BotFather. Then enter the token and your chat ID.
58
40
 
59
- Zero configuration — works out of the box. Set `native.suppressWhenFocused` to `true` to skip native notifications when the active/focused window is already Pi.
41
+ ## Commands
60
42
 
61
- ### Silence after input
43
+ | Command | What it does |
44
+ |---|---|
45
+ | `/unipi:notify-event <event> <on\|off>` | Turns one event on or off without the TUI. Run `/reload` after it to apply the change. |
62
46
 
63
- After a terminal keypress, listed platforms stay quiet for `windowMs`. Default: **off**, native only, 10s. Edit in `/unipi:settings (Notify)` → Platforms (Quiet after activity + channel chips), or in `~/.unipi/config/notify/config.json`:
47
+ All other controls are in `/unipi:settings` → **Notify**.
64
48
 
65
- ```json
66
- {
67
- "silenceAfterInput": {
68
- "enabled": true,
69
- "windowMs": 10000,
70
- "platforms": ["native"]
71
- }
72
- }
73
- ```
49
+ ## Agent tools
74
50
 
75
- Add `gotify`, `telegram`, or `ntfy` to `platforms` to silence those channels too. Empty `platforms` silences all enabled platforms (same as `events.*.platforms`). Blocking events (`ask_user_prompt`, `permission_request`) are never silenced — see below.
51
+ | Tool | What it does |
52
+ |---|---|
53
+ | `notify_user` | Sends a notification. Takes `message`, and optional `title`, `priority` (`low`, `normal`, `high`) and `platforms`. |
76
54
 
77
- ### Re-notify unanswered prompts
55
+ `priority` sets Gotify to 2, 5 or 8 and ntfy to 2, 3 or 5. Native and Telegram ignore it.
78
56
 
79
- When a blocking prompt (`ask_user_prompt`, `permission_request`) is not answered, notify re-sends the same notification every `intervalMs`, with the title suffixed `(still waiting)` and priority `high`, up to `maxRepeats` times. Default: **on**, every 2 minutes, 3 repeats. This is the one notify case where missing the push leaves the agent parked indefinitely.
80
-
81
- ```json
82
- {
83
- "renotify": {
84
- "enabled": true,
85
- "intervalMs": 120000,
86
- "maxRepeats": 3
87
- }
88
- }
57
+ ```text
58
+ notify_user({ title: "Build failed", message: "tsc found 12 errors.", priority: "high" })
89
59
  ```
90
60
 
91
- `maxRepeats: 0` sends the initial notification only. Reminders stop as soon as any of these fires: the user presses a key, herdr reports `herdr:blocked` `active: false`, the agent starts a new turn (`agent_start`), or the session ends. Only one prompt can be outstanding at a time — arming a new one replaces the previous reminder. Reminders bypass `silenceAfterInput` because blocking events are exempt from it.
92
-
93
- Edit in `/unipi:settings (Notify)` → Re-notify, or in `~/.unipi/config/notify/config.json`.
94
-
95
- ### Gotify
96
-
97
- Self-hosted push notification server:
61
+ ## Events
98
62
 
99
- ```json
100
- {
101
- "gotify": {
102
- "enabled": true,
103
- "serverUrl": "https://your-gotify-server.com",
104
- "appToken": "your-app-token",
105
- "priority": 5
106
- }
107
- }
108
- ```
109
-
110
- ### Telegram
63
+ | Event | Default | Sent when |
64
+ |---|---|---|
65
+ | `workflow_end` | on | A workflow command ends. |
66
+ | `ralph_loop_end` | on | A ralph loop ends. |
67
+ | `mcp_server_error` | on | An MCP server reports an error. |
68
+ | `agent_end` | off | One agent run ends. It can occur again after a retry. |
69
+ | `agent_settled` | off | The agent stops after all retries, compaction and queued work. |
70
+ | `memory_consolidated` | off | Memory saves facts. |
71
+ | `session_shutdown` | off | The session ends. |
72
+ | `ask_user_prompt` | off | The agent asks you a question and waits. |
73
+ | `permission_request` | off | A permission prompt opens. This needs [`@gotgenes/pi-permission-system`](https://www.npmjs.com/package/@gotgenes/pi-permission-system). |
111
74
 
112
- Bot API notifications. Run `/unipi:settings` → Notify → telegram → "Setup & test…":
113
- 1. Create a bot via @BotFather
114
- 2. Paste the bot token
115
- 3. Auto-detect your chat ID
75
+ `ask_user_prompt` and `permission_request` are blocking events. The agent stops until you answer.
116
76
 
117
- ### ntfy
77
+ ## Settings
118
78
 
119
- HTTP-based pub-sub notifications via [ntfy.sh](https://ntfy.sh) or self-hosted:
79
+ Open `/unipi:settings` → **Notify**. The file is `~/.unipi/config/notify/config.json`. A project file at `.unipi/config/notify/config.json` overrides it.
120
80
 
121
- ```json
122
- {
123
- "ntfy": {
124
- "enabled": true,
125
- "serverUrl": "https://ntfy.sh",
126
- "topic": "your-topic-name",
127
- "priority": 3
128
- }
129
- }
130
- ```
81
+ | Key | Default | What it does |
82
+ |---|---|---|
83
+ | `events.<event>.enabled` | refer to [Events](#events) | Turns the event on or off. |
84
+ | `events.<event>.platforms` | `[]` | Platforms for the event. An empty list means all enabled platforms. |
85
+ | `native.enabled` | `true` | Turns native OS notifications on or off. |
86
+ | `native.suppressWhenFocused` | `false` | Stops native notifications when the Pi window has focus. Works on Windows only. |
87
+ | `gotify.serverUrl`, `gotify.appToken`, `gotify.priority` | priority `5` | Gotify server, token and priority (0–10). |
88
+ | `telegram.botToken`, `telegram.chatId` | unset | Telegram bot and chat. |
89
+ | `ntfy.serverUrl`, `ntfy.topic`, `ntfy.token`, `ntfy.priority` | `https://ntfy.sh`, priority `3` | ntfy server, topic, token and priority (1–5). |
90
+ | `silenceAfterInput.enabled` | `false` | Stops notifications for a time after you press a key. |
91
+ | `silenceAfterInput.windowMs` | `10000` | Length of that quiet time, in milliseconds. |
92
+ | `silenceAfterInput.platforms` | `["native"]` | Platforms to keep quiet. |
93
+ | `renotify.enabled` | `true` | Sends a blocking event again until you answer. |
94
+ | `renotify.intervalMs` | `120000` | Time between two reminders, in milliseconds. |
95
+ | `renotify.maxRepeats` | `3` | Number of reminders after the first notification. `0` sends no reminders. |
96
+ | `recap.enabled` | `false` | Summarizes the last agent message for `agent_end` and `agent_settled`. |
97
+ | `recap.model` | `openrouter/openai/gpt-oss-20b` | Model for the summary. |
98
+ | `recap.disableThinking` | `false` | Asks a llama.cpp or vLLM server to skip reasoning tokens. |
131
99
 
132
- ## Configurables
100
+ ## How it works
133
101
 
134
- Settings stored at `~/.unipi/config/notify/config.json`. Edit via `/unipi:settings (Notify)` or manual JSON editing.
102
+ A reminder has the text `(still waiting)` in its title and `high` priority. Reminders stop when one of these occurs:
135
103
 
136
- Per-event platform routing lets you control where each event type goes. The settings overlay shows all events with platform toggles.
104
+ - You press a key.
105
+ - herdr reports that the agent is not blocked.
106
+ - The agent starts a new turn.
107
+ - The session ends.
137
108
 
138
- ### Recap (thinking models)
109
+ Only one reminder runs at a time. Silence after input does not apply to blocking events.
139
110
 
140
- Recap summarizes the last assistant message into a one-line push notification (100-token budget). Thinking models served by llama.cpp or vLLM can spend that entire budget on reasoning and return nothing, falling back to a plain 100-character truncation. If your recap endpoint supports chat-template kwargs, set `recap.disableThinking` to skip reasoning tokens:
111
+ Recap sends the last message (2,000 characters at most) to the recap model with a limit of 100 tokens. If the model gives no summary, notify uses the first 100 characters of the message. A thinking model can use all 100 tokens to reason. If your server supports chat template options, set `recap.disableThinking` to `true`. Keep it `false` for a strict OpenAI-compatible server, because that server rejects unknown fields.
141
112
 
142
- ```json
143
- {
144
- "recap": {
145
- "enabled": true,
146
- "model": "localhost/gemma-4-e4b",
147
- "disableThinking": true
148
- }
149
- }
150
- ```
113
+ Native notifications use [node-notifier](https://github.com/mikaelbr/node-notifier): SnoreToast on Windows, terminal-notifier on macOS and `notify-send` on Linux.
151
114
 
152
- This sends `chat_template_kwargs: { enable_thinking: false, preserve_thinking: false }` with the request. Keep it `false` (the default) for strict OpenAI-compatible endpoints — they reject unknown params. Anthropic models are unaffected (thinking is opt-in there).
115
+ Each sent notification emits a `NOTIFICATION_SENT` event on the [event bus](../../docs/architecture/event-bus.md).
153
116
 
154
- ## License
117
+ ## See also
155
118
 
156
- MIT
119
+ - [Ask User](../ask-user/README.md)
120
+ - [Settings reference](../../docs/reference/settings.md)
121
+ - [Event bus](../../docs/architecture/event-bus.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/notify",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
5
5
  "type": "module",
6
6
  "main": "index.ts",
@@ -34,7 +34,7 @@
34
34
  "access": "public"
35
35
  },
36
36
  "dependencies": {
37
- "@pi-unipi/core": "3.0.0-alpha.21",
37
+ "@pi-unipi/core": "3.0.0-alpha.22",
38
38
  "node-notifier": "^10.0.1"
39
39
  },
40
40
  "peerDependencies": {
@@ -1,62 +1,96 @@
1
- # @pi-unipi/skill-registry
1
+ # Skill Registry
2
2
 
3
- Decides which skills the agent sees: per-project on/off, a vault of extra skills, and jev-judged exposure.
3
+ Skill Registry controls which skills the agent sees, per project, and keeps the system prompt stable for the prefix cache.
4
4
 
5
- ## Commands
5
+ `@pi-unipi/skill-registry` · part of [UniPi](../../README.md)
6
6
 
7
- | Command | Description |
8
- |---------|-------------|
9
- | `/unipi:skills` | Opens `/unipi:settings` on Skills (proxy, exposure, and the **Skill settings…** row) |
7
+ ## What it does
10
8
 
11
- ## Skill settings
9
+ - Turns each skill on or off, in the global scope or the project scope.
10
+ - Marks a skill as "must show", so the agent always sees it.
11
+ - Keeps a vault of extra skills in `~/.unipi/skill-vault/`. Vault skills stay off until a scope turns them on.
12
+ - When you have many skills, lists only the skills that matter to the first real request.
13
+ - Names each hidden skill in a short system prompt section, so the agent can read it when necessary.
14
+ - Keeps the listed set the same for all of the session, so the prefix cache stays valid.
12
15
 
13
- `/unipi:settings` → Skills → **Skill settings…** opens a grid of every skill pi loaded, like Fusion's preset editor:
16
+ ## Quick start
14
17
 
18
+ Skill Registry ships in `@pi-unipi/unipi`. To install it alone:
19
+
20
+ ```bash
21
+ pi install npm:@pi-unipi/skill-registry
15
22
  ```
16
- Skill settings · 42 skills · editing global · proxy on
17
- E M skill source description
18
- › [x] [ ] api-contract user Check REST/JSON API changes ...
19
- [ ] [ ] aws-deploy vault Deploy services to AWS with ...
20
-
21
- E enabled — the model sees it (judged first when exposure is on); off removes it and blocks /skill:name
22
- M must show — always listed, even when judging would hide it
23
- bright = set in global · dim = inherited
24
- ```
25
23
 
26
- | Key | Action |
27
- |-----|--------|
28
- | `↑` `↓` | Move between skills (PgUp/PgDn page) |
29
- | `←` `→` | Move between the E / M columns |
30
- | `space` | Toggle the cell |
31
- | `d` | Clear the cell in the edited scope (inherit again) |
32
- | `g` | Edit the global or the project scope |
33
- | `p` | Skill proxy on/off |
34
- | type | Filter by name, source or description (Esc clears) |
35
- | `enter` / `esc` | Save / cancel |
24
+ 1. Type `/unipi:skills`. The settings hub opens on the Skills group.
25
+ 2. Set **Skill proxy** to on. Without the proxy, Skill Registry saves your per-skill choices but does not apply them.
26
+ 3. Select **Skill settings…** to open the skill grid.
27
+ 4. Set the cells, then press `Enter` to save.
28
+
29
+ Changes apply from the next prompt. You do not need `/reload`.
30
+
31
+ ## Commands
32
+
33
+ | Command | What it does |
34
+ |---|---|
35
+ | `/unipi:skills` | Opens `/unipi:settings` on the Skills group. |
36
+
37
+ ## Skill grid
38
+
39
+ **Skill settings…** shows each skill with its source (`vault`, `project`, `user`, `unipi` or `package`) and two columns:
40
+
41
+ - **E** (enabled): the agent can see the skill. Off removes it from the session, and blocks `/skill:name`.
42
+ - **M** (must show): the agent always sees the skill, also when exposure judging would hide it.
43
+
44
+ | Key | What it does |
45
+ |---|---|
46
+ | `↑` `↓`, PgUp, PgDn | Moves between skills. |
47
+ | `←` `→`, Tab | Moves between the E and M columns. |
48
+ | Space | Toggles the cell. |
49
+ | `d` | Clears the cell in the current scope. The cell then inherits again. |
50
+ | `g` | Changes the scope: global or project. |
51
+ | `p` | Turns the skill proxy on or off. |
52
+ | Other letters | Filter by name, source or description. Esc clears the filter. |
53
+ | `Enter` | Saves. |
54
+ | `Esc` | Cancels. |
55
+
56
+ A project value wins over a global value. With no value, vault skills are off and all other skills are on. Skill Registry writes only the cells that you change.
57
+
58
+ ## Settings
59
+
60
+ Open `/unipi:settings` → Skills. The namespace is `skills`.
61
+
62
+ | Key | Default | What it does |
63
+ |---|---|---|
64
+ | `proxy` | `false` | Applies the per-skill states and includes the vault. |
65
+ | `exposure.mode` | `judged` | `judged`: jev picks the listed skills. `all`: list all skills. `off`: remove the UniPi bundled skills from the list. |
66
+ | `exposure.threshold` | `0.8` | Minimum jev relevance score for a skill to stay listed. Range 0 to 1. |
67
+ | `exposure.maxSkills` | `12` | Maximum number of listed skills. With this number of skills or fewer, no judging occurs. |
68
+ | `exposure.recheck` | `true` | On later prompts, tells the agent about hidden skills that jev finds relevant. |
69
+ | `states` | `{}` | Per-skill `enabled` and `mustShow`. Edit it in **Skill settings…**. |
70
+
71
+ The group also has a Decision model section. Set `decisionModel.source` to `inherit` or `custom`.
36
72
 
37
- Cells show the effective value: project over global over the default (vault skills off, everything else on). Only the cells you changed are written, each option on its own, so a project can override just one.
73
+ Set `UNIPI_SKILL_VAULT` to use a different vault folder.
38
74
 
39
- ## Skill proxy
75
+ ## How it works
40
76
 
41
- Off by default. While off, pi's skills pass through untouched (exposure judging still applies), vault skills stay hidden, and your choices are saved but not applied. Turn it on and:
77
+ In `judged` mode, Skill Registry picks the listed set on the first real prompt of the session. Greetings do not count. jev is the UniPi Decision Model.
42
78
 
43
- - Skills turned **off** are removed from the session, including `/skill:name`.
44
- - The **vault**, `~/.unipi/skill-vault/`, takes part. Keep as many skills there as you like; they stay off until a scope turns them on, so a project only gets the ones it needs. Changes apply on the next prompt, no reload needed. Any folder with a `SKILL.md`, up to three levels deep (`vault/<skill>/` or `vault/<pack>/<skill>/`).
79
+ 1. A skill that the prompt names is always kept. A distinctive word of the name is enough: "ssh into coffee" keeps `coffee-sandbox`.
80
+ 2. Must-show skills are always kept.
81
+ 3. jev scores the other skills against the prompt. Skills at or above `exposure.threshold` stay, best first, up to `exposure.maxSkills`.
82
+ 4. A system prompt section names each hidden skill and its folder.
45
83
 
46
- ## Exposure
84
+ After this, the system prompt does not change for the session. On a later prompt, a message tells the agent about hidden skills that the prompt names. With `exposure.recheck`, it also tells the agent about hidden skills that jev finds relevant. Each message names 5 skills at most.
47
85
 
48
- Settings → Skills → Exposure:
86
+ If jev does not answer, Skill Registry lists all skills.
49
87
 
50
- - **judged** (default) — when more skills are available than *Max skills listed* (12), the first real request of the session picks the listed set, and it stays fixed for the session so the system prompt never changes (prefix cache intact). Greetings don't count.
51
- 1. **Named skills are always kept.** A skill whose name appears in the request (`agent-browser`, "grill me") or a word only its name contains ("ssh into **coffee**" → `coffee-sandbox`) is listed without asking a model.
52
- 2. **jev scores the rest** against the request; those above the threshold are listed best first, up to *Max skills listed* in total.
53
- 3. **Hidden skills are still named.** The system prompt gets a short section listing every hidden skill by folder, so the agent knows it exists and can read its `SKILL.md`.
54
- 4. **Later requests** that name a hidden skill (or, with *recheck*, that jev finds it relevant to) get a message pointing at it. The system prompt itself never changes.
55
- - **all** — every skill is listed.
56
- - **off** — UniPi's bundled skills are removed from the list.
88
+ The vault holds any folder with a `SKILL.md`, up to three levels deep: `vault/<skill>/` or `vault/<pack>/<skill>/`.
57
89
 
58
- jev uses the shared Decision Model (Settings → Skills → Decision model: inherit or custom). If jev is unavailable, every skill is listed.
90
+ Other packages can emit the `unipi:skills:reveal` event with `{ names: [...] }` to tell the agent about hidden skills.
59
91
 
60
- ## License
92
+ ## See also
61
93
 
62
- MIT
94
+ - [Prefix cache](../../docs/architecture/prefix-cache.md)
95
+ - [Settings reference](../../docs/reference/settings.md)
96
+ - [Glossary](../../docs/reference/glossary.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/skill-registry",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Skill registry for pi — per-project skill on/off, a skill vault, and jev-judged skill exposure",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -33,7 +33,7 @@
33
33
  },
34
34
  "main": "index.ts",
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,41 +1,87 @@
1
- # @pi-unipi/subagents
1
+ # Subagents
2
2
 
3
- Devin-model subagents for pi: the lead delegates self-contained work to independent child
4
- agents (`pi --mode rpc`) that run alongside it.
3
+ Subagents let the agent give a self-contained task to a child agent, so the
4
+ main context stays small.
5
5
 
6
- - `run_subagent` — foreground (wait + report) or background (`<subagent_completion_notification>`
7
- followUp, exactly once). Approval prompts reach the user only while a foreground waiter is
8
- attached; background subagents are denied with a reason ("running in the background… don't
9
- retry"). `resume:<agent_id>` continues an earlier agent in its session file.
10
- - `read_subagent` — shared tool (core registry): reads subagents AND Fusion sidekick handoffs.
11
- - Profiles: `subagent_explore` (read-only allowlist + cheap default model),
12
- `subagent_general` (all tools minus nesting, parent's model), and custom markdown agents from
13
- `~/.unipi/config/agents/` + `<workspace>/.unipi/config/agents/` (project wins).
14
- - Nesting: children spawn only below `UNIPI_SUBAGENT_MAX_DEPTH` (default 1 = no nesting).
6
+ `@pi-unipi/subagents` · part of [UniPi](../../README.md)
15
7
 
16
- ## Screen
8
+ ## What it does
17
9
 
18
- | Where | What |
10
+ - Starts each child agent as a separate Pi process (`pi --mode rpc`).
11
+ - Runs a child in the foreground, or in the background. A background child
12
+ sends one completion notice when it finishes.
13
+ - Can resume an earlier child in its own session.
14
+ - Gives two built-in profiles and lets you add custom agents as Markdown files.
15
+ - Shows a live card for each child, with the model, tool calls, tokens and cost.
16
+ - Runs 8 children or fewer at the same time by default.
17
+
18
+ | Profile | What it does |
19
19
  |---|---|
20
- | Chat | `● Explore subagent <title>` card — live tail + `└ General · ds/deepseek-flash · 32s · 20 tool calls · 10k in · 0.2k out · $0.11 · ctrl+b background · esc cancel` while it runs, then `└ Completed · 32s · 20 tool calls · 10k in · 0.2k out · $0.11` (ctrl+o shows the report). The stats line ticks live — profile, model, tool-call count, duration, tokens and cost (cost is omitted when the model's pricing is unknown). Background finishes: `● Subagent "<title>" completed └ …`. |
21
- | Below the input | `N subagents (k running) · ↓ select` plus one stat line per running agent, ticking each second — stays for the session, survives restart + resume. |
22
- | Dock (↓ from an empty input, or `/unipi:subagents`) | `↑↓` navigate · `↵` view the live transcript · `f` foreground · `x` cancel · `esc` close. |
23
- | Transcript view | task, tool calls with output, text; `↑↓`/PgUp/PgDn scroll, `g`/`G` top/end, `o` full tool output. |
24
- | Foreground | Spinner reads `Subagent running · Ctrl+B to run in background`. **Ctrl+B** sends every foreground subagent to the background; **Esc** cancels a foreground run. `f` on a background agent shows its live steps above the input and routes its approvals to you. |
20
+ | `subagent_explore` | Read-only research. It uses the default subagent model. |
21
+ | `subagent_general` | General tasks, also code changes. It uses your model. |
22
+
23
+ ## Quick start
24
+
25
+ 1. Install UniPi: `pi install npm:@pi-unipi/unipi`. You can also install this
26
+ package alone: `pi install npm:@pi-unipi/subagents`.
27
+ 2. Ask the agent to explore a part of the code with a subagent.
28
+ 3. Push `Ctrl+B` to send a foreground child to the background.
29
+ 4. Push the down arrow in an empty input to open the subagent panel.
30
+
31
+ ## Commands
32
+
33
+ | Command or key | What it does |
34
+ |---|---|
35
+ | `/unipi:subagents` | Opens the subagent panel. |
36
+ | `/unipi:agents` | Lists profiles. Creates, edits, copies or deletes custom agents. |
37
+ | `Ctrl+B` | Sends all foreground children to the background. |
38
+ | `Esc` | Cancels a foreground child. |
39
+
40
+ In the panel, use the arrow keys to move. Push `Enter` to see the live
41
+ transcript. Push `f` to bring a child to the foreground. Push `x` to cancel it.
42
+
43
+ ## Agent tools
44
+
45
+ | Tool | What it does |
46
+ |---|---|
47
+ | `run_subagent` | Starts a child with a `title`, `task` and `profile`. Use `is_background` to run without a wait. Use `resume` with an agent ID to continue a child. |
48
+ | `read_subagent` | Reads the report of a subagent or a Fusion sidekick. |
49
+
50
+ A background child cannot show approval prompts. A denied call returns a reason
51
+ to the child. A foreground child sends its prompts to you.
52
+
53
+ ## Settings
54
+
55
+ Namespace `subagents`. Open it with `/unipi:settings`. The package reads the
56
+ settings and agent files again each turn, so you do not need to restart Pi.
57
+
58
+ | Key | Default | What it does |
59
+ |---|---|---|
60
+ | `enabled` | `true` | Gives `run_subagent` and `read_subagent` to the agent. |
61
+ | `defaultModel` | empty | Model for `subagent_explore` and custom agents with no model. Empty uses the Fusion sidekick, then your model. |
62
+ | `defaultThinking` | `inherit` | Thinking level for the same agents. |
63
+ | `maxConcurrent` | `8` | Maximum children that run at the same time. Range 1 to 16. |
64
+
65
+ Set `UNIPI_SUBAGENT_MAX_DEPTH` to let children start children. The default is
66
+ `1`, which means no nesting.
67
+
68
+ ## Custom agents
69
+
70
+ Put a Markdown file in `~/.unipi/config/agents/` or in
71
+ `<project>/.unipi/config/agents/`. The project file wins. The body is the system
72
+ prompt. The front matter can have these keys: `name`, `description`, `model`,
73
+ `tools` or `allowed-tools`, `thinking` and `max-nesting`.
25
74
 
26
- States: running `◐`, completed `✓`, failed `✗`, cancelled `⊘` (its own state — "cancelled by you"
27
- when you pressed Esc or `x`).
75
+ The package keeps child sessions in
76
+ `~/.unipi/workspace/<id>/state/subagents/sessions/<lead-session-id>/`.
28
77
 
29
- ## Config
78
+ ## How it works
30
79
 
31
- `/unipi:settings → Subagents`: enabled, default subagent model (picker; empty = Fusion sidekick →
32
- your model), default thinking, max running at once, **Manage agents…**. Settings and agent files
33
- are re-read every turn — no restart.
80
+ Read [Delegation](../../docs/architecture/delegation.md) and
81
+ [Harness messages](../../docs/architecture/harness-messages.md).
34
82
 
35
- `/unipi:agents` — list profiles; create a custom agent step by step (name → this project / all
36
- projects → description → model → tools → prompt); edit, copy between global/project, or delete.
37
- Files use the Devin/Claude format (`name`, `description`, `model`, `allowed-tools`|`tools`,
38
- `thinking`, `max-nesting`; body = system prompt).
83
+ ## See also
39
84
 
40
- State: `~/.unipi/workspace/<id>/state/subagents/sessions/<lead-session-id>/` (`index.json` + one
41
- `<agent_id>.jsonl` child session per agent).
85
+ - [Fusion](../fusion/README.md)
86
+ - [Background tasks](../background-tasks/README.md)
87
+ - [Tools reference](../../docs/reference/tools.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/subagents",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Subagents for UniPi — Devin-model independent child agents",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",
@@ -9,8 +9,8 @@
9
9
  "test": "npx tsx --test src/__tests__/*.test.ts"
10
10
  },
11
11
  "dependencies": {
12
- "@pi-unipi/core": "3.0.0-alpha.21",
13
- "@pi-unipi/utility": "3.0.0-alpha.21",
12
+ "@pi-unipi/core": "3.0.0-alpha.22",
13
+ "@pi-unipi/utility": "3.0.0-alpha.22",
14
14
  "@earendil-works/pi-agent-core": "^0.87.1",
15
15
  "acorn": "8.18.0"
16
16
  },