Repository navigation
Harden desktop-driver server recovery and agent operations - #4479
Merged
Jason Morse (JasonVMo) merged 15 commits intoNov 10, 2026
Merged
Conversation
Page filling rebuilt each candidate's ancestors, recounted every omitted child and re-serialized the whole page, so a 5,000 node sample took seconds per delta page. Pages now grow by the candidate's missing ancestors, measure only the lines whose size changed, and sort once. The canonical projection a delta compares is cached per immutable snapshot. A delta no longer projects a page nobody reads: it issued references it never returned, and a removed element minted a reference that could evict one the agent holds. A removed element now carries the reference the session already holds, or none. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
A reference of 1-32 characters was accepted whatever it contained and then recorded in the journal summaries, and malformed references and unknown keys were echoed back in validation messages. Both are caller-typed text. - referenceSchema now requires the reference grammar, so only a well-formed reference reaches a summary. A malformed one keeps the ref-malformed reason. - A malformed reference is reported without quoting it. - An unknown key is reported as "Unrecognized key." at its path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Journal, reference, outcome and proof capacities were clamped to a floor and floored to an integer, so a ceiling was never checked and NaN made the trimming comparison false forever, leaving a table unbounded. They now share one validator that accepts only an integer inside the budget and throws otherwise, like every other budget. The outcome and proof capacities become budgets with a floor and a ceiling. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
A named accessibility action on a preview element skipped the Storybook context fence that click, clear and value enforce. One predicate now names the mutating element commands. Story verification searched only the session's current window, so a popup waited out the render deadline and quarantined the target; it now searches every window. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…nched quarantine Input release runs without a record when the journal cannot publish, and a release that never ran keeps the application open. The journal reads back after a storage failure, treats an absent record as removed, and bounds every storage and probe call. A launched application's quarantine is lifted only when the probe proves the exact incarnation exited. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
A sequence now checks every step's selector for content predicates and every clear against the session's strict-clear capability before the first step runs, so a refusal no longer lands halfway. The optional `clear` capability is false when the session's input mode demands a mechanism the target cannot perform. A check ends as unsupported as soon as the search reports an unsupported fact instead of retrying until the wait expires. A host event shortens a pause only after a minimum interval, at least as long as the last evaluation, so event bursts no longer trigger back-to-back walks of the application. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
`act` names the reference the selector proved instead of "undefined", and an `enabled` or `visible` fact the provider cannot read refuses with the distinct `state-unsupported` reason rather than reading as false. A dispatch failure no longer passes provider text (window titles, element ids) through: provider failures become fixed text per code, keeping only the machine reason, native code and the settled outcome. A reference or window the provider no longer has is dropped, as it is for a read. A physical click hit-tests first. A point covered inside the element's own window is rejected before the window is raised. Once the window was raised, a failed or still-covered hit test is reported as a partial effect, and hit-test timeouts and cancellations propagate instead of reading as `obscured`. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
`find` no longer reports `complete: true` when `limit` cut matches: complete now means nothing reachable was left out, and the cut is listed in `truncation` as a `limit`. `journal` reports `complete` and `truncation` for entries a page left out or the journal no longer holds. `stories` reports them, with the matching `next`, only when stories after the offset were left out, and marks the fields of an entry that were cut short. A delta now says which budget left its basis incomplete when the provider's own sample was complete, instead of suppressing removals without a reason. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…d routing Reject unknown or mistyped furn: capabilities and return furn:launchMode. Require a loopback Host with the connection's port, refuse browser Fetch Metadata, assert a loopback bind and keep a permanent listener error handler. Validate startup options strictly and read the journal of a target registered after startup before it is reported or opened. Validate timeouts as a whole with safe integers, accept a null script timeout and end implicit waits when the session is deleted. Answer malformed percent-encoding with invalid argument, unknown furn routes with unknown command and window/new with unsupported operation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Describe the request boundary, strict startup options, timeouts, recovery behavior and the content policy scope, and correct the stale statements about the shipped supervisors' recovery storage and WDIO named actions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add the failure reasons operations.md lacked (observation-cursor-expired, story-context-stale, input-policy, input-unsupported, input-mechanism-mismatch, bridge-unavailable, relaunch-required, state-unsupported), a furn:inputMode description, and the behavior of the fixed projection, preflight, check, redaction and complete/truncation semantics. Correct the README row that called /agent bounded, and add the changeset. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Satisfy the consistent-type-imports lint rule in the new act and sequence tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
Bundle size reportTree-shaken, minified production esbuild bundles with React and React Native runtimes externalized.
The job is advisory: size changes are reported but do not fail the pull request. Bundle or analysis errors still fail. |
Jason Morse (JasonVMo)
enabled auto-merge (squash)
November 10, 2026 12:42
Keep the operation capability contract and the server implementation in one PR so strict-clear preflight and result-completeness fixes ship together. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Jason Morse (JasonVMo)
disabled auto-merge
November 10, 2026 12:54
…ication probe Lifting a launched application's quarantine now requires the probe to report the exact application incarnation exited, because closing the application is no proof. The contract served the target without recovery, so the new session stayed quarantined after the close and the case failed on Windows CI. The case that closes the application now serves with the helper's incarnation probe and Windows private storage, and a second case keeps the fail-closed expectation: with no probe, closing the application never ends the quarantine. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…d stories The service now sets the required clear capability from the same strict-mode rule that guards the host call, so sequence preflight refuses a clear the session's input mode or target cannot perform before any earlier step acts, instead of staying permissive when the capability was omitted. stories always reports complete and truncation, as find and journal do. The architecture and contributing references no longer call src/agent bounded. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Vladimir Morozov (vmoroz)
approved these changes
Nov 10, 2026
Jason Morse (JasonVMo)
deleted the
user/jasonvmo/desktop-driver-server-hardening
branch
November 10, 2026 23:14
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Platforms Impacted
Description of changes
Related to #4435.
This PR carries two groups of fixes in
@fluentui-react-native/desktop-driver, merged because the agent operations need the server to report what a session can do, and a Windows CI follow-up:Each group was validated alone before the merge, and those results are kept below, separate from the validation of the combined head.
Server, protocol and recovery
Changes are in
src/server/*,src/protocol/*,src/host/types.ts, the matching tests, andreferences/{security,service,protocol,current-status,remaining-work}.md.POST /element/{id}/furn/accessibility-actiondid not enforce the Storybook preview-context check that click, clear and value enforce, so a stale preview element could be acted on. All four routes now share one "preview mutation" predicate.draining. The release now runs as an unrecorded recovery mutation and raises an in-memory quarantine when its outcome is unknown. The application is left open when the release never ran.furn:capabilities. A typo such asfurn:inputmodesilently becamecompatibility, and a non-stringfurn:targetfell back to implicit selection. Request-sidefurn:keys are allow-listed with their types (clickMode,endpoint,inputMode,launchMode,renderer,target), anything else isinvalid argument, andfurn:launchModeis returned.Originwas checked. A request is now refused whenHostis not127.0.0.1,[::1]orlocalhostwith the connection's own port (DNS rebinding), or when it carriesSec-Fetch-Site,Sec-Fetch-Dest,Sec-Fetch-Useror aSec-Fetch-Modeother thancors. Node'sfetchalways sendsSec-Fetch-Mode: cors, so blanket rejection ofSec-Fetch-*broke every client; a browser always sends the others. The listener closes and startup fails if the bound address is not loopback, and a permanenterrorhandler keeps a later accept error from ending the process.removethat returns false for an absent record, wedged the target. The journal now reads back and adopts an exact match, treats absent as removed, and bounds every storage and probe call with a 10 second deadline.1e300was accepted, andscript: nullwas rejected. All values are validated first, must be safe integers of at least zero,scriptmay benull, and an implicit-wait search stops when the session is deleted, so DELETE no longer waits out the deadline.invalid argument, an unknown/furn/*route isunknown command, andPOST /window/newisunsupported operation, instead of HTTP 500.content: 'Deny'behaved as allow andmaxBodyBytes: NaNmeant unlimited. Options are now validated strictly (unknown keys,content,port,maxBodyBytes,host,recovery). A target registered after the server started reads its journal on registration, and/statusfails instead of reporting a target whose records could not be read.furn/tree) ignoreoperations.content. It governsfurn/opsonly, and grants have no scope that separates the two, so this is documented inservice.mdand the option's JSDoc rather than changed.closeApplicationresolved, but the host contract does not promise the process exited. It is now cleared only when the probe reportsexited;host/types.tsdocuments the contract. Without a probe the quarantine stays until the operator callsrecoverTarget.security.mdsaid neither shipped supervisor suppliesrecoverystorage, andcurrent-status.mdsaid WDIO had no named-action invocation. Both are corrected.Behavior changes to know about (server group): a launched application's quarantine is no longer lifted on close when no
probeApplicationis configured, and unknown option keys, unknownfurn:capabilities and invalid timeouts that were previously ignored are now rejected.Agent operations
Observation paging was quadratic,
sequencecould refuse halfway,actandcheckmisreported and mis-retried, delta observation issued and evicted references, caller and provider text could reach the journal and errors, session capacities were clamped, andcompletemeant different things on different operations. This is the platform-neutral Node operation layer shared by both desktop endpoints; the native helpers are untouched.By file:
src/operations/projection.ts,observe.ts: pages fill incrementally and sort once, and canonical delta items are cached per snapshot. Output is byte-identical for the same input.src/operations/observe.ts: delta mode skips fresh projection and reads removed elements withrefs.peek. A delta element'srefis optional. The truncation of the canonical 5,000-node budget is carried into the delta.src/operations/act.ts: interactability names the entry's reference and reports an unsupportedenabledorvisibleasstate-unsupported. Provider failures are mapped to fixed text per error code. A click hit-tests, activates, then hit-tests again.src/operations/check.ts,limits.ts:unsupportedis terminal, and evaluations are at leastcheckPollMs.minimum(100 ms) apart or as long as the last evaluation took.src/operations/sequence.ts,selector.ts,runtime.ts: preflight covers selector content predicates in act and check steps, and a strict-modeclear.src/operations/envelope.ts,refs.ts: arefmust match the reference grammar, so only well-formed references reach the journal. A malformedrefisref-malformedwithout its text. An unknown key isUnrecognized key.without its name.src/operations/limits.ts,refs.ts,journal.ts,proofs.ts,outcomes.ts:requireCapacityrejects a capacity that is not an integer in range. Proof and outcome capacities gain ceilings.src/operations/find.ts,story.ts,journalOperation.ts,shapes.ts:completemeans nothing reachable was left out.findwith cut matches,journal, andstoriesreport it and atruncationreason (limitordropped). Clipped story fields are listed inclipped.src/testing/operationRuntime.ts,src/operations/*.test.ts: the stub runtime accepts host overrides; newact,sequenceandchecksuites and cases inobserve,projection,find,journal,story,envelope,executor,refsandsessionState.references/operations.mdand the README/agentrow: add the missing reasons and afurn:inputModedescription, and document each fix.Fixes:
sequencepreflight ignored selector content predicates and strict-modeclear, so a refusal landed after earlier steps had acted. It now checks every step first. See the integration section for the server side.actby selector saidReference "undefined" is not enabled., and an unsupportedenabledorvisiblecounted as false. It now names the reference and reportsstate-unsupported.checkretriedunsupported-factuntil the wait expired, and event bursts ran back-to-back tree walks. It now ends asunsupportedafter one attempt, and walks are spaced.observeDeltareturned 41 references for 3 elements with zero changes, and minted references for removed elements, which could evict references the agent holds. It now issues none for unchanged or removed elements.refwas journaled, and malformed refs and unknown keys were echoed in validation messages. Both are now fixed text.interpretFailure, so provider text such as window titles and element ids passed through. They are now fixed words per code, keeping onlyreason,nativeCodeand the rebuilt mutation report.clickreportedrejectedwith no effect after it had already raised the window, and a hit-test timeout becameobscured. A cover in the element's own window is refused before activation. After activation, a failed or covered hit test ispartialandindeterminate. Timeouts and cancellation propagate.observation-cursor-expired,story-context-stale,input-policy,input-unsupported,input-mechanism-mismatch,bridge-unavailable,relaunch-required,state-unsupported) and thefurn:inputModedescription are documented. The stalecatalog.tscomment inshapes.tsnow saysregistry.ts.NaNdisabled trimming and eviction. They are now validated as integers in range and rejected otherwise./agentandagent describebounded.DesktopAgent.describereads the whole tree before trimming, so the README now says so.storiesandjournalhad nocompleteortruncation, andfindreportedcomplete: trueafterlimitcut matches. All three now report them, with one meaning (see the integration section forstories).Integration of the two groups, and a Windows contract fix
These changes exist only because the groups are combined.
clearis always reported by the server (finishes OPS-3). The operation group addedOperationCapabilities.clearas optional, and the real server never set it, sosequencepreflight could not see a strictclearthe target cannot perform, and an omitted capability read as permissive.clearis now required.src/server/sessionOperations.tsderives it fromstrictClearMechanism, the same rule that guards the host call, so it istruefor a compatibility session and, for a strict session, only when the mode allows the clear mechanism and the target advertisesstrictClearand that mechanism. A refusal there isfalse. A newsessionInput.test.tscase drives a realsequencethrough the server: anaccessibleorphysicalsession on a target withoutstrictClear(or with it omitted) refuses a laterclearstep before the earlieractivateortypestep touches the host, with no host actions and no receipts. The same sequence runs when the target can clear, and a compatibility session is still left to the host. A strictactclearon such a target is nowaction-unsupportedbefore dispatch.storiesalways reportscompleteandtruncation(finishes OPS-17). They aretrueand[]when nothing afteroffsetwas left out, andfalsewith alimitentry otherwise, asfindandjournaldo. The server expectation instoryOperations.test.tsandoperations.mdare updated.references/architecture.mdandreferences/contributing.mdno longer callsrc/agent"Bounded", matching the README.protectedService.contract.test.ts:233. CI for the server-only head26f68768efailed in Windows Storybook job 129833452854 (run 42817279330):quarantines the target for every grant when the provider cannot settle, until the application is closedfound the new session still quarantined after the close. This is SRV-11 working as designed, not a recovery regression. A launched application's quarantine is now lifted only whenprobeApplicationreports the exact incarnationexited, and the contract served the target with norecovery, so nothing could prove the exit. The contract now serves that case withcreateWindowsApplicationProbeover the helper's--application-incarnationmode and Windows private storage on a scratch root, as a Windows supervisor does. A second case keeps the fail-closed expectation: with no probe, closing the application never ends the quarantine. Recovery is not weakened.Not in this PR
clifixes. OPS-13, OPS-14: refactors, deferred.Verification
Validation is reported in three separate parts: the server group alone, the operations group alone, and the combined head. Only the combined head is the code this PR contains.
Server group, standalone (on its own branch, before the merge)
Run in
packages/agentic/desktop-driverunless noted, on macOS. No GUI or native runs were needed.yarn formatyarn lintyarn buildyarn testyarn testinpackages/agentic/desktop-testyarn testinpackages/agentic/storybook-desktopyarn oxfmt --checkon the changeset, the edited references,src/serverandsrc/protocol(root)yarn markdown-link-check -c .github/markdown-link-check-config.json packages/agentic/desktop-driver/references/<file>.mdfor the five edited references (root)yarn clean-lage-cache && yarn lage buildci --concurrency 6(root)New tests:
serverBoundary.test.ts(Host and Fetch Metadata rejection, malformed paths, loopback bind assertion, listener error survival, strict startup options), and cases indesktopDriver.test.ts(invalid capabilities,furn:launchMode, atomic and safe-integer timeouts,script: null, DELETE ending an implicit wait, unknown/furn/*,/window/new),storyOperations.test.ts(named-action fence, popup story root, unknownfurn/story/*with an orchestrator),recovery.test.ts(adopt, absent-as-removed, storage deadline, unrecorded release, launched-quarantine proof, late registration) andtimeouts.test.ts(withDeadline). 35 of the new cases inserverBoundary,desktopDriverandrecoveryfail against the previouscreateDesktopDriverServer.ts.Not run: native helper suites (
FURN_NATIVE_DRIVER_TEST) and any Windows or GUI qualification; this change does not touch native code.Operations group, standalone (on its own branch, before the merge)
Run in the operations worktree on macOS, with no GUI or native runs.
yarn test <name>runs while iteratingyarn formatyarn lintconsistent-type-importsin two new tests), fixed, then passedyarn buildyarn testyarn test(consumes agent operations)yarn oxfmt --checkyarn markdown-link-check -c .github/markdown-link-check-config.jsononoperations.mdandREADME.mdyarn clean-lage-cachethenyarn lage buildci --concurrency 6buildciran five times in that worktree because the machine was loaded by parallel agent builds (load average above 80). The three clean-cache runs that failed did so in packages this group does not touch, and each failing test passed when rerun alone:desktop-testcontracts.test.ts;storybook-desktopwdioRunner.test.ts(7 s process deadline); anddesktop-testsupervisor.test.tsandcontracts.test.tson the machine-widefurn-desktop-workloadinteractive.lock. The two reruns that kept the cache passed with exit 0.Combined head (this PR), run in
furn-fix-srvon macOSyarn test sessionInput story sequence actinpackages/agentic/desktop-driver(focused)clear: trueyarn format,yarn lintyarn buildclearto two capability fixtures inregistry.test.tsand asatisfiestype in a new testyarn testyarn testinpackages/agentic/storybook-desktopyarn testinpackages/agentic/desktop-testyarn testinpackages/agentic/desktop-driver-mcpyarn oxfmt --checkonpackages/agentic/desktop-driverand.changesetyarn markdown-link-check -c .github/markdown-link-check-config.jsononoperations.md,architecture.md,contributing.mdyarn clean-lage-cache, thennative-lock.sh srv-ops-buildci yarn lage buildci --concurrency 4(root, one fresh-cache run)Windows: the native contract suites run only on Windows with
FURN_NATIVE_DRIVER_TEST=1, soprotectedService.contract.test.tswas not run on this macOS host. The change to it was checked withtsc -b, lint and format only. The server-only head26f68768efailed that suite in Windows Storybook job 129833452854 (run 42817279330), as described above, and the fix was not run on Windows locally. On the combined head684ff5bf4the Windows Storybook job and the other native and platform CI jobs passed, which is the evidence that the fix works on Windows. If it regresses, the quarantine will have stayed because the probe did not report the closed applicationexited, and the next step is to look at that verdict, not to weaken recovery.Linux CI,
desktop-testcontracts.test.ts › recovery contract. The JS PR job at684ff5bf4(job 129845427368, run 42820692741) failed once in that contract withAggregateError: Desktop supervisor cleanup failed.fromawait seed.close()atcontracts.contract.cjs:1585; the other 14 suites passed. The nested cleanup errors were not captured: the contract'smain().catchwrites onlyerror.stack, which omitserror.errors. The cause is therefore not identified, and the failure did not reproduce here. What is established:26f68768e(JS PR job passed) and684ff5bf4aresrc/operations/*,server/sessionOperations.ts,testing/operationRuntime.ts, docs and the Windows contract test.desktop-testhas no change in this branch.GITHUB_ACTIONSandCIset, and in all 18 whole-file or whole-package jest runs under load. Under the same load otherdesktop-testtests failed on timing, such aslane-cli,reporter-cliand the 5 s service-readiness deadline inowned process lifelines, so that package does flake when the machine is saturated. That is consistent with a load-dependent failure, but it does not show that this one was.The single failed-job retry (
gh run rerun 42820692741 --repo microsoft/fluentui-react-native --failed) passed on unchanged head684ff5bf4. All PR checks, including JS, Windows Storybook, macOS Paper/Fabric Storybook, and Win32 accessible/physical Storybook, are now successful. This does not identify the original cleanup failure's cause. NestedAggregateErrordiagnostics are being added in the separate desktop-test lifecycle/reporting PR #4478; any recurrence should be investigated from those causes rather than by relaxing deadlines or exit proof.No macOS native, GUI or Storybook run was needed for this change.
Host, a typo in afurn:capability ormaxBodyBytes: NaNwas accepted; DELETE could leave keys held.accessibleorphysicalsession whose target cannot clear with one mechanism, asequenceofactivatethenclearran theactivate, then theclearfailed (the server never reportedclear).sequenceis refusedaction-unsupportedbefore theactivate; the host sees no action and no receipt is recorded.storiesomittedcompleteandtruncationunless stories were cut.complete: trueandtruncation: []when the page reaches the end;complete: falseand alimitentry otherwise.view=all: 7,733 ms;observethen an empty delta issued 3, then 41 references.sequencewith denied content in step 2 clicked step 1, then stopped. Arefofa man, a plan, a canalwas journaled as typed, and an unknown key was quoted in the error.content-deniedbefore any click. Therefisref-malformedand nothing is journaled, and the key isUnrecognized key.session.delete(), because nothing proved the application exited.684ff5bf4; not run locally.Pull request checklist
This PR has considered (when applicable):