Skip to content

perf(runtime): reduce idle mailbox polling - #325

Merged
boadij merged 4 commits into
mainfrom
perf/mailbox-observation
Oct 9, 2026
Merged

boadij merged 4 commits into
mainfrom
perf/mailbox-observation

Conversation

@boadij

@boadij boadij commented Oct 9, 2026 •

Copy link
Copy Markdown
Owner

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

  • Adds one shared observeMailbox() helper using fs.watch() on the mailbox directory, coalesced reconciliation, periodic fallback, watcher reattachment after failure, and explicit disposal.
  • Uses the observer for managed-Agent request detection and owner-side result and ask observation; removes the old watchFile() machinery and its retry maps.
  • Continues to use the existing durable mailbox readers and request/result/ask identity checks. Notifications are only hints; durable records remain authoritative. Existing acknowledgement, Pi semantic input, result/ask delivery, retry, cancellation, recovery, and cleanup paths remain in place.
  • Clears a pending-start status entry after result delivery only when its request ID matches, preventing a fast completion from leaving a stale starting projection 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.
  • Idle observer measurement: over 10,001.31 ms with no filesystem events, the candidate invoked reconciliation 10 times (59.99 callbacks/minute), with 0 error callbacks. The main baseline 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.

@boadij

boadij commented Oct 9, 2026

Copy link
Copy Markdown
Owner Author

Addressed External Review #2 in dafe61f:\n\n- Delegation now returns the immutable request ID returned by submit(), even if fast result delivery clears runtime.activeRequestId.\n- Ask observation is registered only while the request remains active after result-observer reconciliation.\n- Extended the fast-completion regression to assert the response request ID and that no mailbox watcher remains after delivery.\n\nValidation: focused regression, npm test -- extension/controller-lifecycle.test.ts (60/60), npm run validate (886 passed, 1 skipped; build and package audit passed), and post-format npm run check (886 passed, 1 skipped). git diff --check passed.

@boadij
boadij merged commit 4c5c46d into main Oct 9, 2026
7 checks passed
@boadij
boadij deleted the perf/mailbox-observation branch October 9, 2026 14:16
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.
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.

perf(runtime): reduce idle managed-Agent mailbox observation work

1 participant