Unified channel system (how integrations plug in)

What it is

The unified channel system is the common ground under Omniscio's message-carrying integrations. Rather than each one inventing its own screen, list and behaviour, each plugs into one shared shape and inherits the same ones.

• Every channel declares what it can do. Some deliver in real time, some only on a refresh; some let you reply from Omniscio, some are read-only; some support threads, attachments, rich text or search, and some do not. The app reads that declaration rather than assuming, so a read-only feed never offers you a reply box it cannot honour.
• Every channel has one place. A channel you have switched on gets its own space in the sidebar listing its conversations, with a count of what is unread, and a reader for the open conversation.
• Every channel has a status. Connected, not connected yet, not configured, connecting, waiting out a rate limit, or in error — and the status is what the alerting and the "unavailable" note read from.

This is the layer under the inbox: the inbox gathers what needs you from across every channel, while this layer is how each channel itself is wired in.

Where to find it

• The sidebar space per channel — switch an integration on (its own Settings panel) and its space appears with its conversations. Switching it off removes it from view again.
• That channel's reader — opening a conversation shows it in the app; a feed shows the article view, a chat shows the message list, a file store shows the file.
• Settings → Connections → Channels — the status of each channel and where to fix one that will not start.
• The Inbox — a channel that fails to start, or later drops out, raises a row here rather than going quiet.
• Search — a query can be run across the channels that support it, from one place.

How it behaves

Turning a channel on creates its space for you. An enabled channel that has no sidebar space gets one; one you previously removed is restored rather than duplicated; one already in place is left alone. Switching a channel off does not tear anything down — the space is simply hidden while the flag is off, so switching it back on brings your history with it.

One bad channel never takes the others down. If a channel fails while starting, the rest still start, and the ones that failed are named in a single inbox alert — "Some integrations could not start" — that lists them and points at Settings → Connections → Channels (the usual causes are an expired sign-in or a missing tool). Repeating failures are deduped, so a channel that keeps failing does not stack up identical rows.

A channel that goes down is shown, not hidden. When a channel drops out while the app is running — a lost connection, an error — the failure is alerted once it has stayed down past a short grace period, so a momentary blip stays quiet. And while a channel is unreachable, listings keep their place and mark it unavailable instead of silently vanishing, so a list that looks short is never mistaken for an empty one.

Reading across channels behaves the same way. Listing conversations, opening one, paging back through messages and searching all fall back gracefully per channel: a channel that cannot answer is reported as unavailable, and the answers from the channels that did respond are still delivered.

For agents

The substrate

• Types: channel-types.ts — ChannelAdapter, ChannelCapabilities (realtime, send, persistence, attachments, threads, createConversation, richText, search), UnifiedMessage, ChannelStatus with ChannelStatusState (connected | disconnected | unconfigured | error | connecting | rate_limited), and composite ids: MAX_COMPOSITE_ID_LENGTH = 8192 with makeCompositeId(channelId, platformId) / parseCompositeId.
• Registry: channel-registry.ts — register() throws on a duplicate id; initializeAll() / connectAll() run each adapter in its own try/catch, collect failed[], and hand them to surfaceChannelBootFailures → buildChannelBootFailureAlertInput (alert title alert.channelBoot.title, dedupKey per phase, F051: any error is swallowed so boot is never disturbed). getAllConversations / searchAll use Promise.allSettled and return failedChannels: string[].
• Wiring at startup: register-channels.ts registers CalendarAdapter, DriveChannelAdapter, OnedriveChannelAdapter, SheetsChannelAdapter, RssAdapter, WebhookAdapter, SlackChannelAdapter; CHANNEL_DOWN_STATES = {error, disconnected}, shouldAlertChannelDown is edge-triggered, CHANNEL_DOWN_GRACE_MS = 15_000.
• IPC: channel-handlers.ts — CHANNELS_LIST / CHANNELS_CONVERSATIONS / CHANNELS_MESSAGES / CHANNELS_SEND / search, all through wrapHandler with zod schemas.
• Sidebar spaces: channel-virtual-projects.ts — CHANNEL_VIRTUAL_PROJECTS, each {id, sentinel, displayName, flagKey, amcGrouped} (gmail, sms, slack, rss, webhook, calendar, drive, onedrive, sheets, dropbox, telegram, telegram-bot, daily-digest, email-summarizer). The sentinel is a member of VIRTUAL_FOLDER_PATHS; this table is the single source of truth for the sidebar rows and is wider than the adapter set (gmail/sms/telegram/briefings/email-summarizer are not ChannelAdapter implementors).
• Lifecycle: channel-project-lifecycle.ts — reconcileChannelProjectRow (enabled+missing → create, enabled+soft-deleted → undelete, enabled+active → no-op, disabled → leave active, renderer flag-gates). Renderer surface: ChannelProjectView.tsx + ChannelContentRouter.tsx.

Related

• inbox-overview.md — the cross-channel triage view built on top of this layer
• slack-integration.md — a real-time chat channel plugged in this way
• rss-integration.md — a read-only feed channel, with its own reader
• webhook-integration.md — a channel that receives pushed events
• drive-integration.md — a file-store channel
• onedrive-integration.md — a second file-store channel
• sheets-integration.md — a spreadsheet channel
• dropbox-integration.md — a third file-store channel