Skip to content

doctor warns when a Buzz agent's directory record and profile disagree on its name - #196

Merged
devin-ai-integration[bot] merged 12 commits into
mainfrom
devin/1794600770-doctor-directory-name
Nov 19, 2026
Merged

devin-ai-integration[bot] merged 12 commits into
mainfrom
devin/1794600770-doctor-directory-name

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

doctor now reads the agent's kind-0 profile and warns when the directory record's display_name matches neither the profile's display_name nor its name. That is the Ron case: the profile was renamed to "Ron", the record kept "Ron Weasley", so @Ron Weasley reached nobody while doctor still said the agent was mentionable. A mismatch replaces the "so it is mentionable" line with:

warn  surface buzz: the directory record's display_name is "Ron Weasley" but the profile names it "Ron", so a mention by the record's name does not resolve — re-run `sageox-agent identity register buzz`, which publishes profile.json's display_name to both (a restart keeps the record's)

The repair it names depends on #194 (re-registering renames the record), which has merged; this branch now includes it and targets main.

  • Whitespace check not added. Ryan approved dropping it. No such check ever existed in code; the issue had only proposed one. Buzz clients match multi-word names, and fleet agents named under the house naming rule ("Rip Merging", "Paul Bunyan") are mentioned every day. A test pins that a two-word name the record and profile agree on passes.
  • packages/adapter-buzz/src/profile.ts: new readProfile, bounded by the same CONNECT_MS connect timeout as a publish. The directory fetch is generalized into fetchOwn(relay, pubkey, kind), which applies NIP-01's replaceable-event rule: newest created_at wins, and a same-second tie goes to the lower id, as supersedes in buzz.ts does.
  • packages/cli/src/cli.ts: profileNameDrift runs after the existing channel, respond_to and allowlist checks. If the profile can't be read, has no name, or the record has no display_name, the check stays silent or gives a read warning. It never adds a new problem.
  • CHANGELOG entry, plus a paragraph in docs/guide/chat-surfaces.md.

Ryan's call (default chosen: warn). I made this a warning, not a problem. The profile's own name still reaches the agent, and buzz-agent-start.sh runs doctor, so a problem would block bring-up of an agent that can still be reached. To make it blocking, change opts.warnings.push(drift) to opts.problems.push(drift) in checkDirectory.

Repair hint names the relay and only offers what registration can do. Registration signs only with BUZZ_NSEC, so the hint says re-run \sageox-agent identity register buzz` against only when the surface's identity resolves to the same key asBUZZ_NSEC` (an alias ref to that key counts). For a surface on another key, the warning says registration cannot fix that record instead.

Part of sageox/sageox-monorepo#3583. The whitespace half needed no code; this PR adds the name check.

Test Plan

New packages/cli/test/doctor-directory-name.test.ts runs the real bin/sageox-agent doctor against an in-process LocalRelay (auth required) that holds a signed directory record and a signed kind-0 profile:

  1. Record "Ron Weasley" with profile {name: "Ron"}: expects the warning with both names and the fix, and no "so it is mentionable".
  2. Record "Paul Bunyan" with a profile that agrees: expects "so it is mentionable" and no warning.

Red first, with only the cli.ts change reverted:

× warns, naming both names and the fix, when the record kept a name the profile dropped
AssertionError: expected '  ok    config /tmp/sageox-agent-doct…' to contain 'surface buzz: the directory record\'s…'
Tests  1 failed | 1 passed (2)

New readProfile test in packages/adapter-buzz/test/profile.test.ts: two profiles signed in the same second, the higher id delivered last. Red with only the tie-break reverted:

× keeps the lower id when two profiles share a second, whichever arrives last
AssertionError: expected { name: 'Ron' } to deeply equal { name: 'Ron Weasley' }

doctor-directory-name.test.ts also covers the hint: a surface on another key (BUZZ_NSEC_TWO) is not offered re-registration, and one whose ref (AGENT_NSEC) holds the BUZZ_NSEC key is. The alias case was red with the key comparison reverted to the ref-name check. Doctor resolves BUZZ_NSEC the way registration's directory publish does (a mounted /mnt/secrets-store/BUZZ_NSEC before .env), so a mounted key that differs from the alias's gets the "cannot fix" warning. That case can't run in CI (it needs a file under /mnt), so I checked it by hand with a throwaway test: red with the mount-first lookup reverted, green with it.

With the fixes restored, those plus doctor-channels, run-directory, identity-register-directory and the rest of adapter-buzz/test/profile pass. pnpm typecheck is green. The full suite runs in CI (this VM has no age binary).

Leftover: confirming the warning against a real drifted agent on buzz.test.sageox.ai needs live relay credentials, so that isn't covered here.


Checklist (expand if needed)
  • Tests added, or N/A documented
  • pnpm typecheck && pnpm test green (typecheck green; full suite on CI)
  • Deployment checks run if deploy/ changed (N/A)
  • CHANGELOG entry added if user-facing
  • Breaking change documented (none)
  • Docs updated if behavior or configuration changed

Link to Devin session: https://app.devin.ai/sessions/ae1a5a2674424adba5e7fe49bb7f165f
Open in Devin Desktop: https://app.devin.ai/desktop/session/ae1a5a2674424adba5e7fe49bb7f165f?variant=devin


🟢 Devin Review found nothing to fix · View findings · Follow Devin's work

Devin Review

Summary by CodeRabbit

  • New Features
    • The doctor check warns when a Buzz agent’s directory display name differs from its profile name or the profile cannot be read. Mismatches show both names and recommend sageox-agent identity register buzz; names containing spaces are supported.
    • If the directory record uses another identity, the warning explains that re-registration cannot update it and that it must be republished by that identity.
  • Documentation
    • Updated the Buzz setup guide and changelog with details about name checks and how profile names affect mentions.

Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

rsnodgrass and others added 3 commits November 13, 2026 13:22
The kind-10100 record kept the first display_name it was published with: directoryFor never set one, so the carried value won on every publish. Registration now passes the display name it was given (profile.json or --name), and publishes under manifest.name as run does, so the two writers stop flipping the name field. run's reconcile still carries the record's display name.

Refs sageox/sageox-monorepo#3582

Co-Authored-By: Madhur Shrimal <642275+shrimalmadhur@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…t leak in

Co-Authored-By: Madhur Shrimal <642275+shrimalmadhur@users.noreply.github.com>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…e on its name

A rename that reached the kind-0 profile but not the directory record left the record's display_name binding to nobody, while doctor still called the agent mentionable. doctor now reads the profile and warns, naming both values and the fix (re-run identity register buzz). A space in the name is not flagged: clients match multi-word names.

Part of sageox/sageox-monorepo#3583

Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

The Buzz adapter now reads kind-0 profiles. The doctor command compares profile names with a directory record’s display_name and warns about profile-read failures or mismatches. The changelog and guide document the check, and tests cover matching and mismatched names, including records for another identity.

Changes: Buzz identity naming

Layer / File(s) Summary
Read the newest profile
packages/adapter-buzz/src/profile.ts, packages/adapter-buzz/test/profile.test.ts
A shared helper selects the newest parseable event for a requested kind, using event ID to resolve timestamp ties. The new readProfile function reads the signer’s kind-0 profile and closes the relay. The test checks selection when timestamps match.
Check doctor name drift
packages/cli/src/cli.ts, packages/cli/test/doctor-directory-name.test.ts, CHANGELOG.md, docs/guide/chat-surfaces.md
doctor compares the directory display_name with nonblank profile names. It warns if profile reading fails or neither profile name matches. For mismatches, the warning gives repair guidance based on the record’s identity. Tests cover mismatched names, matching multi-word names, and another identity. The changelog and guide describe the check.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant checkDirectory
  participant profileNameDrift
  participant readProfile
  participant fetchOwn
  participant Relay
  checkDirectory->>profileNameDrift: Check directory display name
  profileNameDrift->>readProfile: Read agent profile
  readProfile->>fetchOwn: Fetch kind-0 event for signer
  fetchOwn->>Relay: Read events for signer and kind
  Relay-->>fetchOwn: Profile events
  fetchOwn-->>readProfile: Newest parseable profile
  readProfile-->>profileNameDrift: Profile object or read error
  profileNameDrift-->>checkDirectory: Warning or no warning
Loading

Possibly related PRs

  • sageox/agent-toolkit#194: Sets the directory record’s display_name from --name or profile.json, which supports the registration repair guidance in this change.

Suggested reviewers: shrimalmadhur

Merge Risk: Minimal · previous review f0bdc

The doctor command now warns, without blocking, when a Buzz directory name differs from the profile name. The repair guidance is scoped to what registration can actually update. No concrete merge-blocking risk remains.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: doctor now warns when a Buzz agent's directory record display_name disagrees with its kind-0 profile name. The raw summary and objectives confirm this is the primary c…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: doctor now warns when a Buzz agent's directory record display_name disagrees with its kind-0 profile name. The raw summary and objectives confirm this is the primary change, with supporting profile reads, tests, and docs. The title is 82 characters, which is slightly long but still specific and readable.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 40e5659 and f0bdc1a.

Files selected for processing: 4

  • CHANGELOG.md
  • docs/guide/chat-surfaces.md
  • packages/cli/src/cli.ts
  • packages/cli/test/doctor-directory-name.test.ts

Limit details: You’ve used all 3 included reviews currently available. Your 77 included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

@veria-ai

veria-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

PR overview

No security issues were found in this pull request.

Reviews

@greptile-apps

greptile-apps Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The change affects the diagnostic output for configured Buzz agents.

Add a connection time limit before merging so the optional check cannot stall setup.

Fix All in Claude CodeFindings

  1. P1 Profile checks can hang setup ▶

Reviews (1) · Last reviewed commit: "doctor: warn when a Buzz agent's directo..." · Reviewed by Greptile

greptile-apps[bot]

This comment was marked as resolved.

…a silent relay

Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration
devin-ai-integration Bot changed the base branch from devin/1794575975-buzz-directory-rename to main November 19, 2026 17:09
rsnodgrass and others added 2 commits November 19, 2026 17:10
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

#194 landed as a squash. Keep main's copy of the register test, and move this PR's CHANGELOG entry from 0.13.0 back under Unreleased.
…apter do

Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

rsnodgrass and others added 2 commits November 19, 2026 17:25
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
coderabbitai[bot]

This comment was marked as resolved.

rsnodgrass and others added 3 commits November 19, 2026 17:35
…rites

identity register buzz signs only with BUZZ_NSEC, so for a surface on another identity the warning now says it cannot fix that record instead of offering it, and every form names the relay.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…offering re-registration

Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
…re-registration

Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

… typed path

Co-Authored-By: Ryan Snodgrass <ryan@sageox.ai>
Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
@devin-ai-integration
devin-ai-integration Bot merged commit 6240fab into main Nov 19, 2026
7 checks passed
@devin-ai-integration
devin-ai-integration Bot deleted the devin/1794600770-doctor-directory-name branch November 19, 2026 17:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant