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`):**
```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`](../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`):**
```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`](../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:**
```json
{
  "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):

```json
{
  "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