Repository navigation
feat: add bounded Hermes Gmail mailbox broker - #8
Conversation
|
Warning Review limit reached
Next review available in: 50 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds a Gmail mailbox broker with Unix-socket access, mailbox CLI commands, canonical message references, approval-gated trash proposals, Gmail MOVE execution, pending-draft replay, and production installation/systemd configuration. ChangesMailbox broker and approval workflow
Estimated code review effort: 5 (Critical) | ~120 minutes Sequence Diagram(s)sequenceDiagram
participant Agent as Hermes Agent
participant CLI as agent-gate-mailbox
participant Broker as MailboxBrokerServer
participant Gmail as GmailMailboxTrashService
participant Telegram as Telegram Approval Flow
Agent->>CLI: Submit propose-trash request
CLI->>Broker: Send validated references and context
Broker->>Telegram: Persist pending mailbox-trash draft
Telegram->>Gmail: Prepare snapshot for approval
Gmail-->>Telegram: Return message preview snapshot
Telegram-->>Agent: Present approval preview
Agent->>Telegram: Approve proposal
Telegram->>Gmail: Execute approved MOVE
Gmail-->>Telegram: Return moved or move-partial result
Telegram-->>Agent: Send execution notification
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
src/mailbox-client.ts (2)
7-8: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDuplicated socket path and response size constants risk silent breakage.
SOCKET_PATHandMAX_RESPONSE_BYTESare hardcoded here but also defined insrc/mailbox-broker/protocol.tsasMAILBOX_SOCKET_PATHandMAX_RESPONSE_BYTES. If the path changes in one location but not the other, the CLI will silently fail to connect.Consider importing these from
./mailbox-broker/protocol.jsto maintain a single source of truth.♻️ Suggested fix
-import { createConnection } from 'node:net'; +import { createConnection } from 'node:net'; +import { MAILBOX_SOCKET_PATH, MAX_RESPONSE_BYTES } from './mailbox-broker/protocol.js';Then replace usages:
-const SOCKET_PATH = '/run/agent-gate-mailbox/broker.sock'; -const MAX_RESPONSE_BYTES = 1024 * 1024;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/mailbox-client.ts` around lines 7 - 8, Remove the local SOCKET_PATH and MAX_RESPONSE_BYTES declarations in mailbox-client.ts, import MAILBOX_SOCKET_PATH and MAX_RESPONSE_BYTES from mailbox-broker/protocol.js, and update all SOCKET_PATH references to MAILBOX_SOCKET_PATH.
34-52: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winReference validation logic duplicates
decodeInboxReference— divergence risk.
refIdentityreimplements the canonical reference validation fromsrc/mailbox-broker/reference.ts. While currently equivalent, any future change to the reference format (e.g., new fields, different encoding) would need to be updated in both places. The CLI could accept refs the broker rejects or vice versa, producing confusing user errors.Consider importing and reusing
decodeInboxReferencefrom./mailbox-broker/reference.js, wrapping it to returnnullon error instead of throwing.♻️ Suggested fix
+import { decodeInboxReference } from './mailbox-broker/reference.js'; + const refIdentity = (value: string): { uidValidity: string; uid: number } | null => { - if (!/^[A-Za-z0-9_-]{8,256}$/.test(value)) return null; try { - const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8')) as Record<string, unknown>; - const keys = Object.keys(parsed).sort().join(','); - if (keys !== 'folder,uid,uidValidity,v' || parsed.v !== 1 || parsed.folder !== 'inbox' || - typeof parsed.uidValidity !== 'string' || !/^[1-9][0-9]*$/.test(parsed.uidValidity) || - typeof parsed.uid !== 'number' || !Number.isSafeInteger(parsed.uid) || parsed.uid < 1) return null; - const canonical = Buffer.from(JSON.stringify({ - v: 1, - folder: 'inbox', - uidValidity: parsed.uidValidity, - uid: parsed.uid - }), 'utf8').toString('base64url'); - return canonical === value ? { uidValidity: parsed.uidValidity, uid: parsed.uid } : null; + const ref = decodeInboxReference(value); + return { uidValidity: ref.uidValidity, uid: ref.uid }; } catch { return null; } };🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/mailbox-client.ts` around lines 34 - 52, Replace the duplicated validation in refIdentity with decodeInboxReference imported from ./mailbox-broker/reference.js. Call the decoder with the provided value and return its uidValidity/uid identity, catching decoder errors and returning null so the existing caller behavior is preserved.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/mailbox-broker/gmail-inbox.ts`:
- Around line 202-229: Update the markRead method’s Promise return type to
include outcome as 'applied' | 'partial', matching the object returned by the
method; retain the existing outcome field and requested/verified properties.
In `@src/watcher.ts`:
- Around line 61-72: Update the startup error handling around DraftWatcher’s
ready/error promise so chokidar errors cannot synchronously throw through an
unhandled error event. Guard any this.emit('error', error) forwarding with an
appropriate listener check, or defer forwarding until after the watcher is
ready, while ensuring onStartupError still rejects start() and removes the
opposite listener.
---
Nitpick comments:
In `@src/mailbox-client.ts`:
- Around line 7-8: Remove the local SOCKET_PATH and MAX_RESPONSE_BYTES
declarations in mailbox-client.ts, import MAILBOX_SOCKET_PATH and
MAX_RESPONSE_BYTES from mailbox-broker/protocol.js, and update all SOCKET_PATH
references to MAILBOX_SOCKET_PATH.
- Around line 34-52: Replace the duplicated validation in refIdentity with
decodeInboxReference imported from ./mailbox-broker/reference.js. Call the
decoder with the provided value and return its uidValidity/uid identity,
catching decoder errors and returning null so the existing caller behavior is
preserved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c4bb8de0-30b8-422f-a68c-bbd5b364b43b
⛔ Files ignored due to path filters (1)
package-lock.jsonis excluded by!**/package-lock.json
📒 Files selected for processing (17)
package.jsonscripts/install-production.shskill/SKILL.mdsrc/bot.tssrc/executor.tssrc/index.tssrc/mailbox-broker/client.tssrc/mailbox-broker/gmail-inbox.tssrc/mailbox-broker/gmail-trash.tssrc/mailbox-broker/protocol.tssrc/mailbox-broker/reference.tssrc/mailbox-broker/server.tssrc/mailbox-broker/trash-proposal.tssrc/mailbox-client.tssrc/schema.tssrc/watcher.tstests/mailbox-trash-safety.test.ts
Summary
Verification
Deployment
This PR is the first layer of the approved stack: broker → unsubscribe (#6) → multi-account profiles (#7).
Summary by CodeRabbit
agent-gate-mailboxcommand.