feat(desktop): register existing external agent references

[camaragon]

feat(desktop): register existing external agent references

Summary

• add a keyless, device-local registry for existing external agent identities
• render registered identities in the Desktop Agents view as Externally managed cards
• support explicit registration, profile navigation, full-public-key copy, and reference-only removal
• fail closed when lifecycle/configuration commands target a registered reference

Related to block#3054 and block#3556.

Why

Desktop currently models locally managed agents and relay-discovered agents, but it has no explicit way to retain a display reference to an existing identity that is operated elsewhere and may not be discoverable through current relay ownership metadata.

This change adds a narrow local reference type instead of importing the identity as a managed agent. It complements the relay-discovery approach in block#3556: relay discovery remains useful when verified ownership metadata exists, while an explicit local reference covers identities that must be selected directly by public key.

Safety boundary

A registered reference contains only:

• public key
• optional local label
• optional local role summary
• creation and update timestamps

It never contains or owns a private key, authorization credential, runtime, provider, model, environment, system prompt, process, or auto-start configuration.

Registered references are display/navigation metadata only. They are not added to the application-wide trusted-agent set and do not affect bot classification, mention eligibility, or configuration-message authorization. Their cards expose no Start, Stop, Restart, Deploy, model, runtime-error, auto-start, or secret controls.

Managed-agent lifecycle/configuration/delete commands validate ownership before side effects and return agent <pubkey> not found for registered references.

Storage and rollback

References are stored separately from managed agents in a restricted, atomically written JSON file. Invalid JSON is preserved and fails closed. Removing a reference deletes only the local display reference; it does not delete an identity or stop an external process.

Older builds ignore the separate reference file, so code rollback does not alter managed-agent state.

Verification

• cargo fmt --check
• cargo test registered_references --lib — 17 passed
• cargo test registered_agent_references --lib — 10 passed
• cargo test --lib — 2,608 passed, 17 ignored
• frontend unit tests — 5,104 passed
• pnpm typecheck
• pnpm check
• pnpm build:e2e
• node scripts/check-registered-agent-boundary.mjs
• focused registered-reference Playwright coverage — 4 passed

Independent implementation review found no unresolved blocking, high, or medium correctness findings.

[Copilot]

Pull request overview

Adds a new “registered agent reference” concept to the Desktop app: a keyless, device-local registry of external agent identities (pubkey + optional label/role + timestamps) that can be displayed and navigated to, while explicitly preventing lifecycle/configuration commands from targeting these references.

Changes:

• Introduces a new Tauri-backed JSON store + commands to list/register/unregister registered agent references, plus command-boundary guards that fail closed for non-managed targets.
• Adds Desktop UI + React Query plumbing to render “Externally managed” agent cards, register a reference, navigate to profile, copy full pubkey, and remove the local reference.
• Expands unit/E2E coverage and adds a boundary-check script/test to ensure registered references remain display/navigation-only.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
desktop/tests/helpers/bridge.ts	Extends mock bridge options to seed/err registered agent references.
desktop/tests/e2e/agents.spec.ts	Adds E2E coverage for registration flow, display-only controls, profile navigation, removal, and malformed store handling.
desktop/src/testing/e2eBridge.ts	Implements mock Tauri commands for listing/registering/unregistering registered references in E2E mode.
desktop/src/shared/api/tauriRegisteredAgents.ts	New TS API + runtime validation/mapping for registered agent reference Tauri commands.
desktop/src/shared/api/registeredAgents.test.mjs	New unit tests for TS mapping/normalization and failure behavior.
desktop/src/features/agents/ui/UnifiedAgentsSectionCardTarget.test.mjs	Updates UI test props to include registered reference inputs/handlers.
desktop/src/features/agents/ui/UnifiedAgentsSection.tsx	Renders registered reference cards, dedupes against managed agents, and surfaces registered-reference load errors.
desktop/src/features/agents/ui/RemoveRegisteredAgentDialog.tsx	New confirmation dialog for removing a local registered reference.
desktop/src/features/agents/ui/RegisterExistingAgentDialog.tsx	New dialog to register an existing agent reference (pubkey/label/roleSummary).
desktop/src/features/agents/ui/RegisteredAgentIdentityCard.tsx	New card UI for registered references with profile navigation, copy pubkey, and removal action.
desktop/src/features/agents/ui/AgentsView.tsx	Wires registered-reference queries/mutations and adds entry points to open register/remove dialogs.
desktop/src/features/agents/registeredAgentBoundary.test.mjs	New test enforcing “display/navigation-only” boundaries for registered reference usage.
desktop/src/features/agents/lib/useAgentsDataRefresh.ts	Includes registered references in local “agents-data-changed” invalidation set.
desktop/src/features/agents/lib/registeredAgentCards.ts	New helpers for display resolution, role summary labeling, and managed-agent dedupe.
desktop/src/features/agents/lib/registeredAgentCards.test.mjs	New unit tests for registered reference card helpers.
desktop/src/features/agents/hooksRegistered.test.mjs	New tests verifying query invalidation boundaries for registered reference mutations/refresh.
desktop/src/features/agents/hooks.ts	Adds registered references query key, query hook, and register/unregister mutations.
desktop/src-tauri/src/managed_agents/storage.rs	Adds a non-hydrating “managed agent record exists” check to support fail-closed command boundaries.
desktop/src-tauri/src/managed_agents/runtime_commands.rs	Guards runtime lifecycle commands with the registered-reference/ownership preflight.
desktop/src-tauri/src/managed_agents/registered_references.rs	New Tauri store + commands for registered references and the shared “reject target unless managed” guard.
desktop/src-tauri/src/managed_agents/mod.rs	Registers the new registered-reference module and re-exports commands/guard.
desktop/src-tauri/src/lib.rs	Registers new Tauri commands (list/register/unregister registered references).
desktop/src-tauri/src/commands/mod.rs	Adds the new command router module for guarded legacy commands.
desktop/src-tauri/src/commands/agents.rs	Refactors legacy commands into _unchecked internals so guarded wrappers can preflight before side effects.
desktop/src-tauri/src/commands/agent_settings.rs	Adds fail-closed preflight guard to settings commands before spawning blocking work.
desktop/src-tauri/src/commands/agent_registered_targets.rs	New guarded wrapper commands for update/start/stop/delete managed agent operations.
desktop/src-tauri/src/commands/agent_models.rs	Refactors update entry point to allow guarded wrappers while keeping implementation internal.
desktop/src-tauri/src/commands/agent_models_update.rs	Makes the implementation non-command (*_impl) so wrappers own the command boundary.
desktop/scripts/check-registered-agent-boundary.mjs	New script enforcing that registered references remain display/navigation-only consumers.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[camaragon]

Fixed in c76f576. The form submit boundary now catches mutation rejection, keeps the dialog open, and lets the mutation-owned error prop render the failure. Added a focused regression.

[camaragon]

Fixed in c76f576. Clipboard permission/write rejection is now consumed inside the menu event boundary. Added a focused regression.

[camaragon]

Fixed in c76f576. Closing the registration dialog now resets the registration mutation before the next open. Added a focused regression.

[camaragon]

Fixed in c76f576. The unregister promise chain now consumes rejection at the UI event boundary while leaving mutation error state intact. Added a focused regression.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

Suppressed comments (1)

desktop/scripts/check-registered-agent-boundary.mjs:71

• walk() only scans .ts/.tsx files, but this boundary gate’s allowlists include several .mjs files (e.g. hooksRegistered.test.mjs, registeredAgentBoundary.test.mjs). As a result, the script won’t actually enforce the boundary constraints on those .mjs consumers, and it may also traverse unexpected directories if node_modules/dist exist under src.

Update walk() to match the test’s behavior: skip node_modules/dist and include .mjs in the extension filter.

function walk(dir) {
  return readdirSync(dir).flatMap((entry) => {
    const path = join(dir, entry);
    if (statSync(path).isDirectory()) return walk(path);
    return /\.(ts|tsx)$/.test(path) ? [path] : [];

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

Suppressed comments (1)

desktop/src-tauri/src/managed_agents/registered_references.rs:87

• load_from_path() sorts but does not dedupe by pubkey. If the JSON store ever contains duplicate pubkeys (e.g. manual edits or older buggy writes), the frontend will render duplicate cards keyed by reference.pubkey (React key collision), and register_existing_agent_reference() will only update the first matching entry while leaving the others stale. Consider deduping after sorting so pubkeys are unique on read.

    refs.sort_by(|left, right| left.pubkey.cmp(&right.pubkey));
    Ok(refs)

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

desktop/src/shared/api/tauriRegisteredAgents.ts:54

• The invalid-pubkey error message from normalizeRegisteredPubkey ("Malformed registered agent pubkey.") does not match the error surfaced by the Tauri layer in tests/mocks ("invalid public key"), which can lead to inconsistent UX and brittle tests. Consider standardizing on the same message here so the UI shows a consistent validation error regardless of whether it’s caught client-side or returned by Tauri.

  if (!HEX_PUBKEY_RE.test(pubkey)) {
    throw new Error("Malformed registered agent pubkey.");
  }

desktop/src/features/agents/ui/AgentsView.tsx:371

• unregisterReferenceMutation.mutateAsync(...) errors are currently swallowed (.catch(() => undefined)), so a failure to remove a reference provides no user-visible feedback. Since UnifiedAgentsSection already surfaces actionErrorMessage via toasts, forward the error message here so users can tell the action failed.

        onConfirm={(reference) => {
          void unregisterReferenceMutation
            .mutateAsync(reference)
            .then(() => setReferenceToRemove(null))
            .catch(() => undefined);

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

Suppressed comments (1)

desktop/src/features/agents/ui/UnifiedAgentsSection.tsx:133

• When registeredReferencesError is set, this component still renders visibleRegisteredReferences. If the registered-reference query previously succeeded and a later refetch errors, React Query can keep the last successful data, so stale registered-reference cards would remain visible while the error banner is shown (which undermines the intended “fail closed” behavior for malformed reference stores).

  const visibleRegisteredReferences = React.useMemo(
    () => dedupeRegisteredAgentsAgainstManaged(registeredReferences, agents),
    [registeredReferences, agents],
  );

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

desktop/src/features/agents/ui/RegisteredAgentIdentityCard.tsx:82

• The card ariaLabel includes the full 64-char pubkey, which screen readers will read out verbatim and can be extremely verbose. Consider omitting the pubkey from the accessible name, or using the already-rendered truncated form for a more usable announcement.

      ariaLabel={`${display.label} externally managed agent profile, public key ${reference.pubkey}`}

[camaragon]

Fixed in c2ff116. Ownership preflight now deserializes a minimal pubkey-only projection; inline secret and unrelated fields are skipped rather than materialized into ManagedAgentRecord. Added red/green regression proving full-record deserialization fails while pubkey-only ownership lookup succeeds.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.

Suppressed comments (1)

desktop/src/testing/e2eBridge.ts:12744

• In the E2E bridge, list_registered_agent_references returns mockRegisteredAgents in insertion/update order, but the production Tauri implementation sorts registered references by pubkey on load/save. This divergence can hide ordering assumptions (or create flakes) between mock-mode and real app behavior. Sort by pubkey in the mock before returning so tests exercise the same ordering contract as production.

      case "list_registered_agent_references":
        if (activeConfig?.mock?.registeredAgentsError) {
          throw new Error(activeConfig.mock.registeredAgentsError);
        }
        return structuredClone(mockRegisteredAgents);

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

desktop/tests/e2e/agents.spec.ts:2880

• Same issue as above: the registered-agent card uses a truncated pubkey in its aria-label, so matching against the full pubkey will not find the overlay button and will make this E2E assertion fail.

    await expect(
      card.getByRole("button", { name: new RegExp(pubkey) }),
    ).toBeVisible();

desktop/src-tauri/src/managed_agents/registered_references.rs:98

• load_from_path trusts the on-disk RegisteredAgentReference records without validating/normalizing the pubkey and optional fields. A manually edited or corrupted store could contain non-hex pubkeys, mixed-case duplicates, or overlong labels/role summaries; these currently won’t be preserved as .invalid and can later cause frontend mapping errors or React key collisions. Consider validating + normalizing entries during load and failing closed (with .invalid backup) on any invariant violation.

    let mut refs: Vec<RegisteredAgentReference> =
        serde_json::from_str(&content).map_err(|error| {
            backup_invalid_store(path);
            format!("failed to parse registered agent references (preserved as .invalid): {error}")
        })?;

[camaragon]

Fixed in 93f0c60. Both E2E selectors now match the card accessible name using the same truncated pubkey representation; focused Playwright is green 4/4. The same commit validates every loaded registered-reference pubkey/optional field, rejects noncanonical or overlong data, and preserves original bytes as .invalid.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.

Suppressed comments (1)

desktop/src/features/agents/registeredAgentBoundary.test.mjs:7

• ROOT is derived via new URL(...).pathname, which is not a reliable filesystem path (it stays URL-encoded and is incorrect on Windows drive-letter paths). Several other desktop node tests use fileURLToPath(import.meta.url) for this reason, so this test risks failing cross-platform or when paths contain spaces.

import assert from "node:assert/strict";
import { readFileSync, readdirSync, statSync } from "node:fs";
import { join, relative } from "node:path";
import test from "node:test";

const ROOT = new URL("../../..", import.meta.url).pathname;
const SRC = join(ROOT, "src");

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.

Suppressed comments (1)

desktop/src-tauri/src/managed_agents/registered_references.rs:17

• Doc comment says the pubkey is "normalized 64-byte lowercase hex", but a 64-hex-character pubkey is 32 bytes (or 64 characters). This is misleading for anyone working with key sizes or validation.

    /// The referenced agent public key as normalized 64-byte lowercase hex.

[Copilot]

Pull request overview

Copilot reviewed 31 out of 31 changed files in this pull request and generated no new comments.