11# Local agent controls
22
33The 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
66agents. 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
1616quit other Foundation copies first. Saved enabled agents can restore on startup.
1717Keep 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,
3132Create 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
5051use different workers while retaining separate histories. Existing saved agents
5152keep 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
6087Local team-linked imports snapshot the deployment team's instructions from the
6188chosen 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
75102To use an agent, open a channel and select it from ** @ mentions** . Both mention
76103menus 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.
78105A nonmember is labeled ** Not in channel · Choose whether to add when you send** .
79106Selection alone does nothing. Send asks, as block/buzz desktop does: ** Invite**
80107or ** 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,
89116and forum-channel composers share this behavior. DM participants and session
90117admission 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
93120agent (public key + community), without a separate Start click. Import itself
94121remains non-starting. Stop cancels earlier pending mention wakes and active work;
95122a 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;
818851its generic build environment injection is not a Pi resource-bundling contract
819852for this app. Signed bundling, automatic employee provisioning and release
820853pipeline 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.
0 commit comments