@inetafrica/open-claudia 2.15.0 → 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/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.

package/docs/PROVIDER_MIGRATION.md

@@ -0,0 +1,67 @@
+# Provider migration snapshots and rollback
+
+Open Claudia takes a verified, byte-for-byte snapshot before any provider-aware state, session, or job schema is activated. At startup it then migrates and verifies all three stores before loading the vault, scheduler, router, or channel adapters. Direct and agent modes use the same modular `bot.js` runtime, so there is only one active state writer during this process.
+
+Snapshots live under the configured Open Claudia data directory:
+
+```text
+migration-backups/provider-parity-v1.1/snapshots/<timestamp-id>/
+  originals/
+  manifest.json
+  manifest.sha256
+```
+
+The allowlist contains `state.json`, `sessions.json`, `jobs.json`, legacy `crons.json`, an earlier `crons.json.migrated`, and relevant `.bak` siblings. It deliberately excludes `.env`, vault, authentication, identity, transcript, and derived SQLite files. The manifest records relative names, byte sizes, SHA-256 hashes, and advisory schema guesses; it never records source contents or absolute installation paths. Malformed and provider-ambiguous records are preserved as `unresolved` rather than assigned to Claude, Codex, or a project by guesswork. Removed-provider selections, settings, session pointers/history, and jobs are retained only in non-selectable or disabled archives; they are never reassigned to Claude or Codex and never fired.
+
+Snapshot directories are private operator data. They can contain conversation titles, prompts, native session identifiers, and scheduled-job text. Keep them mode `0700` with files mode `0600`; do not share, publish, or commit them.
+
+## Rollback procedure
+
+Rollback is an offline operation. Do not restore files while any Open Claudia process can write them.
+
+1. Stop every Open Claudia bot and scheduler process. Confirm no old or new runtime remains active.
+2. Identify the snapshot referenced by `migration-backups/provider-parity-v1.1/journal.json`. Do not select a partial orphan directory merely because its timestamp is newer.
+3. Validate the complete snapshot with `validateMigrationSnapshot(snapshotDir)`. A manifest mismatch, missing file, corrupt copy, symlink, or checksum failure blocks rollback before any live target changes.
+4. Call `rollbackMigrationSnapshot` from the installed Open Claudia package with the configured state/session/job/cron paths, as in the example below. The helper stages exact bytes, restores the complete allowlisted set, restores original absence where applicable, and verifies every target against the manifest.
+5. Validate the snapshot again and verify the restored live files with the same source list. Keep the snapshot; rollback never deletes it.
+6. If the restored files contain Cursor Agent state, restart the matching older Cursor-capable Open Claudia version. The current runtime intentionally cannot execute that provider. Otherwise restart the upgraded version only after its migration journal and schema expectations have been reviewed.
+
+Rollback restores the snapshot's exact pre-upgrade bytes. Post-upgrade changes are not merged into those older files and will be discarded by the restore. If those changes must be audited, make a separate private copy of the current files while every writer is stopped; never combine records from the two schema generations by hand.
+
+Example from a Node maintenance script run inside the installed package:
+
+```js
+const migration = require("./core/migration-backup");
+const config = require("./core/config");
+const configDir = config.CONFIG_DIR;
+const snapshotDir = process.env.OPEN_CLAUDIA_MIGRATION_SNAPSHOT;
+const sources = migration.defaultMigrationSources({
+  configDir,
+  stateFile: config.STATE_FILE,
+  sessionsFile: config.SESSIONS_FILE,
+  jobsFile: config.JOBS_FILE,
+  cronsFile: config.CRONS_FILE,
+});
+
+migration.validateMigrationSnapshot(snapshotDir);
+migration.rollbackMigrationSnapshot(snapshotDir, { configDir, sources });
+migration.validateMigrationSnapshot(snapshotDir, { sources, verifySources: true });
+```
+
+Never mark a migration globally activated after migrating only one store. The journal tracks `state`, `sessions`, and `jobs` separately and reaches `activated` only after all three component migrations have completed and verified their writes. Each component certificate records the live file's logical path, byte size, schema version, and SHA-256; readiness recomputes those values, so a legacy, corrupt, or subsequently replaced file cannot satisfy an old activation flag.
+
+Startup beyond the migration preflight is gated on that globally activated journal. A missing component, corrupt manifest, stale live-file proof, or partial migration blocks normal runtime initialization. After the gate, an old Cursor selection becomes an explicit “provider selection required” state; the user must choose Claude Code or OpenAI Codex with `/backend`. Old callbacks show a removal notice and do not mutate the provider, model, or session.
+
+Each component write is two-phase. Open Claudia records a `pendingComponents` entry against the verified pre-migration snapshot before the atomic live-file rename, validates the new schema after the rename, and only then marks that component activated. If the process stops between those steps, startup keeps the original snapshot pinned; the component migration must validate and finish the pending write instead of creating a mixed-schema replacement snapshot.
+
+Provider-blind conversation-history records are retained as non-selectable `legacy` entries unless exactly one provider adapter can prove ownership with a read-only probe. New history is keyed by canonical user, project, and provider. Chat buttons contain only short-lived opaque server-side tokens; provider-native session IDs are never embedded in callback payloads.
+
+Provider and project switches restore only that tuple's active conversation, while model, effort, budget, permission mode, and worktree choices remain scoped to the provider. `/new` clears the selected project's active pointer for the current provider only. `/end` closes the project selection and settles transient queued work without deleting provider pointers or conversation history.
+
+Compaction captures one immutable canonical-user/project/provider/session tuple. Summary and seed runs cannot persist ordinary transcripts, usage, or session pointers, and queued user turns remain paused until both stages settle. Claude seeds use its native one-turn limit in read-only plan mode. Codex seeds use a read-only sandbox plus a bounded JSON acknowledgement contract; they deliberately use a persistent compaction invocation instead of Codex's ephemeral utility flag because the resulting seed must remain resumable. No unsupported Codex `maxTurns` or complete tool-suppression claim is made.
+
+The pointer, provider-tagged history lineage, and tuple-scoped usage checkpoint are committed through a recoverable prepared/committed marker. Restart rolls a prepared operation back to the old pointer and history, while a committed marker is finalized without replaying history. Legacy usage-log records expose their existing `backend` as `provider` when read, without rewriting the original JSONL file.
+
+Scheduled work uses a versioned `{schemaVersion, jobs, archived}` document. Every runnable occurrence stores its canonical user, channel, project, provider, provider-settings snapshot, native session lineage, origin run, and stable occurrence ID. A fresh foreground turn can create a job before its native session is known; terminal session persistence binds that job by origin run ID. Compaction descendants are followed only when recorded lineage proves the relationship, and an older scheduled branch cannot replace an unrelated live session pointer.
+
+Wakeups and crons wait for terminal provider completion, transcript/usage/session persistence, and required delivery. A one-shot receives a durable success marker before deletion. Busy or failed occurrences retain their occurrence ID and bounded attempt state across restart; exhaustion and wakeups outside the missed-fire grace window remain visible as disabled dead letters. Provider fallback is empty by default. When `PROVIDER_FALLBACKS` is explicitly configured, a fallback starts a fresh provider session with an archived provider-neutral brief and never receives another provider's native session ID. Legacy `crons.json` remains byte-for-byte untouched after its ambiguous records are copied into the disabled archive.