Cortex-Inara/documentation/ARCH__CHANNELS.md

Architecture: Input Channels

How messages reach Cortex and how Cortex reaches back. Last updated: 2026-04-03

---

Channel Summary

Channel	Direction	Auth	Endpoint
Web UI	In + Out	JWT session cookie	/{user}/{persona}
Nextcloud Talk	In + Out	HMAC-SHA256	POST /webhook/nextcloud/{username}
Google Chat	In + Out	JWT (Google system token)	POST /channels/google-chat/{username}
Cron	Out (proactive)	Internal	APScheduler
Webhooks	In (future)	TBD	POST /webhook/{source}

Per-user config: Each channel that needs secrets (NC Talk bot key, Google Chat audience) stores them in home/{username}/channels.json. No channel access by default — each user sets up their own.

---

Web UI

Single-page app served from cortex/static/. All chat happens via POST /chat (streaming SSE for real-time response) or POST /orchestrate (async job, polled).

Session auth: Login form (/login) → bcrypt password check → JWT cookie (30-day expiry). Google OAuth also available (/auth/google). All non-public routes require a valid cookie.

Modes:

• Direct — message goes straight to LLM via /chat
• Agent — message goes to orchestrator (/orchestrate), tool loop runs, result polled and streamed into UI

Context + Memory panel: Shows current backend (claude/gemini/local), memory tier, active local model. Toggle backend cycles claude → gemini → local.

Files panel: Browse and edit persona markdown files in-browser. Session search at the bottom.

Settings: /settings — Gemini API key, Google account, connected status. /settings/models — model registry (providers, hosts, models, roles).

---

Nextcloud Talk

Bot integration. The bot is registered in a Talk room; it receives messages, generates a response, and sends it back via the NC Talk bot API.

Incoming: POST /webhook/nextcloud/{username}

• Signature verified: HMAC-SHA256(secret, random + raw_body)
• Ignores non-Create events and non-Note types
• Strips @{persona} mention prefix from message text
• Processes in background task (immediate 200 response to NC Talk)

Outgoing: Bot API POST /ocs/v2.php/apps/spreed/api/v1/bot/{room}/message

• Signature: HMAC-SHA256(secret, random + message_text) — note: message text, not body
• Logic lives in notification.py (_send_nct_message) — shared with proactive notifications

Proactive notifications: Set notification_room in channels.json → nextcloud. Used by distill completion alerts and message/brief cron jobs.

Per-user config (channels.json):

{
  "nextcloud": {
    "persona": "inara",
    "url": "https://cloud.dgrzone.com",
    "bot_secret": "...",
    "notification_room": "<room-token>",
    "timeout": 55
  }
}

Full setup guide: docs/NEXTCLOUD_TALK_BOT.md

---

Google Chat

Workspace Add-on. Messages arrive as HTTP POST from Google's infrastructure; the handler returns a JSON response synchronously (no background task — Google expects an immediate reply).

Incoming: POST /channels/google-chat/{username}

• Auth: JWT in authorizationEventObject.systemIdToken, verified against Google's JWKS
• Response format: hostAppDataAction.chatDataAction.createMessageAction

Per-user config (channels.json):

{
  "google_chat": {
    "persona": "inara",
    "audience": "https://cortex.dgrzone.com/channels/google-chat/scott",
    "backend": "claude",
    "timeout": 25
  }
}

Full setup guide: docs/GOOGLE_CHAT_BOT.md

---

Cron / Proactive Messages

User-defined scheduled jobs stored in home/{user}/persona/{name}/CRONS.json. Registered at startup by scheduler.py; manageable via the cron_* orchestrator tools.

Job types:

Type	What happens
remind	Appends to REMINDERS.md — surfaced in context at tier 2+
note	Appends to SCRATCH.md — read on demand
message	Sends payload text to user's notification channel
brief	Runs LLM with payload as prompt, sends response to notification channel

brief example — morning briefing:

{
  "label": "Morning briefing",
  "schedule": "daily:08:00",
  "type": "brief",
  "payload": "Give Scott a brief good morning. Note any pending reminders or tasks due today.",
  "enabled": true
}

Channel selection for message/brief:

1. channel field on the job (if set)
2. notification_channel key in channels.json
3. Auto-detect: uses nextcloud if configured

Schedule formats: hourly | daily | daily:HH:MM | weekly:DOW | weekly:DOW:HH:MM

---

Notification Channel Config

notification_channel in channels.json sets the default outbound channel for all proactive messages (distill alerts, cron message/brief jobs):

{
  "notification_channel": "nextcloud",
  ...
}

If absent, defaults to nextcloud if configured. Currently only NC Talk is supported for outbound; Google Chat outbound is a future item.

---

Future Channels

• WhatsApp — Business API or bridge (not started; needs account)
• Gitea webhooks — push/PR/issue events → orchestrator (router pattern exists; add gitea.py)
• Aether platform events — trigger agent actions from business data changes