Skip to content

refactor(reasons): declare the R6b reasons in ReasonTable rows - #4930

Open
thymikee wants to merge 12 commits into
mainfrom
t3/r6b-typed-reasons
Open

thymikee wants to merge 12 commits into
mainfrom
t3/r6b-typed-reasons

Conversation

@thymikee

@thymikee thymikee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

Declares the 59 published error.details.reason values of the R6b packages in ReasonTable rows beside the code that classifies them, so every wire spelling is declared once, documented by its row comment, and read as TABLE.member.reason.

Three sites published prose or an internal code as their reason. They now publish a typed value, and the old text moved to another details key. These are published-value changes:

  • PNG / JPEG screenshot decode: png_decode_failed / jpeg_decode_failed, decoder message in details.decoderError.
  • find on a sparse capture, on both the read-only and the daemon (click, fill, focus, type) routes: find_snapshot_unreadable, with the verdict prose in details.verdictReason and its code in details.verdictReasonCode. Both routes build this from one capture-kit helper, sparseFindRefusal.
  • Snapshot-router cancelled rethrow: request_canceled always, the value its details already carried; the internal abort-signal code never reached callers.

Value

59 values / 66 sites became table rows. Tables went 18 -> 43 and the generated page 76 -> 138 documented rows.

Before / after

Before: literals and one-off consts, three prose reasons, one undeclared router value.
After: one row per value, each read at its raise sites; the router reuses the kernel's exported REQUEST_CANCELED_REASON.

Validation

pnpm build, check:quick, check:layering (R89: 313 sites in 165 files against 352 in 185 at merge-base), generate:reasons committed, reason-table and repo guards, and the affected suites.

🤖 Generated with Claude Code


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

View guided diff Turn on auto-fix

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging 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.

Apex Sentinel: 1 new finding on 5fb2666. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

The PR is ready at 5fb2666. Not blocking, and fine to take or leave: the old alias constants SETTINGS_APP_NOT_CONSUMED_REASON, REPLAY_TARGET_GUARD_MISMATCH_REASON and MAESTRO_TEST_FAILURE_REASON still exist beside the tables, so importers could read TABLE.member.reason and the aliases could go; daemon_retirement_unconfirmed is still a literal in https://github.com/callstack/agent-device/blob/5fb2666/packages/daemon-contracts/src/daemon-stop.ts#L155 and could be declared once here or in the R1 batch; the jpeg_decode_failed row comment in https://github.com/callstack/agent-device/blob/5fb2666/packages/capture-kit/src/png.ts#L15 could also mention the pixel budget refusal; and the contact sheet rows carry both a JSDoc and a near-identical // comment, so one would do.

The checks are green: 8 checks, none failing at 5fb2666. The PR has merge conflicts with main. Before merge, it needs a rebase onto main (d6767e0, which includes the platform-apple reason tables from #4924) and a regenerated website/docs/docs/error-reasons.md.

The open inline thread on the find route reason (#4930 (comment)) still applies as a non-blocking follow-up for the R1 daemon batch. Not verified here: the exact 59 values / 66 sites count, local test runs and generate:reasons (CI was relied on), and out-of-repo consumers of the old decoder or verdict strings.

@thymikee

Copy link
Copy Markdown
Member Author

At 7d880033b8: FIND_READ_REASONS (find_snapshot_unreadable) moved from command-runtime to capture-kit/src/snapshot-quality-verdict.ts, byte-identical to the declaration in #4936 (the R1 daemon batch, which raises the same value from the daemon find path and cannot import command-runtime). Either PR can merge first; the other rebases cleanly and the guard sees one declaration.

thymikee and others added 2 commits November 21, 2026 22:31
Migrates the 59 published error.details.reason values of the R6b packages
into ReasonTable rows beside the code that raises them, so every wire
spelling is declared once and read as TABLE.member.reason.

Three sites published prose or an internal code as their reason and now
publish a typed value instead: the PNG and JPEG screenshot decoders
(png_decode_failed / jpeg_decode_failed, decoder message moved to
details.decoderError), the sparse-capture find refusal
(find_snapshot_unreadable, verdict prose moved to details.verdictReason),
and the snapshot router's cancelled rethrow (always request_canceled, the
kernel-owned value it already carried in details).

Regenerated website/docs/docs/error-reasons.md.
…here both find paths load it

The daemon find path (#4936) cannot import command-runtime, so the row lives in
capture-kit/snapshot-quality-verdict.ts, byte-identical to #4936's declaration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee
thymikee force-pushed the t3/r6b-typed-reasons branch from 7d88003 to 50d8c3c Compare November 21, 2026 21:32
@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.51 MB 6.51 MB +4.0 kB
Package (unpacked) 6.51 MB 6.51 MB +4.0 kB
Package (download) 1.98 MB 1.98 MB +1.2 kB

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 19.6 ms 18.6 ms -1.0 ms
CLI --help 41.1 ms 41.5 ms +0.4 ms

thymikee and others added 2 commits November 21, 2026 22:37
Nothing imports them; the reasons collector also reads tables that are not exported.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Its only reader was a test, which now asserts the published spelling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The earlier clean review at 5fb2666 (#4930 (comment)) no longer fully holds: f79abea has one docs problem left. The code itself looks right, and all 21 checks pass at f79abea. No conflicts.

The new frameExtractionFailed row on the error reasons page says frame extraction ran. That is not always true. If the decoder executable is missing at launch, spawn throws ENOENT. contact-sheet-frames.ts:105 forwards that error to throwExtractionFailure, which emits contact_sheet_frame_extraction_failed before the decoder has started. The test at contact-sheet-frames.test.ts:259 already covers this case. An agent that reads the reference can conclude the decoder ran and look at the recording, when the real fault is the decoder launch. The rule: each row summary must hold for every path that emits that reason. Please change the frameExtractionFailed summary in contact-sheet-report.ts:16-17 to say the contact sheet could not obtain usable extracted frames, then regenerate error-reasons.md. Not verified here: the output of pnpm generate:reasons at this head, and no CI check compares error-reasons.md with the generator output, so drift would not be caught automatically.

Could the managed agent-browser response refusal table and the batch reason type be private to agent-browser-provider.ts, beside sendTextEntry, fetchRefRects and parseBatchEntries? Those are the only production readers, and they classify the response contents. agent-browser-tool.ts owns process execution and returns an ExecResult.

The open inline thread on the daemon find sparse refusal (#4930 (comment)) does not apply: the thread author no longer raises it at f79abea, and that refusal is untouched by this PR and is covered by #4936.

Once the summary is fixed and the page regenerated, nothing else stops this PR.

…frames

Also drops the JSDoc lines that repeated each row's summary comment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

At 95fd770457: frameExtractionFailed now says the contact sheet could not obtain usable extracted frames (the extractor failed to start or run, which covers the spawn ENOENT), the page is regenerated, and the JSDoc lines that repeated each row's // summary in that table are gone. On the simplicity question: AGENT_BROWSER_REFUSAL_REASONS and AgentBrowserBatchRefusal are used only by agent-browser-provider.ts, but moving them there takes that file to 1,027 lines, over the 1,000-line lint cap, so they stay in agent-browser-tool.ts, which the provider already imports. Splitting the provider to make room would be a bigger change than the gain.

@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready at 95fd770, and the findings from the earlier review (#4930 (comment)) are now fixed. CI is green with 21 checks and none failing. No conflicts. Nothing else blocks the merge.

Not blocking: the summary in https://github.com/callstack/agent-device/blob/95fd770/packages/capture-kit/src/recording/contact-sheet-report.ts#L16 ends with "the extractor failed to start or run", but contact-sheet.ts also emits this reason when the extractor returns an over-wide or over-budget frame, so you could say "failed to start, run, or return frames the sheet can use". Take it or leave it.

Not verified here: pnpm generate:reasons was not run, so consistency was judged by reading the generator and the diff. The collector was not read to confirm // versus JSDoc precedence beyond the row text matching the // comment.

The open inline thread #4930 (comment) (find path prose) is still accurate, but the fix is scoped to #4936 and the base already published that prose, so it does not block this PR.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
thymikee and others added 2 commits November 22, 2026 08:13
* origin/main:
  docs(commands): generate blocks for every public command and halve hand-written prose (#4919)
  fix(depgraph): budget the blast-radius query, not the whole-tree scan (#4920)
  refactor: remove dead exports and stale fallow exemptions (#4931)
  refactor(reasons): declare the R6a reasons in ReasonTable rows (#4938)

# Conflicts:
#	packages/platform-harmonyos/src/app-lifecycle.ts
#	website/docs/docs/error-reasons.md
…on summary

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

At 76c74b4 (after merging main at 4a436c9; the HarmonyOS import conflict kept the table import and dropped the runCmd import main removed): frameExtractionFailed now says the extractor failed to start, run, or return frames the sheet can use, which covers the over-budget frame path in contact-sheet.ts. The two JSDoc lines that repeated their row summaries in that table are gone. The page is regenerated. The find-path thread is answered: #4936 migrates the daemon route.

@apex-sentinel-staging

This comment has been minimized.

@thymikee thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee

Copy link
Copy Markdown
Member Author

The code at 76c74b4 looks correct, and the generated R6b rows match the declarations in a manual diff. All 21 checks pass, and no review threads are open. The earlier review at 95fd770 found nothing to fix, and that still holds. Not verified here: generate:reasons and the tests were not rerun locally, so this rests on CI and the diff read. No conflicts were reported. Could agent-browser-provider.ts own the reply-refusal table and keep AgentBrowserBatchRefusal private, next to the text-entry and geometry checks that use them?

@thymikee

Copy link
Copy Markdown
Member Author

On the simplicity question: I tried it and reverted it. agent-browser-provider.ts is 999 lines at 76c74b4. Moving the table and the batch-refusal union in adds about 23 lines and removes 4 import lines, which puts the file near 1,018, past the repo's 1,000-line max-lines lint limit. Keeping the table in agent-browser-tool.ts avoids splitting the provider in a reasons PR. Evidence: CI passed 21/21 at 76c74b4, including the generated-docs check, and pnpm generate:reasons on this head left no diff after the regenerated page was committed.

@thymikee

Copy link
Copy Markdown
Member Author

The answer settles the simplicity question at 76c74b4: moving the table would push agent-browser-provider.ts past the 1,000-line limit, and the generated-reasons evidence covers the rest. The head now conflicts with main, so please rebase and push; the rebased head gets a delta review.

* origin/main:
  refactor(reasons): declare the R5 provider reasons in ReasonTable rows (#4932)
  refactor(reasons): declare the platform-android reasons in ReasonTable rows (#4928)

# Conflicts:
#	packages/contracts/src/lease-scope.ts
#	website/docs/docs/error-reasons.md
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

Reviewed 7d577f1. The earlier conflict from 76c74b4 is resolved, and CI is green (21 checks, 0 not passing). One defect remains, and the declared wire change does not yet hold for mutating find.

A mutating find such as find Search click still returns the backend prose as the reason when the capture stays sparse after query-scoped recovery: find-target-capture.ts:76 forwards verdict.reason (for example sparse tree). The read-only route publishes find_snapshot_unreadable and carries the prose under verdictReason. A CLI or SDK caller that branches on find_snapshot_unreadable cannot detect the same failure for mutating find. The reason also varies with backend prose and can be absent when the verdict has no reason text. The rule: every find route that refuses a sparse capture must return the capture-kit sparse find reason row, with the verdict prose and code under verdictReason and verdictReasonCode. The call sites of sparseFindSnapshotResponse enumerate the routes. The daemon click scenario at find.test.ts:191-257 still expects sparse tree and must change with it.

The PR text says the declared sparse find reason applies to both read-only and mutating find. At 7d577f1 only the read-only formatter in selector-read-utils.ts:43-47 uses the new row. Please make the code match that claim as described above. The updated runtime wait test at selector-read.test.ts:236-299 covers the read-only route and passes through the real selectors.find path. It does not cover the mutating route.

Could capture-kit own the sparse find refusal details beside its existing reason row, with the read-only and mutating routes each keeping their current error wrapper? Both routes already depend on snapshot-quality-verdict and currently assemble the same refusal independently.

The other changes look right. A range-diff shows the six logical patches carried forward unchanged from 76c74b4, and the agent-browser batch refusal type and its seven rows are used only by that provider. Not verified here: the reasons generator and the test suite were not run locally, and the generated page was checked by text comparison against the row sources. After the mutating route is fixed, no further change is needed before merge.

…for both find routes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

At fbb7342:

  • The daemon route (find-target-capture.ts) now publishes find_snapshot_unreadable, with the verdict prose under details.verdictReason and the code under details.verdictReasonCode, the same as the read-only route.
  • The click sparse test asserts all three fields.
  • Simplicity question: adopted. capture-kit now owns sparseFindRefusal(verdict) beside the reason row, which returns the message and details. The daemon (errorResponse) and command-runtime (AppError) routes keep their own wrappers. FIND_READ_REASONS is module-private now.
  • Local runs: pnpm typecheck passes; find, selector-read and the reason-table guard pass 39/39; generate:reasons shows no diff. The PR body covers the daemon route now.

When #4936 next merges main, it will take this version of the daemon route and keep its four-action sparse test.each.

…failure details

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

At 79bd18b: cherry-picked the replay fix from #4936 (ca3f928). pickSafeCauseDetails now forwards the scrubbed verdictReason and verdictReasonCode from a sparse find refusal into REPLAY_DIVERGENCE, and a new test covers it. This PR moves the daemon route to find_snapshot_unreadable, so without the fix replay would lose the verdict text that base exposed in reason. Replay-port tests pass 8/8, and pnpm typecheck is clean.

… complexity limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The findings from the earlier review at 7d577f1 (#4930 (comment)) are fixed at 5e458f1, and no new problems were found in the change. CI is green: 21 checks, none failing, and they cover the find routes and replay detail projection this update touches. There are no conflicts. Not verified here: tests, the reasons generator and pnpm check were not run locally, so readiness rests on the green CI run. One question on design: could packages/selectors/src/interaction-error.ts own the sparse-find reason and its formatter next to the other shared find refusals, so the snapshot quality module only interprets capture evidence? Nothing else needs to change before merge.

@thymikee

Copy link
Copy Markdown
Member Author

On the simplicity question: not in this PR.

@thymikee

Copy link
Copy Markdown
Member Author

The design answer covers the open question at 5e458f1. capture-kit owns the sparse verdict that triggers the refusal, the move would add no reach and remove nothing, and moving the builder again would cost another round on this PR and #4936. The selectors question is tracked in #4937. Nothing else blocks this head.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee

Copy link
Copy Markdown
Member Author

5e458f1 now conflicts with main after the latest merges. Please rebase onto main and regenerate any generated reason blocks. The code verdict on 5e458f1 is unchanged, and the next review covers only the rebase.

@thymikee thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
* origin/main:
  feat(contracts): allow third-party snapshot producers (#4905)
  refactor(reasons): declare the R3 apple-runner reasons in ReasonTable rows (#4922)
  refactor(reasons): declare the R4 reasons in ReasonTable rows (#4934)
  refactor(snapshot): one shared model for occluding system surfaces (#4956)

# Conflicts:
#	website/docs/docs/error-reasons.md
@thymikee

Copy link
Copy Markdown
Member Author

At ba67ebb: merged main (#4922 and #4934). The only conflict was the generated error-reasons.md, regenerated on top of main. I merged rather than rebased because the branch already has merges from main. No code changes. Local runs: pnpm typecheck passes, and the reason-table guard plus the replay-port tests pass 13/13.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of ba67ebb

Since the review of 5e458f1: 0 new · 0 still open · 0 no longer raised

No open findings.

1 finding below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (a4a35ba7c552).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

This branch has not been deployed

No deployments
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