mouaif 0.3.0

package/src/server-handlers-access.js

@@ -0,0 +1,306 @@
+'use strict';
+
+// App access authentication REST handlers. Extracted from the original
+// single-file http-server.js. Shared helpers live in src/server-shared.js.
+
+const {
+sendJSON,
+readJsonOr400,
+parseCookies,
+accessCookie,
+accessRequestOrigin,
+checkAccessAttempts,
+recordAccessFailure,
+clearAccessFailures,
+publicAccessStatus,
+ACCESS_COOKIE,
+accessAuth,
+qr,
+push,
+settings,
+safeDecode
+} = require('./server-shared.js');
+const { resolveNotificationPrefs } = require('./notifications.js');
+
+// notifyLogin(username, req) — best-effort push that a new browser signed
+// in. Gated by the `notifications.login` preference (on by default) so it
+// can be silenced from Settings. Broadcast to every subscribed endpoint
+// (not the just-issued session, whose subscription list is empty until the
+// page rebinds) so the alert reaches the user's other already-signed-in
+// devices — the whole point of a sign-in notice.
+function notifyLogin(username, req) {
+try {
+let prefs = {};
+try { prefs = resolveNotificationPrefs((settings.getApp() || {}).notifications); } catch { /* defaults apply */ }
+if (prefs.login !== true) return;
+const agent = String((req && req.headers && req.headers['user-agent']) || '');
+const label = /iphone|ipad|ipod/i.test(agent) ? 'iPhone or iPad'
+: /android/i.test(agent) ? 'Android device'
+: /mobile/i.test(agent) ? 'mobile browser'
+: /macintosh|mac os/i.test(agent) ? 'Mac'
+: /windows/i.test(agent) ? 'Windows'
+: /linux/i.test(agent) ? 'Linux'
+: 'this browser';
+push.sendPushToAll({
+title: 'mouaif sign-in',
+body: `New sign-in as ${username || 'user'} from ${label}.`,
+tag: 'mouaif-login',
+data: { kind: 'login', url: '/#/projects' },
+actions: [{ action: 'open', title: 'Open mouaif' }]
+});
+} catch { /* a notification failure must never block sign-in */ }
+}
+
+// notifyAccessChange(enabled) — best-effort push that app access protection
+// changed. A security-relevant event, so it reuses the `login` channel
+// ("sign in to / access of this server") rather than adding a preference;
+// it broadcasts to every subscribed device, including the one that acted,
+// so the state change is visible even if that phone is put down.
+function notifyAccessChange(enabled) {
+try {
+let prefs = {};
+try { prefs = resolveNotificationPrefs((settings.getApp() || {}).notifications); } catch { /* defaults apply */ }
+if (prefs.login !== true) return;
+push.sendPushToAll({
+title: enabled ? 'mouaif access enabled' : 'mouaif access disabled',
+body: enabled
+? 'Password and passkey protection is on again.'
+: 'App access is off. Anyone who can reach this server can open it.',
+tag: 'mouaif-access',
+data: { kind: 'login', url: '/#/settings/access' },
+actions: [{ action: 'open', title: 'Open settings' }]
+});
+} catch { /* a notification failure must never change the access state */ }
+}
+
+
+async function handleAccess(req, res, parsed, serverConfig) {
+  const urlPath = parsed.pathname;
+  const method = req.method;
+  let servedOrigin;
+  try { servedOrigin = accessRequestOrigin(req, serverConfig.publicOrigin); }
+  catch (e) { return sendJSON(res, 400, { error: e.message, code: e.code || 'EORIGIN' }); }
+  const secure = servedOrigin.startsWith('https://');
+  const accessToken = parseCookies(req.headers.cookie)[ACCESS_COOKIE] || '';
+  const activeSession = accessAuth.session(accessToken);
+
+  if (urlPath === '/api/access/status' && method === 'GET') {
+    const status = publicAccessStatus(serverConfig.authEnabled);
+    return sendJSON(res, 200, { ...status, session: !!activeSession, authenticated: !status.enabled || !!activeSession });
+  }
+
+  if (urlPath === '/api/access/login' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    if (!accessAuth.configured()) return sendJSON(res, 409, { error: 'Access is not configured yet', code: 'ENOTCONFIGURED' });
+    if (!checkAccessAttempts(req)) return sendJSON(res, 429, { error: 'Too many sign-in attempts; wait a minute', code: 'ERATE_LIMIT' });
+    if (!accessAuth.verifyPassword(body.username, body.password)) {
+      recordAccessFailure(req);
+      return sendJSON(res, 401, { error: 'User or password is incorrect', code: 'EBADCREDENTIALS' });
+    }
+    clearAccessFailures(req);
+const issued = accessAuth.issueSession();
+res.setHeader('Set-Cookie', accessCookie(issued.token, secure, accessAuth.SESSION_TTL_MS / 1000));
+notifyLogin(accessAuth.user().username, req);
+return sendJSON(res, 200, { ok: true, user: accessAuth.user().username });
+}
+
+
+  if (urlPath === '/api/access/logout' && method === 'POST') {
+    accessAuth.revokeSession(accessToken);
+    res.setHeader('Set-Cookie', accessCookie('', secure, 0));
+    return sendJSON(res, 200, { ok: true });
+  }
+
+  // ---- Turn app access off / back on ------------------------------------
+  // Disabling is signed-in-only and requires a fresh one-time code, so a
+  // request that only holds a cookie (a script, a stale tab) cannot remove
+  // the login wall by itself. The code is minted here — unlike setup codes
+  // it is never printed to stdout or served to an unauthenticated caller.
+  if (urlPath === '/api/access/disable/code' && method === 'POST') {
+    if (!activeSession) return sendJSON(res, 401, { error: 'Sign in is required', code: 'EAUTH_REQUIRED' });
+    const issued = accessAuth.createDisableCode();
+    return sendJSON(res, 200, { code: issued.code, expiresAt: issued.expiresAt, ttlMs: accessAuth.DISABLE_TTL_MS });
+  }
+
+  // The QR is an image so a phone can open it with the system camera. It
+  // encodes the confirmation page, which is what makes the code itself
+  // unnecessary to type on the scanning device.
+  if (urlPath === '/api/access/disable/qr' && method === 'GET') {
+    if (!activeSession) return sendJSON(res, 401, { error: 'Sign in is required', code: 'EAUTH_REQUIRED' });
+    const code = typeof parsed.query.code === 'string' ? parsed.query.code : '';
+    if (!accessAuth.disableCodeValid(code)) return sendJSON(res, 404, { error: 'Disable code is missing or expired', code: 'EDISABLE_CODE' });
+    const confirmUrl = servedOrigin + '/#/disable-access?code=' + encodeURIComponent(accessAuth.normalizeCode(code));
+    const svg = qr.svg(confirmUrl);
+    res.writeHead(200, { 'Content-Type': 'image/svg+xml; charset=utf-8', 'Cache-Control': 'no-store' });
+    res.end(svg);
+    return;
+  }
+
+  if (urlPath === '/api/access/disable' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    // An invalid code is a failed guess, so it counts against the same
+    // per-address limit as a wrong password. The confirmation page is
+    // deliberately reachable without a session, so nothing else slows down
+    // a caller trying codes in a loop.
+    if (!checkAccessAttempts(req)) return sendJSON(res, 429, { error: 'Too many attempts; wait a minute', code: 'ERATE_LIMIT' });
+    if (!accessAuth.disableCodeValid(body.code)) {
+      recordAccessFailure(req);
+      return sendJSON(res, 401, { error: 'That code is invalid or expired', code: 'EDISABLE_CODE' });
+    }
+    if (!accessAuth.consumeDisableCode(body.code)) {
+      recordAccessFailure(req);
+      return sendJSON(res, 409, { error: 'That code was already used or expired', code: 'EDISABLE_CODE' });
+    }
+    clearAccessFailures(req);
+    // Consume every other outstanding invitation and turn the gate off.
+    // Sessions are intentionally kept: with the gate off they authorize
+    // nothing, and holding on to them lets the device that disabled access
+    // re-enable it without having to prove the password again.
+    settings.getDb().prepare('DELETE FROM access_disable_codes').run();
+    settings.getDb().prepare('DELETE FROM access_setup_codes').run();
+    accessAuth.setEnabled(false);
+    notifyAccessChange(false);
+    return sendJSON(res, 200, { ok: true, enabled: false, configured: accessAuth.configured() });
+  }
+
+  // Turning protection back on is safe to do from an unauthenticated screen,
+  // so it accepts any of the store's proofs: a live session, the account
+  // password, or a CLI setup code. That keeps recovery possible even after
+  // session cookies have expired while access was off.
+  if (urlPath === '/api/access/enable' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    const account = accessAuth.user();
+    if (!account) return sendJSON(res, 409, { error: 'Create the access user before enabling protection', code: 'ENOTCONFIGURED' });
+    const bySession = !!activeSession;
+    const byPassword = !bySession && account
+      && accessAuth.verifyPassword(body.username || account.username, body.password);
+    const bySetupCode = !bySession && !byPassword && accessAuth.setupCodeValid(body.code);
+    if (!bySession && !byPassword && !bySetupCode) {
+      return sendJSON(res, 401, { error: 'Sign in, or enter the account password, to enable access', code: 'EAUTH_REQUIRED' });
+    }
+    if (bySetupCode && !accessAuth.consumeSetupCode(body.code)) {
+      return sendJSON(res, 409, { error: 'Setup code was already used or expired', code: 'ESETUP_CODE' });
+    }
+    accessAuth.setEnabled(true);
+    notifyAccessChange(true);
+    return sendJSON(res, 200, { ok: true, enabled: true, configured: true });
+  }
+
+  // Password change from an authenticated browser session. Requires a real
+  // cookie session (a Basic-auth API client cannot ask to rotate the
+  // password through this endpoint). The current session survives the
+  // rotation; every other browser is signed out.
+  if (urlPath === '/api/access/password' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    if (!activeSession) return sendJSON(res, 401, { error: 'Sign in is required', code: 'EAUTH_REQUIRED' });
+    try {
+      const changed = accessAuth.changePassword(activeSession.username, body.currentPassword, body.newPassword, accessToken);
+      res.setHeader('Set-Cookie', accessCookie(accessToken, secure, accessAuth.SESSION_TTL_MS / 1000));
+      return sendJSON(res, 200, { ok: true, user: changed.user && changed.user.username, expiresAt: changed.expiresAt });
+    } catch (e) {
+      return sendJSON(res, e.code === 'EBADCREDENTIALS' ? 401 : 400, { error: e.message, code: e.code || 'EBADINPUT' });
+    }
+  }
+
+  if (urlPath === '/api/access/setup/verify' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    const valid = accessAuth.setupCodeValid(body.code);
+    return sendJSON(res, valid ? 200 : 401, { valid });
+  }
+
+  if (urlPath === '/api/access/setup' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    const setupAuthorized = accessAuth.setupCodeValid(body.code);
+    if (!activeSession && !setupAuthorized) return sendJSON(res, 401, { error: 'A valid one-time setup code or signed-in session is required', code: 'ESETUP_CODE' });
+    try {
+      accessAuth.setPassword(body.username, body.password);
+      if (setupAuthorized && !accessAuth.consumeSetupCode(body.code)) return sendJSON(res, 409, { error: 'Setup code was already used or expired', code: 'ESETUP_CODE' });
+      const issued = accessAuth.issueSession();
+res.setHeader('Set-Cookie', accessCookie(issued.token, secure, accessAuth.SESSION_TTL_MS / 1000));
+notifyLogin(accessAuth.user() && accessAuth.user().username, req);
+return sendJSON(res, 200, { ok: true, ...publicAccessStatus(serverConfig.authEnabled), authenticated: true });
+
+    } catch (e) {
+      return sendJSON(res, 400, { error: e.message, code: e.code || 'EBADINPUT' });
+    }
+  }
+
+  if (urlPath === '/api/access/passkeys/register/options' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    if (!accessAuth.configured()) return sendJSON(res, 409, { error: 'Create the access user before adding a passkey', code: 'ENOTCONFIGURED' });
+    const setupAuthorized = accessAuth.setupCodeValid(body.code);
+    if (!activeSession && !setupAuthorized) return sendJSON(res, 401, { error: 'Sign in or provide a valid setup code first', code: 'EAUTH_REQUIRED' });
+    const username = activeSession ? activeSession.username : String(body.username || accessAuth.user()?.username || '').trim();
+    if (!username) return sendJSON(res, 400, { error: 'username is required' });
+    try {
+      return sendJSON(res, 200, accessAuth.beginRegistration({
+        origin: servedOrigin, username,
+        authorizedBy: setupAuthorized ? accessAuth.normalizeCode(body.code) : 'session'
+      }));
+    } catch (e) { return sendJSON(res, 400, { error: e.message, code: e.code || 'EWEBAUTHN' }); }
+  }
+
+  if (urlPath === '/api/access/passkeys/register/verify' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    try {
+      const result = accessAuth.finishRegistration(body);
+      return sendJSON(res, 200, { ok: true, passkeys: result.passkeys });
+    } catch (e) { return sendJSON(res, 400, { error: e.message, code: e.code || 'EWEBAUTHN' }); }
+  }
+
+  if (urlPath === '/api/access/passkeys/login/options' && method === 'POST') {
+    if (!checkAccessAttempts(req)) return sendJSON(res, 429, { error: 'Too many sign-in attempts; wait a minute', code: 'ERATE_LIMIT' });
+    try { return sendJSON(res, 200, accessAuth.beginAuthentication({ origin: servedOrigin })); }
+    catch (e) { return sendJSON(res, 400, { error: e.message, code: e.code || 'EWEBAUTHN' }); }
+  }
+
+  if (urlPath === '/api/access/passkeys/login/verify' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+    try {
+      const account = accessAuth.finishAuthentication(body);
+      clearAccessFailures(req);
+const issued = accessAuth.issueSession();
+res.setHeader('Set-Cookie', accessCookie(issued.token, secure, accessAuth.SESSION_TTL_MS / 1000));
+notifyLogin(account.username, req);
+return sendJSON(res, 200, { ok: true, user: account.username });
+
+    } catch (e) {
+      recordAccessFailure(req);
+      return sendJSON(res, 401, { error: e.message, code: e.code || 'EWEBAUTHN' });
+    }
+  }
+
+  if (urlPath === '/api/access/passkeys' && method === 'GET') {
+    if (!activeSession) return sendJSON(res, 401, { error: 'Sign in is required', code: 'EAUTH_REQUIRED' });
+    return sendJSON(res, 200, { passkeys: accessAuth.passkeys() });
+  }
+
+  if (urlPath.startsWith('/api/access/passkeys/') && method === 'DELETE') {
+    if (!activeSession) return sendJSON(res, 401, { error: 'Sign in is required', code: 'EAUTH_REQUIRED' });
+    const id = safeDecode(urlPath.slice('/api/access/passkeys/'.length));
+    return sendJSON(res, accessAuth.deletePasskey(id) ? 200 : 404, { ok: true });
+  }
+
+  if (urlPath === '/api/access/setup/qr' && method === 'GET') {
+    const code = typeof parsed.query.code === 'string' ? parsed.query.code : '';
+    if (!accessAuth.setupCodeValid(code)) return sendJSON(res, 404, { error: 'Setup code is missing or expired', code: 'ESETUP_CODE' });
+    const setupUrl = servedOrigin + '/#/setup?code=' + encodeURIComponent(accessAuth.normalizeCode(code));
+    const svg = qr.svg(setupUrl);
+    res.writeHead(200, { 'Content-Type': 'image/svg+xml; charset=utf-8', 'Cache-Control': 'no-store' });
+    res.end(svg);
+    return;
+  }
+
+  return sendJSON(res, 404, { error: 'Not found', scope: 'access' });
+}
+
+module.exports = { handleAccess };

package/src/server-handlers-actions.js

@@ -0,0 +1,100 @@
+'use strict';
+// Project custom-action CRUD + execution REST handlers.
+const { sendJSON, qs, safeDecode, readJsonOr400, chats, mcp, shellTool } = require('./server-shared.js');
+const customActions = require('./custom-actions.js');
+function statusFor(error) {
+if (error && ['EBADINPUT', 'MOUAIF_PROJECT_PARSE_ERROR'].includes(error.code)) return 400;
+if (error && (error.code === 'ETOOL_DISABLED' || error.code === 'EDENIED')) return 403;
+if (error && error.code === 'EMCP_NOTFOUND') return 404;
+return 500;
+}
+function findAction(projectDir, id) {
+return customActions.listActions(projectDir).find((action) => action.id === id) || null;
+}
+async function handleActions(req, res, parsed) {
+const urlPath = parsed.pathname;
+const method = req.method;
+const q = parsed.query || {};
+if (urlPath === '/api/actions' && method === 'GET') {
+const projectDir = qs(q, 'projectDir');
+if (!projectDir) return sendJSON(res, 400, { error: 'projectDir is required' });
+try { return sendJSON(res, 200, { actions: customActions.listActions(projectDir) }); }
+catch (error) { return sendJSON(res, statusFor(error), { error: error.message, code: error.code || 'INTERNAL' }); }
+}
+if (urlPath === '/api/actions' && method === 'POST') {
+const body = await readJsonOr400(req, res);
+if (!body) return;
+const projectDir = body && typeof body.projectDir === 'string' ? body.projectDir : '';
+if (!projectDir) return sendJSON(res, 400, { error: 'projectDir is required' });
+try {
+const action = customActions.normalizeAction(body.action, 0);
+const actions = customActions.listActions(projectDir);
+const originalId = typeof body.originalId === 'string' ? body.originalId : '';
+const index = originalId ? actions.findIndex((item) => item.id === originalId) : -1;
+if (index >= 0) actions[index] = action; else actions.push(action);
+const saved = customActions.replaceActions(projectDir, actions);
+return sendJSON(res, 200, { action, actions: saved });
+} catch (error) {
+return sendJSON(res, statusFor(error), { error: error.message, code: error.code || 'INTERNAL' });
+}
+}
+let match = urlPath.match(/^\/api\/actions\/([^/]+)$/);
+if (match && method === 'DELETE') {
+const projectDir = qs(q, 'projectDir');
+if (!projectDir) return sendJSON(res, 400, { error: 'projectDir is required' });
+const id = safeDecode(match[1]);
+try {
+const actions = customActions.listActions(projectDir);
+const next = actions.filter((action) => action.id !== id);
+if (next.length === actions.length) return sendJSON(res, 404, { error: 'Action not found', id });
+customActions.replaceActions(projectDir, next);
+return sendJSON(res, 200, { ok: true, actions: next });
+} catch (error) {
+return sendJSON(res, statusFor(error), { error: error.message, code: error.code || 'INTERNAL' });
+}
+}
+match = urlPath.match(/^\/api\/actions\/([^/]+)\/run$/);
+if (match && method === 'POST') {
+const body = await readJsonOr400(req, res);
+if (!body) return;
+const projectDir = body && typeof body.projectDir === 'string' ? body.projectDir : '';
+const chatId = body && typeof body.chatId === 'string' ? body.chatId : '';
+const callId = body && typeof body.callId === 'string' ? body.callId : '';
+if (!projectDir || !chatId || !callId) return sendJSON(res, 400, { error: 'projectDir, chatId, and callId are required' });
+if (!chats.getChat(projectDir, chatId)) return sendJSON(res, 404, { error: 'Chat not found', chatId });
+try {
+const id = safeDecode(match[1]);
+const action = findAction(projectDir, id);
+if (!action) return sendJSON(res, 404, { error: 'Action not found', id });
+if (action.kind === 'cli') {
+const authorization = await require('./tools/authorization.js').authorize({
+projectDir, chatId, callId, tool: 'shell', cmd: action.command,
+summary: action.label + ': ' + action.command, timeoutMs: action.timeoutMs, flow: 'retry'
+});
+if (authorization.decision === 'prompt') return sendJSON(res, 409, {
+ok: false, code: 'EAUTH_REQUIRED', projectDir, chatId, callId,
+tool: 'shell', cmd: action.command, timeoutMs: authorization.timeoutMs
+});
+const result = await shellTool.runShell({ projectDir, cmd: action.command, timeoutMs: authorization.timeoutMs });
+return sendJSON(res, 200, { ok: !!result.ok, action, result });
+}
+const server = mcp.getServer(projectDir, action.serverId);
+if (!server) return sendJSON(res, 404, { error: 'MCP server not found', serverId: action.serverId });
+const tool = mcp.composedToolName(server.slug, action.toolName);
+const authorization = await require('./tools/authorization.js').authorize({
+projectDir, chatId, callId, tool, args: action.args,
+summary: action.label + ': ' + JSON.stringify(action.args || {}), flow: 'retry'
+});
+if (authorization.decision === 'prompt') return sendJSON(res, 409, {
+ok: false, code: 'EAUTH_REQUIRED', projectDir, chatId, callId, tool,
+args: action.args, timeoutMs: authorization.timeoutMs
+});
+const result = await mcp.callTool(projectDir, server.slug, action.toolName, action.args || {});
+return sendJSON(res, 200, { ok: result && result.ok !== false, action, result });
+} catch (error) {
+return sendJSON(res, statusFor(error), { ok: false, error: error.message, code: error.code || 'INTERNAL' });
+}
+}
+return sendJSON(res, 404, { error: 'Not found', scope: 'actions' });
+}
+module.exports = { handleActions };

package/src/server-handlers-ai.js

@@ -0,0 +1,248 @@
+'use strict';
+
+// AI proxy REST handlers. Extracted from the original single-file
+// http-server.js. Shared helpers + model resolution live in
+// src/server-shared.js.
+
+const {
+  sendJSON,
+  readJsonOr400,
+  resolveModel,
+  credentialForProvider,
+  settings,
+  projects,
+  ai
+} = require('./server-shared.js');
+const modelList = require('./modelList.js');
+
+async function handleAI(req, res, parsed) {
+  const urlPath = parsed.pathname;
+  const method = req.method;
+
+  // GET /api/ai/models?projectDir=<abs>  -> list models visible to this project
+  if (urlPath === '/api/ai/models' && method === 'GET') {
+    const projectDir = typeof parsed.query.projectDir === 'string' ? parsed.query.projectDir : '';
+    const resolved = settings.getResolved(projectDir || null);
+    const models = (resolved.models || []).map(m => {
+      const rec = {
+        id: m.id, provider: m.provider, label: m.label, auth: m.auth || 'apikey'
+      };
+      // Thinking options come from the provider when it reports them
+      // (per-model on live lists, provider-level otherwise); a
+      // user-set model.thinking always wins.
+      const def = ai.ENDPOINTS[m.provider];
+      const thinking = m.thinking || (def && def.thinkingDescriptor) || null;
+      if (thinking) rec.thinking = thinking;
+      return rec;
+    });
+    return sendJSON(res, 200, { models, providers: Object.keys(ai.ENDPOINTS) });
+  }
+
+  // GET /api/ai/models/live?provider=<id>  -> { models, fetchedAt, cached }
+  // Live model list fetched from the upstream /models endpoint
+  // (OpenAI-shaped), Gemini's /v1beta/models, Ollama's /api/tags, or
+  // the curated Copilot catalog. Results are cached per-provider in
+  // memory for an hour so opening many chats does not re-hit the
+  // upstream. The chat UI calls this from the refresh button next to
+  // the model <select>.
+  //
+  // The fetch + cache live in src/modelList.js, because the dictation
+  // catalog needs the same answer filtered differently. `_bust=1` forces a
+  // reload (the picker's explicit refresh).
+  if (urlPath === '/api/ai/models/live' && method === 'GET') {
+    const provider = typeof parsed.query.provider === 'string' ? parsed.query.provider : '';
+    if (!provider || !ai.ENDPOINTS[provider]) {
+      return sendJSON(res, 400, { error: 'unknown provider', provider });
+    }
+    // `purpose` selects which slice of the provider's catalog to read:
+    // `chat` (default), `transcription`, or `image`. A provider without a
+    // separate slice returns its chat list, so a caller can safely ask for
+    // the image slice on every provider and union the results — which is
+    // what the agent editor's model picker does so an image model reaches
+    // it even though the chat list never carries one.
+    const purposeRaw = typeof parsed.query.purpose === 'string' ? parsed.query.purpose : '';
+    const purpose = (purposeRaw === 'image' || purposeRaw === 'transcription') ? purposeRaw : undefined;
+    try {
+    const result = await modelList.liveModelsFor(provider, { force: !!parsed.query._bust, purpose });
+    return sendJSON(res, 200, { models: result.models, fetchedAt: result.fetchedAt, cached: result.cached });
+    } catch (err) {
+      // Map typed error codes to HTTP statuses. 502 is reserved for
+      // "upstream answered with a non-2xx" (EUPSTREAM) — anything
+      // that isn't a recognized failure shape falls through to a
+      // generic 502 so a regression in the adapter still surfaces
+      // somewhere observable. Distinct failure modes get distinct
+      // statuses so the chat UI can show a useful next step.
+      const code = err && err.code;
+      let status;
+      if (code === 'ENO_LIST')       status = 400;
+      else if (code === 'ENO_APIKEY') status = 400;
+      else if (code === 'EUNREACHABLE') status = 503;
+      else if (code === 'ETIMEOUT') status = 504;
+      else if (code === 'EUPSTREAM' && typeof err.status === 'number') status = err.status;
+      else                            status = 502;
+      const body = { error: String((err && err.message) || err), code: code || 'ELIVE', provider };
+      if (code === 'EUPSTREAM' && typeof err.status === 'number') body.upstreamStatus = err.status;
+      return sendJSON(res, status, body);
+    }
+  }
+
+  // GET /api/ai/provider-credit?provider=<id> -> { supported, remaining? }
+  // Provider-specific account balance lookup. Only OpenRouter exposes a
+  // simple key-scoped credits endpoint; unsupported providers return
+  // { supported: false } so the chat head can hide the pill.
+  if (urlPath === '/api/ai/provider-credit' && method === 'GET') {
+    const provider = typeof parsed.query.provider === 'string' ? parsed.query.provider : '';
+    if (provider !== 'openrouter') return sendJSON(res, 200, { provider, supported: false });
+    let cred;
+    try { cred = credentialForProvider(provider); }
+    catch (e) { return sendJSON(res, 400, { provider, supported: true, error: e.message, code: e.code || 'ENO_APIKEY' }); }
+    if (!cred) return sendJSON(res, 400, { provider, supported: true, error: 'OpenRouter API key required', code: 'ENO_APIKEY' });
+    let r;
+    try {
+      r = await fetch(ai.ENDPOINTS.openrouter.baseUrl + '/credits', {
+        headers: { ...ai.ENDPOINTS.openrouter.authHeader(cred), ...ai.ENDPOINTS.openrouter.staticHeaders }
+      });
+    } catch (e) {
+      return sendJSON(res, 503, { provider, supported: true, error: 'OpenRouter unreachable', code: 'EUNREACHABLE' });
+    }
+    if (!r.ok) return sendJSON(res, r.status, { provider, supported: true, error: 'OpenRouter returned ' + r.status, code: 'EUPSTREAM' });
+    const body = await r.json().catch(() => ({}));
+    const data = body && body.data ? body.data : body;
+    const totalCredits = Number(data && (data.total_credits ?? data.totalCredits ?? data.credits));
+    const totalUsage = Number(data && (data.total_usage ?? data.totalUsage ?? data.usage));
+    const remaining = Number(data && (data.remaining_credits ?? data.remainingCredits ?? data.remaining));
+    const value = isFinite(remaining) ? remaining : (isFinite(totalCredits) && isFinite(totalUsage) ? totalCredits - totalUsage : NaN);
+    if (!isFinite(value)) return sendJSON(res, 502, { provider, supported: true, error: 'OpenRouter credit response missing totals', code: 'EBAD_CREDITS' });
+    return sendJSON(res, 200, { provider, supported: true, label: 'Balance', remaining: value, totalCredits: isFinite(totalCredits) ? totalCredits : undefined, totalUsage: isFinite(totalUsage) ? totalUsage : undefined });
+  }
+
+  // GET /api/ai/models/providers -> { providers: [{ id }] }
+  // The chat uses this when a project has no model records yet. Returning
+  // every configured connection avoids the old "first provider wins"
+  // fallback, which silently queried OpenAI when the user wanted OpenRouter.
+  if (urlPath === '/api/ai/models/providers' && method === 'GET') {
+    const app = settings.getApp();
+    const providers = (Array.isArray(app.providers) ? app.providers : [])
+      .filter((p) => p && typeof p.id === 'string' && ai.ENDPOINTS[p.id])
+      .map((p) => ({ id: p.id }));
+    return sendJSON(res, 200, { providers });
+  }
+
+  // GET /api/ai/models-all  -> { ids: [..] }
+  // Union of every model id the user has configured across every
+  // registered project + the app-level models list. Used by the
+  // SettingsPricing view to surface "the ids you might want to
+  // price" without forcing the user to remember project paths.
+  if (urlPath === '/api/ai/models-all' && method === 'GET') {
+    const ids = new Set();
+    // App-level models (legacy / inline pricing tests)
+    const app = settings.getApp();
+    if (Array.isArray(app.models)) {
+      for (const m of app.models) if (m && m.id) ids.add(m.id);
+    }
+    // Project-level models. Each registered project has its own
+    // .mouaif.json; the registry is the source of truth for which
+    // projects still exist on disk.
+    const registered = projects.listProjects();
+    for (const p of registered) {
+      if (!p || !p.path) continue;
+      try {
+        const projSettings = settings.getProject(p.path);
+        if (Array.isArray(projSettings.models)) {
+          for (const m of projSettings.models) if (m && m.id) ids.add(m.id);
+        }
+      } catch { /* unreadable project file — skip */ }
+    }
+    return sendJSON(res, 200, { ids: Array.from(ids).sort() });
+  }
+
+  // POST /api/ai/test  body: { modelId, projectDir? }  -> { ok, error? }
+  // Lightweight connectivity test: sends a single "hi" message and
+  // checks whether the upstream returns a typed error or a 200 SSE
+  // stream. Aborts after 10 s so the user never waits long.
+  if (urlPath === '/api/ai/test' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+
+    let model;
+    try { model = resolveModel(body.modelId, body.projectDir); }
+    catch (e) { return sendJSON(res, 400, { error: e.message, code: e.code }); }
+
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, 10000);
+    try {
+      const result = await ai.streamChat({
+        model,
+        messages: [{ role: 'user', content: 'Hi' }],
+        signal: controller.signal,
+        onEvent: () => {} // discard events, we only care about ok/error
+      });
+      clearTimeout(timer);
+      if (result.ok) return sendJSON(res, 200, { ok: true });
+      if (timedOut && result.error && result.error.code === 'EABORTED') {
+        return sendJSON(res, 200, { ok: false, error: 'timed out after 10 s', code: 'ETIMEDOUT' });
+      }
+      return sendJSON(res, 200, { ok: false, error: (result.error && result.error.message) || 'upstream error' });
+    } catch (e) {
+      clearTimeout(timer);
+      const code = e.code || 'ETEST';
+      if (timedOut || code === 'EABORTED') {
+        return sendJSON(res, 200, { ok: false, error: 'timed out after 10 s', code: 'ETIMEDOUT' });
+      }
+      return sendJSON(res, 200, { ok: false, error: e.message, code });
+    }
+  }
+
+  // POST /api/ai/chat  body: { modelId, providerId?, messages, projectDir? }  -> SSE stream
+  // `providerId` pins the model id to one provider connection: the same id can
+  // exist under several providers, and without it resolution picks the first
+  // project model with that id (surface-level callers such as the Inspector
+  // pass the provider they picked the model from).
+  if (urlPath === '/api/ai/chat' && method === 'POST') {
+    const body = await readJsonOr400(req, res);
+    if (!body) return;
+
+    let model;
+    try { model = resolveModel(body.modelId, body.projectDir, body.providerId); }
+    catch (e) { return sendJSON(res, 400, { error: e.message, code: e.code }); }
+
+    // Open SSE.
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive'
+    });
+    // Initial comment so the client sees headers immediately.
+    res.write(': connected\n\n');
+
+    const controller = new AbortController();
+    req.on('close', () => { try { controller.abort(); } catch { /* ignore */ } });
+
+    function emit(name, data) {
+      try {
+        res.write('event: ' + name + '\ndata: ' + JSON.stringify(data) + '\n\n');
+      } catch { /* socket already closed */ }
+    }
+
+    const result = await ai.streamChat({
+      model,
+      messages: body.messages || [],
+      signal: controller.signal,
+      onEvent: (name, data) => emit(name, data)
+    });
+
+    if (!result.ok) {
+      emit('error', Object.assign({ code: result.error.code || 'EUPSTREAM' }, result.error));
+    }
+    res.end();
+    return;
+  }
+
+  return sendJSON(res, 404, { error: 'Not found', scope: 'ai' });
+}
+
+module.exports = { handleAI };