Repository navigation
feat(mailbox): channel-shaped envelope foundation (PR A) - #1432
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ 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.
Code Review
This pull request introduces a channel-shaped envelope for the mailbox system, allowing messages to carry source attribution and arbitrary metadata. Key changes include a database migration adding source and meta columns, a new utility for formatting and parsing structured <channel> tags, and updates to the mailbox and inbox logic to support these fields while maintaining backward compatibility for agent-to-agent messages. The review feedback identifies logic errors where the code fails to check the new top-level properties instead of legacy metadata fields, and suggests using more permissive types for metadata to ensure data fidelity for nested objects.
| export function extractSource(msg: any): string { | ||
| if (!msg || typeof msg !== 'object') return 'agent'; | ||
| const meta = (msg.metadata ?? {}) as Record<string, unknown>; | ||
| const value = typeof meta.source === 'string' ? meta.source : null; | ||
| return value && value.length > 0 ? value : 'agent'; | ||
| } |
There was a problem hiding this comment.
The extractSource function currently only looks for the source field within a metadata object. However, the new MailboxMessage and NativeInboxMessage models introduced in this PR place the source field at the top level. This will cause the human-readable inbox to default to [agent] for all messages, even those from other sources like WhatsApp, because the extraction logic fails to find the attribution on the new message shapes.
export function extractSource(msg: any): string {
if (!msg || typeof msg !== 'object') return 'agent';
const source = msg.source ?? msg.metadata?.source;
return typeof source === 'string' && source.length > 0 ? source : 'agent';
}| export function buildInboxEntry(conversation: any, lastMessage: any) { | ||
| const source = extractSource(lastMessage); | ||
| const meta = ((lastMessage?.metadata as Record<string, unknown> | undefined) ?? {}) as Record<string, unknown>; | ||
| return { conversation, lastMessage, source, meta }; | ||
| } |
There was a problem hiding this comment.
Similar to extractSource, buildInboxEntry only attempts to extract metadata from a metadata property. Since the new message models use a top-level meta property, the JSON output of the inbox command will miss the attribution metadata for messages following the new schema.
| export function buildInboxEntry(conversation: any, lastMessage: any) { | |
| const source = extractSource(lastMessage); | |
| const meta = ((lastMessage?.metadata as Record<string, unknown> | undefined) ?? {}) as Record<string, unknown>; | |
| return { conversation, lastMessage, source, meta }; | |
| } | |
| export function buildInboxEntry(conversation: any, lastMessage: any) { | |
| const source = extractSource(lastMessage); | |
| const meta = lastMessage?.meta ?? lastMessage?.metadata ?? {}; | |
| return { conversation, lastMessage, source, meta }; | |
| } |
| * attributes when the body is rendered into a `<channel …>` tag. Persisted | ||
| * verbatim so future readers can round-trip the data. | ||
| */ | ||
| meta?: Record<string, string | number | boolean>; |
There was a problem hiding this comment.
The meta property is restricted to primitive types (string | number | boolean). However, MailboxMessage.meta is a Record<string, unknown> (backed by JSONB in PostgreSQL) and can contain nested objects or arrays. To ensure data fidelity and support the "persisted verbatim" goal mentioned in the comments, this type should be more permissive to allow round-tripping complex metadata through the native inbox JSON.
| meta?: Record<string, string | number | boolean>; | |
| meta?: Record<string, unknown>; |
| const meta: Record<string, string | number | boolean> = {}; | ||
| for (const [key, value] of Object.entries(msg.meta ?? {})) { | ||
| if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') { | ||
| meta[key] = value; | ||
| } | ||
| } |
There was a problem hiding this comment.
This loop filters out non-primitive values from the metadata. This is inconsistent with formatEnvelope (which stringifies nested objects for the XML tag) and prevents the "verbatim" persistence of metadata in the native inbox JSON. If NativeInboxMessage.meta is updated to support unknown values (as suggested in claude-native-teams.ts), this filtering logic can be removed to preserve the full metadata object.
| const meta: Record<string, string | number | boolean> = {}; | |
| for (const [key, value] of Object.entries(msg.meta ?? {})) { | |
| if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') { | |
| meta[key] = value; | |
| } | |
| } | |
| const meta = msg.meta; |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f7e690d18d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| const DEFAULT_SOURCE = 'agent'; | ||
|
|
||
| const TAG_OPEN_RE = /^<channel\s+([^>]*)>([\s\S]*)<\/channel>\s*$/; |
There was a problem hiding this comment.
Parse opening tag without truncating values containing '>'
The opening-tag regex stops the attribute blob at the first > ([^>]*), so envelopes formatted with metadata like meta: { note: 'a>b' } are not parsed correctly: parseEnvelope(formatEnvelope(...)) drops attributes after that value. This breaks the module’s own round-trip guarantee and will lose channel metadata for common text fragments (for example URLs or expressions containing >).
Useful? React with 👍 / 👎.
| for (const [key, value] of Object.entries(input.meta)) { | ||
| if (!isValidAttrName(key)) continue; | ||
| if (value === undefined || value === null) continue; | ||
| attrs.push(`${key}="${escapeAttr(stringifyAttr(value))}"`); |
There was a problem hiding this comment.
Exclude reserved source/from keys from envelope metadata
formatEnvelope serializes all metadata keys, including source and from, after writing canonical source/from attributes. If callers pass meta.source or meta.from, the envelope contains duplicate attributes and parsing can overwrite the canonical attribution (attrs[name] = ... keeps the later value), leading to incorrect source labeling and potentially spoofed origin metadata.
Useful? React with 👍 / 👎.
f7e690d to
3ab0ed3
Compare
|
Replaced by fresh-rebased PR from feat/channel-envelope-inbox-clean — original branch had stale snapshots and accumulated unrelated commits during the wait. New PR opened with clean single-commit and current-version snapshot regen. |
After #1441 pinned COLUMNS=80 at the workflow level, the existing SystemStats snapshots (5 frames: low/mid/high/critical CPU + Nav cold start) drifted by 1 trailing space per line — the prior captures came from a terminal that emitted slightly different right-padding for the "genie vX.Y.Z" header row. Regenerated locally with `COLUMNS=80 bun test test/visual/ -u` to match the CI render exactly. Diff is purely whitespace; visible chars and colour spans unchanged. Unblocks PR #1432 channel-envelope CI. Same baseline now applies to any future visual test addition in this PR or downstream.
Adopt the semantics of Anthropic's Claude Code Channels (structured
`<channel source="X" meta_k=v>body</channel>` envelope) without adopting
the MCP transport. Genie owns the source layer — `genie send`, omni →
whatsapp, system nudges, future external adapters all funnel through the
same mailbox + native-inbox pipeline, with `source` attribution telling
the receiving Claude where the message came from.
Why: PRs B–F (codex hook handler, omni → native migration, system-nudge
migration, injectToTmuxPane removal, external adapters) all build on
this foundation.
Changes:
- migration 054: ALTER TABLE mailbox ADD source TEXT DEFAULT 'agent',
meta JSONB DEFAULT '{}'. Idempotent (IF NOT EXISTS).
- mailbox.send: opts arg `{ source?, meta? }`. Existing 4-arg callers
unchanged. MailboxMessage carries source + meta on every row.
- channel-envelope.ts: pure formatEnvelope/parseEnvelope helpers.
Plain-body passthrough for source='agent' (back-compat); structured
tag for everything else. Round-trips meta values with attribute
escaping.
- toNativeInboxMessage: when source != 'agent', wraps body in
`<channel …>` and carries source/meta onto NativeInboxMessage.
Default-source path is byte-identical to today's output.
- NativeInboxMessage: optional `source` and `meta` fields.
- genie agent inbox: `[<source>]` tag prepended to non-agent previews;
JSON output surfaces source + meta verbatim per conversation.
Tests:
- src/lib/channel-envelope.test.ts: 12 cases covering round-trip,
passthrough, escaping, malformed input.
- src/term-commands/agent/inbox.test.ts: 10 cases covering source tag
rendering and JSON enrichment.
- src/lib/__tests__/mailbox.test.ts: extended with 4 cases for default
source, explicit source=whatsapp round-trip, JSONB meta persistence,
and back-compat for legacy 4-arg callers.
- src/lib/claude-native-teams.test.ts: extended with 2 cases for
source/meta persistence + legacy-shape preservation.
- Existing fixtures in brief.test.ts, unified-log.test.ts,
scheduler-daemon.test.ts updated with source/meta defaults.
Validation:
- bun run typecheck: clean
- bunx biome check .: only pre-existing complexity warnings in unrelated
files
- bun test src/lib/__tests__/mailbox.test.ts src/lib/claude-native-teams.test.ts
src/lib/channel-envelope.test.ts src/term-commands/agent/inbox.test.ts:
92 pass, 0 fail
Out of scope (later PRs): codex UserPromptSubmit hook handler (PR B),
omni → native migration with source='whatsapp' (PR C), system-nudge
migration with source='system' (PR D), injectToTmuxPane removal (PR E),
external adapters (PR F+).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
After #1441 pinned COLUMNS=80 at the workflow level, the existing SystemStats snapshots (5 frames: low/mid/high/critical CPU + Nav cold start) drifted by 1 trailing space per line — the prior captures came from a terminal that emitted slightly different right-padding for the "genie vX.Y.Z" header row. Regenerated locally with `COLUMNS=80 bun test test/visual/ -u` to match the CI render exactly. Diff is purely whitespace; visible chars and colour spans unchanged. Unblocks PR #1432 channel-envelope CI. Same baseline now applies to any future visual test addition in this PR or downstream.
1a4ead1 to
ed881e5
Compare
Scope
PR A in the channels-pivot roadmap. Adopts the semantics of Anthropic's new Claude Code Channels (structured
<channel source="X" meta_k=v>body</channel>envelope) without adopting the MCP transport. Genie owns the source layer —genie send(peer agents), platform integrations (omni → whatsapp), system nudges, future external adapters all funnel through the same mailbox + native-inbox pipeline. What differs is thesourceattribution.Why
Foundation that PRs B–F build on:
UserPromptSubmithook handlersource='whatsapp'source='system'protocol-router.ts:injectToTmuxPaneChanges
Migration 054
Idempotent —
IF NOT EXISTSmakes re-runs safe. No new indexes (existingto_worker/from_workerfilters cover every read path).mailbox.sendsignatureoptsarg:{ source?: string; meta?: Record<string, unknown> }.sourcedefaults to'agent'so all 4-arg callers stay back-compat.MailboxMessagealways carriessource+meta(re-hydrated fromrowToMessage).channel-envelope.ts(new)Pure module — no I/O, no PG. Two helpers:
formatEnvelope({source?, from?, meta?, body})returns plainbodyforsource === 'agent', otherwise<channel source="X" from="Y" k="v">body</channel>with attribute-escaped values.parseEnvelope(text)returns{ source, from?, meta, body } | null. Best-effort, lossless round-trip for well-formed input.toNativeInboxMessageadapter<channel …>envelope andsource+metacarried onto the resultingNativeInboxMessage.NativeInboxMessagetypeOptional
source?: stringandmeta?: Record<string, string | number | boolean>. Existing writers/readers stay compatible; new writers can supply attribution.genie agent inboxrendering[<source>] 13:42 felipe: …for non-default sources; default source prints unchanged.lastMessage,source, andmetaso external consumers round-trip the attribution.extractSource,renderConversation,buildInboxEntry) exported for unit testing.Test plan
Spec-required scoped suite (all pass):
New / extended cases:
channel-envelope.test.ts(12 cases): format/parse round-trip across multiple sources, plain-body passthrough for'agent', attribute escaping for embedded quotes, malformed-input handling, numeric/boolean meta serialisation, invalid-key skipping, leading whitespace tolerance.__tests__/mailbox.test.ts(+4 cases): default source'agent'when opts omitted; explicitsource='whatsapp'round-trip through send → inbox → outbox; nested JSONB meta persistence; legacy 4-arg callers still compile.claude-native-teams.test.ts(+2 cases):writeNativeInboxpersistssource/metawhen supplied; legacy callers withoutsource/metaproduce the same JSON shape as before.term-commands/agent/inbox.test.ts(10 cases, new file): source-tag rendering, default-source omission, JSON entry shape, null-message handling.Compatibility / blast radius
mailbox.sendcallers keep working unchanged (defaultsource='agent').writeNativeInboxcallers keep working unchanged (default-source messages omitsource/metain the output JSON).source/meta; the new columns are purely additive.Out of scope
PRs B–F handle the actual delivery migrations (omni → native, system nudges, codex hook,
injectToTmuxPaneremoval, external adapters). DESIGN.md / WISH.md updates land on a paralleldocs/codex-channels-pivotbranch.Pre-existing test flakes (not regressions)
The full repo suite (
bun run check) has ~28 pre-existing failures unrelated to PR A scope (migration 049/053, executor-read, claude-code-deliver tmux mocks, omni-bridge shutdown, simone phone-id, etc.) — these were red ondevbefore this PR. They are tracked under task #130 ("Group 14: bare-name shadows + master backfill + guardrails", in progress) and are out of CI's required gate. The PR-A scoped suite is 92/92.🤖 Generated with Claude Code