pi-advisor-flow 0.4.0 → 0.5.1
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 +63 -0
- package/README.md +36 -68
- package/package.json +23 -11
- package/src/commands.ts +711 -184
- package/src/config.ts +54 -9
- package/src/model-stream.ts +133 -1
- package/src/session-state.ts +26 -2
- package/src/tools.ts +195 -66
- package/src/ui.ts +1060 -600
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,69 @@ All notable changes to this project are documented here.
|
|
|
4
4
|
|
|
5
5
|
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## 0.5.1
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- Updated CI and local validation to Bun 1.4.1 and kept the Pi compatibility packages at 0.84.4; Pi 0.85.0 currently adds an eager `/server` import without declaring the `@earendil-works/pi-server` dependency required by its coding-agent entry point.
|
|
12
|
+
- Kept benchmark tests out of the normal test run; use `bun run test:bench` to run them explicitly.
|
|
13
|
+
- Added Socket security dependency overrides and a `socket` script for `bunx socket optimize`.
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- Added a repository-only failsafe benchmark with an offline replay tier, a
|
|
18
|
+
24-item decision-point corpus, a fail-closed Pi/Harbor ReactBench adapter,
|
|
19
|
+
pinned live-tier controls, hard budget limits, and task-level
|
|
20
|
+
uplift/dominance reporting. See [Benchmarking](docs/benchmark.md).
|
|
21
|
+
- Added bounded local Harbor runtime controls for Apple Container experiments,
|
|
22
|
+
Docker build-cache cleanup, and a recorded one-hour agent timeout for complex
|
|
23
|
+
ReactBench tasks.
|
|
24
|
+
- Added a disposable, credential-free GitHub build compatibility layer for
|
|
25
|
+
pinned ReactBench Dockerfiles whose Git 2.39 transport is rejected by the
|
|
26
|
+
GitHub endpoint, with bounded pre-agent Harbor infrastructure retries and
|
|
27
|
+
per-attempt artifacts for transient build and transport failures.
|
|
28
|
+
- Derived the host Harbor command timeout from the bounded agent timeout and
|
|
29
|
+
made timeout cleanup terminate the full Harbor process group, including the
|
|
30
|
+
broker and descendants.
|
|
31
|
+
- Ensured configured Advisor reasoning effort reaches the provider-facing
|
|
32
|
+
request field used by current Pi AI adapters.
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
|
|
36
|
+
- Made `/advisor` open the available-model picker on first use or when either saved model is missing or unavailable; activation never silently selects a model outside the user's available catalog.
|
|
37
|
+
- Added a concise `/advisor` explanation of the Advisor's second-opinion role.
|
|
38
|
+
- Preserved Markdown formatting in visible Scout and nested Advisor thinking previews while retaining their speech-bubble cue. During streaming, incomplete Markdown delimiters display transiently until they close, which is expected behavior when thinking arrives incrementally.
|
|
39
|
+
- Adopted an explicit `/model` selection made before `/advisor` as the Executor on the next successful activation, without persisting ordinary model changes while the flow is off.
|
|
40
|
+
|
|
41
|
+
## [5.1.0] - 2026-09-04 [YANKED]
|
|
42
|
+
|
|
43
|
+
### Release status
|
|
44
|
+
|
|
45
|
+
- Published by mistake instead of `0.5.1`; withdrawn from npm and removed from Git, with `latest` restored to `0.5.0`.
|
|
46
|
+
|
|
47
|
+
## 0.5.0
|
|
48
|
+
|
|
49
|
+
### Changed
|
|
50
|
+
|
|
51
|
+
- Updated the development toolchain and Pi compatibility packages, including TypeScript 7, Node.js 26 type definitions, Pi 0.84.4 packages, and Bun 1.3.14 validation.
|
|
52
|
+
|
|
53
|
+
### Added
|
|
54
|
+
|
|
55
|
+
- Added a centered TUI overlay for `/advisor-manual` with an editable prefilled focus message, optional general review, a Git context selector bounded by the configured disclosure ceiling, and live Scout/Advisor progress without duplicate footer status text; non-TUI invocations remain immediate.
|
|
56
|
+
- Reworked `/advisor-settings` into a compact Pi-style searchable settings list with fuzzy search, arrow-key value adjustment, and immediate persistence for every valid change.
|
|
57
|
+
- Restored the animated Simple mode indicator and added a context-depth meter spanning recent history to the complete branch at `ALL`.
|
|
58
|
+
- Added enabled-by-default per-response usage detail display plus an independent, opt-in `showUsageFooter` setting for cumulative Advisor footer usage; both are presentation-only and do not change usage accounting.
|
|
59
|
+
|
|
60
|
+
### Performance
|
|
61
|
+
|
|
62
|
+
- Coalesced Advisor streaming UI updates to roughly 10–12 refreshes per second while flushing the latest partial state immediately on completion or error.
|
|
63
|
+
|
|
64
|
+
### Fixed
|
|
65
|
+
|
|
66
|
+
- Fixed `/advisor-settings` context-meter alignment and numeric controls so custom max-call limits advance to the next numeric option.
|
|
67
|
+
- Made blocked automatic-gate decisions honor the configured session, tool, or warning behavior.
|
|
68
|
+
- Allowed failed local Advisor outcome writes to be retried without consuming the advice.
|
|
69
|
+
|
|
7
70
|
## 0.4.0
|
|
8
71
|
|
|
9
72
|
### Added
|
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# pi-advisor
|
|
1
|
+
# [pi-advisor](https://github.com/philipbrembeck/pi-advisor)
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
4
|
|
|
@@ -8,111 +8,79 @@ A configurable second-opinion workflow for <a href="https://github.com/earendil-
|
|
|
8
8
|
|
|
9
9
|
</div>
|
|
10
10
|
|
|
11
|
-
|
|
12
11
|
 
|
|
13
12
|
|
|
14
13
|
`pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor challenges assumptions, exposes risks, and suggests verification steps without taking over or running tools.
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
Keep implementation on a fast model and borrow frontier reasoning only when decisions matter. [Read why this workflow is useful](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
|
|
16
|
+
|
|
17
|
+
## How it works
|
|
17
18
|
|
|
18
|
-
|
|
19
|
+
1. The Executor works on your task as usual.
|
|
20
|
+
2. It calls `ask_advisor`, or an enabled gate starts a review.
|
|
21
|
+
3. pi-advisor reconstructs the relevant conversation and allowed repository context.
|
|
22
|
+
4. The Advisor returns an opinion. The Executor decides what to adopt, changes the code, and validates it.
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
- **Configurable review gates** before plans, after repeated failures, and before declaring completion.
|
|
22
|
-
- **Automatic loop detection** for repeated tool calls, with explicit proceed, revise, or blocked decisions.
|
|
23
|
-
- **Separate model and reasoning controls** for the Executor and Advisor.
|
|
24
|
-
- **Advisor usage accounting** with per-response token/cost details and cumulative direct usage in the Pi footer and session summary.
|
|
25
|
-
- **Privacy controls** for conversation history, repository context, explicit tracked/untracked file handoff, tool results, secret redaction, and outcome logging.
|
|
26
|
-
- **Optional persistent activation, Simple mode, session summaries, and Herdr integration.**
|
|
27
|
-
- **EXPERIMENTAL Advisor Scout** that uses the configured Executor model to curate conversation evidence before every Advisor call.
|
|
24
|
+
Regular consultations do not block execution. Automatic loop gates are different: they can stop a repeated tool action or session based on your configured failure policy.
|
|
28
25
|
|
|
29
26
|
## Install
|
|
30
27
|
|
|
31
|
-
Requires Pi 0.84.1 or later
|
|
28
|
+
Requires Pi 0.84.1 or later.
|
|
32
29
|
|
|
33
30
|
```bash
|
|
34
|
-
# npm
|
|
35
31
|
pi install npm:pi-advisor-flow
|
|
32
|
+
```
|
|
36
33
|
|
|
37
|
-
|
|
38
|
-
pi install git:github.com/philipbrembeck/pi-advisor.git
|
|
34
|
+
You can also install from GitHub:
|
|
39
35
|
|
|
40
|
-
|
|
41
|
-
pi install /
|
|
36
|
+
```bash
|
|
37
|
+
pi install git:github.com/philipbrembeck/pi-advisor.git
|
|
42
38
|
```
|
|
43
39
|
|
|
44
|
-
|
|
40
|
+
Reload Pi after installing.
|
|
45
41
|
|
|
46
42
|
## Quick start
|
|
47
43
|
|
|
48
|
-
1. Run `/advisor` to enable the flow and register `ask_advisor`.
|
|
49
|
-
2. Run `/advisor-models` to choose the Executor and Advisor models. Current model and thinking-level selections appear first and ticked, so pressing Enter keeps them.
|
|
50
|
-
3. Run `/advisor-settings` to configure review gates, context, privacy, and limits.
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
Unknown fields in `advisor.json` are preserved for forward compatibility and reported as non-blocking warnings. Invalid recognized values remain errors, and Advisor commands show the configuration problem without crashing their handlers.
|
|
55
|
-
|
|
56
|
-
You can also enable the flow and select both models at once:
|
|
57
|
-
|
|
58
44
|
```text
|
|
59
|
-
/advisor
|
|
45
|
+
/advisor # Enable the Advisor Flow
|
|
46
|
+
/advisor-models # Choose the Executor and Advisor models
|
|
47
|
+
/advisor-settings # Configure behavior, modes, etc.
|
|
60
48
|
```
|
|
61
49
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
1. The Executor investigates the task and forms its own candidate direction.
|
|
65
|
-
2. For a consequential decision, stalled attempt, or final review, it calls `ask_advisor` with the reconstructed conversation and allowed repository context.
|
|
66
|
-
3. When Experimental Advisor Scout is enabled, the configured Executor model selects relevant conversation groups and writes a short, explicitly untrusted synthesis.
|
|
67
|
-
4. The Advisor receives selected verbatim evidence, required current-request context, and the unchanged deterministic repository, preference, draft, and attachment regions.
|
|
68
|
-
5. The Executor decides what to adopt, performs the work, and validates the result.
|
|
50
|
+
On first use, or whenever a saved model is unavailable, `/advisor` opens the same available-model picker as `/advisor-models`; it never silently chooses an unconfigured model. After activation, `/advisor` explains that the Advisor reviews the Executor's context without changing files or running tools.
|
|
69
51
|
|
|
70
|
-
|
|
52
|
+
From the Executor, `ask_advisor({})` requests a general review. A targeted `question` or concise `draft` can focus the review on a particular decision.
|
|
71
53
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed.
|
|
75
|
-
|
|
76
|
-
### Experimental Advisor Scout
|
|
77
|
-
|
|
78
|
-
Experimental Advisor Scout is off by default. Enable `Experimental Advisor Scout` in the advanced `/advisor-settings` screen or set `"advisorScoutEnabled": true` in the global `advisor.json`.
|
|
79
|
-
|
|
80
|
-
Scout runs before `ask_advisor`, `/advisor-manual`, and automatic Advisor gates. It uses the configured Executor model and Executor reasoning effort in a separate model call. This adds cost and latency, but can reduce cost in the Advisor call. The compact result shows the model, selection counts, and elapsed time; `Ctrl+O` shows bounded selected labels and the synthesis.
|
|
81
|
-
|
|
82
|
-
Scout receives a bounded manifest of conversation and tool-history groups after the normal tool disclosure, result-cap, and redaction policies are applied. The Scout manifest has its own fixed transport limit, while the reconstructed conversation remains bounded by the Advisor's remaining context budget after repository context; manifest metadata no longer consumes that Advisor conversation budget. A zero remaining budget produces no history groups. For a pending `ask_advisor` call, Scout receives only the allowlisted question and Git-context preference, never the draft or explicit attachment paths. Scout does not receive the deterministic Git context, draft, project preferences, or explicit tracked and untracked attachments. Those regions are appended later through their existing consent and cap rules.
|
|
83
|
-
|
|
84
|
-
This experiment adapts the context-boundary idea from Zhang et al., ["FastContext: Training Efficient Repository Explorer for Coding Agents"](https://arxiv.org/html/2606.14066v1). It is not a reproduction of FastContext. pi-advisor Scout curates conversation history only.
|
|
54
|
+
In the Settings, enable the Simple Mode for a quick start.
|
|
55
|
+
|
|
85
56
|
|
|
86
57
|
## Commands
|
|
87
58
|
|
|
88
|
-
| Command
|
|
89
|
-
|
|
|
90
|
-
| `/advisor`
|
|
91
|
-
| `/advisor-manual [focus]` |
|
|
92
|
-
| `/advisor-models`
|
|
93
|
-
| `/advisor-settings`
|
|
94
|
-
| `/advisor-off`
|
|
59
|
+
| Command | What it does |
|
|
60
|
+
| ------------------------- | ------------------------------------------------- |
|
|
61
|
+
| `/advisor` | Enable the flow; choose available models when needed. |
|
|
62
|
+
| `/advisor-manual [focus]` | Ask for an immediate second opinion. |
|
|
63
|
+
| `/advisor-models` | Choose the Executor and Advisor models. |
|
|
64
|
+
| `/advisor-settings` | Configure behavior, context, privacy, and limits. |
|
|
65
|
+
| `/advisor-off` | Disable the flow and persistent activation. |
|
|
95
66
|
|
|
96
|
-
|
|
67
|
+
### Experimental Advisor Scout
|
|
97
68
|
|
|
98
|
-
|
|
69
|
+
Advisor Scout is off by default. When enabled, the Executor model first selects relevant conversation history before the Advisor sees it. This adds a model call, latency, and cost. See the [configuration guide](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/configuration.md) for details.
|
|
99
70
|
|
|
100
|
-
|
|
71
|
+
## Privacy
|
|
101
72
|
|
|
102
|
-
|
|
73
|
+
Advisor requests can include user messages, tool calls, tool results, and repository information. `/advisor-settings` controls context, tool disclosure, redaction, and explicit file handoff. Secret redaction is off by default, and tools without an explicit policy use full context. Settings are global, so a project cannot silently change them.
|
|
103
74
|
|
|
104
|
-
|
|
75
|
+
Read [Privacy and data handling](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/privacy.md) before using pi-advisor with sensitive work.
|
|
105
76
|
|
|
106
77
|
## Documentation
|
|
107
78
|
|
|
108
79
|
- [Configuration and automatic loop gates](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/configuration.md)
|
|
109
80
|
- [Privacy and data handling](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/privacy.md)
|
|
110
81
|
- [Development](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/development.md)
|
|
111
|
-
- [
|
|
112
|
-
|
|
113
|
-
## Links
|
|
114
|
-
|
|
115
|
-
- [MIT License](LICENSE)
|
|
82
|
+
- [Benchmarking](docs/benchmark.md)
|
|
116
83
|
- [Changelog](CHANGELOG.md)
|
|
84
|
+
- [MIT License](LICENSE)
|
|
117
85
|
- [npm package](https://www.npmjs.com/package/pi-advisor-flow)
|
|
118
86
|
- [Why use an Advisor flow?](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-advisor-flow",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "Advanced Executor/Advisor flow for Pi, fully configurable and extendable.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|
|
@@ -28,33 +28,45 @@
|
|
|
28
28
|
"README.md"
|
|
29
29
|
],
|
|
30
30
|
"scripts": {
|
|
31
|
+
"bench:decisions": "bun bench/src/cli.ts decisions",
|
|
32
|
+
"bench:evaluate": "bun bench/src/cli.ts evaluate",
|
|
33
|
+
"bench:replay": "bun bench/src/cli.ts replay",
|
|
34
|
+
"bench:screen": "bun bench/src/cli.ts screen",
|
|
31
35
|
"format": "bunx ultracite fix --linter-enabled=false",
|
|
32
36
|
"lint": "bunx ultracite check",
|
|
33
37
|
"lint:fix": "bunx ultracite fix",
|
|
34
38
|
"package:check": "node scripts/check-package.mjs",
|
|
35
39
|
"prepare": "husky",
|
|
40
|
+
"socket": "bunx socket optimize",
|
|
36
41
|
"test": "bun test",
|
|
42
|
+
"test:bench": "bun --config=./bunfig.bench.toml test ./bench/test/",
|
|
37
43
|
"typecheck": "tsc --noEmit"
|
|
38
44
|
},
|
|
39
45
|
"lint-staged": {
|
|
40
46
|
"*.{json,jsonc,ts}": "bun run lint:fix --"
|
|
41
47
|
},
|
|
48
|
+
"resolutions": {
|
|
49
|
+
"is-unicode-supported": "npm:@socketregistry/is-unicode-supported@^1",
|
|
50
|
+
"safe-buffer": "npm:@socketregistry/safe-buffer@^1"
|
|
51
|
+
},
|
|
42
52
|
"overrides": {
|
|
43
53
|
"brace-expansion": "5.0.9",
|
|
54
|
+
"is-unicode-supported": "npm:@socketregistry/is-unicode-supported@^1",
|
|
55
|
+
"safe-buffer": "npm:@socketregistry/safe-buffer@^1",
|
|
44
56
|
"undici": "8.9.0"
|
|
45
57
|
},
|
|
46
58
|
"devDependencies": {
|
|
47
|
-
"@biomejs/biome": "2.5.
|
|
48
|
-
"@earendil-works/pi-ai": "^0.84.
|
|
49
|
-
"@earendil-works/pi-coding-agent": "^0.84.
|
|
50
|
-
"@earendil-works/pi-tui": "^0.84.
|
|
51
|
-
"@types/node": "^
|
|
52
|
-
"bun-types": "
|
|
59
|
+
"@biomejs/biome": "2.5.12",
|
|
60
|
+
"@earendil-works/pi-ai": "^0.84.4",
|
|
61
|
+
"@earendil-works/pi-coding-agent": "^0.84.4",
|
|
62
|
+
"@earendil-works/pi-tui": "^0.84.4",
|
|
63
|
+
"@types/node": "^26.4.1",
|
|
64
|
+
"bun-types": "1.4.1",
|
|
53
65
|
"husky": "^9.1.7",
|
|
54
|
-
"lint-staged": "^17.
|
|
55
|
-
"typebox": "^1.3.
|
|
56
|
-
"typescript": "^
|
|
57
|
-
"ultracite": "7.10.
|
|
66
|
+
"lint-staged": "^17.4.1",
|
|
67
|
+
"typebox": "^1.3.25",
|
|
68
|
+
"typescript": "^7.0.2",
|
|
69
|
+
"ultracite": "7.10.8"
|
|
58
70
|
},
|
|
59
71
|
"peerDependencies": {
|
|
60
72
|
"@earendil-works/pi-ai": "^0.84.1",
|