Skip to content

ADFA-7139: Plugin API for the SQLite debugger endpoints - #2261

Open
davidschachterADFA wants to merge 8 commits into
sqlite-debugger/ADFA-7137from
sqlite-debugger/ADFA-7139
Open

davidschachterADFA wants to merge 8 commits into
sqlite-debugger/ADFA-7137from
sqlite-debugger/ADFA-7139

Conversation

@davidschachterADFA

@davidschachterADFA davidschachterADFA commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

ADFA-7139

Plugin API for the SQLite debugger endpoints Code on the Go stores (ADFA-7137), so AI-Agent-MCP can connect without the user typing a port or token. The plugin side (AI-Agent-MCP) is appdevforall/addons#166.

Stack: on sqlite-debugger/ADFA-7137.

What it does

  • DebuggerEndpointService.getEndpoints() (plugin-api, beside ToolSourceRegistry): the open project's endpoints (application ID, port, token, updated at). New permission debugger.endpoints. SecurityException without it; IllegalStateException on a read failure or on the main thread; empty list when no project is open or no app has reported. API dump and docs/PLUGIN_API_CHANGELOG.md (26.47, the next release) updated.
  • plugin-manager implements it; the app supplies the rows from debugger_endpoint_table, looked up by the canonical project path.

Tests: value class; service (permission, no project, other project, read failure, main thread); repository lookup through a non-canonical path (fails when the lookup uses the absolute path). :plugin-api:apiCheck passes.

Known: AI-Core asks for approval on every call of a contributed tool, so the debugger's read-only tools still prompt; the ticket's criteria 1 and 3 are amended for phase 1, and automatic approval is ADFA-7147.

No screens added or changed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@davidschachterADFA davidschachterADFA left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Stack review: this is the tip of #2259 -> #2260 -> #2261 (sqlite-debugger/ADFA-7135 -> ADFA-7137 -> ADFA-7139), nothing is based on it. Claims were checked against this PR's head 86b67f56 (it is the stack tip). No existing approvals and no earlier review comments to re-check. Repo rules: CLAUDE.md and REVIEW.md (including the section 13 plugin-API check); neither defines an approve/request-changes rule, so the default verdict table applied.

MINOR

  • DebuggerEndpointRepository.kt:127 - stored endpoints are never pruned, so a dead app's token/port is returned

NITPICK - 1 inline, not listed

Checked and found sound: permission is checked before anything else and the main-thread guard after it; a read failure is thrown and not turned into an empty list; the lookup uses the canonical path the pairing writes, and the test covers a non-canonical path; DebuggerEndpoint.toString leaves the token out; the service is registered on both plugin registration paths; the ABI dump, changelog, authoring doc and README are updated with the code.

Not verified (static review, no build or device): the :plugin-api:apiCheck claim, the tests, and the "26.43" release-week floor in the changelog.

Verdict: COMMENT. Only a MINOR and a NITPICK, which do not block under the default rule. The PR author is the authenticated account, so GitHub would refuse APPROVE regardless.

* answering "no apps".
*/
suspend fun reportedEndpoints(projectDir: File): List<PluginDebuggerEndpoint> =
dao.getByProjectLocation(projectDir.canonicalProjectLocation()).mapNotNull { row ->

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

MINOR: reportedEndpoints returns every stored row with a token and port, with no age or liveness bound.

The row survives the app being killed or uninstalled (nothing in DebuggerEndpointDao clears token/port except clearEndpointIfProjectDiffers on a project move). A plugin calling getEndpoints() then gets a dead endpoint, and the bearer token goes to whatever listens on that port next. Not reachable as a bug today because the API docs tell callers to re-ask after a refused connection or 401/403 and the token only goes to 127.0.0.1, and the only consumer (addons#166) is in a separate PR I did not verify for this. A client that ignores updatedAtMillis is the one at risk.

Say in the KDoc here (or the plugin-api docs) that rows are not pruned, so clients treat updatedAtMillis as a hint, or filter out rows older than some bound.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 6a99814: endpoints of apps that are no longer installed are left out (injected check; PackageManager in the app; every package is visible because Code on the Go targets SDK 28). The Javadoc now says an endpoint can still be stale after the process dies, that updatedAtMillis is when it last reported, and that clients reconnect after a refused connection.

val root = projectRootProvider() ?: return emptyList()
return try {
sourceProvider().endpointsFor(root.absolutePath)
} catch (e: Exception) {

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

NITPICK: catch (e: Exception) also catches InterruptedException/CancellationException coming out of the app's runBlocking source and rewraps them as IllegalStateException.

No current caller interrupts the plugin thread, so nothing misbehaves today. If one did (for example a plugin shutting down its worker), the interrupt would be reported as "Could not read the debugger endpoints" and the thread's interrupted flag would be gone.

Rethrow InterruptedException (restoring the flag) and CancellationException before the generic catch.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in 6a99814: InterruptedException (with the interrupt flag restored) and CancellationException are rethrown unchanged; tests for both.

davidschachterADFA and others added 6 commits November 15, 2026 23:21
…ission

Plugins such as AI-Agent-MCP need to reach the SQLite debugger of the app
the user just built, without the user typing a port or token.

DebuggerEndpointService.getEndpoints() returns the open project's
endpoints as DebuggerEndpoint values (application ID, port, token,
updated at), behind the new permission debugger.endpoints. Contract:
SecurityException without the permission; IllegalStateException on a read
failure or when called on the main thread; an empty list when no project
is open or no app has reported.

The API dump and docs/PLUGIN_API_CHANGELOG.md (26.43) are updated, and
the plugin docs list the permission. A plugin that declares it needs
plugin.min_ide_version 26.43: an older Code on the Go rejects the unknown
permission at validation.

Tests: the DebuggerEndpoint value class.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
PluginManager hands each plugin a DebuggerEndpointServiceImpl, which
checks the debugger.endpoints permission, refuses the main thread, and
maps a read failure to IllegalStateException so a plugin cannot mistake a
failure for "no app has reported".

Tests: permission refused, no project, endpoints of another project not
returned, read failure, main thread refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
The app registers the service when it loads plugins, backed by
debugger_endpoint_table (ADFA-7137). The repository looks endpoints up by
the canonical project path, so a project opened through a symlink or a
non-normalised path still finds the rows stored under its real location.

Tests: repository lookup through a non-canonical path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
…er README

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
…errupts

reportedEndpoints no longer returns the stored port and token of an app that is
no longer installed (injected check, PackageManager in the app). No
<queries> is needed: Code on the Go targets SDK 28, below the package
visibility filter of SDK 30. The
Javadoc says an endpoint can still be stale after the process dies and that
updatedAtMillis is when it last reported. DebuggerEndpointServiceImpl rethrows
InterruptedException (restoring the flag) and CancellationException unchanged
instead of wrapping them. Tests: an uninstalled app is left out, installed ones
are returned, the interrupt and the cancellation pass through; all three fail
with the fix removed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
26.43 to 26.46 are released without it. The changelog entry moves to a new
26.47 section and the floor plugin.min_ide_version is 26.47.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
davidschachterADFA and others added 2 commits November 16, 2026 10:05

@davidschachterADFA davidschachterADFA left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Re-review of #2261 at 2007193 (medium effort). No new findings. Computed verdict: APPROVE (no findings above NITPICK); submitted as COMMENT because GitHub refuses APPROVE on a self-authored PR, and nothing was posted on a non-interactive run without --verdict.

NITPICK - none

Stack. Layer 3 of 4, a tip: below #2260 (ADFA-7137) and #2259 (ADFA-7135, on #2244). The other tip is #2262 (ADFA-7138, on #2259), which does not touch this layer's files. Claims were checked at this head, which is the tip that holds this code. Counterpart: addons#166 reads DebuggerEndpointService / DebuggerEndpoint from here.

Rules applied. REVIEW.md and CLAUDE.md at the head (REVIEW.md is "a coaching doc, not a gate"; no approve/request-changes rule, so the skill's default table applied). Plugin-API surface touched, so REVIEW.md section 13 applied: the new permission key is in the enum, the ABI dump, the three plugin docs, the changelog (26.47, after the 26.46 tag) and a test that pins the key; the service is permission-gated, main-thread-guarded, and registered in both of PluginManager's registration paths.

Prior threads (judged on the code at this head, not on the replies).

  • DebuggerEndpointRepository.kt:146 reportedEndpoints has no liveness bound: fixed as far as the finding asked. The repository drops apps that are no longer installed (isInstalled, wired in AppModule to PackageManager); the KDoc, DebuggerEndpoint Javadoc, changelog and README all say a dead process stays listed and updatedAtMillis is the last report, and that clients reconnect after a refusal. A row for a dead process is still returned by design, so the finding's residual risk is documented, not removed.
  • DebuggerEndpointServiceImpl.kt:56 interrupt rewrapped: fixed. InterruptedException restores the flag and is rethrown, CancellationException is rethrown, and both have tests.
    Both are fixed, so no thread needed a reply or an unresolve.

Merges and new commits. aa86aa1 (#2244 through #2260) and 2007193 (#2259's README corrections) are conflict-free merges. The README keeps this layer's paragraph on DebuggerEndpointService and no longer lists ADFA-7139 under "Not done yet". cbe541a moves the changelog entry to 26.47, consistent with the 26.46 tag.

Static review only: no build, no device. Leads from the built-in review that I discarded after reading the code: a dead process's token reaching another listener (the thread above, documented, and the token only goes to 127.0.0.1), the service passing an absolute rather than canonical path (the repository canonicalizes it, and the source's only implementation is that repository), Koin lookup and runBlocking without a timeout (a Room read; the plugin thread is not the main thread), permissions captured at registration (the pattern of every other service here; permissions are not revocable at runtime), the duplicated registration block (the pattern of the whole file), the global DebuggerEndpointSources (the same shape as the other *Impl.setX hooks), updatedAt ?: 0L (the DAO writes token, port and time together), the package-visibility assumption (a commented consequence of the hard TARGET_SDK=28 requirement in ARCHITECTURE.md), and the min_ide_version floor (documented in the changelog).

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