@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.
- package/CHANGELOG.md +13 -0
- package/README.md +193 -158
- package/package.json +21 -21
- package/packages/ask-user/README.md +82 -39
- package/packages/ask-user/index.ts +17 -2
- package/packages/ask-user/package.json +2 -2
- package/packages/ask-user/tools.ts +40 -6
- package/packages/autocomplete/README.md +46 -21
- package/packages/autocomplete/package.json +1 -1
- package/packages/background-tasks/README.md +69 -67
- package/packages/background-tasks/package.json +2 -2
- package/packages/btw/README.md +59 -13
- package/packages/btw/package.json +2 -2
- package/packages/compactor/README.md +78 -61
- package/packages/compactor/package.json +3 -3
- package/packages/core/README.md +98 -94
- package/packages/core/package.json +1 -1
- package/packages/footer/README.md +73 -116
- package/packages/footer/package.json +3 -3
- package/packages/fusion/README.md +83 -150
- package/packages/fusion/package.json +4 -4
- package/packages/info-screen/README.md +81 -69
- package/packages/info-screen/package.json +2 -2
- package/packages/input-shortcuts/README.md +47 -47
- package/packages/input-shortcuts/package.json +2 -2
- package/packages/kanboard/README.md +98 -182
- package/packages/kanboard/package.json +7 -7
- package/packages/long-horizon/README.md +98 -16
- package/packages/long-horizon/package.json +2 -2
- package/packages/long-horizon/src/gate.ts +9 -0
- package/packages/mcp/README.md +74 -62
- package/packages/mcp/package.json +2 -2
- package/packages/memory/README.md +93 -118
- package/packages/memory/package.json +3 -3
- package/packages/notify/README.md +85 -120
- package/packages/notify/package.json +2 -2
- package/packages/skill-registry/README.md +78 -44
- package/packages/skill-registry/package.json +2 -2
- package/packages/subagents/README.md +77 -31
- package/packages/subagents/package.json +3 -3
- package/packages/unipi/bundled.js +1210 -1099
- package/packages/updater/README.md +53 -55
- package/packages/updater/package.json +2 -2
- package/packages/utility/README.md +87 -78
- package/packages/utility/package.json +2 -2
- package/packages/utility/src/index.ts +12 -4
- package/packages/utility/src/render/delegated.ts +3 -0
- package/packages/utility/src/render/harness.ts +11 -2
- package/packages/utility/src/render/images.ts +51 -0
- package/packages/utility/src/render/reply-bg.ts +30 -2
- package/packages/utility/src/render/simple.ts +3 -0
- package/packages/utility/src/render/spacing.ts +13 -1
- package/packages/utility/src/settings.ts +2 -2
- package/packages/watchdog/README.md +66 -41
- package/packages/watchdog/package.json +3 -3
- package/packages/web-api/README.md +78 -126
- package/packages/web-api/package.json +2 -2
- package/packages/workflow/README.md +80 -103
- package/packages/workflow/package.json +2 -2
package/packages/btw/README.md
CHANGED
|
@@ -1,23 +1,69 @@
|
|
|
1
|
-
#
|
|
1
|
+
# BTW
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Ask a side question while the main agent works, without adding it to the main conversation.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`@pi-unipi/btw` · part of [UniPi](../../README.md)
|
|
6
6
|
|
|
7
|
-
##
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
23
|
+
|
|
24
|
+
To install this package alone:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pi install npm:@pi-unipi/btw
|
|
15
28
|
```
|
|
16
29
|
|
|
17
|
-
|
|
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
|
-
|
|
64
|
+
BTW comes from [pi-btw](https://github.com/Neuron-Mr-White/pi-btw) by Dan Bachelder.
|
|
20
65
|
|
|
21
|
-
|
|
66
|
+
## See also
|
|
22
67
|
|
|
23
|
-
|
|
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.
|
|
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.
|
|
40
|
+
"@pi-unipi/core": "3.0.0-alpha.22"
|
|
41
41
|
},
|
|
42
42
|
"pi": {
|
|
43
43
|
"extensions": [
|
|
@@ -1,87 +1,104 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Compactor
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
6
|
+
`@pi-unipi/compactor` · part of [UniPi](../../README.md)
|
|
6
7
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
38
|
+
## Agent tools
|
|
42
39
|
|
|
43
|
-
|
|
|
44
|
-
|
|
45
|
-
|
|
|
46
|
-
|
|
|
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
|
-
|
|
45
|
+
## Lossless summary
|
|
54
46
|
|
|
55
|
-
|
|
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
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
-
|
|
61
|
+
## Settings
|
|
67
62
|
|
|
68
|
-
|
|
63
|
+
Namespace `compactor`. Open it with `/unipi:settings`.
|
|
69
64
|
|
|
70
|
-
|
|
71
|
-
|
|
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
|
|
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
|
|
89
|
+
registerCompactionContext("my-module", () => (running ? "Task X is in progress" : null));
|
|
80
90
|
```
|
|
81
91
|
|
|
82
|
-
|
|
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
|
-
##
|
|
100
|
+
## See also
|
|
85
101
|
|
|
86
|
-
-
|
|
87
|
-
-
|
|
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.
|
|
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.
|
|
37
|
-
"@pi-unipi/info-screen": "3.0.0-alpha.
|
|
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": {
|
package/packages/core/README.md
CHANGED
|
@@ -1,108 +1,112 @@
|
|
|
1
|
-
#
|
|
1
|
+
# UniPi Core
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
6
|
+
`@pi-unipi/core` · part of [UniPi](../../README.md)
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+

|
|
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,
|
|
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: "
|
|
16
|
-
commands: ["
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
-
|
|
56
|
-
|
|
57
|
-
-
|
|
58
|
-
|
|
59
|
-
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
-
|
|
89
|
-
-
|
|
90
|
-
|
|
91
|
-
|
|
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)
|