Skip to content

docs(research): What a BYO Harness registration box has to contain - #752

Closed
omesser wants to merge 1 commit into
mainfrom
docs/byo-harness-registration
Closed

omesser wants to merge 1 commit into
mainfrom
docs/byo-harness-registration

Conversation

@omesser

@omesser omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner

Rescues the registration pass that has been sitting unpushed on research/byo-harness-mcp
since before #743. One new file, docs/research/byo-harness-mcp-registration.md. No code.

#743 carried one of this pass's seven sections into byo-harness-mcp-reload.md §6. The
other six have never been published, and they are the half that bears on the Settings work.

What it answers

Story 66 wants an Advanced section on the Director tab: a harness picker, a generated
snippet in a copyable box, per-harness instructions under it. This says what that box has
to contain for each of the five harnesses, and where one box is not enough.

All five take the loopback HTTP endpoint with Authorization: Bearer <token> as an
ordinary configured header
, so ADR-0026's stdio shim is a fallback here, not a
necessity. Four were driven against a replica of mcp_http.rs's gate and connected. None
sends an Origin header, so the DNS-rebinding refusal never fires.

Concrete things the snippet generator needs to know:

  • Emit the token without the Bearer prefix. Three of five templates add it
    themselves; a pre-prefixed token yields Bearer Bearer … in the other two.
  • Claude Code needs two lines, and the first is not optional. Re-adding an existing
    name prints "already exists", exits 0, and leaves the stale URL and token in place. Both
    values change every app run, so the remove is what makes the snippet re-runnable.
  • Never generate -s project or grok's --scope project. Both write a committable
    file, which is the only failure mode here that puts the token somewhere the user did not
    expect.
  • Each harness has a cheap non-interactive verify line — claude mcp list,
    hermes mcp test ai-buddy, opencode mcp list, grok mcp doctor ai-buddy. Four were
    run; they report connected/failed and a tool count without starting a session.
  • The snippet is valid for this app run only. Both halves change on restart, so the box
    is somewhere the user returns to, not a setup step. Only hermes makes it a paste.

The blocker it names

None of it is reachable today. Endpoint in src-tauri/src/mcp_http.rs derives
Clone and nothing else — no Debug, no Serialize — and the token leaves it through
exactly two methods, both called only from harness.rs to compose the mcpServers entry
for a Harness ai-buddy spawned itself. No Tauri command, no settings row, no CLI flag
prints it. That is ADR-0023 and ADR-0026 working as intended for the spawned case, and it
is what story 66 cannot live with.

A second process cannot solve it: ai-buddy --print-mcp-endpoint would have a different
token, and making it ask the running app means an unauthenticated loopback route handing
out the credential. The reveal has to come from the running app's own UI.

Five options are laid out with their costs. The document's own reading is 1 + 2 —
reveal it in the generated snippet, and refuse the shared-file scopes — with 4 (fixed
port, per-run token) held in reserve for when the re-paste is what people actually
complain about. 3 (a stable token on disk) reverses ADR-0026 on its own terms and
should arrive as its own ADR, not as an implementation detail of a settings pane.

This is research, not a decision. It does not amend any ADR.

Evidence discipline

Every claim is marked ran or read, and the two are never mixed in one claim. The
What is not verified section is honest about the soft parts: codex is entirely
unverified
(not installed here), nothing was tested against the running binary, no
harness was observed actually calling a tool, and the mid-session column is the weakest
row in the table. A borrowed machine with codex settles the largest gap in a minute.

Verification

Probes ran at d55beb74. Before publishing I re-checked every claim this document makes
about ai-buddy's own source against 772026cf: Endpoint still derives Clone alone,
and authorization() and stdio_env() are still its only two ways out. The preamble says
so.

node --test tests/ passes (203) and pre-commit is clean on the file.

— Claude Code agent

🤖 Generated with Claude Code

Story 66 wants an Advanced section on the Director tab that points any
MCP-capable harness at ai-buddy. This is the registration pass behind it:
what the generated snippet contains for each of the five harnesses, and
where one box is not enough.

It also names the blocker. ai-buddy has no surface that reveals the token,
so none of these procedures can be completed by a user today. Five options,
with what each costs against ADR-0023 and ADR-0026.

Section 6 of this pass shipped separately in #743; the section here points
at it rather than repeating it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@omesser

omesser commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

Closing this as superseded. The owner was right that it is outdated, and I should have checked before opening it.

The document's central claim is false on current main. It says "None of the above is reachable today, because ai-buddy does not tell anyone the token." #577 surfaced it: settings.rs has byo_harness, byo_snippet, byo_steps and byo_token, and settings/form.rs has the form rows and their tests.

Worse, the findings it presents as new are already in the shipped code as doc comments on byo_registration(), with issue references:

#580 checked all five snippets against the installed CLIs, and every_byo_snippet_carries_the_url_and_the_raw_token guards it. The implementation also goes further than the research on Hermes: it uses hermes mcp add --auth header with an interactive token prompt and keeps the YAML fragment only as the documented alternative.

So every section is merged, implemented, or moot: §"Prompting is not a route" shipped in #743, §"What the Settings box has to contain" and §"Where one box is not enough" are byo_registration(), and §"The token problem" was decided and built as #577.

My verification error, for the record. I did check this branch against main before publishing, but I checked the wrong thing: that Endpoint still derives Clone alone, with no Debug or Serialize. That is still true, and it is irrelevant — the token reaches the user through settings.rs, not through a derive. I verified a proxy and reported the claim as holding.

Nothing here is worth salvaging into a separate document. The branch is deleted.

— Claude Code agent

@omesser omesser closed this Sep 15, 2026
@omesser
omesser deleted the docs/byo-harness-registration branch September 15, 2026 23:12
omesser added a commit that referenced this pull request Sep 22, 2026
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
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