@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,23 +1,69 @@
1
- # @pi-unipi/btw
1
+ # BTW
2
2
 
3
- `/unipi:btw [question]` opens an inline panel over the input area for a quick side question — the main agent keeps running and never sees any of it.
3
+ Ask a side question while the main agent works, without adding it to the main conversation.
4
4
 
5
- Each question runs in a fresh read-only pi session seeded from the main session's current branch (including in-progress tool calls). There is **no memory between btw questions** — earlier Q&As are not fed back. Page history lives only for the pi session and is cleared on new/resume/tree navigation. Nothing is written to the main session.
5
+ `@pi-unipi/btw` · part of [UniPi](../../README.md)
6
6
 
7
- ## Panel
7
+ ## What it does
8
8
 
9
+ - Opens a panel in place of the input box. The main agent continues to run.
10
+ - Answers each question in a new, read-only session. This session starts with a copy of the main conversation, with tool calls that are in progress.
11
+ - Gives the side session four tools only: `read`, `grep`, `find` and `ls`. It cannot run commands or change files.
12
+ - Uses the model and the thinking level of the main session.
13
+ - Writes nothing to the main session. The main agent never sees the question or the answer.
14
+ - Keeps no memory between questions. Each question starts again from the main conversation.
15
+
16
+ ## Quick start
17
+
18
+ UniPi installs this package:
19
+
20
+ ```bash
21
+ pi install npm:@pi-unipi/unipi
9
22
  ```
10
- ❭ <question> your question
11
- … / ✓ tool lines read-only tools only (read, grep, find, ls)
12
- Thinking.. while waiting
13
- answer rendered as markdown
14
- ❭ Ask a /btw… input (locked while streaming)
23
+
24
+ To install this package alone:
25
+
26
+ ```bash
27
+ pi install npm:@pi-unipi/btw
15
28
  ```
16
29
 
17
- - `Enter` ask · `↑`/`↓` (empty input) page earlier Q&As · `PgUp`/`PgDn` scroll long answers · `Ctrl+C` cancel the answer · `Esc` back to the chat (a streaming answer keeps running into history; reopen with `/unipi:btw`).
30
+ Then ask a question:
31
+
32
+ ```text
33
+ /unipi:btw what does the retry loop in client.ts do?
34
+ ```
35
+
36
+ ## Commands
37
+
38
+ | Command | What it does |
39
+ |---|---|
40
+ | `/unipi:btw [question]` | Opens the panel. If you give a question, the panel starts to answer it. |
41
+
42
+ In print mode (no UI), `/unipi:btw <question>` shows the answer as a notification. A question is necessary in this mode.
43
+
44
+ ## Panel keys
45
+
46
+ | Key | What it does |
47
+ |---|---|
48
+ | `Enter` | Asks the question in the input. It does nothing while an answer streams. |
49
+ | `↑` / `↓` | Shows an earlier or later question and answer. Works when the input is empty. |
50
+ | `PgUp` / `PgDn` | Scrolls a long answer. |
51
+ | `Ctrl+C` | Stops the answer that streams. If no answer streams, it closes the panel. |
52
+ | `Esc` | Closes the panel. An answer that streams continues and goes into the history. |
53
+
54
+ Run `/unipi:btw` again to open the history. Only one answer can stream at a time.
55
+
56
+ ## How it works
57
+
58
+ The panel shows each question, a line for each tool call, and the answer as markdown. The history stays in memory for the Pi session only. BTW clears it when a session starts or resumes, and when you move in the session tree.
59
+
60
+ If you want a change to your files, ask in the main conversation.
61
+
62
+ Older sessions can contain `btw-note` messages from an earlier BTW version. BTW still shows these messages and hides them from the model.
18
63
 
19
- Read-only: `read`, `grep`, `find`, `ls` only — no commands, no file changes. If you want something changed, ask in the main conversation.
64
+ BTW comes from [pi-btw](https://github.com/Neuron-Mr-White/pi-btw) by Dan Bachelder.
20
65
 
21
- Without a UI (print mode), `/unipi:btw <question>` prints the answer via notify.
66
+ ## See also
22
67
 
23
- Based on [pi-btw](https://github.com/Neuron-Mr-White/pi-btw) by Dan Bachelder.
68
+ - [Ask User](../ask-user/README.md)
69
+ - [Commands reference](../../docs/reference/commands.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/btw",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
5
5
  "type": "module",
6
6
  "main": "extensions/btw.ts",
@@ -37,7 +37,7 @@
37
37
  "@earendil-works/pi-tui": "^0.87.1"
38
38
  },
39
39
  "dependencies": {
40
- "@pi-unipi/core": "3.0.0-alpha.21"
40
+ "@pi-unipi/core": "3.0.0-alpha.22"
41
41
  },
42
42
  "pi": {
43
43
  "extensions": [
@@ -1,87 +1,104 @@
1
- # @pi-unipi/compactor
1
+ # Compactor
2
2
 
3
- Compaction for Pi that keeps work going. When the context fills up, the compactor replaces older messages with a summary. The full history stays in the session file, so nothing is lost and anything can be recalled.
3
+ Compactor makes the context smaller when it fills up, so long work can continue.
4
+ The full history stays in the session file, and the agent can search it.
4
5
 
5
- ## Methods
6
+ `@pi-unipi/compactor` · part of [UniPi](../../README.md)
6
7
 
7
- | Method | What it does | Cost |
8
- |---|---|---|
9
- | **Lossless** (default) | Builds a structured summary without a model call, in milliseconds. | Free |
10
- | **Model summary** | Pi's own model-written summary, with the active-work block added on top. | One model call |
11
-
12
- ### The lossless summary
13
-
14
- It is rebuilt from the **full** session history on every compaction, never merged onto the previous summary, so it cannot drift or grow over time. Sections, in the order a resuming model needs them:
15
-
16
- 1. **Active Work**: the goal, ralph loop or kanboard task in flight, supplied by those modules from their own state.
17
- 2. **Your Requests**: the user's own messages and answers to agent questions (`ask_user`: "question → answer"). Text that extensions send with the user role (loop prompts, nudges, notifications) is excluded.
18
- 3. **Latest State**: the most recent step and the last full progress report.
19
- 4. **Decisions & Constraints**: the user's instructions ("keep the orange theme"), corrections ("I did not ask for this"), and answers to agent questions. Half the room goes to the most recent ones, the rest to standing rules from anywhere in the session ("always…", "never…", "by default…"). Bug reports, pasted text and code blocks are left out.
20
- 5. **Files**: modified, created and read files, as relative paths.
21
- 6. **Project Knowledge**: what the agent learned that no message states: project notes it wrote or read (SKILL.md, AGENTS.md, DESIGN.md, docs), build/test/deploy commands it ran more than once, and the hosts it worked against. Switched with the Files section.
22
- 7. **Commits**: hash and subject.
23
- 8. **Open Errors**: recent failures that were not followed by a success.
24
- 9. **Recent Transcript**: a ranked slice of recent work.
25
-
26
- Each section has its own share of a hard budget (auto: 1.5k–4k tokens, scaling with session size). Credentials (typed passwords, API keys, bearer tokens) are redacted before anything is clipped; `session_recall` still has them. A closing line points the model to `session_recall`.
8
+ ## What it does
27
9
 
28
- ## In the TUI
10
+ - Replaces old messages with a summary when the context fills up.
11
+ - The default method, lossless, makes the summary with 0 model calls.
12
+ - The model summary method uses Pi's model-written summary. It adds the active
13
+ work block at the top. It costs one model call.
14
+ - Makes each lossless summary again from the full history. It does not merge
15
+ old summaries, so the summary does not grow over time.
16
+ - Removes passwords, API keys and bearer tokens from the summary.
17
+ `session_recall` can still find them.
18
+ - Shows a compaction card in the chat and a compaction count in the footer.
29
19
 
30
- - **Compaction card:** one line under Pi's own `[compaction]` block, e.g. `▌ Compacted 7.9k → 2.2k tokens · lossless · at 3%`. ctrl+o expands it: method, trigger, what was kept verbatim, summary sections. It is a custom entry: shown, never sent to the model.
31
- - **Footer strip** (under the input): `5 compactions · 47k→15k · just now`, hidden until the first compaction. With the glance frame off, the `compactions` segment shows the same (`cmp 5× 47k→15k · 1m`).
32
- - **Info screen** (`/unipi:info` → Compactor): method and trigger settings, compactions by method, tokens before → after, the last compaction.
20
+ ## Quick start
33
21
 
34
- ## When it compacts
22
+ 1. Install UniPi: `pi install npm:@pi-unipi/unipi`. You can also install this
23
+ package alone: `pi install npm:@pi-unipi/compactor`.
24
+ 2. Work as usual. Compaction starts at Pi's context limit.
25
+ 3. Type `/unipi:compact-stats` to see the tokens that compaction saved.
35
26
 
36
- - **Pi's context limit** (default): Pi decides when, using its own compaction settings (`compaction.reserveTokens`, per-model overrides). The compactor decides what the summary contains. Pi continues the run after compacting.
37
- - **At a percentage**: compacts once context use reaches the set percentage. This happens at a turn boundary, so running goal, ralph and kanboard loops are not interrupted.
27
+ ## Commands
38
28
 
39
- ## Settings
29
+ | Command | What it does |
30
+ |---|---|
31
+ | `/unipi:compact-vcc [keep:N]` | Runs lossless compaction now. `keep:N` keeps the last N user turns. |
32
+ | `/unipi:compact-by-llm [focus]` | Runs model summary compaction now. The text sets the focus of the summary. |
33
+ | `/unipi:session-recall <query>` | Searches the full session history. Add `scope:all` or `page:N`. |
34
+ | `/unipi:compact-stats` | Shows the compactions and the saved tokens of this session. |
35
+ | `/unipi:compact-doctor` | Checks the settings, Pi's compaction switch and old files. |
36
+ | `/unipi:compact-help` | Shows a list of compactor commands. |
40
37
 
41
- `/unipi:settings → Compactor`
38
+ ## Agent tools
42
39
 
43
- | Setting | Default | |
44
- |---|---|---|
45
- | Method | lossless | lossless · model summary |
46
- | Pi's /compact | same as Method | What Pi's built-in `/compact` does |
47
- | When | Pi's context limit | Or: at a percentage |
48
- | Percentage | 80 | Used when When = at a percentage |
49
- | Notifications | on | The compaction card after automatic compactions (commands always show it); failures still notify |
50
-
51
- **Advanced compaction** (collapsed): smart keep tail, summary budget, per-section toggles, percentage cooldown and repeat growth, extra instructions for model summaries, debug output.
40
+ | Tool | What it does |
41
+ |---|---|
42
+ | `session_recall` | Searches the session with keywords or a regex. It also finds messages that compaction removed. `expand` gives full entries by index. |
43
+ | `context_budget` | Gives the percent of the context in use and the tokens left. |
52
44
 
53
- Configs from before the rework are translated automatically: `overrideDefaultCompaction: false` becomes Method = model summary, and `autoCompaction.enabled` becomes When = at a percentage.
45
+ ## Lossless summary
54
46
 
55
- ## Commands
47
+ The summary has these sections. Each section gets a part of a token budget. The
48
+ auto budget is 1.5k to 4k tokens. It grows with the session size.
56
49
 
57
- | Command | |
58
- |---|---|
59
- | `/unipi:compact-vcc [keep:N]` | Lossless compaction now; `keep:N` keeps the last N user turns |
60
- | `/unipi:compact-by-llm [focus]` | Model-summary compaction now; optional text focuses the summary |
61
- | `/unipi:session-recall <query>` | Search the full session history (`scope:all`, `page:N`) |
62
- | `/unipi:compact-stats` | This session's compactions and savings |
63
- | `/unipi:compact-doctor` | Check settings, Pi's compaction switch, leftovers |
64
- | `/unipi:compact-help` | Command summary |
50
+ 1. Active Work: the goal, ralph loop or kanboard task that runs now.
51
+ 2. Your Requests: your messages and your `ask_user` answers.
52
+ 3. Latest State: the last step and the last progress report.
53
+ 4. Decisions & Constraints: your instructions, corrections and rules.
54
+ 5. Files: changed, new and read files, with relative paths.
55
+ 6. Lessons: notes that the agent wrote, such as memory notes and diagnoses.
56
+ 7. Project Knowledge: project notes, repeated build and test commands, hosts.
57
+ 8. Commits: hash and subject.
58
+ 9. Open Errors: recent failures with no later success.
59
+ 10. Recent Transcript: a ranked part of the recent work.
65
60
 
66
- Removed: `/unipi:compact` and `/unipi:lossless-compact` (use `/unipi:compact-vcc`), `/unipi:compact-recall` (use `/unipi:session-recall`), `/unipi:compact-jev` and the jev method (a saved `method: "jev"` behaves as lossless).
61
+ ## Settings
67
62
 
68
- ## Tools
63
+ Namespace `compactor`. Open it with `/unipi:settings`.
69
64
 
70
- - `session_recall`: keyword/regex search over the session branch, including compacted-away messages. `expand` returns full entries by index (the `#N` refs in summaries); `mode: "touched"` lists files.
71
- - `context_budget`: how full the context is.
65
+ | Key | Default | What it does |
66
+ |---|---|---|
67
+ | `method` | `vcc` | `vcc` is lossless. `llm` is the model summary. |
68
+ | `piCompact` | `follow` | Sets what Pi's `/compact` does. `follow` uses `method`. |
69
+ | `trigger` | `pi` | `pi` uses Pi's context limit. `percent` compacts at `thresholdPercent`. |
70
+ | `thresholdPercent` | `80` | Context percent for the `percent` trigger. Range 30 to 95. |
71
+ | `notify` | `true` | Shows the card after an automatic compaction. Failures always show. |
72
+ | `smartKeepTail` | `true` | Keeps more recent turns when the kept tail is very small. |
73
+ | `summaryBudgetTokens` | `0` | Lossless summary size. `0` is auto. |
74
+ | `sections.<name>` | `true` | Turns one summary section on or off. |
75
+ | `cooldownMs` | `60000` | Minimum time between two `percent` compactions. |
76
+ | `repeatMinGrowthTokens` | `4000` | New tokens needed before the next `percent` compaction. |
77
+ | `llmInstructions` | empty | More instructions for the model summary. |
78
+ | `debug` | `false` | Writes diagnostics to `/tmp/compactor-debug.json`. |
79
+
80
+ The `percent` trigger compacts at a turn boundary. Goal, ralph and kanboard
81
+ loops continue without a stop.
72
82
 
73
83
  ## For other modules
74
84
 
75
- Register an active-work provider so summaries lead with your state:
85
+ Register an active work provider. The summary then starts with your state.
76
86
 
77
87
  ```ts
78
88
  import { registerCompactionContext } from "@pi-unipi/core";
79
- registerCompactionContext("my-module", () => (running ? "Task X is in progress — …" : null));
89
+ registerCompactionContext("my-module", () => (running ? "Task X is in progress" : null));
80
90
  ```
81
91
 
82
- Compactions applied at a turn boundary (percentage trigger) do not fire Pi's `session_compact`; listen to `UNIPI_EVENTS.COMPACTOR_COMPACTED` to react to every compaction.
92
+ A turn-boundary compaction does not fire Pi's `session_compact` event. Listen to
93
+ `UNIPI_EVENTS.COMPACTOR_COMPACTED` to get each compaction.
94
+
95
+ ## How it works
96
+
97
+ Read [Compaction](../../docs/architecture/compaction.md) and
98
+ [Prefix cache](../../docs/architecture/prefix-cache.md).
83
99
 
84
- ## Removed in 3.0
100
+ ## See also
85
101
 
86
- - **Session continuity**: the SQLite event log and the hidden snapshot restored after compaction. It logged every session under one shared ID, so snapshots mixed projects and grew to ~60k tokens. The summary now derives files, errors and commits from the session itself. `/unipi:compact-doctor` reports the old `~/.unipi/db/compactor` directory, which can be deleted.
87
- - **Sandbox tools** (`sandbox`, `sandbox_file`, `sandbox_batch`), the `compact` tool (it never compacted), `compactor_stats` / `compactor_doctor` tools (use the commands), presets, and the inert strategy modes.
102
+ - [Commands reference](../../docs/reference/commands.md)
103
+ - [Settings reference](../../docs/reference/settings.md)
104
+ - [Memory](../memory/README.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/compactor",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Compaction for Pi — lossless zero-LLM or model summaries, rebuilt from full history, with session recall",
5
5
  "type": "module",
6
6
  "main": "src/index.ts",
@@ -33,8 +33,8 @@
33
33
  "access": "public"
34
34
  },
35
35
  "dependencies": {
36
- "@pi-unipi/core": "3.0.0-alpha.21",
37
- "@pi-unipi/info-screen": "3.0.0-alpha.21",
36
+ "@pi-unipi/core": "3.0.0-alpha.22",
37
+ "@pi-unipi/info-screen": "3.0.0-alpha.22",
38
38
  "@earendil-works/pi-agent-core": "^0.87.1"
39
39
  },
40
40
  "peerDependencies": {
@@ -1,108 +1,112 @@
1
- # @pi-unipi/core
1
+ # UniPi Core
2
2
 
3
- Shared infrastructure for every Unipi package. Provides constants, event types, and utility functions so packages can discover each other without tight coupling.
3
+ Core gives every UniPi package one set of constants, event names, settings and
4
+ file helpers, so packages work together without direct imports.
4
5
 
5
- Other packages import from `@pi-unipi/core` to emit events, read module names, and use common file operations. Without it, each package would need its own event definitions and utilities.
6
+ `@pi-unipi/core` · part of [UniPi](../../README.md)
6
7
 
7
- ## Usage
8
+ ![Unicrab, the UniPi mascot](../../docs/assets/unicrab-pixel.png)
9
+
10
+ ## What it does
11
+
12
+ - Defines the shared event names in `UNIPI_EVENTS` and module names in `MODULES`.
13
+ - Gives the settings engine. Each module registers a namespace. The
14
+ `/unipi:settings` hub shows all namespaces.
15
+ - Gives the state layout under `~/.unipi/`. Each module gets `global`, `config`,
16
+ `state` and `session` folders.
17
+ - Gives the turn arbiter, harness message metadata and the shared TUI kit.
18
+ - Gives the Unicrab hints engine. The `@pi-unipi/utility` package installs it.
19
+
20
+ Core is a library. Its `pi` field registers no extensions. You get it when you
21
+ install UniPi:
22
+
23
+ ```bash
24
+ pi install npm:@pi-unipi/unipi
25
+ ```
26
+
27
+ ## Developer API
28
+
29
+ Import from `@pi-unipi/core`. Use `emitEvent` to send events on the Pi event bus.
30
+ It returns `false` and does not throw if the emit fails.
8
31
 
9
32
  ```typescript
10
- import { UNIPI_EVENTS, MODULES, sanitize, emitEvent } from "@pi-unipi/core";
33
+ import { UNIPI_EVENTS, MODULES, emitEvent, sanitize } from "@pi-unipi/core";
11
34
 
12
- // Emit module ready event
13
35
  emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
14
36
  name: MODULES.WORKFLOW,
15
- version: "1.0.0",
16
- commands: ["brainstorm", "plan"],
37
+ version: "3.0.0",
38
+ commands: ["unipi:plan"],
17
39
  tools: [],
18
40
  });
19
41
 
20
- // Use shared utilities
21
42
  const safeName = sanitize("my/feature: branch");
22
43
  ```
23
44
 
24
- ## Hints (Unicrab)
25
-
26
- The hints system introduces **Unicrab**, a friendly pixel-crab mascot providing contextual onboarding and workflow guidance:
27
-
28
- - **What shows when**:
29
- - **Startup**: One least-shown, least-recent hint on `session_start` (whatsnew hints prioritized after version upgrades; lore and whatsnew excluded from regular startup rotation).
30
- - **Start Screen**: If `hints.header` is enabled, a custom startup header features 22×10 (≥72 cols) or 14×6 (40–71 cols) truecolor half-block crab pixel art, colored wordmark, and random lore line.
31
- - **Widget**: A compact single-row hint above the editor (`<crab> <text> <category · alt+h ›>`) rendered with a 7-column half-block mascot in truecolor/256-color (or opt-in Kitty image mode).
32
- - **Events**: Contextual hints triggered by derived thresholds (`hints:context-high`, `hints:long-bash`, `hints:tool-errors`, `hints:long-prompt`, `hints:remember`, `hints:image-input`) and bus events. Capped at 4 event hints per session; never replaces a hint shown in the same turn.
33
- - **Shortcuts**:
34
- - `Alt+H`: Cycle to the next startup hint (ordered least-shown first).
35
- - `Alt+Shift+H`: Navigate backward in the session hint history stack.
36
- - **Commands**:
37
- - `/unipi:hint`: Opens an interactive hub-kit overlay browser with live filtering, category headers, and seen/unseen/learned status tags.
38
- - `/unipi:hint next`: Same as Alt+H.
39
- - `/unipi:hint reset`: Resets show counts and learned state in `~/.unipi/global/hints/hints.json`.
40
- - **Settings (`hints` namespace)**:
41
- - `hints.enabled` (boolean, default true)
42
- - `hints.header` (boolean, default true): Unicrab start screen banner.
43
- - `hints.crab` (enum: `auto` | `blocks` | `image`, default `auto`): `auto` resolves to half-blocks; `image` is opt-in experimental Kitty terminal graphics.
44
- - `hints.reset` (action): Clears hint history.
45
- - **Lines (`src/hints/lines.ts`)**:
46
- - Central lines file containing audited hints across command, shortcut, setting, capability, explain, trouble, whatsnew, workflow, and lore categories.
47
- - **Rule**: Every named command, key, setting, or tool must be strictly verified against package source code before inclusion.
48
-
49
- ## Exports
50
-
51
- ### Constants
52
-
53
- - `UNIPI_PREFIX` — Command prefix (`unipi:`)
54
- - `MODULES` — All module names
55
- - `WORKFLOW_COMMANDS` — Workflow command names
56
- - `RALPH_COMMANDS` — Ralph command names
57
- - `RALPH_TOOLS` — Ralph tool names
58
- - `RALPH_DEFAULTS` — Default ralph settings
59
- - `RALPH_DIR` — Ralph state directory
60
- - `RALPH_COMPLETE_MARKER` — Loop completion marker
61
-
62
- ### Events
63
-
64
- - `UNIPI_EVENTS` — Event names
65
- - `UnipiModuleEvent` — Module ready/gone payload
66
- - `UnipiWorkflowEvent` — Workflow start/end payload
67
- - `UnipiRalphLoopEvent` — Ralph loop start/end payload
68
- - `UnipiRalphIterationEvent` — Ralph iteration payload
69
- - `UnipiStatusRequestEvent` / `UnipiStatusResponseEvent` — Status payloads
70
-
71
- ### Utilities
72
-
73
- - `sanitize(name)` — Sanitize string for filenames
74
- - `ensureDir(path)` — Create parent directories
75
- - `tryDelete(path)` — Safe file deletion
76
- - `tryRead(path)` — Safe file read
77
- - `safeMtimeMs(path)` — File modification time
78
- - `tryRemoveDir(path)` — Safe directory removal
79
- - `resolvePath(cwd, path)` — Resolve relative/absolute paths
80
- - `fileExists(path)` — Check file existence
81
- - `writeFile(path, content)` — Write file with dir creation
82
- - `readJson<T>(path)` — Read JSON file
83
- - `writeJson(path, data)` — Write JSON file
84
- - `randomId(length)` — Generate random ID
85
- - `now()` — ISO timestamp
86
- - `parseArgs(str)` — Parse quoted arguments
87
- - `getPackageVersion(dir)` — Read package version
88
- - `isModuleAvailable(cwd, name)` — Check if npm module exists
89
- - `emitEvent(pi, name, payload)` — Safe event emission
90
-
91
- ## How Packages Use Core
92
-
93
- Every Unipi package depends on `@pi-unipi/core`. On load, each package:
94
-
95
- 1. Imports `MODULES` to register its own name
96
- 2. Imports `UNIPI_EVENTS` to subscribe to lifecycle events
97
- 3. Calls `emitEvent(pi, UNIPI_EVENTS.MODULE_READY, ...)` to announce itself
98
- 4. Uses utility functions for file I/O and path resolution
99
-
100
- This creates a loose coupling — packages discover each other through events, not direct imports.
101
-
102
- ## Configuration
103
-
104
- Core has no configuration. It's a pure utility layer.
105
-
106
- ## License
107
-
108
- MIT
45
+ | Area | Main exports |
46
+ |---|---|
47
+ | Constants | `UNIPI_PREFIX`, `MODULES`, `WORKFLOW_COMMANDS`, `MEMORY_TOOLS`, `COMPACTOR_TOOLS`, other `*_COMMANDS` and `*_DEFAULTS` |
48
+ | Events | `UNIPI_EVENTS` and payload types such as `UnipiModuleEvent`, `UnipiCompactionEvent`, `UnipiMemoryStoredEvent` |
49
+ | Settings | `registerSettings`, `getSettings`, `setSettings`, `unsetSettings`, `openSettingsHub` |
50
+ | State paths | `unipiRoot`, `workspaceRoot`, `stateDir`, `statePath`, `sessionId` |
51
+ | Turn arbiter | `installArbiter`, `registerNudgeProvider`, `registerWaitSource`, `onSettleDecision` |
52
+ | Harness messages | `sendHarnessUserMessage`, `readHarnessMeta`, `harnessToolResultDetails` |
53
+ | Command runners | `registerCommandRunner`, `runCommandByName` |
54
+ | File helpers | `sanitize`, `ensureDir`, `tryRead`, `tryDelete`, `readJson`, `writeJson`, `fileExists`, `resolvePath` |
55
+ | Other helpers | `randomId`, `now`, `parseArgs`, `getPackageVersion`, `formatTokens`, `compareVersions` |
56
+
57
+ Settings files use this layout. The project file wins over the global file.
58
+
59
+ | Scope | Path |
60
+ |---|---|
61
+ | Global settings | `~/.unipi/config/<namespace>/config.json` |
62
+ | Project settings | `<project>/.unipi/config/<namespace>/config.json` |
63
+ | Cross-project state | `~/.unipi/global/<module>/` |
64
+ | Workspace state | `~/.unipi/workspace/<id>/state/<module>/` |
65
+ | Session state | `~/.unipi/workspace/<id>/sessions/<sid>/<module>/` |
66
+
67
+ ## Unicrab hints
68
+
69
+ Unicrab is the UniPi mascot. The hints engine shows one short tip above the
70
+ editor.
71
+
72
+ - At startup, the engine shows the tip with the lowest show count. After a
73
+ version upgrade, it shows a "what's new" tip first.
74
+ - The start screen shows the Unicrab pixel art, the version and a random lore
75
+ line. It needs 40 columns or more. At 72 columns or more, it shows the large crab.
76
+ - Some events show a tip. Examples are context use of 70% or more, a `bash`
77
+ run of 30 seconds or more, and 3 tool errors in a row.
78
+ - The engine shows 4 event tips or fewer per session. It does not replace a tip
79
+ in the same turn.
80
+ - The engine keeps show counts in `~/.unipi/global/hints/hints.json`.
81
+
82
+ | Command or key | What it does |
83
+ |---|---|
84
+ | `/unipi:hint` | Opens a hint browser with a search filter. |
85
+ | `/unipi:hint next` | Shows the next startup tip. |
86
+ | `/unipi:hint reset` | Clears show counts and learned state. |
87
+ | `Alt+H` | Shows the next startup tip. |
88
+ | `Alt+Shift+H` | Goes back in the tip history of this session. |
89
+
90
+ | Key | Default | What it does |
91
+ |---|---|---|
92
+ | `hints.enabled` | `true` | Shows tips above the editor. |
93
+ | `hints.header` | `true` | Shows the Unicrab start screen. |
94
+ | `hints.crab` | `auto` | Sets the mascot style: `auto`, `blocks` or `image`. `image` uses Kitty graphics and is experimental. |
95
+ | `hints.reset` | action | Clears the hint history. |
96
+
97
+ Each hint text is in `src/hints/lines.ts`. Before you add a hint, find each
98
+ command, key, setting and tool name in the source.
99
+
100
+ ## How it works
101
+
102
+ Packages find each other through events on the Pi event bus. They do not import
103
+ each other. Read the [architecture overview](../../docs/architecture/README.md),
104
+ the [event bus](../../docs/architecture/event-bus.md) and the
105
+ [turn arbiter](../../docs/architecture/turn-arbiter.md).
106
+
107
+ ## See also
108
+
109
+ - [Harness messages](../../docs/architecture/harness-messages.md)
110
+ - [Settings reference](../../docs/reference/settings.md)
111
+ - [Shortcuts reference](../../docs/reference/shortcuts.md)
112
+ - [Glossary](../../docs/reference/glossary.md)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-unipi/core",
3
- "version": "3.0.0-alpha.21",
3
+ "version": "3.0.0-alpha.22",
4
4
  "description": "Shared utilities, event types, and constants for Unipi extension suite",
5
5
  "type": "module",
6
6
  "license": "MIT",