@cloudcli-ai/cloudcli 1.37.2 → 1.37.4

package/server/modules/agent/tests/agent-run-registration.test.ts

@@ -0,0 +1,348 @@
+import assert from 'node:assert/strict';
+import * as nodeCrypto from 'node:crypto';
+import { once } from 'node:events';
+import { mkdtemp, rm } from 'node:fs/promises';
+import type { AddressInfo } from 'node:net';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import express from 'express';
+
+import { closeConnection, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
+import { chatRunRegistry, connectedClients } from '@/modules/websocket/index.js';
+import type { NormalizedMessage } from '@/shared/types.js';
+import { createNormalizedMessage } from '@/shared/utils.js';
+
+import { createAgentRouter } from '../agent.routes.js';
+
+/**
+ * `POST /api/agent` runs a provider for an API-key caller. Until now it wrote
+ * the run's events straight to the HTTP response and nothing else knew: the
+ * session was not on the running-sessions list, no tab could subscribe to
+ * it, and a second request could start a second run on the same session. It
+ * now registers the run with the chat run registry the way a `chat.send`
+ * does, with the HTTP response as the run's first audience.
+ */
+
+type AgentDependencies = Parameters<typeof createAgentRouter>[0];
+type RunFunction = AgentDependencies['queryClaude'];
+
+async function withIsolatedDatabase(run: () => Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'agent-run-registration-'));
+  closeConnection();
+  process.env.DATABASE_PATH = path.join(tempDirectory, 'auth.db');
+  await initializeDatabase();
+  try {
+    await run();
+  } finally {
+    connectedClients.clear();
+    chatRunRegistry.clearAll();
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+function createDependencies(queryClaude: RunFunction): AgentDependencies {
+  const unexpected = async (): Promise<never> => { throw new Error('unexpected provider call'); };
+  return {
+    fileSystem: { access: async () => undefined } as unknown as AgentDependencies['fileSystem'],
+    crypto: nodeCrypto,
+    homeDirectory: () => '/home/test',
+    spawnProcess: (() => { throw new Error('spawn should not run'); }) as unknown as AgentDependencies['spawnProcess'],
+    platformMode: true,
+    users: { getFirstUser: () => ({ id: 1, username: 'test-user' }) },
+    apiKeys: { validateApiKey: () => undefined },
+    githubTokens: { getActiveGithubToken: () => null },
+    projects: { createProjectPath: () => ({ outcome: 'created' }) },
+    models: { getProviderModels: async () => ({ OPTIONS: [], DEFAULT: 'default-model' }) } as unknown as AgentDependencies['models'],
+    sessions: {
+      getSessionById: (sessionId) => sessionsDb.getSessionById(sessionId),
+      getSessionByProviderSessionId: (providerSessionId) => sessionsDb.getSessionByProviderSessionId(providerSessionId),
+      createAppSession: (provider, projectPath, initialMessage) => {
+        const sessionId = `app-${initialMessage.length}-${nodeCrypto.randomUUID()}`;
+        sessionsDb.createAppSession(sessionId, provider, projectPath, initialMessage);
+        return { sessionId };
+      },
+    },
+    runs: chatRunRegistry,
+    queryClaude,
+    queryCursor: unexpected as RunFunction,
+    queryCodex: unexpected as RunFunction,
+    queryOpenCode: unexpected as RunFunction,
+    GithubClient: class {} as unknown as AgentDependencies['GithubClient'],
+  };
+}
+
+async function withAgentServer(dependencies: AgentDependencies, run: (baseUrl: string) => Promise<void>): Promise<void> {
+  const app = express();
+  app.use(express.json());
+  app.use('/api/agent', createAgentRouter(dependencies));
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  try {
+    const address = server.address() as AddressInfo;
+    await run(`http://127.0.0.1:${address.port}`);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+const post = (baseUrl: string, body: Record<string, unknown>) =>
+  fetch(`${baseUrl}/api/agent`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+
+const readEvents = async (response: Response): Promise<Array<Record<string, unknown>>> =>
+  (await response.text())
+    .split('\n\n')
+    .filter((frame) => frame.startsWith('data: '))
+    .map((frame) => JSON.parse(frame.slice('data: '.length)) as Record<string, unknown>);
+
+/** A runtime that announces its native session id, streams one text event, and waits to be released before completing. */
+function createHeldRuntime(nativeSessionId = 'native-1') {
+  let release: () => void = () => undefined;
+  const released = new Promise<void>((resolve) => { release = resolve; });
+  const seen: Array<{ sessionId: unknown; writerIsGateway: boolean }> = [];
+  const queryClaude: RunFunction = async (_command, options, writer) => {
+    seen.push({ sessionId: (options as { sessionId?: unknown }).sessionId, writerIsGateway: Boolean((writer as { isWebSocketWriter?: boolean }).isWebSocketWriter) });
+    // A resumed session announces the id it resumed under; a new one, a fresh id.
+    const announced = (writer as { getSessionId?: () => string | null }).getSessionId?.() ?? nativeSessionId;
+    writer.send(createNormalizedMessage({ kind: 'session_created', provider: 'claude', sessionId: announced, newSessionId: announced }));
+    writer.send(createNormalizedMessage({ kind: 'text', provider: 'claude', sessionId: announced, role: 'assistant', content: 'hello' }));
+    await released;
+    writer.send(createNormalizedMessage({ kind: 'complete', provider: 'claude', sessionId: announced, exitCode: 0 }));
+  };
+  return { queryClaude, release, seen };
+}
+
+test('an API run is registered like a chat send: listed while running, streamed decorated, mapped to its native id', async () => {
+  await withIsolatedDatabase(async () => {
+    const runtime = createHeldRuntime();
+    await withAgentServer(createDependencies(runtime.queryClaude), async (baseUrl) => {
+      const responsePromise = post(baseUrl, { projectPath: '/home/test/project', message: 'Run it' });
+      // Wait for the runtime to be entered.
+      for (let i = 0; i < 50 && runtime.seen.length === 0; i += 1) {
+        await new Promise((resolve) => { setTimeout(resolve, 20); });
+      }
+
+      const [running] = chatRunRegistry.listRunningRuns();
+      assert.ok(running, 'the run is on the running-sessions list while the provider works');
+      assert.equal(running.provider, 'claude');
+      assert.match(running.sessionId, /^app-/, 'listed under the app session id the route allocated');
+      assert.deepEqual(runtime.seen, [{ sessionId: running.sessionId, writerIsGateway: true }], 'the runtime gets the app id and the run\'s gateway writer');
+      // A tab that opens the session mid-run replays what it missed.
+      assert.deepEqual(chatRunRegistry.replayEvents(running.sessionId, 0).map((event) => event.kind), ['text']);
+
+      runtime.release();
+      const response = await responsePromise;
+      assert.equal(response.status, 200);
+      assert.match(response.headers.get('content-type') ?? '', /^text\/event-stream/);
+      const events = await readEvents(response);
+      assert.deepEqual(events.map((event) => event.type ?? event.kind), ['status', 'session-id', 'text', 'complete', 'done']);
+      assert.equal(events[1]?.sessionId, running.sessionId, 'session-id names the app session, not the provider\'s');
+      // Provider events reach the stream as a tab would see them: app session id, sequenced, no session_created.
+      const text = events[2] as NormalizedMessage;
+      assert.equal(text.sessionId, running.sessionId);
+      assert.equal(text.seq, 1);
+
+      assert.equal(chatRunRegistry.isProcessing(running.sessionId), false, 'the terminal complete ends the run');
+      assert.equal(sessionsDb.getSessionById(running.sessionId)?.provider_session_id, 'native-1', 'the native id the runtime announced is mapped onto the row');
+    });
+  });
+});
+
+test('a second API request on a session mid-run is refused with 409, as the chat socket refuses it', async () => {
+  await withIsolatedDatabase(async () => {
+    const runtime = createHeldRuntime();
+    await withAgentServer(createDependencies(runtime.queryClaude), async (baseUrl) => {
+      const first = post(baseUrl, { projectPath: '/home/test/project', message: 'Run it' });
+      for (let i = 0; i < 50 && runtime.seen.length === 0; i += 1) {
+        await new Promise((resolve) => { setTimeout(resolve, 20); });
+      }
+      const [running] = chatRunRegistry.listRunningRuns();
+      assert.ok(running);
+
+      const second = await post(baseUrl, { projectPath: '/home/test/project', message: 'Again', sessionId: running.sessionId, stream: false });
+      assert.equal(second.status, 409);
+      assert.equal(runtime.seen.length, 1, 'the provider is not entered twice');
+
+      runtime.release();
+      await first;
+    });
+  });
+});
+
+test('a non-streaming API run answers with the app session id and is off the list once done', async () => {
+  await withIsolatedDatabase(async () => {
+    const runtime = createHeldRuntime();
+    runtime.release();
+    await withAgentServer(createDependencies(runtime.queryClaude), async (baseUrl) => {
+      const response = await post(baseUrl, { projectPath: '/home/test/project', message: 'Run it', stream: false });
+      assert.equal(response.status, 200);
+      const body = await response.json() as { success: boolean; sessionId: string };
+      assert.equal(body.success, true);
+      assert.match(body.sessionId, /^app-/);
+      assert.deepEqual(chatRunRegistry.listRunningRuns(), []);
+    });
+  });
+});
+
+test('an API run continues a session the caller names by either id, and refuses one that does not exist', async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('app-existing', 'claude', '/home/test/project', 'Existing');
+    sessionsDb.assignProviderSessionId('app-existing', 'native-existing');
+    const runtime = createHeldRuntime();
+    runtime.release();
+    await withAgentServer(createDependencies(runtime.queryClaude), async (baseUrl) => {
+      const byAppId = await post(baseUrl, { projectPath: '/home/test/project', message: 'More', sessionId: 'app-existing', stream: false });
+      assert.equal(byAppId.status, 200);
+      assert.equal((await byAppId.json() as { sessionId: string }).sessionId, 'app-existing');
+
+      // A caller that stored the provider-native id an earlier response gave it.
+      const byNativeId = await post(baseUrl, { projectPath: '/home/test/project', message: 'More', sessionId: 'native-existing', stream: false });
+      assert.equal(byNativeId.status, 200);
+      assert.equal((await byNativeId.json() as { sessionId: string }).sessionId, 'app-existing');
+      assert.deepEqual(runtime.seen.map((call) => call.sessionId), ['app-existing', 'app-existing']);
+
+      const unknown = await post(baseUrl, { projectPath: '/home/test/project', message: 'More', sessionId: 'nope', stream: false });
+      assert.equal(unknown.status, 404);
+      assert.equal(runtime.seen.length, 2);
+    });
+  });
+});
+
+test('a runtime that throws leaves no run behind', async () => {
+  await withIsolatedDatabase(async () => {
+    const queryClaude: RunFunction = async () => { throw new Error('provider exploded'); };
+    await withAgentServer(createDependencies(queryClaude), async (baseUrl) => {
+      const response = await post(baseUrl, { projectPath: '/home/test/project', message: 'Run it', stream: false });
+      assert.equal(response.status, 500);
+      assert.deepEqual(chatRunRegistry.listRunningRuns(), [], 'the safety net completes the run');
+    });
+  });
+});
+
+test('a sessionId that is not a string is refused, not bound to a query', async () => {
+  // The lookup runs before the handler's try: a throw there is an unhandled
+  // rejection, and better-sqlite3 throws on binding an object.
+  await withIsolatedDatabase(async () => {
+    const runtime = createHeldRuntime();
+    await withAgentServer(createDependencies(runtime.queryClaude), async (baseUrl) => {
+      const response = await post(baseUrl, { projectPath: '/home/test/project', message: 'Run', sessionId: { $ne: null }, stream: false });
+      assert.equal(response.status, 400);
+      assert.equal(runtime.seen.length, 0);
+    });
+  });
+});
+
+test('a continued session runs under its own provider and project, as a chat send does', async () => {
+  await withIsolatedDatabase(async () => {
+    sessionsDb.createAppSession('app-codex', 'codex', '/home/test/project', 'Codex one');
+    const claudeCalls: unknown[] = [];
+    const codexCalls: unknown[] = [];
+    const dependencies = createDependencies(async (_command, options, writer) => {
+      claudeCalls.push(options);
+      writer.send(createNormalizedMessage({ kind: 'complete', provider: 'claude', sessionId: null, exitCode: 0 }));
+    });
+    dependencies.queryCodex = async (_command, options, writer) => {
+      codexCalls.push(options);
+      writer.send(createNormalizedMessage({ kind: 'complete', provider: 'codex', sessionId: null, exitCode: 0 }));
+    };
+    await withAgentServer(dependencies, async (baseUrl) => {
+      // No provider named: the row's, not the default.
+      const continued = await post(baseUrl, { projectPath: '/home/test/project', message: 'More', sessionId: 'app-codex', stream: false });
+      assert.equal(continued.status, 200);
+      assert.deepEqual([claudeCalls.length, codexCalls.length], [0, 1]);
+
+      // Another provider named: refused, not re-homed.
+      const mismatched = await post(baseUrl, { projectPath: '/home/test/project', message: 'More', sessionId: 'app-codex', provider: 'claude', stream: false });
+      assert.equal(mismatched.status, 400);
+      assert.equal(claudeCalls.length, 0);
+
+      // Another directory named: not that session.
+      const elsewhere = await post(baseUrl, { projectPath: '/home/test/other', message: 'More', sessionId: 'app-codex', stream: false });
+      assert.equal(elsewhere.status, 500);
+      assert.match((await elsewhere.json() as { error: string }).error, /belongs to project/);
+      assert.equal(codexCalls.length, 1);
+    });
+  });
+});
+
+test('a busy session is refused before anything is cloned', async () => {
+  await withIsolatedDatabase(async () => {
+    const runtime = createHeldRuntime();
+    const dependencies = createDependencies(runtime.queryClaude);
+    let clones = 0;
+    dependencies.spawnProcess = (() => { clones += 1; throw new Error('no clone expected'); }) as unknown as AgentDependencies['spawnProcess'];
+    await withAgentServer(dependencies, async (baseUrl) => {
+      const first = post(baseUrl, { projectPath: '/home/test/project', message: 'Run it' });
+      for (let i = 0; i < 50 && runtime.seen.length === 0; i += 1) {
+        await new Promise((resolve) => { setTimeout(resolve, 20); });
+      }
+      const [running] = chatRunRegistry.listRunningRuns();
+      assert.ok(running);
+
+      const retry = await post(baseUrl, { githubUrl: 'https://github.com/owner/repo.git', projectPath: '/home/test/project', message: 'Again', sessionId: running.sessionId, stream: false });
+      assert.equal(retry.status, 409);
+      assert.equal(clones, 0, 'the refusal comes before the clone step');
+
+      runtime.release();
+      await first;
+    });
+  });
+});
+
+test('a run a tab aborted ends without branching or opening a PR, and says so', async () => {
+  await withIsolatedDatabase(async () => {
+    const runtime = createHeldRuntime();
+    let gitCalls = 0;
+    const dependencies = createDependencies(async (command, options, writer) => {
+      await runtime.queryClaude(command, options, writer);
+    });
+    dependencies.spawnProcess = (() => { gitCalls += 1; throw new Error('git should not run after an abort'); }) as unknown as AgentDependencies['spawnProcess'];
+    await withAgentServer(dependencies, async (baseUrl) => {
+      const responsePromise = post(baseUrl, { projectPath: '/home/test/project', message: 'Run it', createBranch: true, stream: false });
+      for (let i = 0; i < 50 && runtime.seen.length === 0; i += 1) {
+        await new Promise((resolve) => { setTimeout(resolve, 20); });
+      }
+      const [running] = chatRunRegistry.listRunningRuns();
+      assert.ok(running);
+      // What chat.abort does: the run completes as aborted; the runtime then returns.
+      chatRunRegistry.completeRun(running.sessionId, { exitCode: 1, aborted: true });
+      runtime.release();
+
+      const response = await responsePromise;
+      const body = await response.json() as { success: boolean; aborted?: boolean; branch?: unknown };
+      assert.equal(body.success, false);
+      assert.equal(body.aborted, true);
+      assert.equal(body.branch, undefined);
+      assert.equal(gitCalls, 0);
+    });
+  });
+});
+
+test('a non-streaming run answers with the assistant\'s replies, its token usage and the provider id', async () => {
+  await withIsolatedDatabase(async () => {
+    const dependencies = createDependencies(async (_command, _options, writer) => {
+      writer.send(createNormalizedMessage({ kind: 'session_created', provider: 'claude', sessionId: 'native-7', newSessionId: 'native-7' }));
+      writer.send(createNormalizedMessage({ kind: 'text', provider: 'claude', sessionId: 'native-7', role: 'assistant', content: 'pong' }));
+      writer.send(createNormalizedMessage({
+        kind: 'status', text: 'token_budget', provider: 'claude', sessionId: 'native-7',
+        tokenBudget: { used: 130, total: 160_000, inputTokens: 100, outputTokens: 30, cacheReadTokens: 60, cacheCreationTokens: 10, cacheTokens: 70, breakdown: { input: 100, output: 30 } },
+      }));
+      writer.send(createNormalizedMessage({ kind: 'complete', provider: 'claude', sessionId: 'native-7', exitCode: 0 }));
+    });
+    await withAgentServer(dependencies, async (baseUrl) => {
+      const response = await post(baseUrl, { projectPath: '/home/test/project', message: 'ping', stream: false });
+      const body = await response.json() as { providerSessionId: string; messages: Array<{ content: string }>; tokens: Record<string, number> };
+      assert.equal(body.providerSessionId, 'native-7');
+      assert.deepEqual(body.messages.map((message) => message.content), ['pong']);
+      assert.deepEqual(body.tokens, { inputTokens: 100, outputTokens: 30, cacheReadTokens: 60, cacheCreationTokens: 10, totalTokens: 130 });
+    });
+  });
+});

package/server/modules/agent/tests/agent.routes.test.ts

@@ -30,6 +30,23 @@ function createDependencies(
     githubTokens: { getActiveGithubToken: () => null },
     projects: { createProjectPath: () => ({ outcome: 'created' }) },
     models: {} as AgentDependencies['models'],
+    sessions: {
+      getSessionById: () => null,
+      getSessionByProviderSessionId: () => null,
+      createAppSession: () => ({ sessionId: 'app-session-1' }),
+    },
+    // A registry stand-in: the runtime writes straight to the audience, which
+    // is all the tests above this file's registration tests need.
+    runs: {
+      startRun: ((input: { connection: { send(data: string): void } | null }) => ({
+        // The gateway writer's shape: a runtime that feature-detects it (codex)
+        // hands it objects to serialize, as the real one expects.
+        writer: { isWebSocketWriter: true, send: (data: unknown) => input.connection?.send(JSON.stringify(data)), getSessionId: () => null },
+        events: [],
+      })) as unknown as AgentDependencies['runs']['startRun'],
+      completeRunIfCurrent: () => undefined,
+      isProcessing: () => false,
+    },
     queryClaude: unexpectedProviderCall as AgentDependencies['queryClaude'],
     queryCursor: unexpectedProviderCall as AgentDependencies['queryCursor'],
     queryCodex: unexpectedProviderCall as AgentDependencies['queryCodex'],
@@ -154,7 +171,7 @@ test('GitHub cloning keeps credentials out of arguments and remote URL', async (
   assert.equal(cloneEnvironment?.CLOUDCLI_GITHUB_TOKEN, token);
   assert.equal(cloneEnvironment?.GIT_CONFIG_KEY_0, 'credential.helper');
   assert.equal(cloneEnvironment?.GIT_CONFIG_VALUE_0, '');
-  assert.equal(cloneEnvironment?.GIT_CONFIG_KEY_1, 'credential.helper');
+  assert.equal(cloneEnvironment?.GIT_CONFIG_KEY_1, 'credential.https://github.com.helper');
 });
 
 test('Agent route reuses a matching checkout without cloning or deleting it', async () => {
@@ -182,7 +199,7 @@ test('Agent route reuses a matching checkout without cloning or deleting it', as
     } as unknown as AgentDependencies['fileSystem'],
     spawnProcess,
     models: {
-      getProviderModels: async () => ({ models: { DEFAULT: 'default-model' } }),
+      getProviderModels: async () => ({ OPTIONS: [], DEFAULT: 'default-model' }),
     } as unknown as AgentDependencies['models'],
     queryClaude: (async () => undefined) as AgentDependencies['queryClaude'],
   }), async (baseUrl) => {
@@ -203,3 +220,35 @@ test('Agent route reuses a matching checkout without cloning or deleting it', as
   assert.deepEqual(spawnedArguments, [['config', '--get', 'remote.origin.url']]);
   assert.deepEqual(removedPaths, []);
 });
+
+test('Agent route starts codex on the catalog default when the request names no model', async () => {
+  const codexCalls: { model?: string }[] = [];
+
+  await withAgentServer(createDependencies({
+    fileSystem: {
+      access: async () => undefined,
+    } as unknown as AgentDependencies['fileSystem'],
+    models: {
+      // `getProviderModels` resolves to a `ProviderModelsDefinition` - `OPTIONS`
+      // and `DEFAULT`, with nothing wrapped around it.
+      getProviderModels: async () => ({ OPTIONS: [], DEFAULT: 'catalog-default' }),
+    } as unknown as AgentDependencies['models'],
+    queryCodex: (async (_prompt: string, options: { model?: string }) => {
+      codexCalls.push(options);
+    }) as unknown as AgentDependencies['queryCodex'],
+  }), async (baseUrl) => {
+    const response = await fetch(`${baseUrl}/api/agent`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        projectPath: '/home/test/project',
+        message: 'Run',
+        provider: 'codex',
+        stream: false,
+      }),
+    });
+    assert.equal(response.status, 200);
+  });
+
+  assert.deepEqual(codexCalls.map((call) => call.model), ['catalog-default']);
+});

package/server/modules/browser-use/browser-use.routes.ts

@@ -1,9 +1,45 @@
 import express from 'express';
+import type { Response } from 'express';
 
 import { browserUseService } from '@/modules/browser-use/browser-use.service.js';
 
 const router = express.Router();
 
+/**
+ * Stable machine-readable error codes for the browser-use API.
+ *
+ * The server always replies with the structured envelope used by AppError
+ * (`{ success: false, error: { code, message, details } }`). Clients map
+ * `code` to localized copy; `message` is an English fallback and `details`
+ * may carry the underlying error text for diagnostics.
+ */
+export const BROWSER_USE_ERROR_CODES = {
+  STATUS_LOAD_FAILED: 'BROWSER_USE_STATUS_LOAD_FAILED',
+  SETTINGS_LOAD_FAILED: 'BROWSER_USE_SETTINGS_LOAD_FAILED',
+  SETTINGS_SAVE_FAILED: 'BROWSER_USE_SETTINGS_SAVE_FAILED',
+  RUNTIME_INSTALL_FAILED: 'BROWSER_USE_RUNTIME_INSTALL_FAILED',
+  SESSIONS_LOAD_FAILED: 'BROWSER_USE_SESSIONS_LOAD_FAILED',
+  SESSION_STOP_FAILED: 'BROWSER_USE_SESSION_STOP_FAILED',
+  SESSION_DELETE_FAILED: 'BROWSER_USE_SESSION_DELETE_FAILED',
+} as const;
+
+function sendError(
+  res: Response,
+  statusCode: number,
+  code: string,
+  message: string,
+  details?: unknown,
+): void {
+  res.status(statusCode).json({
+    success: false,
+    error: {
+      code,
+      message,
+      details,
+    },
+  });
+}
+
 function readParam(value: string | string[] | undefined): string {
   return Array.isArray(value) ? value[0] || '' : value || '';
 }
@@ -12,10 +48,13 @@ router.get('/status', async (_req, res) => {
   try {
     res.json({ success: true, data: await browserUseService.getStatus() });
   } catch (error) {
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to load Browser status.',
-    });
+    sendError(
+      res,
+      500,
+      BROWSER_USE_ERROR_CODES.STATUS_LOAD_FAILED,
+      'Failed to load Browser status.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 
@@ -23,10 +62,13 @@ router.get('/settings', async (_req, res) => {
   try {
     res.json({ success: true, data: { settings: await browserUseService.getSettings() } });
   } catch (error) {
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to load Browser settings.',
-    });
+    sendError(
+      res,
+      500,
+      BROWSER_USE_ERROR_CODES.SETTINGS_LOAD_FAILED,
+      'Failed to load Browser settings.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 
@@ -35,26 +77,38 @@ router.put('/settings', async (req, res) => {
     const settings = await browserUseService.updateSettings(req.body || {});
     res.json({ success: true, data: { settings } });
   } catch (error) {
-    res.status(400).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to save Browser settings.',
-    });
+    sendError(
+      res,
+      400,
+      BROWSER_USE_ERROR_CODES.SETTINGS_SAVE_FAILED,
+      'Failed to save Browser settings.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 
 router.post('/runtime/install', async (_req, res) => {
   try {
     const result = await browserUseService.installRuntime();
-    res.status(result.success ? 200 : 500).json({
-      success: result.success,
-      data: result,
-      error: result.success ? undefined : result.message,
-    });
+    if (result.success) {
+      res.json({ success: true, data: result });
+      return;
+    }
+    sendError(
+      res,
+      500,
+      BROWSER_USE_ERROR_CODES.RUNTIME_INSTALL_FAILED,
+      'Failed to install Browser runtime.',
+      result.message,
+    );
   } catch (error) {
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to install Browser runtime.',
-    });
+    sendError(
+      res,
+      500,
+      BROWSER_USE_ERROR_CODES.RUNTIME_INSTALL_FAILED,
+      'Failed to install Browser runtime.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 
@@ -62,10 +116,13 @@ router.get('/sessions', async (_req, res) => {
   try {
     res.json({ success: true, data: { sessions: await browserUseService.listSessions() } });
   } catch (error) {
-    res.status(401).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to list browser sessions.',
-    });
+    sendError(
+      res,
+      401,
+      BROWSER_USE_ERROR_CODES.SESSIONS_LOAD_FAILED,
+      'Failed to list browser sessions.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 
@@ -74,10 +131,13 @@ router.post('/sessions/:sessionId/stop', async (req, res) => {
     const result = await browserUseService.stopSession(readParam(req.params.sessionId));
     res.json({ success: true, data: result });
   } catch (error) {
-    res.status(400).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to stop browser session.',
-    });
+    sendError(
+      res,
+      400,
+      BROWSER_USE_ERROR_CODES.SESSION_STOP_FAILED,
+      'Failed to stop browser session.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 
@@ -86,10 +146,13 @@ router.delete('/sessions/:sessionId', async (req, res) => {
     const result = await browserUseService.deleteSession(readParam(req.params.sessionId));
     res.json({ success: true, data: result });
   } catch (error) {
-    res.status(400).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Failed to delete browser session.',
-    });
+    sendError(
+      res,
+      400,
+      BROWSER_USE_ERROR_CODES.SESSION_DELETE_FAILED,
+      'Failed to delete browser session.',
+      error instanceof Error ? error.message : undefined,
+    );
   }
 });
 

package/server/modules/database/connection.ts

@@ -10,11 +10,12 @@
  * `getConnection()` to obtain the shared singleton.
  */
 
-import Database from 'better-sqlite3';
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
+import Database from 'better-sqlite3';
+
 import { APP_CONFIG_TABLE_SCHEMA_SQL } from '@/modules/database/schema.js';
 
 const __filename = fileURLToPath(import.meta.url);

package/server/modules/database/index.ts

@@ -12,6 +12,16 @@ export { providerModelsDb } from '@/modules/database/repositories/provider-model
 export { projectsDb } from '@/modules/database/repositories/projects.db.js';
 export { pushSubscriptionsDb } from '@/modules/database/repositories/push-subscriptions.js';
 export { scanStateDb } from '@/modules/database/repositories/scan-state.db.js';
+// sessionDraftsDb: used by User for drafts and Scheduled Messages for server-owned queued turns.
+export { sessionDraftsDb } from '@/modules/database/repositories/session-drafts.db.js';
+export type {
+  QueuedSessionMessageRecord,
+  SessionDraftRecord,
+} from '@/modules/database/repositories/session-drafts.db.js';
 export { sessionsDb } from '@/modules/database/repositories/sessions.db.js';
 export { userDb } from '@/modules/database/repositories/users.js';
+// userPreferencesDb: used by the User module to persist the settings that used to live in browser localStorage.
+export { userPreferencesDb } from '@/modules/database/repositories/user-preferences.db.js';
 export { vapidKeysDb } from '@/modules/database/repositories/vapid-keys.js';
+export { scheduledMessagesDb } from './repositories/scheduled-messages.db.js';
+export type { ScheduledMessageRow, ScheduledMessageStatus } from './repositories/scheduled-messages.db.js';