Skip to content

ADFA-7137: Store the SQLite debugger's port and token reported by the app - #2260

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

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

Conversation

@davidschachterADFA

@davidschachterADFA davidschachterADFA commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

ADFA-7137

The debug library tells Code on the Go its MCP server's port and token; Code on the Go stores them per app in its project database, for AI-Agent-MCP (ADFA-7139).

Stack: on sqlite-debugger/ADFA-7135 (the debugger module). ADFA-7139 stacks on this one.

What it does

  • debugger_endpoint_table in RecentProjectRoomDatabase (v5 -> v6): application ID, project_location foreign key to recent_project_table.location (ON DELETE and ON UPDATE CASCADE), token, port, updated at. Room enables foreign keys itself once the schema has one.
  • Pairing: a project-started install records (app, project) once the install succeeds; launching only adds a missing pairing and waits for it before starting the app.
  • DebuggerEndpointReceiver (exported): validates the token and port; a broadcast from an app Code on the Go did not install or launch stores nothing; failures are logged, never thrown.
  • The library broadcasts once its server listens, on every start, with an immutable PendingIntent whose creatorPackage identifies the app on every API level (it cannot be forged; decided over getSentFromPackage/an extra because AI-Agent-MCP switches on this entry's read-only tools).

Tests: migration 5 -> 6 on a v5 file opened through Room; delete and rename cascades; DAO and repository; the receiver through the framework under Robolectric (stored, unpaired, no PendingIntent, malformed extras); validation. Reviewed by Sonnet and twice by Opus.

Not verified on a device: the end-to-end path needs a Code on the Go build from the whole stack; Steps to QA are on the ticket.

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.

Review of #2260 (ADFA-7137), medium effort, static (no build, no device).

MINOR

  • DebuggerEndpointRepository.kt:40 - a failed or cancelled install leaves its pending entry behind
  • EndpointBroadcast.kt:38 - broadcast extras are string literals duplicated across modules and the sender has no test

NITPICK - none

Stack: layer 2 of 3 on this line. Below: #2259 (ADFA-7135, base sqlite-debugger/ADFA-7135). Above: #2261 (ADFA-7139, tip, 86b67f56de3f5dcc1673f48a7b07bfd8ccb31510). #2262 (ADFA-7138) also sits on #2259. Claims were verified against the tip; this review's anchors are on this PR's head 6842dfed015f29e9dfb15da01ec15157ac8dad19. Nothing was dropped as fixed higher up: #2261 adds reportedEndpoints and does not touch pendingInstalls.

Rules applied: CLAUDE.md and REVIEW.md at the PR head. They have no explicit approve/request-changes rule beyond "tie every blocking comment to a concrete risk", so the skill default applied: MINOR only gives COMMENT. This PR is self-authored, so GitHub would refuse APPROVE and REQUEST_CHANGES anyway.

Previous rounds: the only earlier review is the claude[bot] boilerplate (no findings), so there was nothing to re-check.

Checked and found sound: the PendingIntent creatorPackage sender identity (a broadcast with no PendingIntent, or from an unpaired app, stores nothing, and the tests cover both); token and port validation against McpHttp.newToken() (32 random bytes, URL-safe base64 without padding, 43 characters); migration 5 to 6 and the foreign key (recent_project_table.location has a unique index, so the parent key is valid; project rename and delete cascade); RecentProjectMaintenance is the only REPLACE insert and it is a separate table, so no cascade wipes pairings; exceptions are caught in the repository and the receiver; the stale-endpoint-after-reinstall window is documented on DebuggerEndpoint in the plugin API at the tip, with a re-query contract.

Not verified: behavior on a device (the PR says the same); whether the Quick Build proxy app carries the debugger library and so never pairs; the effect of the extra suspend before the post-install launch in BaseEditorActivity (no test covers beforePostInstallLaunch ordering).

scope.launch {
try {
val id = runCatching(applicationId).getOrNull()?.takeIf { it.isNotBlank() } ?: return@launch
pendingInstalls[id] = projectDir.canonicalProjectLocation()

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: A pending install that fails or is cancelled is never removed from pendingInstalls, so a later unrelated install of the same applicationId is paired with the wrong project.

expectInstallAsync records applicationId -> project before the install runs; only confirmInstall removes it, and onResult only reaches it on success. Run project A, dismiss the system install dialog, then install the same applicationId from an APK file (InstallFileAction) and confirmInstall pairs it with project A, which the KDoc on confirmInstall says does not happen. Not reachable on the normal Run path, because the next Run for any project overwrites the entry, and a wrong pairing only misdirects one app's endpoint, hence MINOR.

Clear the entry when the install ends without success (the failure branch of onInstallationResult), or expire entries after a short time.

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 2b759e6: every install that ends without a launch (failed, aborted, blocked) discards its note through a new onInstallEndedWithoutLaunch hook, and a note older than 5 minutes is ignored. Tests: a failed install does not pair, an expired note is not used, a recent one still pairs.

Intent(ACTION)
.setPackage(COGO_PACKAGE)
.addFlags(Intent.FLAG_INCLUDE_STOPPED_PACKAGES or Intent.FLAG_RECEIVER_FOREGROUND)
.putExtra("token", token)

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: The extra keys "token" and "port" are hand-copied literals that must match DebuggerEndpointValidation.EXTRA_TOKEN and EXTRA_PORT in :app, and nothing tests the sender.

The library and Code on the Go cannot share a constant, and :subprojects:sqlite-debugger has no test touching EndpointBroadcast (the app-side tests build the intent by hand). A rename or typo on either side makes every report fail validation as "missing or invalid" with no test failing, and QA only finds it end to end on a device. Not a runtime defect today, since both sides currently agree.

Add a unit test in the library that captures the broadcast (Robolectric shadowOf(app).broadcastIntents) and asserts the action, package, extras and creatorPackage, and name the app-side constants in a comment next to these literals.

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 2b759e6: the extra names are const vals in EndpointBroadcast; a Robolectric test captures the real broadcast (action, package, token, port, the PendingIntent's creatorPackage), and DebuggerEndpointContractTest in :app pins the same literals, each naming the other side.

davidschachterADFA and others added 6 commits November 15, 2026 23:21
The SQLite debugger in an app built by Code on the Go reports a token and
a port; Code on the Go needs to keep them per app and per project.

debugger_endpoint_table (RecentProjectRoomDatabase version 6) is keyed by
application_id and holds project_location, token, port and updated_at.
project_location is a foreign key to recent_project_table.location with
ON DELETE CASCADE, so removing a project removes its endpoints, and ON
UPDATE CASCADE, so renaming a project (which rewrites location) does not
fail once an endpoint row exists. Room enables PRAGMA foreign_keys itself
once the schema declares a foreign key, so no extra code is needed.

The pairing upsert is INSERT OR IGNORE plus UPDATE in one transaction:
minSdk 28 ships SQLite 3.22, which predates UPSERT (3.24).

Tests: migration 5 to 6 on a v5 file opened through Room (projects kept,
schema validated, cascade works on the migrated file); delete and rename
cascades.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
LaunchAppAction.kt was indented with spaces; the next commit edits it,
which pulls the whole file under the Spotless ratchet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
Code on the Go must know which project an app belongs to before it
accepts that app's debugger token and port, otherwise any app could
register an endpoint.

- A project-started install records (application ID, project) once the
  install succeeds. An existing pairing moves to the new project and its
  stale token and port are cleared. LaunchAppAction only adds a pairing
  when the app has none, and waits for it before launching. The Activity
  is not captured in the pairing lambda.
- DebuggerEndpointReceiver (exported, action
  com.itsaky.androidide.SQLITE_DEBUGGER_ENDPOINT) stores the endpoint off
  the main thread. The token must be 1-128 URL-safe base64 characters and
  the port 1-65535. A broadcast from an unpaired app stores nothing. A
  database failure is logged, never thrown.
- Sender identity: the app attaches an immutable PendingIntent, and the
  receiver trusts only its creatorPackage, which the framework sets and
  another app cannot forge, on every API level. A forged broadcast could
  otherwise point the AI Agent at another app's debugger server.

Tests: DAO and repository (pairing rules, failures reported as false,
move and clear on re-pairing); the receiver delivered through the
framework under Robolectric (stored, unpaired app ignored, no
PendingIntent ignored, malformed extras ignored); validation of token
and port.

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

The library broadcasts its token and port on every process start, after
the server listens, so a relaunched app (new port) updates its row.

- The broadcast carries an immutable PendingIntent, so Code on the Go can
  identify the sender from its creatorPackage on every API level.
- FLAG_INCLUDE_STOPPED_PACKAGES and FLAG_RECEIVER_FOREGROUND deliver it
  to Code on the Go when that is not running (cold start).
- The library manifest declares <queries> for Code on the Go so the
  package is visible on API 30+.

Code on the Go's receiver is declared in the app manifest, in the
previous commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vh2DAYT7GPoC2cDzo8LErn
The sqlite-debugger README describes the endpoint broadcast;
ARCHITECTURE.md and the Room ADR name Recent Projects database version 6.

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

A failed or cancelled install left its pendingInstalls entry behind, so a later
install of the same applicationId from an APK file was paired with the wrong
project. The editor now tells the repository when an install ends without a
launch, and entries older than five minutes are ignored as a backstop. Tests:
a discarded note is not used, an expired note is not used, a recent note still
pairs (the first two fail with the discard and the expiry removed).

The broadcast extra names are consts in the library, and EndpointBroadcastTest
(Robolectric) checks the sent action, package, extras and creatorPackage. The
library is not on :app's classpath, so DebuggerEndpointContractTest in :app pins
the same literals; each test names the other.

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 #2260 at 8410499 (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 2 of 4: below #2259 (sqlite-debugger/ADFA-7135, on #2244); above it #2261 (ADFA-7139). Sibling on #2259: #2262 (ADFA-7138). Tips: #2261 (2007193) and #2262 (810fe1c); #2261 only adds to this layer's code (a reportedEndpoints read and an isInstalled constructor parameter in DebuggerEndpointRepository, plus plugin-API files); the install-pairing and broadcast code the threads concern is unchanged at both tips, so grading there gives the same result.

Rules applied. REVIEW.md and CLAUDE.md at the head. REVIEW.md is "a coaching doc, not a gate" with no approve/request-changes rule, so the skill's default table applied.

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

  • DebuggerEndpointRepository.kt:40 pending install never cleared on failure: fixed. BaseEditorActivity.onInstallationResult calls onInstallEndedWithoutLaunch for any result that is not a launch and not STATUS_PENDING_USER_ACTION; ProjectHandlerActivity forwards it to discardPendingInstall; confirmInstall ignores a note older than 5 minutes. Tests: failed install does not pair, expired note unused, recent note pairs.
  • EndpointBroadcast.kt:38 hand-copied extra names with no sender test: fixed. The names are const vals with a comment naming the app-side constants; EndpointBroadcastTest captures the real broadcast, and DebuggerEndpointContractTest in :app pins the same literals.
    Both are fixed, so no thread needed a reply or an unresolve.

Merges. a49098e (#2244's sqlite-js 1.4.3 through #2259) and 8410499 (#2259's README corrections) are conflict-free merges; the README and ARCHITECTURE.md text from this layer survived (the "Not done yet" list no longer lists ADFA-7137).

Static review only: no build, no device. Leads from the built-in review that I discarded, each after reading the code: recordLaunched insert-if-absent (the documented design, and Run's confirmInstall re-pairs), the 5-minute expiry (a deliberate fix to the earlier thread), pairing write cancelled with the Activity (narrow, and the install-result handling is Activity-bound already), unguarded Koin lookup in LaunchAppAction (the Koin lookup is the pattern used elsewhere and canonicalProjectLocation cannot throw), the LaunchAppAction reformat (its own "no functional change" commit, reviewable by commit), the one-shot broadcast and hard-coded package, the exported receiver (it validates and only stores for a paired app; creatorPackage cannot be forged), ON DELETE CASCADE (documented in the README), and the expectInstallAsync ordering race (the APK is parsed in milliseconds, the install takes seconds and a user step).

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