@oar-sh/oar 0.9.0

package/server/services/conversation-preferences-service.mjs

@@ -0,0 +1,208 @@
+'use strict';
+
+import { parseAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
+import {
+  DEFAULT_THINKING_DISPLAY,
+  DEFAULT_THINKING_ENABLED,
+  parseThinkingDisplay,
+  parseThinkingEnabled,
+} from '../../shared/claude-thinking.mjs';
+
+function normalizeModeWith(value, normalizeMode) {
+  if (typeof normalizeMode === 'function') {
+    const normalized = normalizeMode(value);
+    const text = String(normalized || '').trim();
+    return text || null;
+  }
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+export function normalizePreferredModel(value) {
+  return String(value || '').trim();
+}
+
+export function normalizePreferredReasoningEffort(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+export function persistConversationPreferences({
+  db,
+  stmts,
+  conversationId = '',
+  preferredRelayMode = '',
+  preferredModel = '',
+  preferredReasoningEffort = '',
+  // `undefined` means "not part of this write" — the composer PATCHes the same
+  // route without ever mentioning the window, and must not clear it.
+  autoCompactWindow = undefined,
+  // Same contract for the thinking control: `undefined` leaves the stored
+  // value alone. Anything else is resolved through the shared parsers, whose
+  // fallback is the relay default (on / summarized).
+  thinkingEnabled = undefined,
+  thinkingDisplay = undefined,
+  updatedAt = new Date().toISOString(),
+  createIfMissing = false,
+  createTitle = 'Session',
+  tolerateMissingColumns = false,
+} = {}) {
+  const convId = String(conversationId || '').trim();
+  const mode = String(preferredRelayMode || '').trim();
+  const model = normalizePreferredModel(preferredModel);
+  const reasoningEffort = normalizePreferredReasoningEffort(preferredReasoningEffort);
+  const writesAutoCompactWindow = autoCompactWindow !== undefined;
+  const window = writesAutoCompactWindow ? parseAutoCompactWindow(autoCompactWindow) : null;
+  const writesThinkingEnabled = thinkingEnabled !== undefined;
+  const enabled = writesThinkingEnabled ? parseThinkingEnabled(thinkingEnabled) : DEFAULT_THINKING_ENABLED;
+  const writesThinkingDisplay = thinkingDisplay !== undefined;
+  const display = writesThinkingDisplay ? parseThinkingDisplay(thinkingDisplay) : null;
+  if (!db || !stmts || !convId || !mode) {
+    return {
+      ok: false,
+      created: false,
+      preferredRelayMode: mode,
+      preferredModel: '',
+      preferredReasoningEffort: '',
+      autoCompactWindow: null,
+      thinkingEnabled: DEFAULT_THINKING_ENABLED,
+      thinkingDisplay: DEFAULT_THINKING_DISPLAY,
+      updatedAt,
+    };
+  }
+  const safeTitle = String(createTitle || '').trim() || 'Session';
+  const writePreferences = db.transaction(() => {
+    const existing = typeof stmts.getConvAnyStatus?.get === 'function'
+      ? (stmts.getConvAnyStatus.get(convId) || null)
+      : null;
+    if (!existing && createIfMissing && typeof stmts.insertConv?.run === 'function') {
+      stmts.insertConv.run(convId, safeTitle, updatedAt, updatedAt);
+    }
+    // Extra per-conversation setting columns this write mentions. The prepared
+    // statement can't carry them, and these writes are rare (one control
+    // change each) — the dynamic form keeps the hot composer path on the
+    // prepared statement.
+    const extraSets = [];
+    const extraValues = [];
+    if (writesAutoCompactWindow) {
+      extraSets.push('auto_compact_window = ?');
+      extraValues.push(window);
+    }
+    // Both axes store the RESOLVED value, never NULL-as-default: NULL means
+    // "never set" and is read back as the relay default, so canonicalizing a
+    // default choice to NULL would silently re-point those rows if the relay
+    // default ever changed.
+    if (writesThinkingEnabled) {
+      extraSets.push('thinking_enabled = ?');
+      extraValues.push(enabled ? 1 : 0);
+    }
+    if (writesThinkingDisplay) {
+      extraSets.push('thinking_display = ?');
+      extraValues.push(display);
+    }
+    try {
+      if (extraSets.length) {
+        db.prepare(`
+          UPDATE conversations
+          SET preferred_relay_mode = ?, preferred_model = ?, preferred_reasoning_effort = ?,
+              ${extraSets.join(', ')}, updated_at = ?
+          WHERE id = ?
+        `).run(mode, model || null, reasoningEffort || null, ...extraValues, updatedAt, convId);
+      } else if (typeof stmts.updateConvPreferences?.run === 'function') {
+        stmts.updateConvPreferences.run(mode, model || null, reasoningEffort || null, updatedAt, convId);
+      } else {
+        db.prepare(`
+          UPDATE conversations
+          SET preferred_relay_mode = ?, preferred_model = ?, preferred_reasoning_effort = ?, updated_at = ?
+          WHERE id = ?
+        `).run(mode, model || null, reasoningEffort || null, updatedAt, convId);
+      }
+    } catch (error) {
+      if (!tolerateMissingColumns) throw error;
+    }
+    return {
+      ok: true,
+      created: !existing,
+      preferredRelayMode: mode,
+      preferredModel: model,
+      preferredReasoningEffort: reasoningEffort,
+      // Always echoed, so a write that didn't touch the window still tells the
+      // client what the stored value is.
+      autoCompactWindow: writesAutoCompactWindow
+        ? window
+        : parseAutoCompactWindow(existing?.auto_compact_window),
+      thinkingEnabled: writesThinkingEnabled
+        ? enabled
+        : parseThinkingEnabled(existing?.thinking_enabled),
+      thinkingDisplay: writesThinkingDisplay
+        ? display
+        : parseThinkingDisplay(existing?.thinking_display),
+      updatedAt,
+    };
+  });
+  return writePreferences();
+}
+
+export function persistConversationModelPreference({
+  db,
+  stmts,
+  conversationId = '',
+  relayMode = '',
+  model = '',
+  reasoningEffort = '',
+  normalizeMode,
+  fallbackRelayMode = 'agent',
+  updatedAt = new Date().toISOString(),
+  createIfMissing = false,
+  createTitle = 'Session',
+  tolerateMissingColumns = false,
+} = {}) {
+  const convId = String(conversationId || '').trim();
+  const modelText = normalizePreferredModel(model);
+  const normalizedRelayMode = normalizeModeWith(relayMode, normalizeMode);
+  const fallbackMode = normalizeModeWith(fallbackRelayMode, normalizeMode) || String(fallbackRelayMode || '').trim() || 'agent';
+  const mode = normalizedRelayMode || fallbackMode;
+  const effortText = normalizePreferredReasoningEffort(reasoningEffort);
+  if (!db || !stmts || !convId || !mode || !modelText) {
+    return {
+      ok: false,
+      created: false,
+      preferredRelayMode: mode || fallbackMode,
+      preferredModel: '',
+      preferredReasoningEffort: '',
+      updatedAt,
+    };
+  }
+
+  const safeTitle = String(createTitle || '').trim() || 'Session';
+  const writeModelPreference = db.transaction(() => {
+    const existing = typeof stmts.getConvAnyStatus?.get === 'function'
+      ? (stmts.getConvAnyStatus.get(convId) || null)
+      : null;
+    if (!existing && createIfMissing && typeof stmts.insertConv?.run === 'function') {
+      stmts.insertConv.run(convId, safeTitle, updatedAt, updatedAt);
+    }
+    const effort = effortText || normalizePreferredReasoningEffort(existing?.preferred_reasoning_effort);
+    try {
+      if (typeof stmts.updateConvPreferences?.run === 'function') {
+        stmts.updateConvPreferences.run(mode, modelText, effort || null, updatedAt, convId);
+      } else {
+        db.prepare(`
+          UPDATE conversations
+          SET preferred_relay_mode = ?, preferred_model = ?, preferred_reasoning_effort = ?, updated_at = ?
+          WHERE id = ?
+        `).run(mode, modelText, effort || null, updatedAt, convId);
+      }
+    } catch (error) {
+      if (!tolerateMissingColumns) throw error;
+    }
+    return {
+      ok: true,
+      created: !existing,
+      preferredRelayMode: mode,
+      preferredModel: modelText,
+      preferredReasoningEffort: effort,
+      updatedAt,
+    };
+  });
+  return writeModelPreference();
+}

package/server/services/cursor-dashboard-usage.mjs

@@ -0,0 +1,217 @@
+'use strict';
+
+/**
+ * Live Cursor plan quota for the Check Usage card.
+ *
+ * The Cursor API key exposes no plan/usage surface (`/v1/agents/:id/usage` is
+ * feature-gated, everything else 404s). The percentages shown on
+ * cursor.com/dashboard ("Included in Ultra": Total / Auto / API) come from the
+ * dashboard's own web API, which authenticates with the browser session
+ * cookie:
+ *
+ *   POST https://cursor.com/api/dashboard/get-current-period-usage
+ *   Cookie: WorkosCursorSessionToken=<token>
+ *   Origin: https://cursor.com
+ *
+ * The token resolves automatically from the relay host's Cursor IDE login
+ * (state.vscdb `cursorAuth/accessToken`, same host-login trust model as the
+ * Grok CLI's auth.json) — the cookie is `<sub-user-id>::<access JWT>`. A
+ * manually pasted cookie (DevTools → Application → Cookies → cursor.com)
+ * takes precedence for headless hosts without an IDE install. On 401/expiry
+ * the card silently degrades to the local estimated view. Tokens never leave
+ * the relay and are never echoed back to clients.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const requireModule = createRequire(import.meta.url);
+
+export const CURSOR_DASHBOARD_USAGE_URL = 'https://cursor.com/api/dashboard/get-current-period-usage';
+const FETCH_TIMEOUT_MS = 6_000;
+// The IDE access token lives for months; re-reading the multi-MB state.vscdb
+// on every Check Usage open would be wasteful.
+const IDE_TOKEN_CACHE_MS = 5 * 60_000;
+
+/**
+ * Default locations of the Cursor IDE's state database per platform.
+ */
+export function defaultCursorStateDbPath({ platform = process.platform, env = process.env, homeDir = os.homedir() } = {}) {
+  if (platform === 'win32') {
+    const appData = String(env.APPDATA || '').trim() || path.join(homeDir, 'AppData', 'Roaming');
+    return path.join(appData, 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+  }
+  if (platform === 'darwin') {
+    return path.join(homeDir, 'Library', 'Application Support', 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+  }
+  return path.join(homeDir, '.config', 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+}
+
+/**
+ * Build the dashboard session cookie value from an IDE access token:
+ * `WorkosCursorSessionToken=<userId>%3A%3A<jwt>` where userId is the JWT
+ * `sub` claim with its provider prefix stripped. Pure; null when the token
+ * is malformed or expired.
+ */
+export function sessionTokenFromAccessToken(accessToken, { now = () => Date.now() } = {}) {
+  const token = String(accessToken || '').trim();
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  let payload;
+  try {
+    payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+  const sub = String(payload?.sub || '').trim();
+  if (!sub) return null;
+  const exp = Number(payload?.exp);
+  if (Number.isFinite(exp) && exp * 1000 <= now()) return null;
+  const userId = sub.includes('|') ? sub.split('|').pop() : sub;
+  return `${userId}%3A%3A${token}`;
+}
+
+/**
+ * Read the Cursor IDE's login from state.vscdb and build the dashboard
+ * session token from it — the same host-login trust model as the Grok CLI's
+ * auth.json. The db is opened READ-ONLY in place: it can be multiple GB, so
+ * copying it is not an option, and SQLite's WAL mode supports concurrent
+ * readers next to the running IDE. Never throws; null when the IDE is
+ * absent, logged out, or the db is momentarily locked.
+ */
+export function readCursorIdeSessionToken({
+  stateDbPath = defaultCursorStateDbPath(),
+  fsImpl = fs,
+  loadDatabase = null,
+  now = () => Date.now(),
+} = {}) {
+  try {
+    if (!fsImpl.existsSync(stateDbPath)) return null;
+    // Lazy-required so importing this module never pays the native-module cost.
+    const openDatabase = loadDatabase
+      || ((file) => requireModule('better-sqlite3')(file, { readonly: true, fileMustExist: true, timeout: 1500 }));
+    const db = openDatabase(stateDbPath);
+    try {
+      const row = db.prepare("SELECT value FROM ItemTable WHERE key = 'cursorAuth/accessToken'").get();
+      return sessionTokenFromAccessToken(row?.value, { now });
+    } finally {
+      try { db.close(); } catch { /* ignore */ }
+    }
+  } catch {
+    return null;
+  }
+}
+
+function toPercent(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : null;
+}
+
+function toCents(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? numeric : null;
+}
+
+function toIso(value) {
+  if (value === null || value === undefined || value === '') return null;
+  // The endpoint has shipped both ISO strings and unix-ms strings.
+  const asNumber = Number(value);
+  const timestamp = Number.isFinite(asNumber) && asNumber > 10_000_000_000
+    ? asNumber
+    : Date.parse(String(value));
+  return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
+}
+
+/**
+ * Normalize the dashboard payload into the fields the plan card needs.
+ * Handles both the flat `planUsage` shape and the older
+ * `individualUsage.plan` shape from /api/usage-summary. Pure; null when
+ * nothing usable is present.
+ */
+export function normalizeCursorDashboardUsage(payload = null) {
+  if (!payload || typeof payload !== 'object') return null;
+  const plan = (payload.planUsage && typeof payload.planUsage === 'object')
+    ? payload.planUsage
+    : (payload.individualUsage?.plan && typeof payload.individualUsage.plan === 'object'
+      ? payload.individualUsage.plan
+      : null);
+  if (!plan) return null;
+
+  const normalized = {
+    totalPercentUsed: toPercent(plan.totalPercentUsed),
+    autoPercentUsed: toPercent(plan.autoPercentUsed),
+    apiPercentUsed: toPercent(plan.apiPercentUsed),
+    includedSpendCents: toCents(plan.includedSpend ?? plan.totalSpend),
+    limitCents: toCents(plan.limit),
+    remainingCents: toCents(plan.remaining),
+    billingCycleStart: toIso(payload.billingCycleStart),
+    billingCycleEnd: toIso(payload.billingCycleEnd),
+    membershipType: String(payload.membershipType || '').trim() || null,
+    displayMessage: String(payload.displayMessage || '').trim() || null,
+    onDemand: (() => {
+      const spend = payload.spendLimitUsage && typeof payload.spendLimitUsage === 'object'
+        ? payload.spendLimitUsage
+        : (payload.individualUsage?.onDemand && typeof payload.individualUsage.onDemand === 'object'
+          ? payload.individualUsage.onDemand
+          : null);
+      if (!spend) return null;
+      const usedCents = toCents(spend.individualUsed ?? spend.totalSpend ?? spend.used);
+      const limitCents = toCents(spend.individualLimit ?? spend.limit);
+      if (usedCents === null && limitCents === null) return null;
+      return { usedCents, limitCents };
+    })(),
+  };
+
+  const hasSignal = normalized.totalPercentUsed !== null
+    || normalized.autoPercentUsed !== null
+    || normalized.apiPercentUsed !== null
+    || normalized.includedSpendCents !== null;
+  return hasSignal ? normalized : null;
+}
+
+/**
+ * Build the best-effort fetcher the usage route calls. Token resolution: a
+ * manually stored session token wins (headless hosts), otherwise the host's
+ * Cursor IDE login is used automatically. Errors, missing or expired tokens
+ * yield `null` so the card degrades to the estimated view.
+ */
+export function createCursorDashboardUsageFetcher({
+  getSessionToken = () => '',
+  readIdeTokenImpl = readCursorIdeSessionToken,
+  fetchImpl = globalThis.fetch,
+  url = CURSOR_DASHBOARD_USAGE_URL,
+  timeoutMs = FETCH_TIMEOUT_MS,
+  now = () => Date.now(),
+} = {}) {
+  let cachedIdeToken = null;
+  let cachedIdeTokenAt = 0;
+  const resolveIdeToken = () => {
+    if (cachedIdeToken && now() - cachedIdeTokenAt < IDE_TOKEN_CACHE_MS) return cachedIdeToken;
+    cachedIdeToken = readIdeTokenImpl() || null;
+    cachedIdeTokenAt = now();
+    return cachedIdeToken;
+  };
+  return async function fetchCursorDashboardUsage() {
+    if (typeof fetchImpl !== 'function') return null;
+    const token = String(getSessionToken() || '').trim() || resolveIdeToken();
+    if (!token) return null;
+    try {
+      const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: {
+          Cookie: `WorkosCursorSessionToken=${token}`,
+          Origin: 'https://cursor.com',
+          'Content-Type': 'application/json',
+        },
+        body: '{}',
+        signal: AbortSignal.timeout?.(timeoutMs),
+      });
+      if (!response?.ok) return null;
+      return normalizeCursorDashboardUsage(await response.json());
+    } catch {
+      return null;
+    }
+  };
+}

package/server/services/cursor-session-root-service.mjs

@@ -0,0 +1,62 @@
+'use strict';
+
+import nodeFs from 'fs';
+import nodePath from 'path';
+
+// Resolve the on-disk folder the Cursor SDK integration keeps for one session,
+// so the file explorer's Session root works on `cursor`-provider conversations.
+//
+// The Cursor worker roots its per-session agent store at
+// `<storeDir>/<sdkSessionId>/` (see cursor-session-worker.mjs / the storePath
+// in cursor-sdk-adapter.mjs), where storeDir is `$CURSOR_AGENT_STORE_DIR` or
+// `<serverDir>/data/cursor-agents`. The directory is created on the session's
+// first turn, so a missing directory means "nothing to browse yet" rather than
+// an error — the resolver returns null and the Session button stays disabled
+// until the first turn lands.
+
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function normalizeText(value) {
+  const text = String(value || '').trim();
+  return text || '';
+}
+
+export function resolveCursorAgentStoreDir({
+  env = process.env,
+  serverDir = '',
+  path = nodePath,
+} = {}) {
+  const override = normalizeText(env?.CURSOR_AGENT_STORE_DIR);
+  if (override) return override;
+  const base = normalizeText(serverDir);
+  if (!base) return '';
+  return path.join(base, 'data', 'cursor-agents');
+}
+
+export function createCursorSessionRootResolver({
+  fs = nodeFs,
+  path = nodePath,
+  env = process.env,
+  serverDir = '',
+} = {}) {
+  /**
+   * @returns {{ sessionRootPath: string, sessionRootName: string } | null}
+   */
+  function resolveCursorSessionRoot({ sdkSessionId = '' } = {}) {
+    const sessionId = normalizeText(sdkSessionId);
+    // The id is joined into a filesystem path, so it is validated before any
+    // syscall (mirrors the Claude session-root resolver).
+    if (!SESSION_ID_PATTERN.test(sessionId)) return null;
+    const storeDir = resolveCursorAgentStoreDir({ env, serverDir, path });
+    if (!storeDir) return null;
+    const sessionRootPath = path.join(storeDir, sessionId);
+    try {
+      if (!fs.statSync(sessionRootPath).isDirectory()) return null;
+    } catch {
+      return null;
+    }
+    return { sessionRootPath, sessionRootName: 'Session' };
+  }
+
+  return { resolveCursorSessionRoot };
+}

package/server/services/delete-archive-service.mjs

@@ -0,0 +1,154 @@
+const DEFAULT_DELETE_RETRIES = 3;
+const RETRY_DELAYS_MS = [250, 500];
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeConversationId(value) {
+  return String(value || '').trim();
+}
+
+function createSdkDeleteSessionCaller(sdkClient) {
+  if (sdkClient && typeof sdkClient.deleteSession === 'function') {
+    return sdkClient.deleteSession.bind(sdkClient);
+  }
+  let warned = false;
+  return async (sessionId) => {
+    if (!warned) {
+      warned = true;
+      console.warn(`[delete-archive] SDK deleteSession() is unavailable; skipping remote delete lifecycle.`);
+    }
+    return { ok: true, skipped: true, sessionId };
+  };
+}
+
+import { cleanupGeneratedImagesForConversation } from './generated-image-cleanup-service.mjs';
+
+export function createDeleteArchiveService(db, sdkClient, { resolveSessionStateRoot = null } = {}) {
+  const callDeleteSession = createSdkDeleteSessionCaller(sdkClient);
+
+  const stmts = {
+    getConversation: db.prepare(`
+      SELECT c.id, c.status, c.sdk_session_id
+      FROM conversations c
+      WHERE c.id = ?
+      LIMIT 1
+    `),
+    markDeleted: db.prepare(`UPDATE conversations SET status = 'deleted', updated_at = ? WHERE id = ?`),
+    markArchived: db.prepare(`UPDATE conversations SET archived = 1, updated_at = ? WHERE id = ?`),
+    listDeletedWithSdkSession: db.prepare(`
+      SELECT c.id, c.sdk_session_id
+      FROM conversations c
+      WHERE c.status = 'deleted'
+      ORDER BY c.updated_at ASC
+    `),
+    listConversationMessages: db.prepare(`
+      SELECT attachments
+      FROM messages
+      WHERE conversation_id = ?
+      ORDER BY timestamp ASC
+    `),
+    hardDeleteConversation: db.transaction((conversationId) => {
+      db.prepare(`DELETE FROM relay_questions WHERE conversation_id = ?`).run(conversationId);
+      db.prepare(`DELETE FROM relay_boards WHERE conversation_id = ?`).run(conversationId);
+      db.prepare(`DELETE FROM queue WHERE conversation_id = ?`).run(conversationId);
+      db.prepare(`DELETE FROM messages WHERE conversation_id = ?`).run(conversationId);
+      db.prepare(`DELETE FROM runtime_sessions WHERE conversation_id = ?`).run(conversationId);
+      db.prepare(`DELETE FROM conversations WHERE id = ?`).run(conversationId);
+    }),
+  };
+
+  async function deleteSdkSessionWithRetries(sdkSessionId, conversationId) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= DEFAULT_DELETE_RETRIES; attempt += 1) {
+      try {
+        await callDeleteSession(sdkSessionId);
+        return { ok: true };
+      } catch (error) {
+        lastError = error;
+        const suffix = attempt >= DEFAULT_DELETE_RETRIES ? ' (no more retries)' : '';
+        console.warn(
+          `[delete-archive] SDK delete failed for conversation=${conversationId}, session=${sdkSessionId}, attempt=${attempt}/${DEFAULT_DELETE_RETRIES}${suffix}: ${error?.message || error}`
+        );
+        if (attempt < DEFAULT_DELETE_RETRIES) {
+          await sleep(RETRY_DELAYS_MS[attempt - 1] || RETRY_DELAYS_MS[RETRY_DELAYS_MS.length - 1] || 0);
+        }
+      }
+    }
+    return { ok: false, error: lastError };
+  }
+
+  async function hardDeleteConversation(conversationId) {
+    const row = stmts.getConversation.get(conversationId);
+    cleanupGeneratedImagesForConversation({
+      conversationId,
+      sdkSessionId: String(row?.sdk_session_id || '').trim() || null,
+      messageRows: stmts.listConversationMessages.all(conversationId),
+      resolveSessionStateRoot,
+    });
+    stmts.hardDeleteConversation(conversationId);
+  }
+
+  async function deleteConversation(conversationId) {
+    const id = normalizeConversationId(conversationId);
+    if (!id) return { ok: false, error: 'Missing conversation id' };
+
+    const row = stmts.getConversation.get(id);
+    if (!row) return { ok: true, alreadyDeleted: true };
+    if (row.status === 'deleted') return { ok: true, alreadyDeleted: true, tombstoned: true };
+
+    stmts.markDeleted.run(new Date().toISOString(), id);
+
+    const sdkSessionId = String(row.sdk_session_id || '').trim();
+
+    if (!sdkSessionId) {
+      await hardDeleteConversation(id);
+      return { ok: true, deleted: true, tombstoned: true };
+    }
+
+    const sdkDeleteResult = await deleteSdkSessionWithRetries(sdkSessionId, id);
+    if (sdkDeleteResult.ok) {
+      await hardDeleteConversation(id);
+      return { ok: true, deleted: true, tombstoned: true, sdkDeleted: true };
+    }
+
+    console.warn(`[delete-archive] Leaving tombstoned conversation=${id}; SDK delete failed. Will retry on next startup.`);
+    return { ok: true, deleted: false, tombstoned: true, sdkDeleted: false };
+  }
+
+  async function archiveConversation(conversationId) {
+    const id = normalizeConversationId(conversationId);
+    if (!id) return { ok: false, error: 'Missing conversation id' };
+
+    const row = stmts.getConversation.get(id);
+    if (!row) return { ok: true, alreadyDeleted: true };
+    if (row.status === 'deleted') return { ok: true, alreadyDeleted: true, tombstoned: true };
+
+    stmts.markArchived.run(new Date().toISOString(), id);
+    return { ok: true, archived: true };
+  }
+
+  async function retryPendingDeletesOnStartup() {
+    const pendingRows = stmts.listDeletedWithSdkSession.all();
+    for (const row of pendingRows) {
+      if (!row || !row.id) continue;
+      const id = String(row.id).trim();
+      if (!id) continue;
+      const sdkSessionId = String(row.sdk_session_id || '').trim();
+      if (!sdkSessionId) {
+        await hardDeleteConversation(id);
+        continue;
+      }
+      const sdkDeleteResult = await deleteSdkSessionWithRetries(sdkSessionId, id);
+      if (sdkDeleteResult.ok) {
+        await hardDeleteConversation(id);
+      } else {
+        console.warn(`[delete-archive] Startup retry failed for conversation=${id}; tombstone retained for next restart.`);
+      }
+    }
+    return { ok: true, pendingCount: pendingRows.length };
+  }
+
+  return { deleteConversation, archiveConversation, retryPendingDeletesOnStartup };
+}