@inetafrica/open-claudia 1.20.0 → 2.0.0

package/core/auth-flow.js

@@ -0,0 +1,433 @@
+// Claude/Codex login state machines and helpers. The actual handler
+// commands (/login, /setup_token, /codex_login, …) live in
+// core/handlers; this module owns the heavy lifting they call into.
+
+const fs = require("fs");
+const { spawn, execSync } = require("child_process");
+const {
+  config, saveEnvKey,
+  CLAUDE_PATH, resolvedCodexPath,
+  botSubprocessEnv,
+} = require("./config");
+const { vault } = require("./vault-store");
+const { redactSensitive, stripTerminalControls, extractUrls } = require("./redact");
+const { send } = require("./io");
+const { currentState } = require("./state");
+
+const CLAUDE_OAUTH_TOKEN_KEY = "CLAUDE_CODE_OAUTH_TOKEN";
+const CLAUDE_OAUTH_VAULT_KEY = "claude_oauth_token";
+
+function getClaudeOAuthToken() {
+  if (config[CLAUDE_OAUTH_TOKEN_KEY]) return { value: config[CLAUDE_OAUTH_TOKEN_KEY], source: ".env" };
+  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) return { value: process.env.CLAUDE_CODE_OAUTH_TOKEN, source: "process env" };
+  if (vault.isUnlocked()) {
+    const value = vault.get(CLAUDE_OAUTH_VAULT_KEY) || vault.get(CLAUDE_OAUTH_TOKEN_KEY);
+    if (value) return { value, source: "vault" };
+  }
+  return { value: null, source: null };
+}
+
+function claudeSubprocessEnv() {
+  const env = botSubprocessEnv();
+  const token = getClaudeOAuthToken().value;
+  if (token) env.CLAUDE_CODE_OAUTH_TOKEN = token;
+  return env;
+}
+
+function saveClaudeOAuthToken(token) {
+  const clean = String(token || "").trim();
+  if (!clean) return false;
+  saveEnvKey(CLAUDE_OAUTH_TOKEN_KEY, clean);
+  config[CLAUDE_OAUTH_TOKEN_KEY] = clean;
+  process.env.CLAUDE_CODE_OAUTH_TOKEN = clean;
+  if (vault.isUnlocked()) vault.set(CLAUDE_OAUTH_VAULT_KEY, clean);
+  return true;
+}
+
+function clearClaudeOAuthToken() {
+  saveEnvKey(CLAUDE_OAUTH_TOKEN_KEY, "");
+  config[CLAUDE_OAUTH_TOKEN_KEY] = "";
+  delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
+  if (vault.isUnlocked()) {
+    vault.remove(CLAUDE_OAUTH_VAULT_KEY);
+    vault.remove(CLAUDE_OAUTH_TOKEN_KEY);
+  }
+}
+
+function extractClaudeToken(text) {
+  const match = String(text || "").match(/sk-ant-[A-Za-z0-9._-]+/);
+  return match ? match[0] : null;
+}
+
+function looksLikeClaudeToken(value) {
+  const text = String(value || "").trim();
+  return /^sk-ant-[A-Za-z0-9._-]+$/.test(text) || (text.length >= 80 && /^[A-Za-z0-9._=-]+$/.test(text));
+}
+
+function looksLikeClaudeAuthReply(value) {
+  const text = String(value || "").trim();
+  if (!text) return false;
+  if (looksLikeClaudeToken(text)) return true;
+  if (/^https?:\/\//i.test(text) && /claude|anthropic/i.test(text)) return true;
+  if (text.length >= 24 && !/\s/.test(text) && /^[A-Za-z0-9._~:/?#[\]@!$&'()*+,;=%-]+$/.test(text)) return true;
+  return false;
+}
+
+function isClaudeAuthUrl(url) {
+  try {
+    const u = new URL(url);
+    const host = u.hostname.toLowerCase();
+    return host === "claude.com" || host.endsWith(".claude.com") ||
+      host === "anthropic.com" || host.endsWith(".anthropic.com") ||
+      host === "localhost" || host === "127.0.0.1";
+  } catch (e) {
+    return false;
+  }
+}
+
+function looksLikeOpenAIKey(value) {
+  return /^sk-(?:proj-)?[A-Za-z0-9._-]{20,}$/.test(String(value || "").trim());
+}
+
+function isClaudeAuthErrorText(text) {
+  const lower = String(text || "").toLowerCase();
+  return lower.includes("unauthorized") ||
+    lower.includes("not logged in") ||
+    lower.includes("login required") ||
+    lower.includes("reauthenticate") ||
+    lower.includes("re-authenticate") ||
+    lower.includes("authentication failed") ||
+    lower.includes("auth failed") ||
+    lower.includes("invalid api key") ||
+    (lower.includes("api key") && lower.includes("invalid")) ||
+    (lower.includes("keychain") && (lower.includes("unlock") || lower.includes("could not") || lower.includes("failed"))) ||
+    lower.includes("security unlock-keychain");
+}
+
+function isClaudeUsageLimitText(text) {
+  const lower = String(text || "").toLowerCase();
+  return lower.includes("usage limit") ||
+    lower.includes("you've hit your usage limit") ||
+    lower.includes("you have hit your usage limit") ||
+    lower.includes("spend limit") ||
+    lower.includes("monthly cycle") ||
+    (lower.includes("rate limit") && lower.includes("model"));
+}
+
+function isCodexAuthErrorText(text) {
+  return /not (?:logged in|authenticated)|unauthenticated|login required|please (?:log|sign) in|401 unauthorized|invalid api key|no credentials/i.test(String(text || ""));
+}
+
+function summarizeAuthOutput(output, ok) {
+  const clean = redactSensitive(stripTerminalControls(output || "")).replace(/\s+/g, " ").trim();
+  if (!clean) return ok ? "ok" : "no output";
+  return clean.length > 160 ? clean.slice(0, 157) + "..." : clean;
+}
+
+function summarizeClaudeAuthStatus(output, exitCode, tokenInfo) {
+  const text = String(output || "");
+  const lower = text.toLowerCase();
+  const loggedOut = /not (logged in|authenticated)|unauthenticated|no auth|login required/.test(lower);
+  const loggedIn = !loggedOut && (exitCode === 0 || /logged in|authenticated|claude\.ai|anthropic/.test(lower));
+  const email = (text.match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i) || [null])[0];
+  const provider = /claude\.ai|claudeai/.test(lower) ? "Claude.ai" : (/anthropic/.test(lower) ? "Anthropic" : "unknown");
+  let method = tokenInfo.value ? `OAuth token (${tokenInfo.source})` : "unknown";
+  if (/api key|apikey/.test(lower)) method = "API key";
+  else if (/oauth|claude\.ai|claudeai/.test(lower)) method = tokenInfo.value ? `OAuth token (${tokenInfo.source})` : "OAuth/Claude.ai";
+  return [
+    `Logged in: ${loggedIn ? "yes" : (loggedOut ? "no" : "unknown")}`,
+    `Auth method: ${method}`,
+    `Email: ${email || "unknown"}`,
+    `Provider: ${provider}`,
+  ];
+}
+
+function claudeAuthRecoveryMessage(reason = "Claude Code authentication failed") {
+  const tokenInfo = getClaudeOAuthToken();
+  const tokenLine = tokenInfo.value
+    ? `Stored OAuth token: yes (${tokenInfo.source})`
+    : "Stored OAuth token: no";
+  return [
+    `Claude auth needs attention: ${redactSensitive(reason)}`,
+    "",
+    tokenLine,
+    "",
+    "Try one of these from chat:",
+    "1. /auth_status — check what Claude sees",
+    "2. /setup_token — create a long-lived Claude Code token, then store it",
+    "3. /use_oauth_token — paste the token securely if you already generated one",
+    "4. /login — interactive Claude.ai browser login fallback",
+    "",
+    "If this is a macOS Keychain problem after SSH/reboot, run on the Mac:",
+    "security unlock-keychain",
+    "",
+    "Recommended for this bot: /setup_token + /use_oauth_token so launchd does not depend on Keychain.",
+  ].join("\n");
+}
+
+function claudeUsageLimitMessage(details = "") {
+  return [
+    "Claude ran, but the selected model is unavailable/limited right now.",
+    details ? `\nDetails:\n${redactSensitive(details)}` : "",
+    "",
+    "Try from chat:",
+    "1. /model sonnet",
+    "2. Then send your message again",
+    "",
+    "If you specifically need Opus, wait for the usage window to reset or increase the spend/usage limit.",
+  ].filter(Boolean).join("\n");
+}
+
+function runClaudeAuthStatusDiagnostic() {
+  try {
+    const output = execSync(`"${CLAUDE_PATH}" auth status`, {
+      cwd: process.env.HOME || require("os").homedir(),
+      env: claudeSubprocessEnv(),
+      encoding: "utf8",
+      timeout: 10000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return output.trim();
+  } catch (e) {
+    return `${e.stdout || ""}\n${e.stderr || ""}\n${e.message || ""}`.trim();
+  }
+}
+
+async function sendClaudeAuthStatusSummary(prefix = "Claude auth status") {
+  const output = runClaudeAuthStatusDiagnostic();
+  const tokenInfo = getClaudeOAuthToken();
+  const lines = summarizeClaudeAuthStatus(output, isClaudeAuthErrorText(output) ? 1 : 0, tokenInfo);
+  await send([
+    prefix,
+    "",
+    ...lines,
+    `Bot OAuth token: ${tokenInfo.value ? "configured via " + tokenInfo.source : "not configured"}`,
+  ].join("\n"));
+}
+
+function clearPendingClaudeAuth(state = currentState()) {
+  if (state.pendingClaudeAuthProcess && state.pendingClaudeAuthProcess.kill) {
+    try { state.pendingClaudeAuthProcess.kill("SIGTERM"); } catch (e) {}
+  }
+  state.pendingClaudeAuthProcess = null;
+  state.pendingClaudeAuthLabel = null;
+}
+
+async function runClaudeAuthCommand(args, label, opts = {}) {
+  const state = currentState();
+  if (state.pendingClaudeAuthProcess) {
+    await send(`Another Claude auth flow is already running (${state.pendingClaudeAuthLabel}). Send the requested code/token or wait for it to finish.`);
+    return;
+  }
+  await send(`${label} started...`);
+  const proc = spawn(CLAUDE_PATH, args, {
+    cwd: process.env.HOME || require("os").homedir(),
+    env: claudeSubprocessEnv(),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  state.pendingClaudeAuthProcess = proc;
+  state.pendingClaudeAuthLabel = label;
+  let output = "";
+  let sentUrls = new Set();
+  let tokenStored = false;
+  let lastSnippetAt = 0;
+
+  const handleChunk = async (chunk) => {
+    output += chunk;
+    const token = opts.captureToken ? extractClaudeToken(chunk) || extractClaudeToken(output) : null;
+    if (token && !tokenStored) {
+      tokenStored = saveClaudeOAuthToken(token);
+      await send(tokenStored ? "Claude OAuth token captured and stored. I did not print it." : "Claude OAuth token appeared, but I could not store it.");
+    }
+    for (const url of extractUrls(chunk)) {
+      if (!isClaudeAuthUrl(url)) continue;
+      if (!sentUrls.has(url)) {
+        sentUrls.add(url);
+        await send(`${label} URL:\n${redactSensitive(url)}\n\nOpen it, complete the flow, then paste any code Claude asks for here.`);
+      }
+    }
+    const redacted = redactSensitive(stripTerminalControls(chunk)).trim();
+    const now = Date.now();
+    const usefulAuthLine = /opening browser|paste code|enter code|login|auth|token|error|failed/i.test(redacted);
+    if (redacted && usefulAuthLine && now - lastSnippetAt > 3000 && !looksLikeClaudeToken(redacted) && !/github\.com\/vadimdemedes\/ink/i.test(redacted)) {
+      lastSnippetAt = now;
+      await send(redacted.length > 1200 ? redacted.slice(-1200) : redacted);
+    }
+  };
+
+  proc.stdout.on("data", (d) => handleChunk(d.toString()).catch((e) => console.error("Auth output error:", e.message)));
+  proc.stderr.on("data", (d) => handleChunk(d.toString()).catch((e) => console.error("Auth stderr error:", e.message)));
+  proc.on("close", async (code) => {
+    state.pendingClaudeAuthProcess = null;
+    state.pendingClaudeAuthLabel = null;
+    const token = opts.captureToken ? extractClaudeToken(output) : null;
+    if (token && !tokenStored) tokenStored = saveClaudeOAuthToken(token);
+    const cleaned = redactSensitive(stripTerminalControls(output))
+      .replace(/https?:\/\/github\.com\/vadimdemedes\/ink\S*/gi, "")
+      .trim();
+    const isTtyError = /raw mode is not supported|process\.stdin/i.test(output);
+    if (tokenStored) {
+      await send(`${label} finished. OAuth token stored for launchd/non-interactive Claude runs.`);
+      await sendClaudeAuthStatusSummary("Post-auth check:");
+    } else if (isTtyError && opts.captureToken) {
+      await send(`${label} cannot complete from this bot — the Claude CLI needs an interactive terminal for setup-token.\n\nRun this in your Mac terminal:\n  claude setup-token\n\nThen paste the token here with:\n  /use_oauth_token <token>`);
+    } else if (cleaned) {
+      await send(`${label} finished (exit ${code}).\n\n${cleaned.slice(-2500)}`);
+      await sendClaudeAuthStatusSummary("Post-auth check:");
+    } else {
+      await send(`${label} finished (exit ${code}).`);
+      await sendClaudeAuthStatusSummary("Post-auth check:");
+    }
+  });
+  proc.on("error", async (err) => {
+    state.pendingClaudeAuthProcess = null;
+    state.pendingClaudeAuthLabel = null;
+    await send(`${label} failed: ${redactSensitive(err.message)}`);
+  });
+}
+
+// ── Codex ──────────────────────────────────────────────────────────
+
+function clearPendingCodexAuth(state = currentState()) {
+  if (state.pendingCodexAuthProcess && state.pendingCodexAuthProcess.kill) {
+    try { state.pendingCodexAuthProcess.kill("SIGTERM"); } catch (e) {}
+  }
+  state.pendingCodexAuthProcess = null;
+  state.pendingCodexAuthLabel = null;
+}
+
+function runCommand(command, args = [], opts = {}) {
+  try {
+    const out = execSync([command, ...args].map((v) => `"${String(v).replace(/"/g, '\\"')}"`).join(" "), {
+      cwd: opts.cwd || process.env.HOME || require("os").homedir(),
+      env: opts.env || botSubprocessEnv(),
+      encoding: "utf-8",
+      timeout: opts.timeout || 10000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, output: out.trim(), code: 0 };
+  } catch (e) {
+    return { ok: false, output: `${e.stdout || ""}\n${e.stderr || ""}\n${e.message || ""}`.trim(), code: e.status ?? 1 };
+  }
+}
+
+function runCodexLoginStatus() {
+  if (!resolvedCodexPath) return { ok: false, code: 1, output: "Codex CLI not found" };
+  const result = runCommand(resolvedCodexPath, ["login", "status"], { timeout: 12000 });
+  return { ...result, ok: result.ok && !isCodexAuthErrorText(result.output) };
+}
+
+async function sendCodexAuthStatusSummary(prefix = "Codex auth status") {
+  const status = runCodexLoginStatus();
+  const version = resolvedCodexPath ? runCommand(resolvedCodexPath, ["--version"]) : { ok: false, output: "not found" };
+  await send([
+    prefix,
+    "",
+    `CLI: ${resolvedCodexPath ? "found" : "not found"}`,
+    `Version: ${summarizeAuthOutput(version.output, version.ok)}`,
+    `Logged in: ${status.ok ? "yes" : "no/unknown"}`,
+    `Status: ${summarizeAuthOutput(status.output, status.ok)}`,
+    status.ok ? "" : "Next: /codex_login for device auth, or /codex_setup_token to paste an OpenAI API key securely.",
+  ].filter(Boolean).join("\n"));
+}
+
+async function saveCodexApiKeyWithCli(apiKey) {
+  return new Promise((resolve) => {
+    const proc = spawn(resolvedCodexPath, ["login", "--with-api-key"], {
+      cwd: process.env.HOME || require("os").homedir(),
+      env: botSubprocessEnv(),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let output = "";
+    proc.stdout.on("data", (d) => { output += d.toString(); });
+    proc.stderr.on("data", (d) => { output += d.toString(); });
+    proc.on("close", (code) => resolve({ ok: code === 0, code, output }));
+    proc.on("error", (err) => resolve({ ok: false, code: 1, output: err.message }));
+    proc.stdin.write(apiKey.trim() + "\n");
+    proc.stdin.end();
+  });
+}
+
+async function runCodexDeviceLogin() {
+  const state = currentState();
+  if (!resolvedCodexPath) return send("Codex CLI not found. Install: npm install -g @openai/codex");
+  if (state.pendingCodexAuthProcess) return send(`Another Codex auth flow is already running (${state.pendingCodexAuthLabel}). Send /cancel_codex_auth to cancel.`);
+  await send("Codex device login started. I'll send the URL/code if the CLI prints one.");
+  const proc = spawn(resolvedCodexPath, ["login", "--device-auth"], {
+    cwd: process.env.HOME || require("os").homedir(),
+    env: botSubprocessEnv(),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  state.pendingCodexAuthProcess = proc;
+  state.pendingCodexAuthLabel = "Codex device login";
+  let output = "";
+  let sent = new Set();
+  let lastSnippetAt = 0;
+  const handleChunk = async (chunk) => {
+    output += chunk;
+    const cleanChunk = redactSensitive(stripTerminalControls(chunk));
+    for (const url of extractUrls(cleanChunk)) {
+      if (!sent.has(url)) {
+        sent.add(url);
+        await send(`Codex login URL:\n${redactSensitive(url)}\n\nOpen it and enter the device code if shown.`);
+      }
+    }
+    const codeMatch = cleanChunk.match(/(?:code|device code)[:\s]+([A-Z0-9-]{6,})/i);
+    if (codeMatch && !sent.has(codeMatch[1])) {
+      sent.add(codeMatch[1]);
+      await send(`Codex device code: ${codeMatch[1]}`);
+    }
+    const now = Date.now();
+    if (cleanChunk.trim() && /device|code|login|browser|open|auth|token|error|failed|api key/i.test(cleanChunk) && now - lastSnippetAt > 3000) {
+      lastSnippetAt = now;
+      await send(cleanChunk.trim().slice(-1200));
+    }
+  };
+  proc.stdout.on("data", (d) => handleChunk(d.toString()).catch((e) => console.error("Codex auth output error:", e.message)));
+  proc.stderr.on("data", (d) => handleChunk(d.toString()).catch((e) => console.error("Codex auth stderr error:", e.message)));
+  proc.on("close", async (code) => {
+    state.pendingCodexAuthProcess = null;
+    state.pendingCodexAuthLabel = null;
+    const clean = redactSensitive(stripTerminalControls(output)).trim();
+    if (/raw mode is not supported|not a tty|inappropriate ioctl/i.test(clean)) {
+      await send("Codex device login could not complete inside the bot on this host. Use /codex_setup_token to paste an OpenAI API key securely, or run `codex login --device-auth` in an SSH/terminal session.");
+    } else if (clean) await send(`Codex login finished (exit ${code}).\n\n${clean.slice(-2000)}`);
+    else await send(`Codex login finished (exit ${code}).`);
+    await sendCodexAuthStatusSummary("Post-Codex-auth check:");
+  });
+  proc.on("error", async (err) => {
+    state.pendingCodexAuthProcess = null;
+    state.pendingCodexAuthLabel = null;
+    await send(`Codex login failed: ${redactSensitive(err.message)}`);
+  });
+}
+
+module.exports = {
+  CLAUDE_OAUTH_TOKEN_KEY, CLAUDE_OAUTH_VAULT_KEY,
+  getClaudeOAuthToken,
+  claudeSubprocessEnv,
+  saveClaudeOAuthToken,
+  clearClaudeOAuthToken,
+  extractClaudeToken,
+  looksLikeClaudeToken,
+  looksLikeClaudeAuthReply,
+  isClaudeAuthUrl,
+  looksLikeOpenAIKey,
+  isClaudeAuthErrorText,
+  isClaudeUsageLimitText,
+  isCodexAuthErrorText,
+  summarizeAuthOutput,
+  summarizeClaudeAuthStatus,
+  claudeAuthRecoveryMessage,
+  claudeUsageLimitMessage,
+  runClaudeAuthStatusDiagnostic,
+  sendClaudeAuthStatusSummary,
+  runClaudeAuthCommand,
+  clearPendingClaudeAuth,
+  clearPendingCodexAuth,
+  runCommand,
+  runCodexLoginStatus,
+  sendCodexAuthStatusSummary,
+  saveCodexApiKeyWithCli,
+  runCodexDeviceLogin,
+};

package/core/channel-wizard.js

@@ -0,0 +1,174 @@
+// Interactive wizard for /channel add kazee.
+//
+// State machine keyed by canonicalUserId. The router checks isAwaiting()
+// before dispatching slash commands or media handlers, so once a user
+// enters the wizard their next plain-text message becomes the wizard's
+// input. A Cancel button (payload "chw:cancel") bails out at any step.
+//
+// validateKazee() is exported separately so setup.js can reuse the same
+// /me probe without going through the chat-driven flow.
+
+const { saveEnvKey, config } = require("./config");
+const { send, deleteMessage } = require("./io");
+const { publicCommands } = require("./commands");
+const registry = require("./adapter-registry");
+const { validateKazee } = require("./kazee-probe");
+
+const sessions = new Map(); // canonicalUserId -> session
+
+function isAwaiting(canonicalUserId) {
+  const s = sessions.get(canonicalUserId);
+  return !!s && s.step !== "idle";
+}
+
+function getSession(canonicalUserId) {
+  return sessions.get(canonicalUserId) || null;
+}
+
+function endSession(canonicalUserId) {
+  sessions.delete(canonicalUserId);
+}
+
+const cancelKeyboard = { inline_keyboard: [[{ text: "Cancel", callback_data: "chw:cancel" }]] };
+
+async function start(canonicalUserId, kind) {
+  if (kind !== "kazee") {
+    await send(`Channel type "${kind}" not supported yet.`);
+    return;
+  }
+  sessions.set(canonicalUserId, { kind: "kazee", step: "awaiting-url", data: {} });
+  await send(
+    "Add a Kazee channel.\n\nStep 1 of 3: Kazee bot API URL (e.g. https://chat.example.com/api).",
+    { keyboard: cancelKeyboard },
+  );
+}
+
+async function cancel(canonicalUserId, { silent } = {}) {
+  if (!sessions.has(canonicalUserId)) return;
+  sessions.delete(canonicalUserId);
+  if (!silent) await send("Channel setup cancelled.");
+}
+
+async function handleText(envelope) {
+  const session = sessions.get(envelope.canonicalUserId);
+  if (!session) return;
+  const text = (envelope.text || "").trim();
+
+  if (session.step === "awaiting-url") {
+    if (!/^https?:\/\//i.test(text)) {
+      await send("That doesn't look like a URL. Try again, or hit Cancel.", { keyboard: cancelKeyboard });
+      return;
+    }
+    session.data.url = text.replace(/\/$/, "");
+    session.step = "awaiting-token";
+    await send(
+      "Step 2 of 3: Kazee bot token. I'll delete your message after reading.",
+      { keyboard: cancelKeyboard },
+    );
+    return;
+  }
+
+  if (session.step === "awaiting-token") {
+    await deleteMessage(envelope.messageId);
+    if (!text) {
+      await send("Empty token. Try again, or hit Cancel.", { keyboard: cancelKeyboard });
+      return;
+    }
+    session.data.token = text;
+    session.step = "validating";
+    await send("Validating against the Kazee API…");
+    const check = await validateKazee({ url: session.data.url, token: session.data.token });
+    if (!check.ok) {
+      sessions.delete(envelope.canonicalUserId);
+      await send(`Validation failed: ${check.error}\n\nRun /channel add kazee to try again.`);
+      return;
+    }
+    session.data.botUserId = check.botUserId || "";
+    session.step = "awaiting-owner";
+    await send(
+      `Step 3 of 3: Kazee user id that should be treated as the owner (or send "skip" to leave blank).`,
+      { keyboard: cancelKeyboard },
+    );
+    return;
+  }
+
+  if (session.step === "awaiting-owner") {
+    const ownerUserId = text.toLowerCase() === "skip" ? "" : text;
+    session.data.ownerUserId = ownerUserId;
+    session.step = "applying";
+    await applySession(envelope.canonicalUserId, session);
+    return;
+  }
+}
+
+async function handleAction(envelope) {
+  const payload = envelope.action?.payload || envelope.action?.buttonId || "";
+  if (payload !== "chw:cancel") return false;
+  await cancel(envelope.canonicalUserId);
+  return true;
+}
+
+async function applySession(canonicalUserId, session) {
+  const { url, token, ownerUserId } = session.data;
+
+  // Capture rollback state so we can undo .env changes if the adapter
+  // refuses to start.
+  const previous = {
+    KAZEE_URL: config.KAZEE_URL || "",
+    KAZEE_BOT_TOKEN: config.KAZEE_BOT_TOKEN || "",
+    KAZEE_OWNER_USER_ID: config.KAZEE_OWNER_USER_ID || "",
+    CHANNELS: config.CHANNELS || "telegram",
+  };
+
+  saveEnvKey("KAZEE_URL", url);
+  saveEnvKey("KAZEE_BOT_TOKEN", token);
+  saveEnvKey("KAZEE_OWNER_USER_ID", ownerUserId);
+
+  const channels = previous.CHANNELS.split(",").map((s) => s.trim()).filter(Boolean);
+  if (!channels.some((c) => c === "kazee" || c.startsWith("kazee:"))) {
+    channels.push("kazee");
+  }
+  const newChannels = channels.join(",");
+  saveEnvKey("CHANNELS", newChannels);
+
+  // Refresh in-process view so subsequent loadChannels() sees the new
+  // values without a restart.
+  config.KAZEE_URL = url;
+  config.KAZEE_BOT_TOKEN = token;
+  config.KAZEE_OWNER_USER_ID = ownerUserId;
+  config.CHANNELS = newChannels;
+
+  const result = await registry.addAdapter(
+    { id: "kazee", type: "kazee", opts: { url, token, ownerUserId } },
+    { publicCommands: publicCommands() },
+  );
+
+  if (!result.ok) {
+    // Roll the .env back so the next bot start doesn't crash-loop.
+    saveEnvKey("KAZEE_URL", previous.KAZEE_URL);
+    saveEnvKey("KAZEE_BOT_TOKEN", previous.KAZEE_BOT_TOKEN);
+    saveEnvKey("KAZEE_OWNER_USER_ID", previous.KAZEE_OWNER_USER_ID);
+    saveEnvKey("CHANNELS", previous.CHANNELS);
+    config.KAZEE_URL = previous.KAZEE_URL;
+    config.KAZEE_BOT_TOKEN = previous.KAZEE_BOT_TOKEN;
+    config.KAZEE_OWNER_USER_ID = previous.KAZEE_OWNER_USER_ID;
+    config.CHANNELS = previous.CHANNELS;
+    sessions.delete(canonicalUserId);
+    await send(`Could not start the Kazee adapter: ${result.error}\n\nReverted .env. Run /channel add kazee to try again.`);
+    return;
+  }
+
+  sessions.delete(canonicalUserId);
+  await send("Kazee channel added and live.");
+}
+
+module.exports = {
+  isAwaiting,
+  getSession,
+  endSession,
+  start,
+  cancel,
+  handleText,
+  handleAction,
+  validateKazee,
+};

package/core/commands.js

@@ -0,0 +1,73 @@
+// Slash-command registry. Replaces the spray of bot.onText() handlers.
+// Each entry declares metadata (so adapters can register the slash menu)
+// + a handler. Both adapters dispatch through one parser → one handler
+// per command.
+
+const _commands = [];
+
+function register(spec) {
+  if (!spec || !spec.name) throw new Error("command needs a name");
+  if (!spec.handler && !spec.match) throw new Error(`command ${spec.name} needs a handler or match()`);
+  const entry = {
+    name: String(spec.name).replace(/^\//, ""),
+    aliases: (spec.aliases || []).map((a) => String(a).replace(/^\//, "")),
+    description: spec.description || "",
+    args: spec.args || "",
+    hidden: !!spec.hidden,
+    ownerOnly: !!spec.ownerOnly,
+    authRequired: spec.authRequired !== false,
+    pattern: spec.pattern || null,            // optional regex if you need richer parsing
+    match: spec.match || null,                // (text, envelope) → falsy or { args, regexMatch }
+    handler: spec.handler,
+  };
+  _commands.push(entry);
+  return entry;
+}
+
+function list() {
+  return _commands.slice();
+}
+
+// Public-facing command list for adapter.registerCommands(). Hides
+// internal-only entries and the regex-matched variants that share a
+// canonical name.
+function publicCommands() {
+  const seen = new Set();
+  const out = [];
+  for (const c of _commands) {
+    if (c.hidden) continue;
+    if (seen.has(c.name)) continue;
+    seen.add(c.name);
+    out.push({ name: c.name, description: c.description, args: c.args });
+  }
+  return out;
+}
+
+// Dispatch incoming text. Returns { matched: true } if a command ran.
+async function dispatch(text, envelope) {
+  const trimmed = String(text || "").trim();
+  if (!trimmed.startsWith("/")) return { matched: false };
+  const space = trimmed.indexOf(" ");
+  const cmdRaw = (space >= 0 ? trimmed.slice(1, space) : trimmed.slice(1)).toLowerCase();
+  const tail = space >= 0 ? trimmed.slice(space + 1).trim() : "";
+  // Strip @botname suffix Telegram appends in groups (kept for safety).
+  const cmd = cmdRaw.split("@")[0];
+
+  for (const c of _commands) {
+    if (c.name !== cmd && !c.aliases.includes(cmd)) continue;
+    let matchInfo = null;
+    if (c.pattern) {
+      const m = trimmed.match(c.pattern);
+      if (!m) continue;
+      matchInfo = m;
+    } else if (c.match) {
+      matchInfo = c.match(trimmed, envelope);
+      if (!matchInfo) continue;
+    }
+    await c.handler(envelope, { tail, args: tail ? tail.split(/\s+/) : [], match: matchInfo });
+    return { matched: true, command: c };
+  }
+  return { matched: false };
+}
+
+module.exports = { register, list, publicCommands, dispatch };