Skip to content

Commit 427619f

Browse files
loganjLarryclassy-murderbot
authored
Document unified inventory and verify focused import and compact-row acceptance (#293)
Signed-off-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz> Signed-off-by: Logan Johnson <[email protected]> Co-authored-by: Larry <627498bd4bd1f281a16431e3c6cce3b5c25b6692798c78672298aefbf2f8f8b5@buzz.block.builderlab.xyz> Co-authored-by: classy-murderbot <[email protected]>
1 parent bd62d53 commit 427619f

9 files changed

Lines changed: 498 additions & 62 deletions

File tree

‎docs/agent-control.md‎

Lines changed: 98 additions & 22 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
@@ -558,8 +585,10 @@ Settings says **Shell setup not verified**; Buzz does not check it before Start.
558585
Snapshots name the deciding key (`launchModelEnv`/`launchProviderEnv`,
559586
including `DATABRICKS_MODEL` or a hidden provider behind a blank buzz-agent
560587
model) and omit the resolved value.
561-
- Import previews only the chosen installed/development library and requires an
562-
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
563592
pins at runtime; blank, stale or malformed saved pins do not route or hide
564593
identities here. Native validates the chosen destination, shows it beside each
565594
exact key, and retains it with the preview token through commit. Source or
@@ -822,3 +851,50 @@ configuration. The current internal release repository builds the old desktop;
822851
its generic build environment injection is not a Pi resource-bundling contract
823852
for this app. Signed bundling, automatic employee provisioning and release
824853
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/app/agent-control.integration.test.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,21 @@ it("retains working injected control across Agents disable/re-enable and communi
113113
.find((entry) => entry.pluginId === "buzz.agents");
114114
// The production registration wrapper passes its injected capability as props.
115115
const component = page?.component as unknown as () => {
116-
props: { control: AgentControl };
116+
props: {
117+
control: AgentControl;
118+
communities: Pick<
119+
typeof services.communities,
120+
"snapshot" | "subscribe"
121+
>;
122+
};
117123
};
118-
return component().props.control;
124+
const props = component().props;
125+
expect(Object.keys(props.communities).sort()).toEqual([
126+
"snapshot",
127+
"subscribe",
128+
]);
129+
expect(props.communities.snapshot()).toBe(services.communities.snapshot());
130+
return props.control;
119131
};
120132
expect(injectedControl()).toBe(control);
121133
await control.refresh();

‎src/bundled/agents/AgentsPage.test.tsx‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -561,13 +561,14 @@ it("focuses the imported managed identity without starting it", async () => {
561561
fireEvent.click(
562562
await screen.findByRole("button", { name: "Import Fixture agent" }),
563563
);
564-
const notice = await screen.findByText(
565-
"Imported, not started. Start it when you are ready.",
566-
);
564+
const notice = await screen.findByText(/Imported, not started\./);
567565
const imported = notice.closest("article");
568566
if (!imported) throw Error("Imported card missing");
569567
expect(imported).toHaveTextContent("wss://third.example");
570568
expect(notice.parentElement).toHaveFocus();
569+
expect(
570+
within(imported).queryByRole("button", { name: "Use here" }),
571+
).toBeNull();
571572
expect(within(imported).getByRole("button", { name: "Start" })).toBeEnabled();
572573
expect(f.calls.some((call) => call.action === "start")).toBe(false);
573574
});
@@ -1241,9 +1242,7 @@ it("credential import keeps real Stop controls reachable without trapping the ed
12411242
await gate;
12421243
});
12431244
await waitFor(() => expect(control.snapshot().busy).toBe(false));
1244-
expect(
1245-
screen.queryByText("Imported, not started. Start it when you are ready."),
1246-
).toBeNull();
1245+
expect(screen.queryByText(/Imported, not started\./)).toBeNull();
12471246
await act(async () => control.refresh());
12481247
const imported = control
12491248
.snapshot()
@@ -2680,9 +2679,7 @@ it("uses snapshot capabilities rather than JS wrappers and retains older-host im
26802679
fireEvent.click(
26812680
await screen.findByRole("button", { name: "Import Fixture agent" }),
26822681
);
2683-
const notice = await screen.findByText(
2684-
"Imported, not started. Start it when you are ready.",
2685-
);
2682+
const notice = await screen.findByText(/Imported, not started\./);
26862683
const card = notice.closest("article");
26872684
if (!card) throw Error("Imported card missing");
26882685
expect(within(card).getByRole("button", { name: "Start" })).toBeEnabled();

‎src/bundled/agents/InventoryIdentityCard.tsx‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -187,19 +187,13 @@ export function InventoryIdentityCard({
187187
state.busy ||
188188
state.status !== "ready" ||
189189
!!decision.blocked ||
190-
!data.localInventoryActions ||
191190
!control.configureHere
192191
}
193192
onClick={() => onUseHere(row.pubkey, "use")}
194193
>
195194
Use here
196195
</Button>
197196
{decision.blocked && <p role="status">{decision.blocked}</p>}
198-
{!data.localInventoryActions && (
199-
<p>
200-
Restart an updated desktop build to use local inventory actions.
201-
</p>
202-
)}
203197
</>
204198
)}
205199
{(tile || decision.action === "clone") && cloneAction}

‎src/bundled/agents/ManagedAgentActions.tsx‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ export function ManagedAgentActions({
109109
>
110110
Use here
111111
</Button>
112-
) : state.data?.localInventoryActions && control.configureHere ? (
112+
) : control.configureHere ? (
113113
<LocalInventoryAction
114114
control={control}
115115
agent={agent}
@@ -121,9 +121,7 @@ export function ManagedAgentActions({
121121
onUsed={() => {}}
122122
onClone={() => {}}
123123
/>
124-
) : (
125-
<p>Update the desktop app to set up this imported identity.</p>
126-
))}
124+
) : null)}
127125
{agent.startOnAppLaunch && (
128126
<p className="m-0 text-body-sm text-secondary">Starts with this app.</p>
129127
)}

0 commit comments

Comments
 (0)