@x-otto/notification

Unified notification spine for otto sessions: terminal escapes, external commands, and app-internal callbacks.

@x-otto/notification delivers session-level notifications (turn complete, errors, approval requests) through configurable channels. It runs in CLI, TUI, and headless modes with zero frontend dependencies. Notifications are fire-and-forget — they never block or interrupt the session.

Installation

pnpm add @x-otto/notification

Usage

import {
  NotificationDispatcher,
  TerminalChannel,
  PresenceTracker,
  TimestampPresenceGate,
} from '@x-otto/notification'

const dispatcher = new NotificationDispatcher({
  getConfig: () => settings.notification,
  gate: new TimestampPresenceGate({
    state: presenceTracker,
    getCondition: () => 'unfocused',
    getIdleThresholdMs: () => 60000,
  }),
})

// Register terminal channel (OSC 9/99/777 + bell)
dispatcher.registerChannel(new TerminalChannel({
  getConfig: () => settings.notification,
}))

// Subscribe to a session's EventBus
dispatcher.attach(session)

The dispatcher automatically normalizes session events to four kinds:

• turn_complete — agent finished responding
• error — session error
• approval_required — user approval needed for tool/plan
• input_required — user input needed

Presence gating suppresses notifications when the user is actively interacting (idle < threshold), and only the highest-priority event per tick is delivered.

Key Exports

Dispatcher

• NotificationDispatcher — Subscribe to sessions, merge events, fan-out to registered channels
• NotificationDispatcherOptions — getConfig, gate, schedule, isFollowUpPending

Channels

• TerminalChannel — Terminal escape sequences (OSC 9 for iTerm2, OSC 99 for Kitty, OSC 777 for Ghostty) + bell fallback
• CallbackChannel — Generic callback bridge for app-internal or hook dispatch
• CommandChannel — Spawn external program, JSON payload on stdin (trust-gated)
• MemoryChannel — In-memory accumulator for testing

Gating

• PresenceTracker — Idle time tracker (records interactions, optional DEC1004 focus)
• TimestampPresenceGate — Idle-threshold-based gate (60s turn_complete, 6s urgent)
• ALWAYS_PRESENT_GATE — Bypass gate (always deliver)

Terminal

• detectTerminal(env) — Probe terminal capabilities
• bell() — ASCII bell character
• osc9() / osc99() / osc777() — Desktop notification escape sequences

Dependencies

• Internal: @x-otto/hook-contracts (type-only), @x-otto/setting (type-only)
• External: Node.js built-ins only

Related

• Architecture