@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/web-auth.js

@@ -6,13 +6,13 @@
 
 const { spawn } = require("child_process");
 const os = require("os");
-const { CLAUDE_PATH, resolvedCodexPath, botSubprocessEnv } = require("./config");
+const { discoverProviderExecutable } = require("./config");
+const { inspectProviderConfiguration } = require("./provider-status");
 const { redactSensitive, stripTerminalControls, extractUrls } = require("./redact");
 const {
-  claudeSubprocessEnv, saveClaudeOAuthToken, getClaudeOAuthToken,
+  claudeSubprocessEnv, codexSubprocessEnv, saveClaudeOAuthToken, getClaudeOAuthToken,
   extractClaudeToken, isClaudeAuthUrl, looksLikeClaudeToken, looksLikeOpenAIKey,
-  runClaudeAuthStatusDiagnostic, isClaudeAuthErrorText,
-  runCodexLoginStatus, saveCodexApiKeyWithCli,
+  saveCodexApiKeyWithCli,
 } = require("./auth-flow");
 
 const HOME = process.env.HOME || os.homedir();
@@ -22,7 +22,9 @@ let claude = null;
 
 function startClaudeLogin() {
   if (claude && claude.proc && !claude.done) return { ok: true, already: true };
-  const proc = spawn(CLAUDE_PATH, ["auth", "login", "--claudeai"], {
+  const binary = discoverProviderExecutable("claude");
+  if (!binary) return { ok: false, error: "Claude Code CLI not found." };
+  const proc = spawn(binary, ["auth", "login", "--claudeai"], {
     cwd: HOME, env: claudeSubprocessEnv(), stdio: ["pipe", "pipe", "pipe"],
   });
   claude = { proc, url: null, log: "", awaitingCode: false, done: false, ok: false, error: null, tokenStored: false };
@@ -89,10 +91,11 @@ function saveClaudeToken(token) {
 let codex = null;
 
 function startCodexLogin() {
-  if (!resolvedCodexPath) return { ok: false, error: "Codex CLI not found." };
+  const binary = discoverProviderExecutable("codex");
+  if (!binary) return { ok: false, error: "Codex CLI not found." };
   if (codex && codex.proc && !codex.done) return { ok: true, already: true };
-  const proc = spawn(resolvedCodexPath, ["login", "--device-auth"], {
-    cwd: HOME, env: botSubprocessEnv(), stdio: ["pipe", "pipe", "pipe"],
+  const proc = spawn(binary, ["login", "--device-auth"], {
+    cwd: HOME, env: codexSubprocessEnv(), stdio: ["pipe", "pipe", "pipe"],
   });
   codex = { proc, url: null, code: null, log: "", done: false, ok: false, error: null };
   const onChunk = (buf) => {
@@ -135,7 +138,7 @@ function codexState() {
 
 // Reliable path: save a pasted OpenAI API key via the Codex CLI.
 async function saveCodexApiKey(key) {
-  if (!resolvedCodexPath) return { ok: false, error: "Codex CLI not found." };
+  if (!discoverProviderExecutable("codex")) return { ok: false, error: "Codex CLI not found." };
   const k = String(key || "").trim();
   if (!looksLikeOpenAIKey(k)) return { ok: false, error: "That does not look like an OpenAI API key." };
   const result = await saveCodexApiKeyWithCli(k);
@@ -145,11 +148,24 @@ async function saveCodexApiKey(key) {
 // ── Combined status ─────────────────────────────────────────────────
 function authStatus() {
   const tokenInfo = getClaudeOAuthToken();
-  const diag = runClaudeAuthStatusDiagnostic();
-  const codexStatus = resolvedCodexPath ? runCodexLoginStatus() : { ok: false };
+  const summary = inspectProviderConfiguration();
+  const claudeStatus = summary.providers.find((provider) => provider.id === "claude");
+  const codexStatus = summary.providers.find((provider) => provider.id === "codex");
   return {
-    claude: { configured: !!tokenInfo.value, source: tokenInfo.source, loggedIn: !isClaudeAuthErrorText(diag) },
-    codex: { cliFound: !!resolvedCodexPath, loggedIn: !!codexStatus.ok },
+    providers: summary.providers,
+    defaultProvider: summary.defaultProvider,
+    // Transitional fields keep existing dashboard clients working while the
+    // generic provider list is the authoritative status surface.
+    claude: {
+      configured: !!tokenInfo.value,
+      source: tokenInfo.source,
+      cliFound: claudeStatus?.availability.state === "available",
+      loggedIn: claudeStatus?.auth.state === "authenticated",
+    },
+    codex: {
+      cliFound: codexStatus?.availability.state === "available",
+      loggedIn: codexStatus?.auth.state === "authenticated",
+    },
   };
 }
 

package/core/web-sessions.js

@@ -0,0 +1,78 @@
+// Revocable dashboard sessions. The web login used to set the cookie to a
+// static sha256(password): identical for every session, valid until the password
+// changed, and impossible to revoke — a leaked cookie or /otp link granted
+// permanent access. Instead we mint a random 256-bit token per login, track it
+// server-side with an expiry, and validate the cookie against that store. Tokens
+// can be individually revoked, expire on their own, and are all dropped when the
+// password changes. Persisted via the atomic writer (core/fsutil) so a login
+// survives a bot restart/upgrade, and a torn write falls back to the last good
+// file rather than logging everyone out.
+
+const crypto = require("crypto");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+const { atomicWriteFileSync, readJsonWithFallback } = require("./fsutil");
+
+const SESSIONS_FILE = path.join(CONFIG_DIR, "web-sessions.json");
+const TTL_MS = 24 * 60 * 60 * 1000; // 24h — matches the cookie Max-Age
+
+function load() {
+  const raw = readJsonWithFallback(SESSIONS_FILE, {});
+  return raw && typeof raw === "object" ? raw : {};
+}
+
+function persist(sessions) {
+  try { atomicWriteFileSync(SESSIONS_FILE, JSON.stringify(sessions), { backup: true }); }
+  catch (e) { console.error("web-sessions: write failed:", e.message); }
+}
+
+// Drop expired (or malformed) entries in place. Returns true if anything went.
+function sweep(sessions, now = Date.now()) {
+  let changed = false;
+  for (const token of Object.keys(sessions)) {
+    const meta = sessions[token];
+    if (!meta || typeof meta.expires !== "number" || meta.expires <= now) {
+      delete sessions[token];
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+// Mint and persist a fresh session token, returning it for the Set-Cookie.
+function issue() {
+  const token = crypto.randomBytes(32).toString("hex");
+  const sessions = load();
+  sweep(sessions);
+  const now = Date.now();
+  sessions[token] = { created: now, expires: now + TTL_MS };
+  persist(sessions);
+  return token;
+}
+
+// Is this cookie token a live, unexpired session? hasOwnProperty guards against
+// an attacker presenting "__proto__"/"constructor" and hitting the prototype.
+function valid(token) {
+  if (!token || typeof token !== "string") return false;
+  const sessions = load();
+  if (!Object.prototype.hasOwnProperty.call(sessions, token)) return false;
+  const meta = sessions[token];
+  if (!meta || typeof meta.expires !== "number" || meta.expires <= Date.now()) return false;
+  return true;
+}
+
+function revoke(token) {
+  if (!token) return;
+  const sessions = load();
+  if (Object.prototype.hasOwnProperty.call(sessions, token)) {
+    delete sessions[token];
+    persist(sessions);
+  }
+}
+
+// Kill every session — used when the password changes.
+function revokeAll() {
+  persist({});
+}
+
+module.exports = { issue, valid, revoke, revokeAll, sweep, TTL_MS, SESSIONS_FILE };

package/docs/CHANNEL_DESIGN.md

@@ -0,0 +1,181 @@
+# Open Claudia — Channel design (Phase 0/2)
+
+> Provider-parity update: current direct and agent modes both run through the
+> modular `bot.js` entrypoint. `bot-agent.js` is now only a compatibility shim.
+> Channel adapters dispatch normalized turns to the provider registry and do
+> not choose a provider or construct provider-specific CLI arguments.
+> Provider state/session/job changes use the verified snapshot and rollback
+> process in [PROVIDER_MIGRATION.md](./PROVIDER_MIGRATION.md). References below
+> to leaving the old monolith unchanged describe the historical channel refactor.
+
+Companion to MULTI_CHANNEL_PLAN.md. Decides the concrete shape of channels in code before refactor begins.
+
+---
+
+## 1. Channel-config mechanism
+
+Channels are a configurable list. Each entry declares an adapter type + adapter-specific env keys. No hardcoded if/else in core.
+
+`.env` example (both enabled):
+```
+CHANNELS=telegram,kazee
+
+# telegram adapter
+TELEGRAM_BOT_TOKEN=...
+TELEGRAM_CHAT_ID=6251055967
+
+# kazee adapter
+KAZEE_URL=https://chat.kazee.africa
+KAZEE_BOT_TOKEN=bot_...
+KAZEE_BOT_USER_ID=64f8...
+```
+
+Backwards compat: if `CHANNELS` is unset, default to `telegram` so existing installs keep working (no migration on v1.21.0).
+
+`core/config.js` exports `loadChannels()` returning `[{id, type, opts}]`. Bot bootstrap iterates and calls `createAdapter(type, opts)` per entry. Unknown type → log + skip, not fatal.
+
+## 2. ChannelAdapter contract
+
+One JS class per channel. All identified IO with the outside world (Telegram API, Kazee REST/socket) lives behind this surface — core code never touches transport SDKs directly.
+
+```js
+// channels/types.js — JSDoc-only contract (no runtime base class)
+
+/**
+ * @typedef {Object} InboundEnvelope
+ * @property {string} channelId       // raw transport id (telegram chatId, kazee chatId)
+ * @property {string} canonicalUserId // "telegram:123" | "kazee:abc"
+ * @property {string} userId          // raw transport user id
+ * @property {string} [text]
+ * @property {string} [replyToId]
+ * @property {Array<MediaRef>} [mediaRefs]
+ * @property {string} type            // "text" | "voice" | "audio" | "photo" | "document" | "action"
+ * @property {any} raw                // original payload, adapter-specific
+ */
+
+/**
+ * @typedef {Object} SendOpts
+ * @property {string} [parseMode]
+ * @property {Object} [keyboard]      // {inline_keyboard:[[{text,callback_data}]]} OR
+ *                                    // {buttons:[{id,label,style,payload}]} for kazee interactive
+ * @property {string|number} [replyTo]
+ */
+
+/**
+ * Every adapter implements:
+ *   id: string                            "telegram" | "kazee"
+ *   start(): Promise<void>
+ *   stop(): Promise<void>
+ *   on(event, fn): unsubscribe            events: "message" | "action"
+ *   send(channelId, text, opts): Promise<messageId|null>
+ *   edit(channelId, messageId, text, opts): Promise<void>
+ *   delete(channelId, messageId): Promise<void>
+ *   sendVoice(channelId, oggPath): Promise<boolean>
+ *   sendFile(channelId, filePath, caption?): Promise<boolean>
+ *   typing(channelId): Promise<void>
+ *   downloadMedia(mediaRef): Promise<localPath>
+ */
+```
+
+Notes
+- `keyboard` is the one leaky abstraction. Telegram's `inline_keyboard` and Kazee's `interactive.buttons` differ enough that core builds a portable representation and each adapter renders it natively. Core uses `{buttons: [{id, label, style?, payload?}]}` as the canonical shape; the telegram adapter converts to `inline_keyboard`.
+- `channelId` is opaque to core. Adapters route on it. Same chatId may exist on different channels — disambiguation happens via the adapter the message arrived on.
+- `canonicalUserId` is the only user identifier core code cares about. It maps to per-user state.
+
+## 3. Channel-aware chat context
+
+Today: `chatContext = new AsyncLocalStorage()` stores chatId as a plain string. Every `send/edit/...` reads `currentChatId()`.
+
+After: context stores `{adapter, channelId, canonicalUserId}`. New helpers:
+```js
+core/context.js
+  runInChat({adapter, channelId, canonicalUserId}, fn)
+  currentAdapter()       // returns the ChannelAdapter for the in-flight request
+  currentChannelId()     // raw channel id
+  currentCanonicalUserId()
+```
+
+`send(text, opts)` becomes `currentAdapter().send(currentChannelId(), text, opts)`. All 19 Telegram primitives flatten down to ~7 adapter methods + utility helpers.
+
+## 4. Command registry
+
+`core/commands.js` exports a registry:
+```js
+register({
+  name: "model",
+  description: "Pick or show active model",
+  args: [{name: "model", required: false}],
+  handler: async (ctx, args) => { ... },
+});
+```
+- `ctx` = `{canonicalUserId, channelId, adapter, raw, replyToId}`.
+- `args` = `string[]` (raw tokens after `/cmd`), parser is intentionally dumb so handlers keep flexibility.
+- The router parses `/cmd args` from inbound text and dispatches. Both adapters share one parser.
+- Telegram-specific behaviour (regex multimatch like `/cron add "..." "..." "..."`) — handlers that need richer parsing can fall back to raw text via `ctx.raw.text`.
+
+On startup the bot:
+1. Loads registry.
+2. Telegram adapter: no-op (Telegram has its own BotFather menu we don't auto-register; current behaviour preserved).
+3. Kazee adapter: `PUT /bot/<botId>/commands` with `[{name, description, args}]` so web/mobile slash menus populate.
+
+## 5. Refactor strategy (low-risk, incremental)
+
+The 3544-line bot.js gets split across multiple commits, each shippable on its own and behaviour-preserving for Telegram.
+
+| Step | Commit | Scope | Risk |
+|---|---|---|---|
+| A | extract config | `core/config.js` (loadEnv + loadChannels) | nil |
+| B | extract identity | `core/identity.js` (canonicalForChannel, identities file IO) | nil |
+| C | extract state | `core/state.js` (userStates, savedState, sessions persistence) | low |
+| D | extract commands registry | `core/commands.js` empty registry + router that delegates to existing `bot.onText` handlers | nil (no behaviour change) |
+| E | introduce ChannelAdapter | `channels/telegram/adapter.js` wraps existing `bot.sendMessage/...`. `chatContext` now stores `{adapter,channelId}`. All `send/edit/delete/sendVoice` in bot.js refactored to delegate to `currentAdapter()` | medium — touches every IO call site |
+| F | migrate handlers to registry | Convert each `bot.onText` into a `register({...})` entry. Telegram adapter routes inbound text → registry. | medium — 35+ touchpoints, but mechanical |
+| G | ship v1.21.0 | smoke test Telegram parity end-to-end | — |
+| H | kazee adapter | `channels/kazee/adapter.js` — socket client, send/edit/delete/sendFile/sendVoice, interactive button shape | new code, no Telegram risk |
+| I | ship v1.22.0 | kazee adapter behind `CHANNELS=telegram,kazee` once dev verified | — |
+
+After step G the file tree looks like:
+```
+open-claudia/
+  bot.js                  # ~200 lines — bootstrap, signal handling, channel loop
+  core/
+    config.js
+    identity.js
+    state.js
+    context.js
+    commands.js
+    router.js             # parses /cmd, dispatches registry, handles voice/media
+    transcripts.js        # re-export of project-transcripts.js
+  channels/
+    types.js              # JSDoc
+    telegram/
+      adapter.js
+      format.js           # Telegram-MD quirks (single-asterisk bold)
+  bot-agent.js            # unchanged
+  health.js               # unchanged
+  web.js                  # unchanged
+```
+
+After step H:
+```
+  channels/kazee/
+    adapter.js
+    format.js             # standard markdown, no chunking
+    socket.js             # socket.io-client wrapper
+```
+
+## 6. Open items I'm flagging now
+
+1. **Telegram `parseMode: "Markdown"` vs `MarkdownV2`** — many existing `send(text, {parseMode: "Markdown"})` calls. Kazee adapter ignores parseMode (always standard MD). Need adapter-side normalisation if we ever ship the same text through both. For Phase 0, parseMode flows through unchanged for Telegram; Kazee adapter silently drops it.
+2. **Reply IDs across channels** — `replyTo` is a Telegram `message_id`. Kazee uses Mongo `_id`. Already opaque in `SendOpts`. Fine.
+3. **`bot.on("callback_query")`** in Telegram becomes a `{type:"action", actionId, payload}` envelope on the adapter. Same path Kazee uses for button presses. Core router sees both the same way.
+4. **Voice download path** — `downloadFile(fileId, ext)` is Telegram-specific. Becomes `adapter.downloadMedia(mediaRef)` returning a local file path. Telegram adapter wraps `bot.getFile + https.get`; Kazee adapter does `GET <minio-url>`.
+5. **Crons & notifyError** — both currently call `bot.sendMessage(CHAT_ID, ...)` directly. Need to route through the *owner's* preferred adapter. Cron entries store `canonicalUserId`; lookup their preferred channel via identities and dispatch via that adapter. (`notifyError` keeps Telegram-only fallback — last-resort crash channel.)
+
+## 7. What I won't change in this refactor
+
+- At that time, `bot-agent.js` stayed as the Claude runner subprocess wrapper; it is now a provider-neutral compatibility shim.
+- `health.js`, `web.js`, `setup.js` — untouched.
+- Historical subprocess management stayed unchanged during this channel-only refactor; provider convergence happened later.
+- Vault, soul, crons schemas on disk — same files, same format. No migration.
+- Identities file format — adds `kazee:<userId>` keys naturally; no schema change needed.

package/docs/MULTI_CHANNEL_PLAN.md

@@ -0,0 +1,254 @@
+# Open Claudia — Multi-Channel Plan (Telegram + Kazee Chat)
+
+> This is a historical design plan. The target adapter architecture has since
+> shipped; Section 1 records the current Open Claudia implementation, while the
+> later rollout estimates and external-client notes are retained as design history.
+
+## Goal
+Make Open Claudia channel-agnostic, with Telegram as one adapter and **Kazee Chat** as a second equal-class adapter. Slash commands must work natively in both.
+
+---
+
+## 1. Current implementation
+
+### open-claudia
+- `bot.js` is the modular runtime bootstrap; Telegram, Kazee, and voice are channel adapters behind one normalized router and command registry.
+- Async chat context carries the adapter, channel ID, and canonical user ID. Linked channels can resolve to one canonical identity and share provider/project state safely.
+- All model-bearing paths call the provider-neutral runner. The provider registry owns Claude Code and OpenAI Codex capabilities, invocation arguments, event parsing, auth status, and native session semantics.
+- Setup, web configuration, doctor, and status remain available with no provider installed. Model turns require one compatible authenticated provider.
+- Provider-aware state, sessions, and scheduled jobs use the verified snapshot and rollback procedure in [PROVIDER_MIGRATION.md](./PROVIDER_MIGRATION.md).
+- Shared operator stores such as the vault and soul remain intentionally global; conversations, settings, usage, and transcripts are canonical-user/project/provider scoped.
+
+### Historical external-service baseline: chat-central (ActionHero + Socket.IO + Mongo + Redis)
+- **Bot infrastructure already exists**:
+  - `User.type: "Bot"` with `botToken` field (unique, indexed).
+  - Auth middleware accepts `Authorization: Bearer bot_<token>` and bypasses Central JWT.
+  - `BotRole` model with `webhookUrl` (for external webhook fan-out).
+  - `createBot`, `listBots`, `createBotRole`, `listBotRoles` actions exist.
+- Message model is rich: text/image/video/file/audio/poll/system, replyTo, mentions, reactions, edits, media[], read receipts.
+- Real-time via Socket.IO V2 — events: `message:new`, `message:update`, `message:delete`, `typing`, `reaction:updated`, `pin:updated`, `chat:read`, etc.
+- DMs: `isGroupChat: false`, 2 participants. Existing dedup query.
+- File upload: `POST /chat/:chat_id/media` (MinIO-backed).
+- **No native slash-command framework** — content is plain text. We need to build the slash menu UX in the clients.
+
+### kazee-chat (web, Next.js + TipTap + Socket.IO V2)
+- Rich text editor (TipTap) for input. Mentions autocomplete exists; **no slash menu yet**.
+- Markdown rendering (react-markdown + rehype-highlight) — good for our outputs.
+- File upload, voice recording, image rendering — all working.
+
+### kazee-chat-mobile (React Native + Expo + Socket.IO V2)
+- @-mention autocomplete in `ChatInputToolbar.tsx`; **no slash menu yet**.
+- Voice recording via `expo-audio`; uploads via `mediaPipeline`.
+- Markdown rendering via `react-native-markdown-display`.
+
+---
+
+## 2. Target architecture
+
+### 2.1 ChannelAdapter interface (open-claudia)
+A single interface every transport implements. The bot core becomes transport-agnostic and only talks to adapters.
+
+```js
+// channels/types.d.ts (conceptual)
+class ChannelAdapter {
+  readonly id;                              // "telegram" | "kazee"
+
+  // Lifecycle
+  start();                                  // connect/poll
+  stop();
+
+  // Inbound (emit to core)
+  on("message",  fn(InboundMessage));
+  on("command",  fn(InboundCommand));       // parsed slash command
+  on("media",    fn(InboundMedia));         // voice/photo/document
+  on("action",   fn(InboundAction));        // button click / callback
+
+  // Outbound (called by core)
+  send(channelId, text, opts);              // {parseMode, replyTo, buttons}
+  edit(channelId, messageId, text, opts);
+  delete(channelId, messageId);
+  sendFile(channelId, path, caption);
+  sendVoice(channelId, path);
+  typing(channelId);
+
+  // Identity
+  canonicalUserId(rawId);                   // "telegram:123" / "kazee:abc"
+  downloadMedia(mediaRef) -> localPath;
+}
+```
+
+`InboundMessage` is a normalised envelope:
+```ts
+{ channelId, userId, canonicalUserId, text, replyToId, mediaRefs[], raw }
+```
+
+### 2.2 Bot core (transport-agnostic)
+- `core/router.js` — receives normalised events, dispatches to command registry or chat handler.
+- `core/commands.js` — explicit registry: `{name, description, args, handler}`. Both adapters consume the same registry; Telegram converts to `bot.onText` regex, Kazee exposes it via REST so clients can build the slash menu.
+- `core/state.js` — already mostly transport-agnostic (sessions, vault, soul, crons). Stays.
+- `core/identity.js` — `canonicalForChannel(transport, channelId)` already exists; generalise to `kazee:` prefix.
+
+### 2.3 Refactor scope (bot.js → modules)
+| New module | Lifted from bot.js (approx lines) | Notes |
+|---|---|---|
+| `channels/telegram/index.js` | client init 228-232, polling 238-250, all `bot.onText` 755-3091, media handlers 3259-3339, callback_query 3102-3255, `send/edit/delete/getFile` wrappers 986-1113 | Becomes a thin adapter |
+| `channels/kazee/index.js` | NEW | Socket.IO V2 client + REST send + media download |
+| `core/router.js` | NEW — dispatch logic from `bot.on("message")` 3343-3497 |
+| `core/commands.js` | extract command handlers + descriptions | Each handler becomes `{name, desc, args, fn}` |
+| `core/identity.js` | 376-392, 487-491, 561-589 | Generalised |
+| `core/transcripts.js` | already split (project-transcripts.js) | No change |
+| `core/state.js` | 501-503, 597-649 | No change |
+
+bot.js shrinks to ~200 lines of bootstrap.
+
+---
+
+## 3. Kazee Chat adapter — concrete plan
+
+### 3.1 Bot account setup (one-time, ops)
+On chat-central:
+1. `POST /botRole` → `{botName: "open-claudia", webhookUrl: null}` (we won't use webhook; we use Socket.IO).
+2. `POST /bot` → creates `User{type:"Bot", botToken, botRole, name:"Open Claudia"}`.
+3. Store `botToken` in open-claudia env (`KAZEE_BOT_TOKEN`) — never in code.
+
+### 3.2 Connect (open-claudia → chat-central)
+- Open Socket.IO V2 connection: `wss://<chat-central>/socket.io?version=v2` with `Authorization: Bearer bot_<token>`.
+- On connect: `GET /chats?userId=<botUserId>` → list of chats the bot is in.
+- Batch-join those chat rooms (same pattern web/mobile use).
+- Listen to `message:new`. Filter: ignore own messages, process DMs + group messages mentioning bot.
+
+### 3.3 Identity
+- Canonical user ID: `kazee:<userId>` (chat-central User._id).
+- Per-user transcripts: same isolation logic as Telegram — `projectHash` already userId-scoped.
+
+### 3.4 Send / edit / delete
+- Send: `POST /chat/:chatId/message` with `{content, type:"text"}` or `{type:"image", mediaIds}`.
+- Edit: there's no documented edit endpoint in the explore report; we either (a) add `PATCH /message/:id` to chat-central, or (b) skip in-place edits and just send a follow-up. **Recommend (a)** — chat already supports `edited` + `editHistory` in the model.
+- Delete: similar — likely needs a `DELETE /message/:id` action if not present. **Confirm in chat-central** before assuming.
+
+### 3.5 Voice / files
+- Receive: when `message:new` arrives with `type:"audio"`/`"voice"`, fetch media URL, download via REST, run Whisper (same as today's `transcribeAudio`).
+- Send file: `POST /chat/:chatId/media` (returns mediaId) → `POST /chat/:chatId/message` with `mediaIds:[id]`.
+
+### 3.6 Buttons / callback queries (the awkward gap)
+Telegram inline keyboards have no Kazee equivalent today. Used in open-claudia for: auth approval, project picker, model/backend/effort selection, session switcher, onboarding style, cron presets.
+
+Three options, ranked:
+1. **Recommended — add a `type:"interactive"` message kind to chat-central** with a `buttons:[{label, callbackId}]` field, plus a `message:action` socket event when a user clicks. Render natively in web + mobile. Reuses existing message infra. Highest UX quality.
+2. **Text-fallback** — bot sends `Reply with 1/2/3` style menus, parses replies. No frontend work, ugly UX, fragile when humans free-type.
+3. **Web-only mini-form** — bot embeds a special markdown block (`:::buttons[...]:::`), web/mobile parse and render. Lighter than (1), heavier than (2). Drifts from chat-central message model.
+
+Decision needed before implementation — flagging this as the biggest design choice.
+
+### 3.7 Markdown
+- Standard Markdown — react-markdown / react-native-markdown-display already render `**bold**`, `_italic_`, `` `code` ``, fenced code, lists. Bot's existing Telegram-Markdown output is mostly compatible; minor: Telegram uses `*bold*` (single asterisk). The adapter normalises asterisks on the way out.
+
+---
+
+## 4. Slash commands — UX across clients
+
+### 4.1 Server side (chat-central, new)
+- Add `commands: [{name, description, args:[{name, required}]}]` to `User` (for Bot type) or to `BotRole`. Prefer `BotRole.commands`.
+- New action: `GET /bot/:userId/commands` → returns the list.
+- Bot registers/updates its command list on startup via `PUT /botRole/:id/commands`.
+- Estimated effort: 1 model field, 2 actions, ~1 day in chat-central.
+
+### 4.2 Web (kazee-chat) — slash menu in `ChatInput.tsx`
+- TipTap extension or input-level handler that:
+  - Detects `/` as first character of an empty message.
+  - Calls `GET /bot/:botUserId/commands` if the other party is a Bot user.
+  - Shows a floating dropdown (same component family as mentions menu).
+  - On selection: inserts the slash command name, leaves cursor for args.
+- Caches command list per bot for the session.
+- Submit sends `content: "/cmd arg1 arg2"` as normal text — bot parses on its side.
+- Estimated effort: ~2 days.
+
+### 4.3 Mobile (kazee-chat-mobile) — slash menu in `ChatInputToolbar.tsx`
+- Same logic, RN implementation. Reuse the mentions autocomplete pattern that already exists.
+- Floating list above keyboard.
+- Estimated effort: ~2 days.
+
+### 4.4 Bot side (open-claudia)
+- Parse `/cmd args` from inbound text. `core/commands.js` registry already handles this — no Telegram dependency.
+- Same handlers work on both adapters.
+
+---
+
+## 5. Phased rollout
+
+**Phase 0 — prep (no behaviour change)**
+- Refactor `bot.js` to extract `core/commands.js`, `core/router.js`, `channels/telegram/`. All existing functionality goes through the new abstraction. Ship as v1.21.0. Verify Telegram still works.
+
+**Phase 1 — chat-central additions**
+- Add `BotRole.commands` field + `GET /bot/:id/commands`.
+- Add `PATCH /message/:id` (edit) + `DELETE /message/:id` (delete) actions, if not present.
+- Decision on interactive buttons (§3.6). If option 1 (new message type), spec + implement.
+
+**Phase 2 — kazee adapter**
+- Build `channels/kazee/index.js` in open-claudia.
+- Provision bot account in chat-central (dev env first).
+- Connect, listen, send text. Parity with Telegram for plain text + file + voice.
+- Ship as v1.22.0 behind `KAZEE_ENABLED=true` env flag.
+
+**Phase 3 — slash menu UX**
+- Web: slash menu in `ChatInput.tsx`.
+- Mobile: slash menu in `ChatInputToolbar.tsx`.
+- Bot registers its full command list (currently 35+).
+
+**Phase 4 — interactive buttons (if option 1 chosen)**
+- chat-central: `type:"interactive"` message + `message:action` event.
+- Web + mobile: render buttons in `MessageBubble`, emit action on tap.
+- Bot: emit interactive menus instead of text for auth/project/model selection.
+
+**Phase 5 — production**
+- Flip `KAZEE_ENABLED` on in prod.
+- Document onboarding: how a Kazee user starts a chat with Open Claudia and authenticates.
+
+---
+
+## 6. Onboarding flow (Kazee)
+
+1. User opens Kazee, searches for "Open Claudia" in users.
+2. Creates DM (existing flow: `createChat` with bot as participant).
+3. Bot receives `message:new` for the first message → triggers `/start`-equivalent: replies with auth instructions.
+4. Auth: same model as Telegram today (vault-stored credentials, OAuth flow). No changes — `canonicalUserId = kazee:<userId>` ensures isolation.
+5. Subsequent messages flow normally.
+
+---
+
+## 7. Risks & open questions
+
+| # | Risk | Mitigation |
+|---|---|---|
+| 1 | Edit/delete endpoints may not exist in chat-central today | Verify before Phase 1; add if missing |
+| 2 | Telegram inline keyboards have no equivalent — biggest design call | Decide §3.6 option before Phase 4 |
+| 3 | Markdown dialect drift (Telegram `*bold*` vs standard `**bold**`) | Normalise in `channels/telegram/format.js` and `channels/kazee/format.js` |
+| 4 | Long-message chunking (4KB Telegram limit) doesn't apply to Kazee | Move chunking into Telegram adapter only |
+| 5 | Voice transcription path coupled to TEMP_DIR + ffmpeg + whisper | Already path-based; just changes how media is fetched (REST vs Telegram API) |
+| 6 | Bot in group chats: noise if it processes every message | Only respond when @mentioned or in DM (chat-central `mentions[]` already supports this) |
+| 7 | Onboarding identity binding — how do we know which Kazee user is which workspace operator? | `/auth` flow stays the same; first message after `/auth` binds canonical user to bot state |
+
+---
+
+## 8. Work breakdown (rough)
+
+| Area | Effort | Owner |
+|---|---|---|
+| Phase 0 — bot.js refactor | 3-4 days | open-claudia |
+| Phase 1 — chat-central additions (commands list + edit/delete) | 2 days | chat-central |
+| Phase 2 — Kazee adapter (open-claudia) | 3 days | open-claudia |
+| Phase 3 — slash menu (web) | 2 days | kazee-chat |
+| Phase 3 — slash menu (mobile) | 2 days | kazee-chat-mobile |
+| Phase 4 — interactive buttons (optional but recommended) | 4 days across 3 repos | shared |
+| **Total core (Phases 0–3)** | **~12 days** | |
+| **With Phase 4** | **~16 days** | |
+
+---
+
+## 9. Decisions to lock before starting
+
+1. **Interactive buttons** — option 1, 2, or 3 from §3.6? Affects all three frontends and chat-central scope.
+2. **Bot scope in group chats** — DMs only initially, or mention-driven in groups too?
+3. **Command registration** — does bot register commands on every startup, or one-shot via ops script?
+4. **Edit/delete endpoints in chat-central** — confirm they exist; if not, add to Phase 1.
+5. **`KAZEE_ENABLED` flag** — env-flag rollout vs straight cutover.