@oar-sh/oar 0.9.5 → 0.9.7

package/server/services/claude-cloud-session-service.mjs

@@ -0,0 +1,326 @@
+'use strict';
+
+// What the relay keeps about a Claude Cloud conversation (provider
+// `claude-cloud`), and the two things it does with it besides showing it:
+// taking the worker's reports and archiving the cloud session.
+//
+// A cloud conversation has two records. `conversations.cloud_source_json` says
+// what the session clones and where it is shown (`{ repoUrl, branch,
+// environmentId, sessionUrl, pushedBranches }`); the runtime session row holds
+// the binding the worker reports (`claude_cloud_session_id`, the last handled
+// event sequence, the cost). Nothing here ever sees the Claude login: the
+// cloud client that archives is injected and reads the token itself.
+
+import { isValidBranchName, normalizeGitHubRepoUrl } from '../../shared/claude-cloud/repo-url.mjs';
+
+export const CLAUDE_CLOUD_PROVIDER_TYPE = 'claude-cloud';
+export const CLAUDE_CLOUD_PROVIDER_LABEL = 'Claude Cloud';
+
+// A session that pushes more branches than this keeps the newest ones.
+const MAX_PUSHED_BRANCHES = 20;
+// Ids go into request paths (the worker's and the archive call's), so only
+// the characters the cloud uses for them are taken.
+const CLOUD_ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const SEQUENCE_PATTERN = /^\d{1,30}$/;
+
+function toText(value) {
+  return typeof value === 'string' ? value.trim() : (typeof value === 'number' ? String(value) : '');
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isClaudeCloudProviderType(value) {
+  return String(value || '').trim().toLowerCase() === CLAUDE_CLOUD_PROVIDER_TYPE;
+}
+
+export function isSafeClaudeCloudId(value) {
+  return CLOUD_ID_PATTERN.test(String(value || ''));
+}
+
+/** A link the browser may show: https only, so a stored value is never a script URL. */
+function normalizeSessionUrl(value) {
+  const text = toText(value);
+  if (!text || text.length > 500) return null;
+  try {
+    const url = new URL(text);
+    return url.protocol === 'https:' ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizePushedBranches(value) {
+  const out = [];
+  for (const entry of Array.isArray(value) ? value : []) {
+    const branch = isPlainObject(entry) ? entry.branch : entry;
+    if (!isValidBranchName(branch)) continue;
+    if (out.some((existing) => existing.branch === branch)) continue;
+    out.push({ branch, at: toText(entry?.at) || null });
+  }
+  return out.slice(-MAX_PUSHED_BRANCHES);
+}
+
+/**
+ * The stored cloud source of a conversation, or null when the column is empty
+ * or does not name a repository (every other conversation).
+ */
+export function parseCloudSourceJson(raw) {
+  let parsed = raw;
+  if (typeof raw === 'string') {
+    if (!raw.trim()) return null;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (!isPlainObject(parsed)) return null;
+  const repo = normalizeGitHubRepoUrl(parsed.repoUrl);
+  if (!repo) return null;
+  return {
+    repoUrl: repo.repoUrl,
+    branch: isValidBranchName(parsed.branch) ? parsed.branch : null,
+    environmentId: isSafeClaudeCloudId(parsed.environmentId) ? parsed.environmentId : null,
+    sessionUrl: normalizeSessionUrl(parsed.sessionUrl),
+    pushedBranches: normalizePushedBranches(parsed.pushedBranches),
+  };
+}
+
+/**
+ * Checks the `cloudSource` of a bootstrap request. The repository comes back
+ * in its canonical https form; an empty branch means the default branch.
+ */
+export function validateCloudSourceRequest(cloudSource) {
+  const source = isPlainObject(cloudSource) ? cloudSource : {};
+  const repo = normalizeGitHubRepoUrl(source.repoUrl);
+  if (!repo) {
+    return {
+      ok: false,
+      code: 'claude_cloud_repo_invalid',
+      error: 'A Claude Cloud conversation needs a GitHub repository (for example https://github.com/owner/repo).',
+    };
+  }
+  const branch = typeof source.branch === 'string' ? source.branch.trim() : '';
+  if (source.branch != null && typeof source.branch !== 'string') {
+    return { ok: false, code: 'claude_cloud_branch_invalid', error: 'The branch must be a branch name.' };
+  }
+  if (branch && !isValidBranchName(branch)) {
+    return { ok: false, code: 'claude_cloud_branch_invalid', error: `"${branch.slice(0, 80)}" is not a valid branch name.` };
+  }
+  return { ok: true, repoUrl: repo.repoUrl, slug: repo.slug, branch: branch || null };
+}
+
+/** The `cloud_source_json` of a new conversation. */
+export function buildCloudSourceRecord({ repoUrl, branch = null, environmentId = null } = {}) {
+  return {
+    repoUrl,
+    branch: branch || null,
+    environmentId: environmentId || null,
+    sessionUrl: null,
+    pushedBranches: [],
+  };
+}
+
+function normalizeCostUsd(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
+/**
+ * The `cloud` field of the conversation list and detail payloads:
+ * `{ repoUrl, slug, branch, sessionUrl, pushedBranches, costUsd }`, or null
+ * for a conversation that is not a cloud one.
+ */
+export function buildConversationCloudPayload({ cloudSourceJson = null, costUsd = null } = {}) {
+  const source = parseCloudSourceJson(cloudSourceJson);
+  if (!source) return null;
+  return {
+    repoUrl: source.repoUrl,
+    slug: normalizeGitHubRepoUrl(source.repoUrl)?.slug || null,
+    branch: source.branch,
+    sessionUrl: source.sessionUrl,
+    pushedBranches: source.pushedBranches,
+    costUsd: normalizeCostUsd(costUsd),
+  };
+}
+
+/**
+ * The `claudeCloud` field of a delivered message: what the worker needs to
+ * create the session (first message) or to send into it (every later one).
+ * Null for another provider, and for a cloud conversation whose source is
+ * missing: the worker answers that with its own "no repository" reply.
+ */
+export function buildClaudeCloudDelivery({ conversation = null, runtimeSession = null, fallbackEnvironmentId = '' } = {}) {
+  if (!isClaudeCloudProviderType(runtimeSession?.provider_type)) return null;
+  const source = parseCloudSourceJson(conversation?.cloud_source_json);
+  if (!source) return null;
+  const sessionId = toText(runtimeSession?.claude_cloud_session_id);
+  const lastSequence = toText(runtimeSession?.claude_cloud_last_sequence);
+  const fallback = toText(fallbackEnvironmentId);
+  return {
+    sessionId: isSafeClaudeCloudId(sessionId) ? sessionId : null,
+    lastSequence: SEQUENCE_PATTERN.test(lastSequence) ? lastSequence : null,
+    repoUrl: source.repoUrl,
+    branch: source.branch,
+    environmentId: source.environmentId || (isSafeClaudeCloudId(fallback) ? fallback : null),
+    title: toText(conversation?.title) || 'New Conversation',
+  };
+}
+
+/** The larger of two sequence numbers (strings of digits), so a late report never moves the cursor back. */
+function laterSequence(stored, reported) {
+  const a = SEQUENCE_PATTERN.test(toText(stored)) ? toText(stored) : null;
+  const b = SEQUENCE_PATTERN.test(toText(reported)) ? toText(reported) : null;
+  if (!a) return b;
+  if (!b) return a;
+  return BigInt(b) > BigInt(a) ? b : a;
+}
+
+export function createClaudeCloudSessionService({
+  stmts,
+  // The shared cloud client (archive). A getter, so the server can build the
+  // client lazily and tests can leave it out.
+  getCloudClient = () => null,
+  emit = () => {},
+  now = () => new Date(),
+  logger = console,
+} = {}) {
+  function nowIso() {
+    const value = now();
+    return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+  }
+
+  function cloudPayloadFor(conversation, runtimeSession) {
+    return buildConversationCloudPayload({
+      cloudSourceJson: conversation?.cloud_source_json,
+      costUsd: runtimeSession?.claude_cloud_cost_usd,
+    });
+  }
+
+  /**
+   * POST /api/claude-cloud-session: the worker's binding report (after the
+   * session was created, after every `result`, and on a push).
+   * Returns `{ ok, statusCode, error }` or `{ ok: true, cloud }`.
+   */
+  function recordWorkerReport(body = {}) {
+    const conversationId = toText(body?.conversationId);
+    const cloudSessionId = toText(body?.cloudSessionId);
+    if (!conversationId || !cloudSessionId) {
+      return { ok: false, statusCode: 400, error: 'Missing conversationId or cloudSessionId' };
+    }
+    if (!isSafeClaudeCloudId(cloudSessionId)) {
+      return { ok: false, statusCode: 400, error: 'Invalid cloudSessionId' };
+    }
+    const runtimeSession = stmts.getRuntimeSessionByConversation?.get?.(conversationId) || null;
+    if (!runtimeSession) {
+      return { ok: false, statusCode: 404, error: 'Runtime session not found for conversation' };
+    }
+    if (!isClaudeCloudProviderType(runtimeSession.provider_type || 'github')) {
+      return { ok: false, statusCode: 409, error: 'Conversation is not bound to the Claude Cloud provider' };
+    }
+    if (typeof stmts.updateRuntimeSessionClaudeCloudSession?.run !== 'function'
+      || typeof stmts.updateConvCloudSource?.run !== 'function') {
+      return { ok: false, statusCode: 500, error: 'Claude Cloud session storage is unavailable' };
+    }
+    const conversation = stmts.getConvAnyStatus?.get?.(conversationId) || null;
+    const source = parseCloudSourceJson(conversation?.cloud_source_json);
+    if (!conversation || !source) {
+      return { ok: false, statusCode: 409, error: 'Conversation has no cloud repository' };
+    }
+
+    // The sequence and the cost belong to one cloud session: a report naming
+    // another session (the first one was replaced) starts both again.
+    const storedSessionId = toText(runtimeSession.claude_cloud_session_id);
+    const sameSession = !storedSessionId || storedSessionId === cloudSessionId;
+    const reportedCost = normalizeCostUsd(body?.costUsd);
+    const lastSequence = laterSequence(sameSession ? runtimeSession.claude_cloud_last_sequence : null, body?.lastSequence);
+    const costUsd = reportedCost !== null
+      ? reportedCost
+      : (sameSession ? normalizeCostUsd(runtimeSession.claude_cloud_cost_usd) : null);
+    const timestamp = nowIso();
+    stmts.updateRuntimeSessionClaudeCloudSession.run(cloudSessionId, lastSequence, costUsd, timestamp, conversationId);
+
+    const next = {
+      ...source,
+      sessionUrl: normalizeSessionUrl(body?.sessionUrl) || (sameSession ? source.sessionUrl : null),
+      pushedBranches: sameSession ? [...source.pushedBranches] : [],
+    };
+    const pushedBranch = typeof body?.pushedBranch === 'string' ? body.pushedBranch.trim() : '';
+    if (pushedBranch && isValidBranchName(pushedBranch)) {
+      // A branch pushed again moves to the end with its new time.
+      next.pushedBranches = [
+        ...next.pushedBranches.filter((entry) => entry.branch !== pushedBranch),
+        { branch: pushedBranch, at: timestamp },
+      ].slice(-MAX_PUSHED_BRANCHES);
+    }
+    const nextJson = JSON.stringify(next);
+    stmts.updateConvCloudSource.run(nextJson, conversationId);
+
+    const cloud = buildConversationCloudPayload({ cloudSourceJson: nextJson, costUsd });
+    emit('claude_cloud_session', { conversationId, cloud });
+    return { ok: true, cloud };
+  }
+
+  /**
+   * Archives the cloud session of a conversation that is being deleted or
+   * archived here. Best effort: it returns at once (true when an archive was
+   * started), and a failure is logged and never reaches the caller.
+   */
+  function archiveSessionInBackground({ conversationId = '', runtimeSession = null } = {}) {
+    if (!isClaudeCloudProviderType(runtimeSession?.provider_type)) return false;
+    const cloudSessionId = toText(runtimeSession?.claude_cloud_session_id);
+    if (!isSafeClaudeCloudId(cloudSessionId)) return false;
+    let client = null;
+    try {
+      client = getCloudClient();
+    } catch {
+      client = null;
+    }
+    if (typeof client?.archiveSession !== 'function') return false;
+    const label = toText(conversationId).slice(0, 8) || 'unknown';
+    Promise.resolve()
+      .then(() => client.archiveSession(cloudSessionId))
+      .then(() => {
+        logger?.log?.(`[claude-cloud] archived the cloud session of conversation ${label}`);
+      })
+      .catch((error) => {
+        // The client's errors carry a code and a redacted message, never the token.
+        const reason = toText(error?.code) || toText(error?.message).slice(0, 200) || 'unknown error';
+        logger?.warn?.(`[claude-cloud] the cloud session of conversation ${label} was not archived: ${reason}`);
+      });
+    return true;
+  }
+
+  /**
+   * The reverse, for a conversation that is unarchived here: the cloud
+   * session comes back so the next message reaches it. Same best-effort rule.
+   */
+  function unarchiveSessionInBackground({ conversationId = '', runtimeSession = null } = {}) {
+    if (!isClaudeCloudProviderType(runtimeSession?.provider_type)) return false;
+    const cloudSessionId = toText(runtimeSession?.claude_cloud_session_id);
+    if (!isSafeClaudeCloudId(cloudSessionId)) return false;
+    let client = null;
+    try {
+      client = getCloudClient();
+    } catch {
+      client = null;
+    }
+    if (typeof client?.unarchiveSession !== 'function') return false;
+    const label = toText(conversationId).slice(0, 8) || 'unknown';
+    Promise.resolve()
+      .then(() => client.unarchiveSession(cloudSessionId))
+      .then(() => {
+        logger?.log?.(`[claude-cloud] unarchived the cloud session of conversation ${label}`);
+      })
+      .catch((error) => {
+        const reason = toText(error?.code) || toText(error?.message).slice(0, 200) || 'unknown error';
+        logger?.warn?.(`[claude-cloud] the cloud session of conversation ${label} was not unarchived: ${reason}`);
+      });
+    return true;
+  }
+
+  return { cloudPayloadFor, recordWorkerReport, archiveSessionInBackground, unarchiveSessionInBackground };
+}

package/server/services/claude-cloud-settings-service.mjs

@@ -0,0 +1,269 @@
+'use strict';
+
+// Settings of the Claude Cloud provider (Settings → Providers → Claude Cloud).
+//
+// Three stored values: the switch (off by default), the default model of a
+// new cloud chat, and the cloud environment its sessions run in. Everything
+// else the tab shows is read, never stored: the account from the Claude CLI's
+// own status, the state of its login from the credentials module (source and
+// expiry, never the token), the environments from the cloud.
+//
+// While the provider is switched off nothing here talks to Anthropic: the
+// environments are only listed once it is on.
+
+import { isSafeClaudeModelId } from '../../shared/model-id.mjs';
+import { stripModelTierSuffix } from '../../shared/claude-cloud/repo-url.mjs';
+import { CLAUDE_CLOUD_PROVIDER_TYPE, isSafeClaudeCloudId } from './claude-cloud-session-service.mjs';
+
+export const CLAUDE_CLOUD_ENABLED_SETTING_KEY = 'claude_cloud_enabled';
+export const CLAUDE_CLOUD_DEFAULT_MODEL_SETTING_KEY = 'claude_cloud_default_model';
+export const CLAUDE_CLOUD_ENVIRONMENT_SETTING_KEY = 'claude_cloud_environment_id';
+export const DEFAULT_CLAUDE_CLOUD_MODEL = 'claude-sonnet-5-5';
+
+const ENVIRONMENTS_CACHE_MS = 60_000;
+
+function toText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+/**
+ * The cloud's model ids for a Claude catalog: the tier suffix dropped
+ * ("claude-opus-5[1m]" and "claude-opus-5" are one cloud model), no
+ * duplicates, the default first.
+ */
+export function buildClaudeCloudModelList(defaultModel, catalogModels = []) {
+  const out = [];
+  const seen = new Set();
+  for (const candidate of [defaultModel, ...(Array.isArray(catalogModels) ? catalogModels : [])]) {
+    const model = stripModelTierSuffix(candidate);
+    const key = model.toLowerCase();
+    if (!model || seen.has(key) || !isSafeClaudeModelId(model)) continue;
+    seen.add(key);
+    out.push(model);
+  }
+  return out;
+}
+
+/** Reads `{ enabled?, defaultModel?, environmentId? }` from a request body. */
+export function parseClaudeCloudSettingsUpdateRequest(body = {}) {
+  const payload = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+  const update = {};
+  if (hasOwn(payload, 'enabled')) {
+    if (typeof payload.enabled !== 'boolean') return { ok: false, error: 'enabled must be true or false' };
+    update.enabled = payload.enabled;
+  }
+  if (hasOwn(payload, 'defaultModel')) {
+    const model = stripModelTierSuffix(payload.defaultModel);
+    if (!model || !isSafeClaudeModelId(model)) return { ok: false, error: 'Invalid Claude Cloud model ID' };
+    update.defaultModel = model;
+  }
+  if (hasOwn(payload, 'environmentId')) {
+    const environmentId = payload.environmentId === null ? '' : payload.environmentId;
+    if (typeof environmentId !== 'string') return { ok: false, error: 'Invalid environment id' };
+    const trimmed = environmentId.trim();
+    if (trimmed && !isSafeClaudeCloudId(trimmed)) return { ok: false, error: 'Invalid environment id' };
+    update.environmentId = trimmed;
+  }
+  if (!Object.keys(update).length) return { ok: false, error: 'No Claude Cloud settings update provided' };
+  return { ok: true, ...update };
+}
+
+export function createClaudeCloudSettingsService({
+  readSetting = () => '',
+  writeSetting = null,
+  deleteSetting = null,
+  // The Claude provider's settings: its model catalog is the cloud's too.
+  getClaudeProviderSettings = () => null,
+  // `claude auth status` of the host CLI (cached there); the account line.
+  claudeAuthService = null,
+  // shared/claude-cloud/credentials.mjs → describe(); never the token.
+  credentials = null,
+  // shared/claude-cloud/api-client.mjs → listEnvironments().
+  cloud = null,
+  emit = () => {},
+  now = () => Date.now(),
+  logger = console,
+} = {}) {
+  let environmentsCache = null;
+  let environmentsInFlight = null;
+
+  function readEnabled() {
+    return toText(readSetting(CLAUDE_CLOUD_ENABLED_SETTING_KEY)) === 'true';
+  }
+
+  function readDefaultModel() {
+    const stored = stripModelTierSuffix(readSetting(CLAUDE_CLOUD_DEFAULT_MODEL_SETTING_KEY));
+    return stored && isSafeClaudeModelId(stored) ? stored : DEFAULT_CLAUDE_CLOUD_MODEL;
+  }
+
+  function readEnvironmentId() {
+    const stored = toText(readSetting(CLAUDE_CLOUD_ENVIRONMENT_SETTING_KEY));
+    return isSafeClaudeCloudId(stored) ? stored : '';
+  }
+
+  function listModels(defaultModel) {
+    const claude = getClaudeProviderSettings() || {};
+    const catalog = Array.isArray(claude.models) && claude.models.length
+      ? claude.models
+      : (Array.isArray(claude.availableModels) ? claude.availableModels : []);
+    return buildClaudeCloudModelList(defaultModel, catalog);
+  }
+
+  /** What is stored, without any I/O beyond the settings table. */
+  function getSettings() {
+    const defaultModel = readDefaultModel();
+    return {
+      enabled: readEnabled(),
+      defaultModel,
+      environmentId: readEnvironmentId(),
+      models: listModels(defaultModel),
+      providerType: CLAUDE_CLOUD_PROVIDER_TYPE,
+    };
+  }
+
+  function describeToken() {
+    let described = null;
+    try {
+      described = credentials?.describe?.() || null;
+    } catch {
+      described = null;
+    }
+    const source = ['env', 'file'].includes(described?.source) ? described.source : 'none';
+    return {
+      source,
+      hasToken: described?.hasToken === true,
+      expiresAt: toText(described?.expiresAt) || null,
+      subscriptionType: toText(described?.subscriptionType) || null,
+    };
+  }
+
+  async function describeAccount(token) {
+    if (typeof claudeAuthService?.getStatus !== 'function') return null;
+    let status = null;
+    try {
+      status = await claudeAuthService.getStatus();
+    } catch {
+      status = claudeAuthService.getCachedStatus?.() || null;
+    }
+    if (!status || status.ok === false) return null;
+    return {
+      loggedIn: status.loggedIn === true,
+      email: toText(status.email) || null,
+      orgName: toText(status.orgName) || null,
+      subscriptionType: toText(status.subscriptionType) || token.subscriptionType || null,
+    };
+  }
+
+  function redact(text) {
+    const value = String(text ?? '');
+    try {
+      return typeof credentials?.redact === 'function' ? credentials.redact(value) : value;
+    } catch {
+      return 'The cloud environments could not be read.';
+    }
+  }
+
+  async function loadEnvironments({ force = false } = {}) {
+    if (!force && environmentsCache && (now() - environmentsCache.at) < ENVIRONMENTS_CACHE_MS) {
+      return environmentsCache.value;
+    }
+    if (environmentsInFlight) return environmentsInFlight;
+    environmentsInFlight = (async () => {
+      let value;
+      try {
+        if (typeof cloud?.listEnvironments !== 'function') throw new Error('The cloud client is unavailable.');
+        const listed = await cloud.listEnvironments();
+        const environments = (Array.isArray(listed) ? listed : [])
+          .filter((entry) => isSafeClaudeCloudId(entry?.id) && (!toText(entry?.state) || toText(entry.state) === 'active'))
+          .map((entry) => ({ id: entry.id, name: toText(entry?.name) || entry.id }));
+        value = { environments, environmentsError: null };
+      } catch (error) {
+        value = {
+          environments: null,
+          environmentsError: redact(toText(error?.message) || 'The cloud environments could not be read.').slice(0, 300),
+        };
+      }
+      environmentsCache = { at: now(), value };
+      return value;
+    })().finally(() => { environmentsInFlight = null; });
+    return environmentsInFlight;
+  }
+
+  /**
+   * The environment new sessions run in: the stored one, else the first
+   * active environment of the account, which is then stored. Empty when
+   * there is none (or the cloud cannot be asked).
+   */
+  async function resolveEnvironmentId({ force = false } = {}) {
+    const stored = readEnvironmentId();
+    if (stored) return stored;
+    if (!describeToken().hasToken) return '';
+    const { environments } = await loadEnvironments({ force });
+    const first = Array.isArray(environments) && environments.length ? environments[0].id : '';
+    if (first && typeof writeSetting === 'function') {
+      writeSetting(CLAUDE_CLOUD_ENVIRONMENT_SETTING_KEY, first);
+      logger?.log?.(`[claude-cloud] using cloud environment ${first}`);
+    }
+    return first;
+  }
+
+  /** The body of GET /api/settings/claude-cloud. */
+  async function describe({ refreshEnvironments = false } = {}) {
+    const token = describeToken();
+    const enabled = readEnabled();
+    // Nothing is asked of Anthropic while the provider is off.
+    const listing = enabled && token.hasToken
+      ? await loadEnvironments({ force: refreshEnvironments })
+      : { environments: null, environmentsError: null };
+    if (enabled && token.hasToken) await resolveEnvironmentId();
+    const settings = getSettings();
+    return {
+      enabled: settings.enabled,
+      defaultModel: settings.defaultModel,
+      environmentId: settings.environmentId || null,
+      environments: listing.environments,
+      environmentsError: listing.environmentsError,
+      account: await describeAccount(token),
+      token: { source: token.source, hasToken: token.hasToken, expiresAt: token.expiresAt },
+      models: settings.models,
+    };
+  }
+
+  /**
+   * POST /api/settings/claude-cloud. Returns `{ ok: true, settings }` (the GET
+   * body) or `{ ok: false, statusCode, error, code? }`.
+   */
+  async function update(body = {}) {
+    const parsed = parseClaudeCloudSettingsUpdateRequest(body);
+    if (!parsed.ok) return { ok: false, statusCode: 400, error: parsed.error };
+    if (typeof writeSetting !== 'function') {
+      return { ok: false, statusCode: 500, error: 'Claude Cloud settings are unavailable' };
+    }
+    if (parsed.enabled === true && !readEnabled() && !describeToken().hasToken) {
+      return {
+        ok: false,
+        statusCode: 400,
+        code: 'claude_cloud_login_missing',
+        error: 'Claude Cloud needs the Claude CLI login on this host. Log in on Settings → Providers → Claude, then switch it on.',
+      };
+    }
+    if (hasOwn(parsed, 'enabled')) writeSetting(CLAUDE_CLOUD_ENABLED_SETTING_KEY, parsed.enabled ? 'true' : 'false');
+    if (hasOwn(parsed, 'defaultModel')) writeSetting(CLAUDE_CLOUD_DEFAULT_MODEL_SETTING_KEY, parsed.defaultModel);
+    if (hasOwn(parsed, 'environmentId')) {
+      if (parsed.environmentId) writeSetting(CLAUDE_CLOUD_ENVIRONMENT_SETTING_KEY, parsed.environmentId);
+      else if (typeof deleteSetting === 'function') deleteSetting(CLAUDE_CLOUD_ENVIRONMENT_SETTING_KEY);
+      else writeSetting(CLAUDE_CLOUD_ENVIRONMENT_SETTING_KEY, '');
+    }
+    // Switching it on reads the environments afresh: the account may have
+    // changed since they were last listed.
+    const settings = await describe({ refreshEnvironments: parsed.enabled === true });
+    emit('claude_cloud_settings_updated', settings);
+    return { ok: true, settings };
+  }
+
+  return { getSettings, describe, update, resolveEnvironmentId };
+}