Skip to content

Commit 5f35541

Browse files
author
Rizz
committed
Merge remote-tracking branch 'origin/main' into tho/composer-focus-outline
* origin/main: Document unified inventory and verify focused import and compact-row acceptance (#293) fix(ux): clarify Pi installation and setup errors (#511) Signed-off-by: Rizz <302abe414ca6e3134763d2539bfcf145aea2a63fe5f8455204ed602fd40cf381@buzz.block.builderlab.xyz>
2 parents b5c3cc6 + 427619f commit 5f35541

14 files changed

Lines changed: 759 additions & 182 deletions

‎docs/agent-control.md‎

Lines changed: 104 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Local agent controls
22

33
The Agents page uses one app-owned native controller for creating, importing,
4-
editing and running local agents. Managed cards are keyed by exact identity and
5-
community. Browser-only access keeps the read-only old library; it cannot run
4+
editing and running local agents. Inventory cards join records by exact public key;
5+
managed actions remain keyed by native identity/community record. Browser-only access keeps the read-only old library; it cannot run
66
agents. The only product entry point is ordinary desktop startup.
77

88
## Normal desktop workflow
@@ -16,16 +16,17 @@ configuration and persistent native settings. Coordinate the native rebuild/rela
1616
quit other Foundation copies first. Saved enabled agents can restore on startup.
1717
Keep imported agents disabled and old Buzz running until an attended handover.
1818

19-
Open **Agents → My agents** for imported identities, their destination community,
20-
process evidence and visible **Start / Stop**. **Edit**, **Duplicate**, and
21-
**Delete** are in the card’s three-dot menu. Duplicate seeds Create with editable
22-
settings and a fresh identity; write-only environment values require re-entry.
23-
Delete stops the local process and removes this app's settings and Keychain key
24-
after confirmation. It does not archive the relay identity or erase messages.
25-
Deployed remote records are refused.
26-
Same-key identities at different destinations have separate
27-
cards; actions use native ID/revision, never the display name. Managed controls
28-
remain available when the old library is disconnected, unavailable or archived.
19+
Open **Agents** for discovered and imported identities grouped by known community
20+
associations. Each identity card keeps the configured destinations’ **Start / Stop**
21+
controls. **Edit**, **Duplicate**, and **Delete** are in the card’s three-dot menu.
22+
Duplicate seeds Create with editable settings and a fresh identity; write-only
23+
environment values require re-entry. Delete stops the local process and removes
24+
this app's settings and Keychain key after confirmation. The key remains while
25+
another setup of the same identity still uses it. Delete does not archive the
26+
relay identity or erase messages. Deployed remote records are refused. Actions
27+
use native ID/revision, never the display name. Older hosts without parked
28+
inventory retain the **My agents** and read-only library sections. Managed
29+
controls remain available when discovery is disconnected, unavailable or archived.
2930

3031
**Add agent** shares the Edit fields and model browser. In the development desktop,
3132
Create generates a native key, obtains the captured viewer's owner authorization,
@@ -50,12 +51,38 @@ worker count. With **Each thread** conversation context, separate threads can
5051
use different workers while retaining separate histories. Existing saved agents
5152
keep their settings; add the variable and restart them to enable more workers.
5253

53-
**Not imported from old Buzz** is a separate collapsible section. Expanding it
54-
loads installed identities for the connected community; already-managed exact
55-
identities are excluded. Each remaining row says **Not imported** and has its own
56-
**Import** action. Source/destination overrides and source warnings stay under
57-
Import options. Import focuses the imported card and says **Imported, not started**.
58-
It does not start a listener, invite an agent or change the old library.
54+
**Clone to this community** opens the existing creation dialog with only the old
55+
agent’s name and resolved instructions. Review that text for embedded secrets.
56+
Runtime settings and workspace use this app’s defaults and remain editable.
57+
Clone generates a new native identity; it does not copy identity keys, environment
58+
values, command arguments, paths, history or membership. Saving leaves the new
59+
agent stopped. The source is read-only and no legacy credential access occurs.
60+
61+
**Import** preserves the selected old-installation identity and private key. It
62+
requires an explicit destination and a fresh source/destination-bound preview.
63+
Successful import saves a configured, stopped setup. It does not start a listener,
64+
invite an agent, or modify the source installation. An identity already held
65+
locally cannot be imported again into another community; use **Clone** instead.
66+
The native prepare and commit boundaries both enforce that exact-key rule.
67+
68+
The unified inventory offers Import only under **Available to import**, once per
69+
exact public key. Multiple old installations require an explicit source choice.
70+
The selected row opens the import review. Without a selected community, such
71+
as in Personal space, the review asks for the destination before it loads a
72+
fresh preview. Each startup reads every old installation again: an identity
73+
deleted from all of them, or whose installation is removed, leaves the list. A
74+
damaged source keeps its previous entries. Source read failures remain visible.
75+
Older hosts retain the separate installation browser as a compatibility path.
76+
77+
**Use here** is recovery for older incomplete local imports, not a normal next
78+
step after Import. It retains the identity/key, requires owner-authorized community
79+
confirmation, and leaves the recovered setup stopped with app-launch start off.
80+
The development broker and the packaged desktop app both provide that
81+
confirmation; the desktop app signs it natively (`relay_agent_resolve`). Native
82+
code refuses a new
83+
community when that identity already has a configured setup elsewhere. A retry
84+
for the already recovered destination is harmless. Existing historical setups
85+
remain visible and controllable; this rule does not move or delete them.
5986

6087
Local team-linked imports snapshot the deployment team's instructions from the
6188
chosen library's `agents/teams.json`, alongside the resolved persona prompt.
@@ -74,7 +101,7 @@ perform the same attended old-Buzz handover as for a fresh import.
74101

75102
To use an agent, open a channel and select it from **@ mentions**. Both mention
76103
menus include the selected community’s people directory alongside channel members
77-
and managed agents. Directory reads are bounded; narrow the search for more people.
104+
and configured managed agents. Directory reads are bounded; narrow the search for more people.
78105
A nonmember is labeled **Not in channel · Choose whether to add when you send**.
79106
Selection alone does nothing. Send asks, as block/buzz desktop does: **Invite**
80107
or **Do nothing**. Without add permission, the only action is **Send anyway**.
@@ -89,7 +116,7 @@ before a new add; unknown outcomes are never silently replaced. Channel, thread,
89116
and forum-channel composers share this behavior. DM participants and session
90117
admission rules are unchanged.
91118

92-
A confirmed outgoing channel or thread mention now starts an exact imported local
119+
Once an identity is configured by Import or legacy **Use here** recovery, a confirmed outgoing channel or thread mention starts that exact local
93120
agent (public key + community), without a separate Start click. Import itself
94121
remains non-starting. Stop cancels earlier pending mention wakes and active work;
95122
a later deliberate mention can start the agent again. Plain name text without
@@ -203,8 +230,12 @@ The **Harnesses** card lists only **Buzz Agent**, **Goose**, and **Pi**:
203230
Installation has a private log, re-detects the executables, and restarts only
204231
enabled Pi agents that previously failed because their executable was missing.
205232
User-global Pi installations remain untouched. Windows and unsupported
206-
architectures retain manual setup. The copyable commands remain the manual
207-
fallback (Node.js required):
233+
architectures retain manual setup. Settings explains that **Install** supplies
234+
Node.js, Pi, and the adapter automatically. Copyable terminal commands are
235+
collapsed under **Manual setup** within the Pi row (Node.js 22.19 or newer required).
236+
Failed installs show the failed step and a bounded npm error excerpt above
237+
the expandable private install log; errors do not assume a registry problem.
238+
The manual fallback commands are:
208239

209240
```sh
210241
npm install -g '@earendil-works/pi-coding-agent@>=0.99.0'
@@ -554,8 +585,10 @@ Settings says **Shell setup not verified**; Buzz does not check it before Start.
554585
Snapshots name the deciding key (`launchModelEnv`/`launchProviderEnv`,
555586
including `DATABRICKS_MODEL` or a hidden provider behind a blank buzz-agent
556587
model) and omit the resolved value.
557-
- Import previews only the chosen installed/development library and requires an
558-
explicit secure **Destination community** origin. Old Buzz ignores saved relay
588+
- Local browsing reads only the chosen installed/development library without a
589+
destination. Native keeps no pending import for that read and invalidates any
590+
prior import token. An actionable import preview requires an explicit secure
591+
**Destination community** origin. Old Buzz ignores saved relay
559592
pins at runtime; blank, stale or malformed saved pins do not route or hide
560593
identities here. Native validates the chosen destination, shows it beside each
561594
exact key, and retains it with the preview token through commit. Source or
@@ -818,3 +851,50 @@ configuration. The current internal release repository builds the old desktop;
818851
its generic build environment injection is not a Pi resource-bundling contract
819852
for this app. Signed bundling, automatic employee provisioning and release
820853
pipeline migration require separate release work; no release is published here.
854+
855+
### Community setup confirmation
856+
857+
Local installation import validates the source configuration, owner authorization
858+
and private key. It does not require relay inventory or a community confirmation.
859+
The imported agent stays stopped.
860+
861+
For explicit setup in a community, the broker can sign the selected owner's
862+
intent for an identity/community pair. Native code verifies that signature against
863+
the retained source-owner authorization. This does not establish channel membership,
864+
key availability or exclusive community membership. It does not reserve a community
865+
before import. Setup recovery cannot add another community to an identity that
866+
already has a configured setup elsewhere; copying that agent requires Clone.
867+
868+
Joined-community discovery reads each joined community's scoped inventory without
869+
selecting it or opening a relay session. Exact keys appear once with all known
870+
associations. Each failed community read has its own warning and Refresh retry;
871+
successful reads remain visible. Discovery does not provide credentials, an import
872+
source, or permission to extend an existing local identity into another community.
873+
874+
### Local inventory actions
875+
876+
Startup copies only identity names, public keys and source labels into a durable
877+
inventory. It does not read keys, configure a setup, or start an imported agent.
878+
Import copies the selected local key and settings, independent of relay inventory.
879+
New imports require a destination and are saved configured but stopped.
880+
**Use here** only recovers older incomplete imports. **Start** remains a separate
881+
action; a later deliberate mention can also start a configured agent. Existing
882+
saved setups without the configured flag keep their prior behavior.
883+
884+
The unified card's **Import** opens the existing installation form with its exact
885+
identity and known local source selected. The source is fixed during review;
886+
if the preview fails or the identity is unavailable there, you can choose
887+
another source. **Clone**
888+
from a local source or imported identity opens a review of only its name and
889+
instructions; creation generates a fresh key. Clone never imports the old key.
890+
891+
Community groups show known associations, not exclusive membership or admission.
892+
An inventory failure does not block local Import or setup confirmation. Every
893+
configured setup keeps Start, Stop and Edit, whichever community is selected.
894+
Cards for other communities also offer Clone to bring a new identity here,
895+
without changing the source.
896+
Archived discovery rows remain hidden after sources join, except where local
897+
controls must remain reachable. Linked profiles remain visible on identity cards.
898+
899+
Before starting an imported identity, stop the old agent and disable its automatic
900+
startup in the old application. Do not run duplicate copies of the same identity.

‎docs/agents.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,14 +23,14 @@ add-existing membership, Save/recovery and all runner management are out of V1.
2323
- Only definition ID/name, identity public key/name/definition link, and optional
2424
avatar artwork leave the host. Prompts, configuration, credentials and execution receipts are not
2525
projected. This is local library evidence, **not verified ownership**.
26-
- Selected definitions remain one card each, including definitions without an
27-
identity. Exact linked keys remain available in each card’s identity disclosure, including namesakes; unlinked and
28-
unmatched identities use Custom agents/Other identities groupings. Unlike old Buzz's
29-
runtime-dependent representative selection, this read-only view shows all
30-
non-archived linked keys and has no profile/start action or running badge.
31-
- Confirmed relay archives hide identity rows, not definition cards. Missing
32-
archive evidence is labeled; it does not erase the saved library. This is
33-
display behavior, never mention permission.
26+
- The library shows one tile per exact identity, grouped only by explicit profile
27+
links. Each tile discloses its full public key. Profiles with no linked identity
28+
appear separately; an archived identity does not become an empty profile.
29+
- Only distinct keys with the same displayed name need a short npub suffix. Names
30+
alone never create a profile group. Suffix collisions extend deterministically using
31+
the complete inventory, including identities hidden by archive filtering.
32+
- Missing archive evidence keeps identities visible. Archive filtering affects
33+
display only, never mention permission or runtime control.
3434
- One lazy host read per opening/Refresh; no polling or relay-directory startup
3535
scan. Concurrent host requests coalesce. Read caps: 8 MiB / 2000 records;
3636
malformed/missing files fail visibly without echoing their contents. The host
@@ -520,5 +520,21 @@ service. Each relay session binds its own view. A ready native record takes
520520
precedence only in its matching community; otherwise the ready legacy display
521521
inventory supplies the name, then the public profile. Plugin disable restores
522522
public-profile names. These labels never change identity keys, membership,
523-
credentials, or runtime admission. Profile panels consume this view; other name
524-
surfaces are being migrated separately.
523+
credentials, or runtime admission. Profile panels, messages, mention choices,
524+
activity, conversation labels and new notifications consume this view. Mention
525+
parsing still uses signed identity evidence before resolving its visible label.
526+
527+
### Additive community inventory
528+
529+
The active session reads the owner's kind-30175 profiles and kind-30177 identities
530+
from its accessible relay. It also retains the local library reader. The inventory
531+
joins exact public keys, not equal names; explicit profile references use the
532+
publisher's slug mapping only when local definitions do not collide. Local names
533+
and artwork win for matching keys. Native configuration still wins within its
534+
matching community. A failed source leaves the other source visible with a warning.
535+
536+
Discovery is not global coverage, verified membership, credentials, or execution
537+
status. Native cards keep their controls. Other known identities appear in a
538+
read-only section. Each card offers its own Import; the separate installation
539+
browser appears only for repair.
540+
No keys, config, memory, membership, or runtime state are changed by discovery.

‎src-tauri/src/harness_setup.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ fn open_log(path: &Path) -> Result<File, String> {
131131
std::fs::create_dir_all(path.parent().ok_or("Invalid install log location")?)
132132
.map_err(|_| "Could not create the Harnesses install log directory")?;
133133
let mut options = OpenOptions::new();
134-
options.write(true).create(true).truncate(true);
134+
options.read(true).write(true).create(true).truncate(true);
135135
#[cfg(unix)]
136136
{
137137
use std::os::unix::fs::OpenOptionsExt;

0 commit comments

Comments
 (0)