feat(bestie): add Inbox access and refine settings - #2622

…uzz tools (#2707)

## TL;DR

An approved external app (like Nexus) now gets the selected agent's
whole Buzz MCP tool catalog and native dispatcher, including tools
plugins add later, after one explicit "full access" approval. Before, it
got a hand-picked list of six tools with rewritten arguments. Older
narrow approvals still connect but grant no tools until the owner
approves full access again, so no existing grant widens on its own.

Initiative status:
https://g2.sqprod.co/apps/kylez-nexus-buzz-plugins-status

Fixes NEXUS-4262

## What changes

- **One scope, `agent`.** New links request `scope=agent`, and `agent`
can't be combined with other scopes. Rust pairing accepts only
`["agent"]` for new approvals (`valid_scopes`). Saved
`read`/`post`/`create` approvals still load, renew and resume, but grant
nothing.
- **No adapter.** `respondExternal` now passes `tools/list` and
`tools/call` to `respond` in `rpc.ts`, using the same
`sessionTools(added)` catalog as native sessions. Plugin-added tools
come from `addedTools.snapshot()` (the source native harnesses use) and
are re-read on every message, so enabling or disabling a plugin changes
the catalog live. The old policy map, argument rewriting and Bestie
injection are removed.
- **The agent's own authority.** The connection uses the agent's run
handle (`runners.handle(key, undefined, true)`), so it gets device
settings, plugin requests, Git access and handoff exactly as a native
run does. Plugin installs still go through the owner's confirmation.
Memory reads use the agent's `memoryListing`, like the native plugin
path. Protected agents are still refused. `plugin_disable` acts at once,
as it does natively, and the consent text says so.
- **Handoff with true provenance.** `self_handoff` goes through the
run's own handoff and `Agents.wakeIn`, but its `from` is `{ external:
true }`. `wakeSection` shows it as an `<app-wake>` section that says an
external app the owner approved sent it, and that it is not a message, a
watch or timer, or another of the agent's conversations.
- **Files where the agent reads them.** `send` with `path`/`files` calls
a new optional `AgentType.readFile`. Claude, Codex, Pi and goose
implement it with the reader their own tools use, in the agent's saved
workspace on this device. Relative paths start there; absolute and `~/`
paths reach any file the account can read, as they do natively, and the
consent text says so. A Claude or Codex agent bound to an execution
target refuses, because only a conversation's session opens that target.
A type without `readFile` refuses with the same message its tools give
natively. Closing the connection cancels a read in progress.
- **No implicit conversation.** Calls run with an empty context, so
every tool needs explicit channel or message IDs.
- **Consent.** The dialog now states full access plainly: future plugin
tools, Git access, waking the agent, Nexus workers, settings changes,
posting any file the agent can read (including outside its workspace),
and immediate plugin disabling. A legacy narrow link shows an
update-required notice with Deny only, which sends the normal denial
callback. `approve()` refuses non-`agent` requests as a second check.
Agent settings flags a saved legacy approval as no longer working.

## Companion-client contract (for the Nexus consumer)

| | Behavior |
| --- | --- |
| Request | `scope=agent` alone. Narrow scopes get the update-required
notice and only a denial callback. |
| `tools/list` | The full native catalog: 66 built-in tools with
settings, plus plugin tools. Each tool is listed as natively, plus
`_meta: {"buzz/requiredScopes": ["agent"]}`. Result `_meta`:
`buzz/grantedScopes` (`["agent"]`, or `[]` for a legacy approval) and
`buzz/supportedScopes: ["agent"]`. Cursors are rejected (single page). |
| `tools/call` without the grant | `isError` result, nothing dispatched,
`_meta["buzz/error"] = {code: "authorization_required", required_scopes:
["agent"]}`. |
| `tools/call` with the grant | Native result and errors, unchanged. |
| `self_handoff` | Native arguments. The wake reaches the agent as an
`<app-wake>` from the app. |
| `send` `path`/`files` | Read by the agent's type in its saved
workspace. Agents on an execution target, and types without a reader,
return their refusal. |
| `channel_create` | Takes native arguments. A private Solo chat with
the owner's Bestie must now pass `visibility: "private"`, `solo: true`
and `members` explicitly. Buzz no longer fills them in. |

An unupdated consumer that accepts only `read`/`post`/`create` will
reject `supportedScopes: ["agent"]`. Its upgrade path is to accept
`agent` and request `scope=agent`, which takes one owner approval.

## Overlap

These open PRs touch nearby files. This PR neither depends on nor
replaces any of them:

- #2260 and #2685 cover external pairing and identity.
- #2647 adds plugin skills to `session-tools`.
- #2622 covers Bestie settings.
- #1939, #1909, #1854, #2311 and #2070 change `service.ts`/`runner.ts`.
- #2610 has no shared files.

## Validation

Ran on a Linux Blox box against the current head:

- `tsc --noEmit` and `tsc -p tsconfig.design.json`;
- Biome on the touched files;
- Vitest for `src/buzz-mcp`, the external connection, dialog and
settings tests, `AgentsPage.test.tsx`, `service.test.ts`,
`plugin-wake.test.ts` and the Claude, Codex, Pi and goose runtime tests.

New tests cover the external handoff's trigger and `<app-wake>` wording,
file reads through the type's reader (target workspace, cancellation on
close, native refusal), the Claude and Codex workspace and
execution-target cases, a saved narrow approval that a link asks to
resume as `agent`, and memory read from the selected agent. The Rust
pairing tests (`host_mcp::pairing`) need the Tauri system libraries, so
they are left to PR CI. No browser journeys were added or removed.
Independent security reviews traced authorize, approve, resume, renew
and call, and found no path that grants tools without the `agent` scope.

Not done:

- The native desktop consent dialog and a live external connection have
not been exercised against this build, including a live `<app-wake>`
turn and a file read in a running Claude, Codex, Pi or goose agent.
- No human testing yet.
- The Nexus side of the contract is a separate change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: Kyle Zemek <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>

## TL;DR

Removes the six owner-session read tools that let a Buzz-hosted agent
read with its owner's own access: channel, member and DM lists, channel
details, messages and canvases. An agent's own reads and the channel
archive, unarchive and delete changes are unchanged. The tools are gone
from discovery on every harness, and a cached or direct call to one is
refused before anything is read with the owner's session.

Fixes NEXUS-4348 · Initiative:
https://blockcell.sqprod.co/sites/kylez-buzz-mcp-initiative/

## Scope

Kyle's request was to remove "the channel/member/dm list/get" endpoints
and leave the archive/delete channel changes for now. Removing
`owner_read` and the two Canvas tools as well is the initiative lead's
interpretation: they read through the same owner session and handle, and
leaving them would keep the owner-read capability this removes. If that
is wrong, the #2881 half can be restored on its own.

### Removed

From #2745 (owner channels and members):
- `owner_channel_list`, `owner_channel_get`, `owner_member_list`, their
hint text and discovery on Claude Code, Codex, Pi, the session RPC and
the harness kit.
- `src/features/agents/owner-access.ts`, the run handle's `ownerAccess`
field and the runner's host hook that built it for bundled-revision
runs.
- The `BUZZ_OWNER_MCP_COMMUNITIES` build setting (`vite.config.ts`). A
distributor build that still sets it now gets nothing from it;
`docs/configuration.md` lists it with the other retired inputs.
- The owner-tool sections in `docs/agents.md`, `docs/configuration.md`,
`docs/buzz-help.md` and `src/buzz-mcp/AGENTS.md`.

From #2881 (owner messages and canvases):
- `owner_read`, `owner_canvas_get`, `owner_canvas_history`,
`src/buzz-mcp/owner.ts` and the `Owner*` client types.
- The `docs/relay-queries.md` paragraph, and the exports of `tools.ts`
helpers that only `owner.ts` used. `edited()` keeps its author-only edit
selection, minus the owner parameter.

### Kept

- From #2745: the Stop and cancellation fences in the Claude Code, Goose
and ACP sessions (`workLifetime`, `current()`), which every Buzz tool
call now depends on, and the channel-lifecycle changes
(`channel-lifecycle.ts`, including its `records` parameter).
- `addTool` still refuses plugin tool names starting with `owner_`, so a
stale call to a retired name can never reach plugin code. There is no
other owner-prefixed restriction and no new permission layer.
- Ordinary agent-scoped reads, Codex per-thread/turn tool validation,
plugin and external isolation.

## Alternate routes checked

Nothing else reached these tools: no Rust, IPC, sidecar or RPC path, and
Mesh and external agents use the same run handle that no longer carries
owner access. Codex thread tool keys no longer carry the `:owner`
suffix, so threads created with owner tools are replaced instead of
reused with a stale tool list.

## Tests

The new tests list the six names as a fixed fixture rather than reading
them from the catalog:
- `session-tools.test.ts`: `sessionTools()` and `sessionHint()`, which
every harness lists from, name none of the six.
- `service.test.ts`: a real bundled run handle has no `ownerAccess`.
With the owner's session stubbed to return an `OWNER_ONLY` message for
an owner-only channel, each retired name is refused with `No tool
<name>` before any relay query. An ordinary `read` of that channel then
runs with the agent's own key, filtered to that channel, and returns `No
messages.`. The same client's `read` of the agent's own channel returns
its message, and no read through the owner's session ever names the
owner-only channel. External agents see none of the names and are
refused the same way.
- `codex/runtime.test.ts`: `dynamicTools` lists none of the names, each
call fails Codex's validation, a planted owner-access spy is never
called, and the thread's own `read` works.
- `app-client.test.ts`: a handle that still carries an owner capability
doesn't pass it to the tool client.
- The Claude Code and Goose Stop/timer tests now hold an ordinary
`mem_get` read instead of an owner tool.

On a Blox box with these commits applied to main: `tsc` passes, and the
12 affected Vitest files pass (claude, codex, goose, pi runtimes,
app-client, tools, session-tools, service, kit, ACP client,
channel-lifecycle). Full CI covers the rest. `git push --no-verify`
skipped the pre-push lanes (types-and-related-unit-tests, design-system,
rust-clippy); CI's `pnpm check`, sharded Vitest and clippy jobs repeat
all three.

Fail-before check: the removal tests in `service.test.ts` and
`codex/runtime.test.ts` were run against the pre-removal source
(0a5c190). Three of them fail on real assertions:
- Codex `dynamicTools` contains `owner_channel_list`.
- An external agent's call returns "Owner tools are not available to
this agent here; nothing was read." instead of `No tool
owner_channel_list`.
- The bundled handle has `ownerAccess`.

All three pass on this branch. Vitest strips types, so this check
doesn't cover `tsc`. The `session-tools.test.ts` discovery test also
passes on the old source, because that source only lists the tools when
the owner setting is on, so it doesn't count as a fail-before check.

## Not covered

- No native app run or live relay check. The removal is exercised
through the service, runner and harness tests above.
- A Buzz process already running a build with these tools keeps them
until it updates. This doesn't revoke anything remotely.

## Related open PRs

- Human work in overlapping files keeps its behavior but may need a
rebase: #2700, #2974, #3081, #2972 (cancel added tools on native Stop),
#2935, #1634, #2622, #3095, #2882.
- #3004, #3005, #3006, #3008 and #2980 build on the removed owner access
and are not part of this change.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
(claude-opus-5-5) on behalf of kylez

---------

Signed-off-by: Kyle Zemek <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>

…ge plugins (#3073)

## Problem

Both **Import an agent** dialogs (Agents → New agent → Import an agent,
and a shared agent's Import) said only "Enable an agent type plugin to
import agents." In a browser no agent type can ever register, because
Agents is unavailable outside the desktop app, so that advice could not
help. On desktop nothing linked to where plugins are turned on.

Bestie's **Remembers you** row told people to "Clear memory in the
Memory tab", but the Memory tab only reads memories; deletion there
never shipped.

## Change

`NoImportTypes` in `AgentBrowse.tsx` now owns the empty state for both
Import dialogs and branches on the Agents snapshot status:

- **unavailable** (browser): "Agents runs in the desktop app. Open Buzz
there to import one.", worded as the Agents page's own empty state.
- **error**: "Agents could not load." with the snapshot's error, or the
page's "Try again." fallback.
- **loading**: a delayed "Loading agent types…" status through
`LoadingRegion`, since types may not have registered yet.
- **ready with no runnable type**: "No harness that runs agents on this
computer is available. Check Manage plugins." with **Manage plugins** as
a `SettingsSectionLink` to Settings → Plugins. Only this state has a
link. It names what is missing, not why, because the component cannot
tell every plugin off from only a hosted type such as Builderlab on, or
from a plugin that is on but failed to activate; Manage plugins shows a
plugin enabled in the last two.

The Agents page passes its existing `openSettings` to `ImportAgents` and
the Marketplace's shared agent panel. An agent card in a conversation
renders the same shared dialog, so it opens Settings through the
navigator it already uses. Each dialog closes before Settings opens.

Bestie's description now ends "To clear a memory, ask Bestie to forget
it." Forgetting comes from the shared Buzz base prompt and `mem_rm`, so
it works whether Remembers you is on or off; verified for Claude Code,
Codex and Goose. The Bestie README and `docs/buzz-help.md` say the same,
and the help notes that Import works only in the desktop app and, when
no agent type plugin that runs agents on this computer is on, that the
dialog says no harness that runs agents on this computer is available
and links Manage plugins.

## Before and after

Left is `main`, right is this fix. Three segments: the browser Import
dialog, the Bestie Remembers you row and the Memory tab, then Import
with the only agent type plugin turned off, after turning it off in
Settings → Manage plugins. Recorded in the browser build against the
fixture relay.


https://github.com/user-attachments/assets/5276ed5e-4ef1-4095-9bd0-578fa4821d35

![Browser Import an agent: main still says to enable a plugin, the fix
says Agents runs in the desktop
app](https://github.com/user-attachments/assets/0cd4c939-e9ab-4232-aadc-41b8f2ff8114)

![Bestie Remembers you row: main ends "Clear memory in the Memory tab",
the fix ends "To clear a memory, ask Bestie to forget
it"](https://github.com/user-attachments/assets/3be0213f-94b1-48bc-8b66-129b8b43e026)

![No agent type plugin on. Top: main's dialog is a dead end, the fix
says no harness that runs agents on this computer is available, with
Manage plugins as a link (the frame and the video predate the final
wording, which the text above quotes). Bottom: clicking it has closed
the dialog and opened Settings → Manage
plugins](https://github.com/user-attachments/assets/685bfa7e-85f6-4406-a6a0-3ddcf4b05089)

## Verification

| Check | Result |
| --- | --- |
| vitest on `AgentBrowse`, `AgentsPage`, `BestieTab`,
`SettingsSectionLink`, `AgentCardAttachment` | 5 files, 208 tests pass |
| The same five files with `main`'s `AgentBrowse.tsx` swapped back | 9
fail, 199 pass |
| `tsc --noEmit` | clean |
| biome on changed files | clean |
| `git diff --check` | clean |

Two agent review rounds: the first flagged plugin advice leaking into
the error and loading states, a wording mismatch with the Agents page
empty state, unclear help wording and an unverified Bestie forget claim,
all fixed in this commit; the second found nothing to change.

## Overlap

#2622 edits `src/bundled/bestie/features.ts`, the Bestie README and the
help, and keeps the "Clear memory in the Memory tab" sentence. Whichever
lands second takes a trivial conflict on that sentence.

## Not checked

- The native desktop app was not run; the plugin-off segment uses the
browser fixture's fake native layer.
- Dark theme, narrow width and enlarged text were not inspected.
- A hosted Builderlab Bestie's prompt and tools belong to its provider
and cannot be verified from this repo, so the sentence says what to do
rather than promising a result.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: mtoohey <[email protected]>
Signed-off-by: Matt Toohey <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>