@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/handlers.js

@@ -9,15 +9,21 @@ const { execSync } = require("child_process");
 const {
   WORKSPACE, FULL_PATH, AUTO_COMPACT_TOKENS, CONFIG_DIR,
   config, saveEnvKey,
-  CHAT_ID, DEFAULT_CLAUDE_MODEL, resolvedCursorPath, resolvedCodexPath, SOUL_FILE,
+  CHAT_ID, discoverProviderExecutable, SOUL_FILE,
 } = require("./config");
 const { register } = require("./commands");
 const { send, deleteMessage } = require("./io");
-const { currentState, resetSettings, resetSessionUsage, saveState, getProjectSessions, getLastProjectSession, recordSession, linkIdentity } = require("./state");
+const {
+  currentState, saveState,
+  freshUsage, getActiveProvider, getProviderSession, setProviderSession, clearProviderSession,
+  getProviderSettings,
+  getProjectSessions, getLastProjectSession, userOwnsProviderSession,
+  createSessionCallbackToken, linkIdentity,
+} = require("./state");
 const { canonicalForChannel, canonicalForTelegram, normalizeCanonicalUserId, channelKey, identities, isConfiguredOwnerChannel, removeIdentityMapping } = require("./identity");
 const { isChatAuthorized, isChatOwner, recordPendingAuthRequest, authRequestLabel, hasOwner, bootstrapOwner } = require("./access");
 const { isOnboarded, startOnboarding } = require("./onboarding");
-const { listProjects, findProject, projectKeyboard, workspacePath } = require("./projects");
+const { listProjects, findProject, projectKeyboard } = require("./projects");
 const { vault } = require("./vault-store");
 const keyring = require("./keyring");
 const { redactSensitive, registerSecrets } = require("./redact");
@@ -28,19 +34,21 @@ const scheduler = require("./scheduler");
 const skillsLib = require("./skills");
 const packsLib = require("./packs");
 const {
-  runClaude, compactActiveSession, getActiveSessionId, effectiveCompactThreshold,
+  admitRunContext, runAgent, compactActiveSession, getActiveSessionId, effectiveCompactThreshold,
 } = require("./runner");
 const {
-  getClaudeOAuthToken, claudeSubprocessEnv, saveClaudeOAuthToken,
+  getClaudeOAuthToken, saveClaudeOAuthToken,
   clearClaudeOAuthToken, looksLikeClaudeToken, looksLikeClaudeAuthReply,
   looksLikeOpenAIKey,
   isClaudeAuthErrorText,
   summarizeClaudeAuthStatus,
+  runClaudeAuthStatusDiagnostic,
   sendClaudeAuthStatusSummary,
   runClaudeAuthCommand, clearPendingClaudeAuth,
   sendCodexAuthStatusSummary, runCodexDeviceLogin, clearPendingCodexAuth,
-  saveCodexApiKeyWithCli, providerAuthStatus,
+  saveCodexApiKeyWithCli,
 } = require("./auth-flow");
+const providerRegistry = require("./providers");
 
 const CURRENT_VERSION = require(path.join(__dirname, "..", "package.json")).version;
 
@@ -60,8 +68,236 @@ function requireSession() {
   return true;
 }
 
-function startSession(name, resumeSessionId) {
+function cancelledQueueResult(item, reason) {
+  return {
+    ok: false,
+    status: "cancelled",
+    runId: item?.runContext?.runId || null,
+    provider: item?.runContext?.provider || null,
+    project: item?.runContext?.project || null,
+    error: { code: "SESSION_CONTEXT_CLEARED", message: reason },
+  };
+}
+
+function clearTransientQueue(state, reason = "Session context changed before the queued run started") {
+  const queued = Array.isArray(state?.messageQueue) ? state.messageQueue.splice(0) : [];
+  for (const item of queued) {
+    try { item?.deferred?.resolve(cancelledQueueResult(item, reason)); } catch (_) {}
+  }
+  return queued.length;
+}
+
+function persistSessionControl(state, options, rollback) {
+  if (options.persist === false) return { ok: true };
+  try {
+    saveState({ strict: true });
+    return { ok: true };
+  } catch (error) {
+    if (typeof rollback === "function") rollback();
+    return { ok: false, error };
+  }
+}
+
+function providerFromRegistry(providerId, registry = providerRegistry) {
+  try { return registry.getProvider(String(providerId || "").trim().toLowerCase()); }
+  catch (error) { return null; }
+}
+
+function providerAvailability(provider) {
+  try { return provider.isAvailable() === true; }
+  catch (_) { return false; }
+}
+
+const SETTING_CAPABILITY = Object.freeze({
+  effort: "effort",
+  budget: "budget",
+  worktree: "worktree",
+  permissionMode: "readOnlyMode",
+});
+
+function applyProviderSetting(state, providerId, setting, value, options = {}) {
+  const registry = options.registry || providerRegistry;
+  const provider = providerFromRegistry(providerId, registry);
+  if (!provider) {
+    return { ok: false, code: "UNKNOWN_PROVIDER", message: `Unknown provider: ${providerId}` };
+  }
+  if (options.requireActive && getActiveProvider(state) !== provider.id) {
+    return {
+      ok: false,
+      code: "STALE_PROVIDER_CONTROL",
+      message: `That ${provider.label} control is stale because another provider is active. Open the command again.`,
+    };
+  }
+  const capabilityName = SETTING_CAPABILITY[setting];
+  if (!capabilityName) {
+    return { ok: false, code: "UNKNOWN_PROVIDER_SETTING", message: `Unknown provider setting: ${setting}` };
+  }
+  const capability = provider.capabilities[capabilityName];
+  if (!capability || capability.support === "unsupported") {
+    return {
+      ok: false,
+      code: "UNSUPPORTED_PROVIDER_CAPABILITY",
+      message: capability?.reason || `${provider.label} does not support ${capabilityName}`,
+      providerId: provider.id,
+      capability: capabilityName,
+    };
+  }
+
+  let normalized = value;
+  if (setting === "effort") {
+    normalized = value == null || value === "default" ? null : String(value).trim().toLowerCase();
+    if (normalized && !capability.values.includes(normalized)) {
+      return {
+        ok: false,
+        code: "INVALID_PROVIDER_SETTING",
+        message: `${provider.label} effort must be one of: ${capability.values.join(", ")}`,
+      };
+    }
+  } else if (setting === "budget") {
+    if (value == null || value === "none" || value === "default") normalized = null;
+    else {
+      normalized = Number(value);
+      if (!Number.isFinite(normalized) || normalized <= 0) {
+        return { ok: false, code: "INVALID_PROVIDER_SETTING", message: "Budget must be a positive number or none." };
+      }
+    }
+  } else if (setting === "worktree") {
+    normalized = !!value;
+  } else if (setting === "permissionMode") {
+    normalized = value == null ? null : String(value).trim().toLowerCase();
+    if (normalized !== null && !new Set(["plan", "ask"]).has(normalized)) {
+      return { ok: false, code: "INVALID_PROVIDER_SETTING", message: "Read-only mode must be plan, ask, or off." };
+    }
+  }
+
+  const settings = state.providerSettings?.[provider.id] || getProviderSettings(state, provider.id);
+  const previous = settings[setting];
+  settings[setting] = normalized;
+  if (options.persist) {
+    try { saveState({ strict: true }); }
+    catch (error) {
+      settings[setting] = previous;
+      return { ok: false, code: "PROVIDER_SETTING_PERSIST_FAILED", message: error.message };
+    }
+  }
+  return {
+    ok: true,
+    code: null,
+    providerId: provider.id,
+    providerLabel: provider.label,
+    capability: capabilityName,
+    support: capability.support,
+    value: normalized,
+  };
+}
+
+function switchProviderState(providerId, options = {}) {
+  const state = options.state || currentState();
+  const provider = String(providerId || "").trim().toLowerCase();
+  if (!providerFromRegistry(provider, options.registry || providerRegistry)) {
+    return { ok: false, error: Object.assign(new Error(`Unknown provider: ${providerId}`), { code: "UNKNOWN_PROVIDER" }) };
+  }
+  const previous = {
+    provider: getActiveProvider(state),
+    activeSessions: structuredClone(state.activeSessions || {}),
+    providerSettings: structuredClone(state.providerSettings || {}),
+    isFirstMessage: state.isFirstMessage,
+  };
+  state.settings.backend = provider;
+  if (Object.prototype.hasOwnProperty.call(options, "model")) state.settings.model = options.model;
+  const project = state.currentSession?.name || null;
+  if (project && !getProviderSession(state, provider, project)) {
+    const last = getLastProjectSession(state.userId, project, provider);
+    if (last) setProviderSession(state, provider, project, last.id);
+  }
+  state.isFirstMessage = !getProviderSession(state, provider, project);
+  const persisted = persistSessionControl(state, options, () => {
+    state.activeSessions = previous.activeSessions;
+    state.providerSettings = previous.providerSettings;
+    state.settings.backend = previous.provider;
+    state.isFirstMessage = previous.isFirstMessage;
+  });
+  return persisted.ok
+    ? { ok: true, provider, sessionId: getProviderSession(state, provider, project), settings: state.providerSettings[provider] }
+    : persisted;
+}
+
+function selectProjectState(project, options = {}) {
+  const state = options.state || currentState();
+  if (!project || typeof project.name !== "string" || !project.name.trim()) {
+    return { ok: false, error: new TypeError("project name is required") };
+  }
+  const previous = {
+    currentSession: state.currentSession,
+    activeSessions: structuredClone(state.activeSessions || {}),
+    isFirstMessage: state.isFirstMessage,
+  };
+  clearTransientQueue(state, "Project changed before the queued run started");
+  state.currentSession = { name: project.name.trim(), dir: project.dir || null };
+  const provider = getActiveProvider(state);
+  const last = provider ? getLastProjectSession(state.userId, state.currentSession.name, provider) : null;
+  if (last) setProviderSession(state, provider, state.currentSession.name, last.id);
+  const sessionId = getProviderSession(state, provider, state.currentSession.name);
+  state.isFirstMessage = !sessionId;
+  const persisted = persistSessionControl(state, options, () => {
+    state.currentSession = previous.currentSession;
+    state.activeSessions = previous.activeSessions;
+    state.isFirstMessage = previous.isFirstMessage;
+  });
+  return persisted.ok ? { ok: true, provider, sessionId } : persisted;
+}
+
+function startNewConversation(options = {}) {
+  const state = options.state || currentState();
+  const project = state.currentSession?.name || null;
+  if (!project || (options.projectName && options.projectName !== project)) {
+    return { ok: false, error: Object.assign(new Error("The selected project changed"), { code: "STALE_PROJECT" }) };
+  }
+  const provider = getActiveProvider(state);
+  if (!provider) return { ok: false, error: Object.assign(new Error("Choose a provider with /backend first"), { code: "NO_ACTIVE_PROVIDER" }) };
+  const previous = {
+    activeSessions: structuredClone(state.activeSessions || {}),
+    usageBySession: structuredClone(state.usageBySession || {}),
+    isFirstMessage: state.isFirstMessage,
+  };
+  clearTransientQueue(state, "A new conversation started before the queued run began");
+  clearProviderSession(state, provider, project);
+  state.sessionUsage = freshUsage();
+  state.isFirstMessage = true;
+  const persisted = persistSessionControl(state, options, () => {
+    state.activeSessions = previous.activeSessions;
+    state.usageBySession = previous.usageBySession;
+    state.isFirstMessage = previous.isFirstMessage;
+  });
+  return persisted.ok ? { ok: true, provider, project } : persisted;
+}
+
+function endCurrentSession(options = {}) {
+  const state = options.state || currentState();
+  if (!state.currentSession) return { ok: false, error: Object.assign(new Error("No session"), { code: "NO_SESSION" }) };
+  const previous = { currentSession: state.currentSession, isFirstMessage: state.isFirstMessage };
+  const project = state.currentSession.name;
+  clearTransientQueue(state, "The project session ended before the queued run started");
+  state.currentSession = null;
+  state.isFirstMessage = true;
+  state.cancelRequested = false;
+  const persisted = persistSessionControl(state, options, () => {
+    state.currentSession = previous.currentSession;
+    state.isFirstMessage = previous.isFirstMessage;
+  });
+  return persisted.ok ? { ok: true, project } : persisted;
+}
+
+function activeContinueOptions(state = currentState()) {
+  const provider = getActiveProvider(state);
+  if (!provider) return null;
+  const sessionId = getProviderSession(state, provider, state.currentSession?.name);
+  return sessionId ? { provider, resumeSessionId: sessionId } : null;
+}
+
+function startSession(name, resumeSessionId, options = {}) {
   const state = currentState();
+  const provider = options.provider || getActiveProvider(state);
   let projectName, projectDir;
   if (name === "__workspace__") {
     projectName = "Workspace";
@@ -74,37 +310,49 @@ function startSession(name, resumeSessionId) {
     projectDir = path.join(WORKSPACE, result);
   }
 
-  state.currentSession = { name: projectName, dir: projectDir };
-  state.messageQueue = []; resetSettings(state);
+  if (!provider) return send("Choose Claude Code or OpenAI Codex with /backend before opening a project session.");
+
+  if (resumeSessionId && !userOwnsProviderSession(state.userId, projectName, provider, resumeSessionId)) {
+    return send("That conversation is unavailable for this project and provider. Open /sessions again.");
+  }
+
+  const selected = selectProjectState({ name: projectName, dir: projectDir }, { state, persist: false });
+  if (!selected.ok) return send(`Could not select project: ${selected.error.message}`);
 
   if (resumeSessionId) {
-    state.lastSessionId = resumeSessionId;
-    const sessions = getProjectSessions(state.userId, projectName);
-    const s = sessions.find((x) => x.id === resumeSessionId);
+    setProviderSession(state, provider, projectName, resumeSessionId);
+    const sessions = getProjectSessions(state.userId, projectName, provider);
+    const s = sessions.find((x) => x.id === resumeSessionId && x.provider === provider);
     const title = s ? s.title : "";
     state.isFirstMessage = false;
     saveState();
     send(`Session: ${projectName}\nResumed: ${title || resumeSessionId.slice(0, 8)}\n\nSend text, voice, or images.\n\n/sessions — switch conversation\n/session — switch project`);
   } else {
-    const last = getLastProjectSession(state.userId, projectName);
+    const last = getLastProjectSession(state.userId, projectName, provider);
     if (last) {
-      state.lastSessionId = last.id;
+      setProviderSession(state, provider, projectName, last.id);
       state.isFirstMessage = false;
       saveState();
       send(`Session: ${projectName}\nResumed: ${last.title}\n\nSend text, voice, or images.\n\n/sessions — switch conversation\n/session — switch project`, {
         keyboard: { inline_keyboard: [[{ text: "New conversation", callback_data: `new:${projectName}` }]] },
       });
     } else {
-      state.lastSessionId = null;
-      state.isFirstMessage = true;
+      const existing = getProviderSession(state, provider, projectName);
+      state.isFirstMessage = !existing;
       saveState();
-      send(`Session: ${projectName}\n\nSend text, voice, or images.\n\n/sessions — switch conversation\n/session — switch project`);
+      send(`Session: ${projectName}${existing ? `\nResumed: ${existing.slice(0, 8)}` : ""}\n\nSend text, voice, or images.\n\n/sessions — switch conversation\n/session — switch project`);
     }
   }
 }
 
 // Make startSession reachable for the action router.
 module.exports.startSession = startSession;
+module.exports.clearTransientQueue = clearTransientQueue;
+module.exports.switchProviderState = switchProviderState;
+module.exports.selectProjectState = selectProjectState;
+module.exports.startNewConversation = startNewConversation;
+module.exports.endCurrentSession = endCurrentSession;
+module.exports.activeContinueOptions = activeContinueOptions;
 
 // ── Registry ────────────────────────────────────────────────────────
 
@@ -610,78 +858,100 @@ register({
     if (!authorized(env)) return;
     if (!requireSession()) return;
     const state = currentState();
-    const sessions = getProjectSessions(state.userId, state.currentSession.name);
+    const provider = getActiveProvider(state);
+    if (!provider) return send("Choose Claude Code or OpenAI Codex with /backend first.");
+    const project = state.currentSession.name;
+    const sessions = getProjectSessions(state.userId, project, provider)
+      .filter((session) => session.selectable !== false);
     if (sessions.length === 0) return send("No past conversations for this project.");
     const rows = sessions.slice(0, 10).map((s) => {
       const date = new Date(s.lastUsed).toLocaleDateString();
-      const active = state.lastSessionId === s.id ? " (active)" : "";
-      return [{ text: `${s.title}${active} — ${date}`, callback_data: `ss:${s.id}` }];
+      const active = getProviderSession(state, provider, project) === s.id ? " (active)" : "";
+      const token = createSessionCallbackToken({
+        userId: state.userId,
+        project,
+        provider: s.provider,
+        sessionId: s.id,
+      });
+      return [{
+        text: `${s.title}${active} · ${s.provider} · ${project} — ${date}`,
+        callback_data: `ss:${token}`,
+      }];
     });
     rows.push([{ text: "New conversation", callback_data: `new:${state.currentSession.name}` }]);
     send(`Conversations in ${state.currentSession.name}:`, { keyboard: { inline_keyboard: rows } });
   },
 });
 
-// Shared model picker used by /model and the unified /login. When authAware is
-// set, the provider section headers show connection status so the user knows a
-// tap on an unconnected provider will start its auth flow (handled in the mb:
-// callback in actions.js).
-function buildModelPicker({ authAware = false } = {}) {
-  const { settings } = currentState();
-  const auth = authAware ? providerAuthStatus() : null;
-  const mark = (ok) => authAware ? (ok ? " · connected" : " · tap to connect") : "";
+function buildBackendPicker({ state = currentState(), registry = providerRegistry } = {}) {
+  const activeProvider = getActiveProvider(state);
+  const entries = registry.listProviders().map((provider) => ({
+    id: provider.id,
+    label: provider.label,
+    available: providerAvailability(provider),
+    active: provider.id === activeProvider,
+  }));
+  return {
+    entries,
+    activeProvider,
+    rows: [entries.map((entry) => ({
+      text: `${entry.active ? "✓ " : ""}${entry.label}${entry.available ? "" : " · unavailable"}`,
+      callback_data: `be:${entry.id}`,
+    }))],
+  };
+}
+
+// Shared model picker used by /model and the unified /login. Provider names,
+// models, defaults, and auth markers all come from the registry contract.
+function buildModelPicker({ authAware = false, state = currentState(), registry = providerRegistry } = {}) {
   const rows = [];
-  rows.push([{ text: `── Claude${mark(auth && auth.claude)} ──`, callback_data: "noop" }]);
-  rows.push([
-    { text: "Fable 5", callback_data: "mb:claude:claude-fable-5" },
-    { text: "Opus 4.8", callback_data: "mb:claude:claude-opus-4-8" },
-  ]);
-  rows.push([
-    { text: "Opus 4.7", callback_data: "mb:claude:claude-opus-4-7" },
-    { text: "Opus 4.6", callback_data: "mb:claude:claude-opus-4-6" },
-  ]);
-  rows.push([
-    { text: "Sonnet 4.6", callback_data: "mb:claude:claude-sonnet-4-6" },
-    { text: "Haiku", callback_data: "mb:claude:claude-haiku-4-5-20251001" },
-  ]);
-  if (resolvedCursorPath) {
-    rows.push([{ text: "── Cursor ──", callback_data: "noop" }]);
-    rows.push([
-      { text: "Composer 2", callback_data: "mb:cursor:composer-2" },
-      { text: "Composer 2 Fast", callback_data: "mb:cursor:composer-2-fast" },
-      { text: "Auto", callback_data: "mb:cursor:auto" },
-    ]);
-    rows.push([
-      { text: "Opus 4.6 Thinking", callback_data: "mb:cursor:claude-4.6-opus-high-thinking" },
-      { text: "GPT-5.4", callback_data: "mb:cursor:gpt-5.4-medium" },
-    ]);
+  for (const provider of registry.listProviders()) {
+    let authMarker = "";
+    if (authAware) {
+      let connected = false;
+      try { connected = provider.authStatus().state === "authenticated"; } catch (_) {}
+      authMarker = connected ? " · connected" : " · tap to connect";
+    }
+    const availableMarker = providerAvailability(provider) ? "" : " · unavailable";
+    rows.push([{ text: `── ${provider.label}${availableMarker}${authMarker} ──`, callback_data: "noop" }]);
+    const choices = provider.modelChoices();
+    for (let index = 0; index < choices.length; index += 3) {
+      rows.push(choices.slice(index, index + 3).map((model) => ({
+        text: model,
+        callback_data: `mb:${provider.id}:${model}`,
+      })));
+    }
+    const defaultModel = provider.defaultModel();
+    rows.push([{
+      text: `Default${defaultModel ? ` (${defaultModel})` : ""}`,
+      callback_data: `mb:${provider.id}:default`,
+    }]);
   }
-  if (resolvedCodexPath) {
-    rows.push([{ text: `── Codex${mark(auth && auth.codex)} ──`, callback_data: "noop" }]);
-    rows.push([
-      { text: "GPT-5.5", callback_data: "mb:codex:gpt-5.5" },
-      { text: "gpt-5", callback_data: "mb:codex:gpt-5" },
-      { text: "gpt-5-codex", callback_data: "mb:codex:gpt-5-codex" },
-    ]);
-    rows.push([
-      { text: "o3", callback_data: "mb:codex:o3" },
-      { text: "o4-mini", callback_data: "mb:codex:o4-mini" },
-    ]);
-  }
-  rows.push([{ text: `Default (Claude: ${DEFAULT_CLAUDE_MODEL})`, callback_data: "m:default" }]);
-  const beLabel = settings.backend === "cursor" ? "Cursor" : settings.backend === "codex" ? "Codex" : "Claude";
-  return { rows, beLabel, model: settings.model };
+  const active = providerFromRegistry(getActiveProvider(state), registry);
+  const settings = active ? getProviderSettings(state, active.id) : { model: null };
+  return {
+    rows,
+    beLabel: active?.label || "No provider selected",
+    model: settings.model,
+  };
 }
 
+module.exports.buildBackendPicker = buildBackendPicker;
+module.exports.buildModelPicker = buildModelPicker;
+module.exports.applyProviderSetting = applyProviderSetting;
+
 register({
-  name: "model", description: "Switch model (opus/sonnet/haiku)", args: "[<model>]",
+  name: "model", description: "Switch model for the active provider", args: "[<model>]",
   handler: async (env, { tail }) => {
     if (!authorized(env)) return;
     if (tail) {
-      const { settings } = currentState();
-      settings.model = tail.toLowerCase();
-      if (settings.model === "default") settings.model = null;
-      return send(`Model: ${settings.model || "default"}`);
+      const state = currentState();
+      const provider = providerFromRegistry(getActiveProvider(state));
+      if (!provider) return send("Choose an available provider with /backend first.");
+      const settings = getProviderSettings(state, provider.id);
+      settings.model = tail.trim().toLowerCase() === "default" ? null : tail.trim();
+      saveState();
+      return send(`${provider.label} model: ${settings.model || provider.defaultModel() || "provider default"}`);
     }
     const { rows, beLabel, model } = buildModelPicker();
     send(`Current: ${beLabel} · ${model || "default"}\n\nPick a model — backend switches automatically.\nOr type /model <name>.`, { keyboard: { inline_keyboard: rows } });
@@ -689,22 +959,25 @@ register({
 });
 
 register({
-  name: "effort", description: "Set effort level", args: "[low|medium|high|max]",
+  name: "effort", description: "Set provider effort level", args: "[<level>|default]",
   handler: async (env, { tail }) => {
     if (!authorized(env)) return;
-    const { settings } = currentState();
-    if (settings.backend === "cursor") return send("Effort levels are not supported on Cursor Agent.\nSwitch to Claude with /claude to use this.");
-    if (settings.backend === "codex") return send("Effort levels are not exposed as a flag on Codex.\nSet `model_reasoning_effort` in ~/.codex/config.toml, or switch to /claude.");
+    const state = currentState();
+    const provider = providerFromRegistry(getActiveProvider(state));
+    if (!provider) return send("Choose an available provider with /backend first.");
+    const settings = getProviderSettings(state, provider.id);
+    const capability = provider.capabilities.effort;
+    if (capability.support === "unsupported") return send(capability.reason);
     if (tail) {
-      const e = tail.toLowerCase();
-      settings.effort = ["low", "medium", "high", "max"].includes(e) ? e : null;
-      return send(`Effort: ${settings.effort || "default"}`);
-    }
-    send(`Effort: ${settings.effort || "default"}`, {
-      keyboard: { inline_keyboard: [
-        [{ text: "Low", callback_data: "e:low" }, { text: "Med", callback_data: "e:medium" }, { text: "High", callback_data: "e:high" }, { text: "Max", callback_data: "e:max" }],
-        [{ text: "Default", callback_data: "e:default" }],
-      ] },
+      const result = applyProviderSetting(state, provider.id, "effort", tail, { requireActive: true, persist: true });
+      return send(result.ok ? `${provider.label} effort: ${result.value || "default"}` : result.message);
+    }
+    const buttons = capability.values.map((value) => ({ text: value, callback_data: `e:${provider.id}:${value}` }));
+    const rows = [];
+    for (let index = 0; index < buttons.length; index += 4) rows.push(buttons.slice(index, index + 4));
+    rows.push([{ text: "Default", callback_data: `e:${provider.id}:default` }]);
+    send(`${provider.label} effort: ${settings.effort || "default"}`, {
+      keyboard: { inline_keyboard: rows },
     });
   },
 });
@@ -808,52 +1081,49 @@ register({
   name: "budget", description: "Set max spend for next task", args: "[$N]",
   handler: async (env, { tail }) => {
     if (!authorized(env)) return;
-    const { settings } = currentState();
-    if (settings.backend === "cursor") return send("Budget limits are not supported on Cursor Agent.\nSwitch to Claude with /claude to use this.");
-    if (settings.backend === "codex") return send("Budget limits are not supported on Codex.\nSwitch to Claude with /claude to use this.");
+    const state = currentState();
+    const provider = providerFromRegistry(getActiveProvider(state));
+    if (!provider) return send("Choose an available provider with /backend first.");
+    const capability = provider.capabilities.budget;
+    if (capability.support === "unsupported") return send(capability.reason);
+    const settings = getProviderSettings(state, provider.id);
     if (tail) {
-      const v = parseFloat(tail.replace("$", ""));
-      settings.budget = v > 0 ? v : null;
-      return send(`Budget: ${settings.budget ? "$" + settings.budget : "none"}`);
+      const value = tail.trim().toLowerCase() === "none" ? null : tail.replace("$", "");
+      const result = applyProviderSetting(state, provider.id, "budget", value, { requireActive: true, persist: true });
+      return send(result.ok ? `${provider.label} budget: ${result.value ? "$" + result.value : "none"}` : result.message);
     }
-    send(`Budget: ${settings.budget ? "$" + settings.budget : "none"}`, {
+    send(`${provider.label} budget: ${settings.budget ? "$" + settings.budget : "none"}`, {
       keyboard: { inline_keyboard: [
-        [{ text: "$1", callback_data: "b:1" }, { text: "$5", callback_data: "b:5" }, { text: "$10", callback_data: "b:10" }, { text: "$25", callback_data: "b:25" }],
-        [{ text: "No limit", callback_data: "b:none" }],
+        [{ text: "$1", callback_data: `b:${provider.id}:1` }, { text: "$5", callback_data: `b:${provider.id}:5` }, { text: "$10", callback_data: `b:${provider.id}:10` }, { text: "$25", callback_data: `b:${provider.id}:25` }],
+        [{ text: "No limit", callback_data: `b:${provider.id}:none` }],
       ] },
     });
   },
 });
 
+async function toggleReadOnlyMode(env, mode) {
+  if (!authorized(env)) return;
+  const state = currentState();
+  const provider = providerFromRegistry(getActiveProvider(state));
+  if (!provider) return send("Choose an available provider with /backend first.");
+  const settings = getProviderSettings(state, provider.id);
+  const next = settings.permissionMode === mode ? null : mode;
+  const result = applyProviderSetting(state, provider.id, "permissionMode", next, { requireActive: true, persist: true });
+  if (!result.ok) return send(result.message);
+  const label = mode === "ask" ? "Read-only Q&A" : "Plan mode";
+  return send(next === null
+    ? `${label} off.`
+    : `${label} on for ${provider.label} (${result.support}).`);
+}
+
 register({
-  name: "plan", description: "Toggle plan mode",
-  handler: async (env) => {
-    if (!authorized(env)) return;
-    const state = currentState();
-    const { settings } = state;
-    const p = settings.permissionMode === "plan";
-    settings.permissionMode = p ? null : "plan";
-    const label = settings.backend === "cursor" ? "read-only planning, no edits"
-      : settings.backend === "codex" ? "read-only sandbox, no edits"
-      : "plan permission mode";
-    if (p) {
-      if (settings.backend === "cursor") state.cursorSessionId = null;
-      else if (settings.backend === "codex") state.codexSessionId = null;
-    }
-    send(p ? "Plan mode off (session reset)." : `Plan mode on (${label}).`);
-  },
+  name: "plan", description: "Toggle read-only planning",
+  handler: async (env) => toggleReadOnlyMode(env, "plan"),
 });
 
 register({
-  name: "ask", description: "Toggle ask mode (Cursor only)",
-  handler: async (env) => {
-    if (!authorized(env)) return;
-    const { settings } = currentState();
-    if (settings.backend !== "cursor") return send("Ask mode is only available on Cursor Agent.\nUse /cursor to switch.");
-    const a = settings.permissionMode === "ask";
-    settings.permissionMode = a ? null : "ask";
-    send(a ? "Ask mode off." : "Ask mode on (read-only Q&A, no edits).");
-  },
+  name: "ask", description: "Toggle read-only Q&A",
+  handler: async (env) => toggleReadOnlyMode(env, "ask"),
 });
 
 register({
@@ -875,13 +1145,28 @@ register({
   },
 });
 
+register({
+  name: "new", description: "Start a new conversation for this provider",
+  handler: async (env) => {
+    if (!authorized(env)) return;
+    if (!requireSession()) return;
+    const result = startNewConversation();
+    if (!result.ok) return send(`Could not start a new conversation: ${result.error.message}`);
+    return send(`Session: ${result.project}\nNew ${result.provider} conversation\n\nSend text, voice, or images.`);
+  },
+});
+
 register({
   name: "continue", description: "Resume last conversation",
   handler: async (env) => {
     if (!authorized(env)) return;
     if (!requireSession()) return;
-    if (!getActiveSessionId()) return send("No conversation to continue.");
-    await runClaude("continue where we left off", currentState().currentSession.dir, env.messageId);
+    const state = currentState();
+    const continuation = activeContinueOptions(state);
+    if (!continuation) return send("No conversation to continue.");
+    const prompt = "continue where we left off";
+    const runContext = admitRunContext(prompt, state.currentSession.dir, env.messageId, continuation);
+    return runAgent(prompt, runContext.cwd, env.messageId, { runContext, ...continuation });
   },
 });
 
@@ -941,65 +1226,60 @@ register({
   name: "worktree", description: "Toggle isolated git branch",
   handler: async (env) => {
     if (!authorized(env)) return;
-    const { settings } = currentState();
-    settings.worktree = !settings.worktree;
-    send(settings.worktree ? "Worktree on." : "Worktree off.");
-  },
-});
-
-register({
-  name: "cursor", description: "Switch to Cursor Agent backend",
-  handler: async (env) => {
-    if (!authorized(env)) return;
-    if (!resolvedCursorPath) return send("Cursor Agent CLI not found.\nSet CURSOR_PATH in .env or install: https://docs.cursor.com/agent");
     const state = currentState();
-    state.settings.backend = "cursor";
-    state.settings.model = null;
-    saveState();
-    const sid = state.cursorSessionId ? `\nSession: ${state.cursorSessionId.slice(0, 8)}...` : "\nNew session.";
-    send(`Switched to Cursor Agent.${sid}\n\n/claude — switch back · /codex — Codex`);
+    const provider = providerFromRegistry(getActiveProvider(state));
+    if (!provider) return send("Choose an available provider with /backend first.");
+    const settings = getProviderSettings(state, provider.id);
+    const result = applyProviderSetting(state, provider.id, "worktree", !settings.worktree, { requireActive: true, persist: true });
+    send(result.ok ? `${provider.label} worktree ${result.value ? "on" : "off"}.` : result.message);
   },
 });
 
+async function switchProviderCommand(env, providerId) {
+  if (!authorized(env)) return;
+  const provider = providerFromRegistry(providerId);
+  if (!provider) return send(`Unknown provider: ${providerId}`);
+  if (!providerAvailability(provider)) {
+    return send(`${provider.label} is unavailable. Install its CLI or configure its path, then run /doctor.`);
+  }
+  const state = currentState();
+  const switched = switchProviderState(provider.id, { state });
+  if (!switched.ok) return send(`Could not switch provider: ${switched.error.message}`);
+  const session = switched.sessionId ? `\nSession: ${switched.sessionId.slice(0, 8)}...` : "\nNew session.";
+  return send(`Switched to ${provider.label}.${session}`);
+}
+
 register({
-  name: "claude", description: "Switch to Claude Code backend",
-  handler: async (env) => {
-    if (!authorized(env)) return;
-    const state = currentState();
-    state.settings.backend = "claude";
-    state.settings.model = null;
-    saveState();
-    const sid = state.lastSessionId ? `\nSession: ${state.lastSessionId.slice(0, 8)}...` : "\nNew session.";
-    send(`Switched to Claude Code.${sid}\n\n/cursor — Cursor · /codex — Codex`);
-  },
+  name: "claude", description: "Switch to Claude Code provider",
+  handler: async (env) => switchProviderCommand(env, "claude"),
 });
 
 register({
-  name: "codex", description: "Switch to OpenAI Codex backend",
-  handler: async (env) => {
-    if (!authorized(env)) return;
-    if (!resolvedCodexPath) return send("Codex CLI not found.\nInstall: npm install -g @openai/codex\nThen run `codex login` to authenticate.");
-    const state = currentState();
-    state.settings.backend = "codex";
-    state.settings.model = null;
-    saveState();
-    const sid = state.codexSessionId ? `\nSession: ${state.codexSessionId.slice(0, 8)}...` : "\nNew session.";
-    send(`Switched to Codex.${sid}\n\n/claude — Claude · /cursor — Cursor`);
-  },
+  name: "codex", description: "Switch to OpenAI Codex provider",
+  handler: async (env) => switchProviderCommand(env, "codex"),
 });
 
 register({
-  name: "backend", description: "Show/switch active backend",
-  handler: async (env) => {
+  name: "backend", description: "Show/switch active provider", args: "[claude|codex]",
+  handler: async (env, { tail }) => {
     if (!authorized(env)) return;
-    const { settings } = currentState();
-    const label = settings.backend === "cursor" ? "Cursor Agent" : settings.backend === "codex" ? "Codex" : "Claude Code";
-    const cursorAvail = resolvedCursorPath ? "available" : "not found";
-    const codexAvail = resolvedCodexPath ? "available" : "not found";
-    send(`Backend: ${label}\n\nClaude Code: available\nCursor Agent: ${cursorAvail}\nCodex: ${codexAvail}`, {
-      keyboard: { inline_keyboard: [
-        [{ text: "Claude Code", callback_data: "be:claude" }, { text: "Cursor Agent", callback_data: "be:cursor" }, { text: "Codex", callback_data: "be:codex" }],
-      ] },
+    if (tail) {
+      const provider = tail.trim().toLowerCase();
+      const descriptor = providerFromRegistry(provider);
+      if (!descriptor) return send(`Usage: /backend [${providerRegistry.listProviders().map((entry) => entry.id).join("|")}]`);
+      if (!providerAvailability(descriptor)) return send(`${descriptor.label} is unavailable. Run /doctor for recovery steps.`);
+      const switched = switchProviderState(descriptor.id);
+      if (!switched.ok) return send(`Could not switch provider: ${switched.error.message}`);
+      return send(`Switched to ${descriptor.label}.${switched.sessionId ? `\nSession: ${switched.sessionId.slice(0, 8)}...` : "\nNew session."}`);
+    }
+    const picker = buildBackendPicker();
+    const active = providerFromRegistry(picker.activeProvider);
+    send([
+      `Provider: ${active?.label || "none"}`,
+      "",
+      ...picker.entries.map((entry) => `${entry.label}: ${entry.available ? "available" : "unavailable"}`),
+    ].join("\n"), {
+      keyboard: { inline_keyboard: picker.rows },
     });
   },
 });
@@ -1008,9 +1288,11 @@ register({
   name: "mode", description: "Bot mode (direct/agent)",
   handler: async (env) => {
     if (!authorized(env)) return;
-    await send("Bot mode: *direct* (default)\n\nSwitch to agent mode for non-blocking execution.\nIn agent mode, heavy tasks run in the background and you can keep chatting.", {
+    const mode = require("./side-chat").readRuntimeMode(CONFIG_DIR);
+    const target = mode === "agent" ? "direct" : "agent";
+    await send(`Bot mode: ${mode}\n\nBoth modes use the same modular runtime. Agent mode gives one isolated, read-only side response while a heavy main task runs; direct mode queues follow-up messages.`, {
       parseMode: "HTML",
-      keyboard: { inline_keyboard: [[{ text: "Switch to Agent Mode", callback_data: "mode:agent" }]] },
+      keyboard: { inline_keyboard: [[{ text: `Switch to ${target} mode`, callback_data: `mode:${target}` }]] },
     });
   },
 });
@@ -1020,6 +1302,7 @@ register({
   handler: async (env) => {
     if (!authorized(env)) return;
     const state = currentState();
+    const sideCancellation = require("./side-chat").sideChatCoordinator.cancel(state.userId);
     if (state.runningProcess) {
       const pid = state.runningProcess.pid;
       const { killProcessTree } = require("./process-tree");
@@ -1029,15 +1312,18 @@ register({
       if (state.streamInterval) clearTimeout(state.streamInterval);
       if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
       state.messageQueue = [];
+      await sideCancellation;
       await send("Cancelled.");
     } else if (state.preparingRun) {
       // Turn is mid-recall/compaction — no process to kill yet. Flag it so
-      // runClaude bails at its pre-spawn checkpoint, and stop typing now.
+      // runAgent bails at its pre-spawn checkpoint, and stop typing now.
       state.cancelRequested = true;
       state.messageQueue = [];
       if (state.typingHeartbeat) { clearInterval(state.typingHeartbeat); state.typingHeartbeat = null; }
+      await sideCancellation;
       await send("Cancelled.");
-    } else await send("Nothing running.");
+    } else if (await sideCancellation) await send("Cancelled side response.");
+    else await send("Nothing running.");
   },
 });
 
@@ -1045,7 +1331,9 @@ register({
   name: "doctor", aliases: ["requirements"], description: "Check CLI requirements",
   handler: async (env) => {
     if (!authorized(env)) return;
-    await send(formatDoctorReport(runDoctorChecks()));
+    // Includes the live Codex tool-hook probe (a real, short codex exec turn)
+    // — /doctor is the only surface that opts in.
+    await send(formatDoctorReport(runDoctorChecks({ probeCodexHook: true })));
   },
 });
 
@@ -1054,15 +1342,22 @@ register({
   handler: async (env) => {
     if (!authorized(env)) return;
     const state = currentState();
-    if (!state.currentSession) return send("No session.", { keyboard: { inline_keyboard: [[{ text: "Pick", callback_data: "show:projects" }]] } });
-    const { settings } = state;
-    const backendLabel = settings.backend === "cursor" ? "Cursor Agent" : settings.backend === "codex" ? "Codex" : "Claude Code";
+    const provider = providerFromRegistry(getActiveProvider(state));
+    const settings = provider ? getProviderSettings(state, provider.id) : null;
     const cronCount = jobs.listForChannel(env.adapter.id, env.channelId).filter((j) => j.kind === "cron").length;
-    const activeEngine = require("./recall").activeEngineName(settings) + (settings.recallEngine ? "" : " (default)");
+    const commonSettings = state.settings;
+    const activeEngine = require("./recall").activeEngineName(commonSettings) + (commonSettings.recallEngine ? "" : " (default)");
+    const capabilitySummary = provider
+      ? ["readOnlyMode", "effort", "budget", "worktree"].map((name) => {
+          const capability = provider.capabilities[name];
+          return `${name === "readOnlyMode" ? "read-only" : name} ${capability.support}`;
+        }).join(" · ")
+      : "none";
     send([
-      `Project: ${state.currentSession.name}`,
-      `Backend: ${backendLabel}`,
-      `Model: ${settings.model || "default"} | Effort: ${settings.effort || "default"}`,
+      `Project: ${state.currentSession?.name || "none"}`,
+      `Provider: ${provider?.label || "none"}`,
+      `Model: ${settings?.model || provider?.defaultModel() || "default"} | Effort: ${settings?.effort || "default"}`,
+      `Capabilities: ${capabilitySummary}`,
       `Recall engine: ${activeEngine}`,
       `Auto-compact: ${formatCompactWindow(state)}`,
       `Vault: ${vault.isUnlocked() ? "unlocked" : "locked"} | Crons: ${cronCount}`,
@@ -1077,14 +1372,9 @@ register({
     if (!authorized(env)) return;
     const state = currentState();
     if (state.currentSession) {
-      const n = state.currentSession.name;
-      state.currentSession = null;
-      state.lastSessionId = null;
-      state.messageQueue = [];
-      resetSettings(state);
-      resetSessionUsage(state);
-      saveState();
-      send(`Ended: ${n}`, { keyboard: { inline_keyboard: [[{ text: "New session", callback_data: "show:projects" }]] } });
+      const result = endCurrentSession({ state });
+      if (!result.ok) return send(`Could not end session: ${result.error.message}`);
+      send(`Ended: ${result.project}`, { keyboard: { inline_keyboard: [[{ text: "New session", callback_data: "show:projects" }]] } });
     } else send("No session.");
   },
 });
@@ -1281,7 +1571,9 @@ register({
       `CRUCIAL — also crystallise the EXECUTABLE part: if the work involved a script, API call, or any repeatable command sequence you wrote inline (a heredoc, a one-off .py/.sh, a curl chain), turn it into a reusable tool instead of leaving it to be re-typed. Write the script to a file (parameterise the bits that vary; read any credential from the env as $NAME rather than hardcoding), then register it with 'open-claudia tool add <path> --pack <dir> --desc "..." [--requires "key1,key2"] [--usage "..."]', linking it to the pack you just touched. Reference creds by their keyring names (see 'open-claudia keyring list'); never write a secret into the tool. The tool is the runnable form of the pack's Procedure — save both. ` +
       `No secrets or tokens in packs OR tools. When done, reply with one short line naming the pack you created or updated, any tool you saved, and what it covers. ` +
       `If the recent work is genuinely not reusable, say so instead of forcing a skill.`;
-    await runClaude(prompt, currentState().currentSession.dir, env.messageId);
+    const state = currentState();
+    const runContext = admitRunContext(prompt, state.currentSession.dir, env.messageId, { purpose: "learn" });
+    return runAgent(prompt, runContext.cwd, env.messageId, { runContext, purpose: "learn" });
   },
 });
 
@@ -1291,32 +1583,19 @@ register({
   name: "auth_status", aliases: ["auth status"], description: "Check Claude Code auth",
   handler: async (env) => {
     if (!authorized(env)) return;
-    const { spawn } = require("child_process");
-    const { CLAUDE_PATH } = require("./config");
     const tokenInfo = getClaudeOAuthToken();
-    const proc = spawn(CLAUDE_PATH, ["auth", "status"], {
-      cwd: process.env.HOME || require("os").homedir(),
-      env: claudeSubprocessEnv(),
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let output = "";
-    proc.stdout.on("data", (d) => { output += d.toString(); });
-    proc.stderr.on("data", (d) => { output += d.toString(); });
-    await new Promise((resolve) => {
-      proc.on("close", async (code) => {
-        const clean = redactSensitive(output.trim()) || "(no output)";
-        await send([
-          `Claude auth status: exit ${code}`,
-          ...summarizeClaudeAuthStatus(output, code, tokenInfo),
-          `Bot OAuth token: ${tokenInfo.value ? "configured via " + tokenInfo.source : "not configured"}`,
-          `Vault: ${vault.isUnlocked() ? "unlocked" : "locked"}`,
-          "",
-          clean.slice(-2500),
-        ].join("\n"));
-        resolve();
-      });
-      proc.on("error", async (err) => { await send(`Claude auth status failed: ${redactSensitive(err.message)}`); resolve(); });
-    });
+    const status = providerRegistry.providerStatus("claude");
+    const output = runClaudeAuthStatusDiagnostic();
+    const code = status.availability.state !== "available" ? 127 : (status.auth.state === "unauthenticated" ? 1 : 0);
+    const clean = redactSensitive(output.trim()) || "(no output)";
+    await send([
+      `Claude auth status: exit ${code}`,
+      ...summarizeClaudeAuthStatus(output, code, tokenInfo),
+      `Bot OAuth token: ${tokenInfo.value ? "configured via " + tokenInfo.source : "not configured"}`,
+      `Vault: ${vault.isUnlocked() ? "unlocked" : "locked"}`,
+      "",
+      clean.slice(-2500),
+    ].join("\n"));
   },
 });
 
@@ -1432,7 +1711,7 @@ register({
   name: "codex_setup_token", aliases: ["codex_use_api_key"], description: "Save an OpenAI API key", args: "[<key>]", ownerOnly: true,
   handler: async (env, { tail }) => {
     if (!ownerEnv(env)) return send("Owner only — Codex auth is shared across users.");
-    if (!resolvedCodexPath) return send("Codex CLI not found. Install: npm install -g @openai/codex");
+    if (!discoverProviderExecutable("codex")) return send("Codex CLI not found. Install: npm install -g @openai/codex");
     const key = (tail || "").trim();
     await deleteMessage(env.messageId);
     if (!key) {
@@ -1606,17 +1885,24 @@ register({
   handler: async (env, { tail }) => {
     if (!authorized(env)) return;
     const channelJobs = () => jobs.listForChannel(env.adapter.id, env.channelId).filter((j) => j.kind === "cron");
+    const archivedNote = () => {
+      const archived = jobs.listArchived().filter((j) => !j.channelId || String(j.channelId) === String(env.channelId));
+      if (archived.length === 0) return "";
+      const shown = archived.slice(0, 5).map((j) => `• ${j.label || j.id} — ${j.archiveReason || "archived"}`);
+      const more = archived.length > 5 ? `\n…and ${archived.length - 5} more (open-claudia cron-list shows all).` : "";
+      return `\n\n⚠️ Disabled by provider migration (will not fire):\n${shown.join("\n")}${more}`;
+    };
     if (!tail) {
       const list = channelJobs();
       if (list.length === 0) {
-        return send("No crons.\n\nAdd: /cron add \"<schedule>\" <project> \"<prompt>\"\n\nOr pick a preset:", {
+        return send("No crons." + archivedNote() + "\n\nAdd: /cron add \"<schedule>\" <project> \"<prompt>\"\n\nOr pick a preset:", {
           keyboard: { inline_keyboard: [
             [{ text: "Standup 9am", callback_data: "cp:standup" }, { text: "Git digest 6pm", callback_data: "cp:git" }],
             [{ text: "Dep check Mon", callback_data: "cp:deps" }, { text: "Health 30min", callback_data: "cp:health" }],
           ] },
         });
       }
-      return send("Crons:\n\n" + list.map((c, i) => `${i + 1}. ${c.label} (${c.schedule}) — ${c.project || ""}`).join("\n") + "\n\nRemove: /cron remove <#>");
+      return send("Crons:\n\n" + list.map((c, i) => `${i + 1}. ${c.label} (${c.schedule}) — ${c.project || ""}`).join("\n") + archivedNote() + "\n\nRemove: /cron remove <#>");
     }
 
     const addMatch = tail.match(/^add\s+"(.+)"\s+(\S+)\s+"(.+)"$/);