Skip to content

Commit 708294b

Browse files
salman1993Opusclaude
authored
feat(pi): add the Pi agent type using pi-durable (#1420)
Signed-off-by: Salman Mohammed <[email protected]> Co-authored-by: Opus <f038cc09b32a776e7d95b65c267e9d851777ee2b6cdbd46a48edba01b1d10ebd@buzz.block.builderlab.xyz> Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent df6843c commit 708294b

29 files changed

Lines changed: 8379 additions & 52 deletions

‎crates/plugin-manager/src/lib.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,8 @@ pub fn bundled_manifests() -> Vec<Manifest> {
286286
.expect("codex manifest"),
287287
serde_json::from_str(include_str!("../../../src/bundled/goose/manifest.json"))
288288
.expect("goose manifest"),
289+
serde_json::from_str(include_str!("../../../src/bundled/pi/manifest.json"))
290+
.expect("pi manifest"),
289291
serde_json::from_str(include_str!("../../../src/bundled/workflows/manifest.json"))
290292
.expect("workflows manifest"),
291293
serde_json::from_str(include_str!("../../../src/bundled/feedback/manifest.json"))

‎crates/plugin-manager/tests/management.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1134,7 +1134,7 @@ fn bundled_defaults_preserve_saved_choices_and_only_channels_is_required() {
11341134
let id = plugin.manifest.id.as_str();
11351135
let default = !matches!(
11361136
id,
1137-
"buzz.bestie" | "buzz.todos" | "buzz.usage" | "buzz.relay-notes"
1137+
"buzz.bestie" | "buzz.pi" | "buzz.todos" | "buzz.usage" | "buzz.relay-notes"
11381138
);
11391139
assert_eq!(plugin.enabled, default, "{id}");
11401140
if id == "buzz.channels" {

‎docs/view-pi-session.md‎

Lines changed: 0 additions & 50 deletions
This file was deleted.

‎scripts/design-system/check-icons.mjs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,9 @@ const nonIconDependencies = new Set([
1414
"@buzz/author",
1515
"@deepseek-ai/cordis",
1616
"@dnd-kit/core", // Pointer drag and drop for sidebar channel moves.
17+
"@earendil-works/chord", // The Pi host's packages, which pi.sh installs.
18+
"@earendil-works/pi-ai",
19+
"@earendil-works/pi-durable",
1720
"@emoji-mart/data",
1821
"@fontsource-variable/inter",
1922
"@fontsource/jetbrains-mono",
@@ -57,6 +60,7 @@ const nonIconDependencies = new Set([
5760
"nostr-tools",
5861
"pele",
5962
"postcss",
63+
"proper-lockfile", // The Pi host's lock on each agent's storage.
6064
"prosemirror-commands",
6165
"prosemirror-history",
6266
"prosemirror-model",

‎src/app/pages.integration.test.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ test("the app runtime exposes ready bundled pages and removes them on disable",
7272
plugin.enabledByDefault,
7373
![
7474
"buzz.bestie",
75+
"buzz.pi",
7576
"buzz.todos",
7677
"buzz.usage",
7778
"buzz.relay-notes",

‎src/bundled/claude-code/transcript.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ const KINDS: Record<string, string> = {
6464
};
6565

6666
/** A Buzz prompt, or a steer wrapping one, as the turn's opening item. */
67-
function prompt(id: string, at: number, raw: string): TranscriptItem {
67+
export function prompt(id: string, at: number, raw: string): TranscriptItem {
6868
let sections = promptSections(raw);
6969
const steer = sections.find((section) => section.tag === STEER);
7070
if (steer) sections = promptSections(steer.body);

‎src/bundled/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ import codexManifest from "./codex/manifest.json";
3434
import * as codex from "./codex";
3535
import gooseManifest from "./goose/manifest.json";
3636
import * as goose from "./goose";
37+
import piManifest from "./pi/manifest.json";
38+
import * as pi from "./pi";
3739
import channelsManifest from "./channels/manifest.json";
3840
import githubManifest from "./github/manifest.json";
3941
import * as channels from "./channels";
@@ -199,6 +201,11 @@ export const bundledPlugins: readonly BundledPlugin[] = [
199201
module: goose,
200202
enabledByDefault: true,
201203
},
204+
{
205+
manifest: { ...piManifest, apiVersion: 1 },
206+
module: pi,
207+
enabledByDefault: false,
208+
},
202209
{
203210
manifest: { ...workflowsManifest, apiVersion: 1 },
204211
module: workflows,

‎src/bundled/pi/README.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# Pi
2+
3+
Create agents that run Pi on your computer, with any provider Pi supports, and answer you in Buzz. Each conversation continues its own Pi conversation.
4+
5+
## Getting started
6+
7+
1. Turn on **Pi** in **Settings** → **Plugins**. Pi needs Node.js 22.19 or later on this computer.
8+
2. Choose **New agent** → **Create a new agent**, pick **Pi** as the **Harness**, and choose its provider and model.
9+
3. Mention your agent in a conversation to give it work.
10+
11+
---
12+
13+
# Pi for Agents
14+
15+
A desktop plugin that ships with Buzz on macOS, Linux and Windows, off until
16+
turned on in **Settings → Plugins**. Its agents run on
17+
[Pi durable](https://earendil.com/posts/pi-1-0/) (`@earendil-works/pi-durable`),
18+
not the Pi coding agent, with any provider Pi supports.
19+
Agents owns the identity, admission, configuration, and signed Buzz actions. This
20+
plugin owns Pi work after delivery handover. One Pi host process ([`host.mjs`](host.mjs))
21+
runs every Pi agent here. Each agent has its own SQLite storage, and each Buzz
22+
conversation the agent is in is one durable Pi conversation.
23+
24+
## Try it
25+
26+
From the feature worktree:
27+
28+
```sh
29+
source bin/activate-hermit
30+
BUZZODZ_PROFILE=pi-agents BUZZ_DEV_VIEWER= bin/just desktop
31+
```
32+
33+
Pi needs Node.js 22.19 or later on this computer (`node:sqlite`). On macOS and
34+
Linux the app's PATH is searched first, then an interactive login shell's, so
35+
Homebrew, nvm, fnm and similar installs work. On Windows, `node` must be on the PATH Buzz
36+
starts with.
37+
38+
1. Turn on **Pi** in **Settings → Plugins**. Then open **Agents → New agent**
39+
and choose **Pi** as the **Harness**. Its **Model** starts on **Pi default**:
40+
the `defaultProvider` and `defaultModel` in `~/.pi/agent/settings.json`, as
41+
the `pi` command sets them. The first time Buzz asks Pi anything, it
42+
installs Pi's packages (a few seconds).
43+
2. Click the model (marked with Pi, and with the provider when Buzz has its
44+
mark) and choose a provider. A provider Pi has no key for shows an
45+
**API key** field; **Save to Pi** stores it in
46+
`~/.pi/agent/auth.json`, shared with the `pi` command. A provider that signs
47+
in some other way (OAuth, cloud credentials) says to run `pi`, then `/login`.
48+
Choose a model, click **Test connection**, then **Use**. Name the agent and
49+
click **Create agent**. Its library card shows the same control.
50+
3. Open the agent. Its **Identity** tab has the **Provider**, **Model**,
51+
**Thinking** level (Pi's default, or one the model has) and
52+
**Instructions**. Its **Settings** tab has the provider's key with **Test
53+
connection**, the **Workspace** (default `~/.buzz`), and thread or channel
54+
**Conversations**.
55+
4. In a channel, send: `@Pi create hello.txt containing hello in the workspace,
56+
read it back, and report what you found` (use the agent's actual name).
57+
Expect steps under your message, one reply in the thread, and the file in the
58+
workspace. Then reply in the same thread: `@Pi what did you write?`. It
59+
remembers, because the thread is the same Pi conversation.
60+
5. While it works, send another mention in the thread. It steers the running
61+
turn: Pi reads it at its next step. The activity moves to the newer message.
62+
6. Quit Buzz during a long turn, start it again, and mention the agent in that
63+
thread. Pi continues the interrupted run from its storage, and the new
64+
mention steers it.
65+
7. Choose **View activity** on one of its messages in that thread, or open the
66+
agent's **Activity** tab from there. **This thread** is its Pi conversation,
67+
with the agent's other recent ones below. **View transcript** shows each
68+
turn's prompt, thinking, tool calls with their output, and what it sent,
69+
read from Pi's storage.
70+
71+
The composer's model picker offers the agent's provider's models, and each
72+
model's thinking levels, for one turn. Without a pick, a turn runs the
73+
agent's saved model and Thinking level.
74+
75+
## Checks
76+
77+
```sh
78+
bin/pnpm exec vitest run src/bundled/pi
79+
PI_DEPS="$HOME/Library/Application Support/Buzz/pi/deps/<sum>" bin/pnpm exec vitest run src/bundled/pi/host.live.test.ts
80+
```
81+
82+
The unit tests cover the stdio protocol (`pi.ts`), the runtime against a fake
83+
host, the install script in a throwaway home, and the New agent and Settings
84+
fields. The opt-in live test runs the real `host.mjs` on Pi durable, using Pi's
85+
faux provider as the model. It checks that a final `send` ends the run, that the
86+
model reads what a Buzz tool answered, that a plain answer comes back as text,
87+
that a request steers a working run, that a run cut off by a stop continues in
88+
the next host, that aborting a run leaves it unanswered, and that a deferred
89+
Buzz tool is offered once `tool_search` finds it. `PI_DEPS` is any folder
90+
the launcher installed Pi's packages in.
91+
92+
## Buzz's copy of Pi's packages
93+
94+
[`launch.mjs`](launch.mjs) runs the host on this computer's Node. On macOS and
95+
Linux, [`pi.sh`](pi.sh) finds that Node and starts the launcher on it; Windows,
96+
which has no bash, starts `node` itself. The launcher's first line on stdin
97+
carries the host source and the packages to install, since together they pass
98+
Windows' 32 KB command line. On first use it runs `npm ci` with
99+
[`deps/package-lock.json`](deps/package-lock.json), which pins every package and
100+
its integrity hash. Install scripts are off, and npm uses the registry it is
101+
configured for. Each lock gets its own folder under
102+
`~/Library/Application Support/Buzz/pi/deps/`
103+
(`${XDG_DATA_HOME:-~/.local/share}/buzz/pi/deps/` on Linux,
104+
`%LOCALAPPDATA%\Buzz\pi\deps\` on Windows). The folder appears
105+
whole or not at all, and is shared by every Buzz build. An install removes the
106+
folders no build has started for 30 days. Agents' storage is in `agents/<pubkey>.sqlite`
107+
beside it. A lock on each agent's storage keeps a second Buzz build from opening
108+
it; that build's turns fail and say so. It also keeps Pi's `auth.json` writes
109+
from colliding with the `pi` command's.
110+
111+
To update Pi, change the versions in [`deps/package.json`](deps/package.json),
112+
then regenerate the lock without registry URLs:
113+
114+
```sh
115+
cd src/bundled/pi/deps
116+
npm install --package-lock-only --ignore-scripts --omit-lockfile-registry-resolved
117+
```
118+
119+
## Limits and boundaries
120+
121+
- Only the owner's events, or ones the owner delegated, start work. Watches,
122+
timers and catch-ups run as standalone turns, each a one-off Pi
123+
conversation, in the lanes and with the 5-minute deadline Buzz's agent
124+
runner gives every harness.
125+
- Pi has the coding tools `read`, `write`, `edit` and `bash`, in the workspace,
126+
with no sandbox or approvals, like Claude's `bypassPermissions`. Buzz's tools
127+
are offered as `buzz_<name>` (`buzz_send`, `buzz_read`, …), since `read` and
128+
`edit` would collide. They run inside Buzz through the agent's native-held
129+
handle, so the host holds no Buzz key. A final `buzz_send` ends the run.
130+
The Buzz tools Claude and Codex load on search (the attention tools, and
131+
those plugins add) are deferred: Pi's `tool_search` loads them when the
132+
model looks for them, and they stay loaded in that conversation.
133+
- **Stop** on a turn's activity aborts the Pi run it is in, and posts
134+
nothing.
135+
- A turn that answered in text and never called `buzz_send` has its answer
136+
posted in the thread, as goose does. A turn that fails posts `⚠️ I couldn't
137+
finish that: …` and tags the owner.
138+
- A Buzz tool call that a stop cuts off runs again when the run continues, so a
139+
`send` may be posted twice.
140+
- Pi's storage keeps every conversation, including each one-off watch or timer
141+
turn; nothing prunes it. The Activity tab lists thread and channel
142+
conversations only, and rereads an open transcript when its turn ends, not
143+
as it streams.
144+
- A host that stops while a turn waits is started again once and waits for it
145+
there. A run resumed that way shows no steps.
146+
- Runs left unfinished when the app quit continue at the first turn after it
147+
starts again, in whatever thread. A mention's run shows as working and its
148+
answer or failure is posted where it would have been, but it shows no steps
149+
and Stop does not reach it. A watch's or timer's run is ended instead, as
150+
quitting ends other harnesses' turns: continued, it would have no deadline.
151+
- Pi durable records some requests that have no answer, such as compaction's,
152+
only in its totals. Usage counts each model's share of those as one more
153+
request, at the newest compaction.
154+
- A provider that needs more than a key, such as Bedrock or Vertex, is set up
155+
with the `pi` command. Signing in from Buzz is not supported.
156+
- A `!command` or `$NAME` key in `auth.json`, which the `pi` command runs or
157+
reads from its environment to get the key, is not used: one host serves
158+
every agent, and a command would hold them all, and the desktop app often
159+
lacks the shell's environment. Its turns fail and say so; enter the key in
160+
Buzz instead.
161+
- Only Pi's built-in providers run. One that a Pi package adds (`packages` in
162+
Pi's settings), such as databricks, is not loaded: the provider field, the
163+
New agent Model field and a turn's error say so, and Use and Save wait for another.
164+
- On Windows, Pi's `bash` tool needs a bash, such as Git for Windows'; the
165+
other tools work without one.
166+
- Windows, Linux, packaged-app behavior, and human acceptance need separate
167+
validation.

0 commit comments

Comments
 (0)