Repository navigation
perf(runtime): reduce idle mailbox polling - #325
Merged
Merged
Conversation
Owner
Author
|
Addressed External Review #2 in |
boadij
pushed a commit
that referenced
this pull request
Oct 9, 2026
🤖 I have created a release *beep* *boop* --- ## [0.22.1](v0.22.0...v0.22.1) (2026-10-09) ### Performance * **runtime:** reduce idle mailbox polling ([#325](#325)) ([4c5c46d](4c5c46d)) * **snapshot:** eliminate redundant scans and traversals ([#328](#328)) ([9b9c218](9b9c218)), closes [#321](#321) * **supervision:** reduce redundant fleet observation ([#326](#326)) ([91c5422](91c5422)) ### Documentation * **readme:** Revise demo description and update demo link ([#322](#322)) ([d5bf7e6](d5bf7e6)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
boadij
added a commit
that referenced
this pull request
Oct 9, 2026
## Summary - Establish performance and efficiency as cross-cutting product goals for runtime, model-facing interactions, and development workflows. - Favor eliminating avoidable work and weighing optimization complexity against evidence, without weakening correctness, reliability, security, or recovery. - Keep the principle in its existing canonical owner, `docs/development/product-philosophy.md`, rather than creating a separate ADR or implementation-specific guidance. This generalizes the lessons from merged PRs #325, #326, and #328 without prescribing their particular mechanisms or introducing an additional documentation source of truth. ## Validation - Verified against the current `main` base (`123848b`): one commit, one file, **7 additions and 0 deletions**. - Confirmed the original document and heading structure remain intact; Markdown paragraph lines fit the existing 80-column wrapping. - No automated tests or smoke tests run (documentation-only change). GitHub CI not yet verified. No runtime behavior or public interface changes.
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.
Closes #319
Problem
Managed-Agent request pumps and owner-side result/ask watchers repeatedly polled durable mailbox files every 250 ms, including while idle. This PR replaces those long-lived polling loops with native directory notifications and a one-second reconciliation fallback.
Changes
observeMailbox()helper usingfs.watch()on the mailbox directory, coalesced reconciliation, periodic fallback, watcher reattachment after failure, and explicit disposal.watchFile()machinery and its retry maps.startingprojection without clearing a replacement assignment.Validation
npm run check— PASS: 886 passed, 1 skipped, 0 failed ((rerun before commit)).npm run build— PASS.npm run package:audit— PASS.git diff --check— PASS.npm run smoke -- core— PASS, cleanup passed.npm run smoke -- continuation— PASS, cleanup passed.mainbaseline of 250 ms schedules 40 checks over the same interval, or 240/minute; this is source-derived, not measured by running the baseline, and excludes the immediate startup pump. CPU usage was not measured. This is a callback-count comparison, not a CPU or filesystem-I/O benchmark.Remaining validation / risks
The initial GitHub CI run exposed a test-harness issue: the native-watcher test had a pending promise when the event loop became idle on Ubuntu, macOS, and Windows (no assertion failures were reported). A follow-up test-only commit holds a referenced timer while the test waits for notification or fallback reconciliation. The subsequent full CI run passed on Ubuntu, macOS, and Windows, as well as package, container, and scope jobs: run 37935048347. CPU usage and filesystem I/O were not measured. Live smoke was run in the local isolated harness against the current worktree's built extension.
The atomic-publication test verifies eventual reconciliation, which may be triggered either by a native filesystem notification or the one-second fallback; it does not guarantee native notification delivery. Mocked emitMailboxChange() tests separately exercise the notification path.
The mismatched-ID regression confirms an unrelated result is not delivered, but does not directly reach the pending-start cleanup guard: result observation is keyed to the active request ID, and deliverResult() independently rejects a result whose ID differs from the runtime's active/completed request ID. A valid public-flow result therefore cannot pair with a different pending-start ID; directly testing that internal impossible state would require a production-only hook or weakening identity checks. The matching fast-completion regression exercises cleanup during the initial result check.