Module mail_route

Expand description

One route for every message: which door reaches a receiver, and delivery through it.

Every caller that delivers mail — supercode message send, harness.v1.sessions.message, and idle notices — goes through door_for and deliver, so the choice of door is made in one place. The doors, best first:

runtime — a session supercode controls (a hosted runtime of any harness): its own steer/send_input (crate::runtime_mail). This is the default tier.
native — a Claude Code session supercode does not control: a Claude relay sends with Claude’s own SendMessage (crate::claude_relay).
hook — a Codex session supercode does not control, with supercode’s hooks in its hooks file: filed in its mailbox, and the hook points the session at it.
stored — no door: filed in its mailbox, seen only when the session reads it.

Tiers 2–4 are the degradation tier, for sessions supercode does not control. An operator (a board, a script) is not a session: its mail is filed in its mailbox and read with sessions.inbox.

Structs§

Caller: The session a process belongs to: the sender a message is from.
LiveSession: One running session on this machine, as the router reaches it.
LiveSessions: Every running session on this machine with its door, read once: what message list shows, what names resolve against, and what discovery projects onto each discovered session as delivery.

Enums§

Delivered: How a delivery ended.
Door: The door that reaches one receiver.
NoDoor: Why no door reaches an address on this machine.
Refused: A delivery refused before anything was sent.
Unresolved: Why a receiver named by an agent was not found.
UserTurn: How the user’s own turn reached its session.

Constants§

CALLER_UNRESOLVED: Why no session could be found behind a process.
CODEX_HOOK_ARGUMENTS: Arguments a Codex hook entry carries, which is how its presence is found.
MAX_RELAYED_BYTES: Largest message relayed into a Claude session. The relay copies it into a model turn byte for byte, so it must fit comfortably in one.

Functions§

codex_hooks_path: Codex’s user-level hooks file.
codex_name: Display name of a Codex conversation: codex- and the start of its id.
codex_project_hook_installed: Whether supercode’s mail hook is in a project’s Codex hooks file, in the session’s directory or one above it.
codex_user_hook_installed: Whether supercode’s mail hook is in Codex’s user hooks file. (Codex runs it only once its user has trusted it.)
daemon_pane: The daemon pane a session runs in, when it runs in one.
deliver: Deliver envelope to to through door. With wake false an idle receiver is not started. With notify_when_idle the sender gets one idle notice after the receiver’s next turn ends.
deliver_user_turn: Deliver the user’s own turn to to through the one door that carries the user’s authority: a hosted runtime’s own input, or the session’s pane. A session with neither (running outside supercode) is refused, never reached as a peer instead. Callers hold the owner’s authority already: this is reached only through owner doors (the machine’s own harness.v1).
door_for: The door that reaches to on this machine.
has_message_tools: Whether the session process pid has supercode’s messaging tools: a harness starts each MCP server as a child of the session, so the tools are loaded exactly when a live supercode message mcp is one of its children.
process_ancestry: This process’s ancestry, nearest first (itself included), from ps.
resolve_caller: The session behind a process, from its ancestry pids (nearest first): the first that owns a hosted runtime, a Claude session or a Codex conversation. Never declared by the caller; an environment id only corroborates, and a mismatch refuses.
type_user_turns: Type the user’s waiting turns into pane, oldest first, each only when the pane’s composer is empty. Stops at the first that has to wait. Returns the ids typed.