Skip to content

Commit 6c35e82

Browse files
salman1993ampagent
andauthored
fix(acp): improve hints in pi agent setup guide (#7594)
## Summary Handle missing Pi adapter setup and update its install guidance. ### Related issue None found. ### Testing No manual testing. Generated with Amp --------- Signed-off-by: Salman Mohammed <[email protected]> Co-authored-by: Amp <[email protected]>
1 parent f3940ff commit 6c35e82

5 files changed

Lines changed: 87 additions & 57 deletions

File tree

‎crates/buzz-acp/TESTING.md‎

Lines changed: 10 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,29 @@
11
# Pi adapter integration
22

3-
Buzz's Pi preset uses [salman1993/pi-acp](https://github.com/salman1993/pi-acp).
4-
Requires Node.js 22 or newer. Install Pi and configure its model provider,
5-
then install the adapter directly from the fork:
3+
Buzz uses the [buzz-pi-acp fork](https://github.com/salman1993/buzz-pi-acp).
4+
Install Node.js 22 or newer, configure Pi, and install the latest development
5+
adapter from the fork's `main` branch:
66

77
```sh
88
npm install -g @earendil-works/pi-coding-agent
99
pi
10-
npm install -g --install-links=true git+https://github.com/salman1993/pi-acp.git#main
10+
npm install -g --install-links=true 'git+https://github.com/salman1993/buzz-pi-acp.git#main'
1111
```
1212

13-
Restart Buzz, then select **Pi** as the agent harness. Buzz starts `buzz-pi-acp`
14-
automatically. Run the same adapter install command again to update it.
15-
The unscoped `npm install -g pi-acp` command installs the upstream package,
16-
without these extensions. Use fresh sessions to replace old user-framed
17-
standing instructions.
13+
This test setup intentionally tracks `main`; the Desktop runtime catalog pins a
14+
reviewed adapter revision for users.
1815

19-
Buzz adds `-- --skill <harness-cwd>/.agents/skills` when launching `buzz-pi-acp`.
20-
An existing separator and explicit Pi options are preserved. Managed agents
21-
run from the Buzz nest (normally `~/.buzz`): Desktop sets the `buzz-acp` child
22-
CWD through `default_agent_workdir()`, and adapters inherit it. The default
23-
skill directory is that launch workspace's `.agents/skills`. Standalone CLI
24-
launches use the caller's working directory.
25-
The path is fixed at adapter launch and applies to every Pi subprocess.
16+
Make sure `pi` and `buzz-pi-acp` are on PATH, then restart Buzz.
2617

27-
The full composed session prompt is sent as a replacement string through the
28-
provisional `session/new.params._meta.systemPrompt` field. Buzz recognizes
29-
`buzz-pi-acp` by the agent name returned during initialization, regardless of
30-
protocol version. Upstream `pi-acp` does not receive this fork-specific metadata.
31-
No custom capability negotiation or legacy Pi prompt fallback is used.
32-
Session titles continue to use `_meta.sessionTitle`.
33-
34-
## Validation
35-
36-
Activate Hermit from the Buzz repository root, then run the package tests:
18+
## Tests
3719

3820
```sh
39-
. ./bin/activate-hermit
4021
cargo test -p buzz-acp
4122
```
4223

43-
To exercise the real adapter through Buzz's production session composer:
24+
Run the ignored real-adapter test with a built fork checkout:
4425

4526
```sh
46-
BUZZ_TEST_PI_ACP=/absolute/pi-acp/dist/index.js \
27+
BUZZ_TEST_PI_ACP=/absolute/buzz-pi-acp/dist/index.js \
4728
cargo test -p buzz-acp real_pi_preserves -- --ignored
4829
```
49-
50-
This test requires Node and Pi on PATH. It isolates HOME and Pi settings,
51-
disables extensions and context files, and uses a synthetic transcript without
52-
model calls. It inspects Pi's effective prompt through RPC HTML export after
53-
switching sessions and restarting the adapter. Base, persona, team, core memory,
54-
huddle, canvas, and the extra skill must each appear once, without another
55-
session's instructions or Pi's default coding preamble.
56-
57-
HTML export reports the exporting process's current system prompt. It cannot
58-
recover a historical prompt from an old transcript alone.

‎crates/buzz-acp/src/setup_mode.rs‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,8 @@ pub(crate) enum RequirementPayload {
116116
},
117117
/// Git for Windows is missing; open Agent runtimes for the installation guide.
118118
GitBash,
119+
/// A custom harness command could not be resolved in the current PATH.
120+
MissingBinary { command: String },
119121
}
120122

121123
impl RequirementPayload {
@@ -190,6 +192,9 @@ impl RequirementPayload {
190192
RequirementPayload::GitBash => {
191193
"install Git for Windows (open Agent runtimes in Settings to diagnose)".to_string()
192194
}
195+
RequirementPayload::MissingBinary { command } => {
196+
format!("install `{command}` or add it to PATH")
197+
}
193198
}
194199
}
195200
}
@@ -262,13 +267,19 @@ impl SetupPayload {
262267
.requirements
263268
.iter()
264269
.all(|r| matches!(r, RequirementPayload::CliConfigInvalid { .. }));
270+
let all_missing_binary = self
271+
.requirements
272+
.iter()
273+
.all(|r| matches!(r, RequirementPayload::MissingBinary { .. }));
265274
let any_external = self
266275
.requirements
267276
.iter()
268277
.any(|r| matches!(r, RequirementPayload::CliConfigInvalid { .. }));
269278

270279
let footer = if has_doctor_requirement {
271280
"Open Agent runtimes in Settings, install Git for Windows, then re-check and restart the agent.".to_string()
281+
} else if all_missing_binary {
282+
"Install the missing binary or update PATH, then restart Buzz.".to_string()
272283
} else if all_external {
273284
// All requirements are external config files — Edit Agent cannot
274285
// help. Don't send the user there.
@@ -739,6 +750,23 @@ mod tests {
739750
));
740751
}
741752

753+
#[test]
754+
fn setup_payload_deserializes_missing_binary_requirement() {
755+
let payload = SetupPayload::from_raw_env_value(Some(
756+
r#"{"agent_name":"Carol","agent_pubkey":"test","requirements":[{"surface":"missing_binary","command":"buzz-pi-acp"}]}"#.to_string(),
757+
))
758+
.unwrap()
759+
.expect("missing_binary payload must parse");
760+
assert!(matches!(
761+
payload.requirements.as_slice(),
762+
[RequirementPayload::MissingBinary { command }] if command == "buzz-pi-acp"
763+
));
764+
let body = payload.nudge_body();
765+
assert!(body.contains("install `buzz-pi-acp` or add it to PATH"));
766+
assert!(body.contains("restart Buzz"));
767+
assert!(!body.contains("Open Edit Agent"));
768+
}
769+
742770
#[tokio::test]
743771
async fn authorized_workflow_nudge_mentions_effective_owner_not_relay_signer() {
744772
let agent_keys = nostr::Keys::generate();

‎desktop/src-tauri/src/managed_agents/discovery/presets.rs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,8 @@ pub(super) const PRESET_HARNESSES: &[PresetHarness] = &[
109109
label: "Pi",
110110
command: "buzz-pi-acp",
111111
args: &[],
112-
install_instructions_url: "https://github.com/salman1993/pi-acp",
113-
install_hint: "Requires Node.js 22 or newer. Install the Pi ACP adapter with `npm install -g --install-links=true git+https://github.com/salman1993/pi-acp.git#main`. Restart Buzz, then select Pi as the agent harness. Run the same install command again to update the adapter.",
112+
install_instructions_url: "https://github.com/salman1993/buzz-pi-acp",
113+
install_hint: "Requires Node.js 22 or newer. Install the Pi ACP adapter with `npm install -g --install-links=true 'git+https://github.com/salman1993/buzz-pi-acp.git#86b201e'`. Make sure `buzz-pi-acp` is on PATH, then restart Buzz.",
114114
underlying_cli: Some("pi"),
115115
underlying_cli_install_hint: Some(
116116
"Install Pi with `npm install -g @earendil-works/pi-coding-agent`, then run `pi` to configure its model provider.",
@@ -434,11 +434,11 @@ mod tests {
434434
assert!(adapter_missing.default_args.is_empty());
435435
assert_eq!(
436436
adapter_missing.install_hint,
437-
"Requires Node.js 22 or newer. Install the Pi ACP adapter with `npm install -g --install-links=true git+https://github.com/salman1993/pi-acp.git#main`. Restart Buzz, then select Pi as the agent harness. Run the same install command again to update the adapter."
437+
"Requires Node.js 22 or newer. Install the Pi ACP adapter with `npm install -g --install-links=true 'git+https://github.com/salman1993/buzz-pi-acp.git#86b201e'`. Make sure `buzz-pi-acp` is on PATH, then restart Buzz."
438438
);
439439
assert_eq!(
440440
adapter_missing.install_instructions_url,
441-
"https://github.com/salman1993/pi-acp"
441+
"https://github.com/salman1993/buzz-pi-acp"
442442
);
443443

444444
let cli_missing = preset_catalog_entry(preset, |command| {
@@ -462,7 +462,7 @@ mod tests {
462462
);
463463
assert_eq!(
464464
not_installed.install_hint,
465-
"Install Pi with `npm install -g @earendil-works/pi-coding-agent`, then run `pi` to configure its model provider. Requires Node.js 22 or newer. Install the Pi ACP adapter with `npm install -g --install-links=true git+https://github.com/salman1993/pi-acp.git#main`. Restart Buzz, then select Pi as the agent harness. Run the same install command again to update the adapter."
465+
"Install Pi with `npm install -g @earendil-works/pi-coding-agent`, then run `pi` to configure its model provider. Requires Node.js 22 or newer. Install the Pi ACP adapter with `npm install -g --install-links=true 'git+https://github.com/salman1993/buzz-pi-acp.git#86b201e'`. Make sure `buzz-pi-acp` is on PATH, then restart Buzz."
466466
);
467467
}
468468

‎desktop/src/shared/ui/config-nudge-attachment.test.mjs‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ globalThis.window = {
2828

2929
import {
3030
focusTargetForRequirement,
31+
missingBinaryRecoveryMessage,
3132
shouldOpenDoctor,
3233
} from "./config-nudge-attachment.tsx";
3334
import {
@@ -60,6 +61,21 @@ test("shouldOpenDoctor_regularMixedRequirements_routesToEditAgent", () => {
6061
);
6162
});
6263

64+
test("shouldOpenDoctor_missingBinary_routesToAgentRuntimes", () => {
65+
assert.equal(
66+
shouldOpenDoctor([{ surface: "missing_binary", command: "buzz-pi-acp" }]),
67+
true,
68+
"a missing runtime binary must route to Agent runtimes",
69+
);
70+
});
71+
72+
test("missingBinaryRecoveryMessage_requiresBuzzRestart", () => {
73+
assert.equal(
74+
missingBinaryRecoveryMessage(),
75+
"not found in PATH — install it or update PATH, then restart Buzz",
76+
);
77+
});
78+
6379
// ── focusTargetForRequirement — pure function ─────────────────────────────────
6480

6581
test("focusTargetForRequirement_envKey_returnsEnvKeyTarget", () => {

‎desktop/src/shared/ui/config-nudge-attachment.tsx‎

Lines changed: 28 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -43,26 +43,39 @@ function requirementKey(
4343
}
4444

4545
/**
46-
* Returns true when every requirement in the nudge is a `cli_login` surface.
47-
* Non-authOnly all-cli_login cards (at least one install-state row) route to
48-
* Agent runtimes — install/login problems can't be fixed in Edit Agent. AuthOnly cards
49-
* (every row is `availability === "available"`) are purely informational and
50-
* do not route anywhere.
46+
* Requirements owned by runtime discovery route to Agent runtimes. This covers
47+
* Git Bash, unresolved binaries, and all-CLI-login cards with installation work.
48+
* Auth-only cards remain informational because Agent runtimes cannot log in to
49+
* an external CLI for the user.
5150
*/
5251
function hasGitBashRequirement(
5352
reqs: ConfigNudgePayload["requirements"],
5453
): boolean {
5554
return reqs.some((r) => r.surface === "git_bash");
5655
}
5756

57+
function hasMissingBinaryRequirement(
58+
reqs: ConfigNudgePayload["requirements"],
59+
): boolean {
60+
return reqs.some((r) => r.surface === "missing_binary");
61+
}
62+
5863
function isAllCliLogin(reqs: ConfigNudgePayload["requirements"]): boolean {
5964
return reqs.length > 0 && reqs.every((r) => r.surface === "cli_login");
6065
}
6166

6267
export function shouldOpenDoctor(
6368
reqs: ConfigNudgePayload["requirements"],
6469
): boolean {
65-
return isAllCliLogin(reqs) || hasGitBashRequirement(reqs);
70+
return (
71+
isAllCliLogin(reqs) ||
72+
hasGitBashRequirement(reqs) ||
73+
hasMissingBinaryRequirement(reqs)
74+
);
75+
}
76+
77+
export function missingBinaryRecoveryMessage(): string {
78+
return "not found in PATH — install it or update PATH, then restart Buzz";
6679
}
6780

6881
/**
@@ -165,9 +178,10 @@ export function focusTargetForRequirement(
165178
* the system.
166179
*
167180
* Routing:
168-
* (A) Any card with a `git_bash` requirement, or one whose requirements are all
169-
* install-state `cli_login`, opens Settings → Agent runtimes. A card-level
170-
* Agent runtimes label in `AttachmentActions` confirms the action at rest.
181+
* (A) Any card with a `git_bash` or `missing_binary` requirement, or one whose
182+
* requirements are all install-state `cli_login`, opens Settings → Agent
183+
* runtimes. A card-level Agent runtimes label in `AttachmentActions` confirms
184+
* the action at rest.
171185
* (A-auth) A card whose requirements are all available `cli_login` surfaces is
172186
* purely informational: Agent runtimes cannot authenticate a CLI, and `setup_copy`
173187
* already gives the needed command.
@@ -211,7 +225,7 @@ export function ConfigNudgeCard({
211225

212226
const handleOpen = () => {
213227
if (shouldOpenDoctor(nudge.requirements)) {
214-
// Git Bash and install-state CLI requirements both resolve in Agent runtimes.
228+
// Runtime installation and discovery requirements resolve in Agent runtimes.
215229
// Informational-only cards never mount this trigger.
216230
openDoctor();
217231
} else {
@@ -384,15 +398,16 @@ function RequirementRow({
384398
</div>
385399
);
386400
case "missing_binary": {
387-
// Missing-binary rows are purely informational — the user must install the
388-
// binary or update their PATH. No in-app action can fix this.
401+
// Agent runtimes owns installation guidance and the re-check action. The
402+
// restart guidance remains visible here because a normal agent restart does
403+
// not invalidate Desktop's negative command-resolution cache.
389404
return (
390405
<div className="flex items-center gap-2 text-xs leading-4 text-muted-foreground">
391406
<span className="flex-1 [overflow-wrap:anywhere]">
392407
<code className="rounded bg-muted px-1 py-0.5 font-mono text-xs text-foreground">
393408
{requirement.command}
394409
</code>{" "}
395-
not found in PATH — install it or check your PATH settings
410+
{missingBinaryRecoveryMessage()}
396411
</span>
397412
</div>
398413
);

0 commit comments

Comments
 (0)