Skip to content

feat(mailbox): channel-shaped envelope foundation (PR A) - #1432

Merged
namastex888 merged 3 commits into
devfrom
feat/channel-envelope-inbox
Apr 28, 2026
Merged

namastex888 merged 3 commits into
devfrom
feat/channel-envelope-inbox

Conversation

@namastex888

Copy link
Copy Markdown
Contributor

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 the source attribution.

Why

Foundation that PRs B–F build on:

  • PR B: codex UserPromptSubmit hook handler
  • PR C: omni → native migration with source='whatsapp'
  • PR D: system-nudge migration with source='system'
  • PR E: removal of protocol-router.ts:injectToTmuxPane
  • PR F+: external channel adapters (telegram, webhook, …)

Changes

Migration 054

ALTER TABLE mailbox ADD COLUMN IF NOT EXISTS source TEXT NOT NULL DEFAULT 'agent';
ALTER TABLE mailbox ADD COLUMN IF NOT EXISTS meta JSONB NOT NULL DEFAULT '{}'::jsonb;

Idempotent — IF NOT EXISTS makes re-runs safe. No new indexes (existing to_worker / from_worker filters cover every read path).

mailbox.send signature

  • New optional opts arg: { source?: string; meta?: Record<string, unknown> }.
  • source defaults to 'agent' so all 4-arg callers stay back-compat.
  • MailboxMessage always carries source + meta (re-hydrated from rowToMessage).

channel-envelope.ts (new)

Pure module — no I/O, no PG. Two helpers:

  • formatEnvelope({source?, from?, meta?, body}) returns plain body for source === '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.

toNativeInboxMessage adapter

  • Default-source messages pass through unchanged (byte-identical to today).
  • Non-default sources get the body wrapped in a <channel …> envelope and source + meta carried onto the resulting NativeInboxMessage.

NativeInboxMessage type

Optional source?: string and meta?: Record<string, string | number | boolean>. Existing writers/readers stay compatible; new writers can supply attribution.

genie agent inbox rendering

  • Human render: [<source>] 13:42 felipe: … for non-default sources; default source prints unchanged.
  • JSON render: enriches each conversation entry with lastMessage, source, and meta so external consumers round-trip the attribution.
  • Pure helpers (extractSource, renderConversation, buildInboxEntry) exported for unit testing.

Test plan

Spec-required scoped suite (all pass):

bun run typecheck                  # clean
bunx biome check <PR-A files>      # clean
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, 204 expect calls

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; explicit source='whatsapp' round-trip through send → inbox → outbox; nested JSONB meta persistence; legacy 4-arg callers still compile.
  • claude-native-teams.test.ts (+2 cases): writeNativeInbox persists source/meta when supplied; legacy callers without source/meta produce 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

  • All 4-arg mailbox.send callers keep working unchanged (default source='agent').
  • All writeNativeInbox callers keep working unchanged (default-source messages omit source/meta in the output JSON).
  • No existing query path references 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, injectToTmuxPane removal, external adapters). DESIGN.md / WISH.md updates land on a parallel docs/codex-channels-pivot branch.

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 on dev before 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

@coderabbitai

coderabbitai Bot commented Apr 28, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7aaae612-1c8b-4f4b-baed-c912e8094212

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/channel-envelope-inbox

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +25 to +30
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';
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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';
}

Comment on lines +67 to 71
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 };
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

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.

Suggested change
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>;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
meta?: Record<string, string | number | boolean>;
meta?: Record<string, unknown>;

Comment thread src/lib/mailbox.ts
Comment on lines +333 to +338
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;
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
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;

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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*$/;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment on lines +53 to +56
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))}"`);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

@namastex888

Copy link
Copy Markdown
Contributor Author

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.

namastex888 added a commit that referenced this pull request Apr 28, 2026
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.
@namastex888 namastex888 reopened this Apr 28, 2026
namastex888 and others added 3 commits April 28, 2026 02:46
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.
@namastex888
namastex888 force-pushed the feat/channel-envelope-inbox branch from 1a4ead1 to ed881e5 Compare April 28, 2026 05:46
@namastex888
namastex888 merged commit 91044dc into dev Apr 28, 2026
11 checks passed
@automagik-genie
automagik-genie deleted the feat/channel-envelope-inbox branch September 25, 2026 04:49
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.

1 participant