@cloudcli-ai/cloudcli 1.36.2 → 1.37.0

package/server/modules/voice/tests/voice.service.test.ts

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createVoiceService } from '../voice.service.js';
+
+const defaults = {
+  baseUrl: 'https://voice.example/v1',
+  apiKey: 'server-key',
+  sttModel: 'whisper-1',
+  ttsModel: 'tts-1',
+  ttsVoice: 'alloy',
+};
+
+test('reports whether the server-controlled backend is configured', () => {
+  const service = createVoiceService({
+    defaults: { ...defaults, baseUrl: '' },
+    timeoutMs: 1_000,
+    fetchBackend: async () => {
+      throw new Error('fetch should not run');
+    },
+  });
+
+  assert.deepEqual(service.getHealth(), { configured: false });
+});
+
+test('transcribes with injected fetch and request-level credential/model overrides', async () => {
+  let requestedUrl = '';
+  let requestedOptions: RequestInit | undefined;
+  const service = createVoiceService({
+    defaults,
+    timeoutMs: 1_000,
+    fetchBackend: async (url, options) => {
+      requestedUrl = url;
+      requestedOptions = options;
+      return new Response(JSON.stringify({ text: 'hello' }), { status: 200 });
+    },
+  });
+
+  const result = await service.transcribe({
+    audio: {
+      bytes: Buffer.from('audio'),
+      mimeType: 'audio/webm',
+      fileName: 'recording.webm',
+    },
+    overrides: { apiKey: 'request-key', sttModel: 'custom-whisper' },
+  });
+
+  assert.deepEqual(result, { ok: true, value: { text: 'hello' } });
+  assert.equal(requestedUrl, 'https://voice.example/v1/audio/transcriptions');
+  assert.equal((requestedOptions?.headers as Record<string, string>).Authorization, 'Bearer request-key');
+  assert.equal((requestedOptions?.body as FormData).get('model'), 'custom-whisper');
+});
+
+test('forwards the explicit TTS format and maps backend authentication failures', async () => {
+  let requestBody = '';
+  const service = createVoiceService({
+    defaults,
+    timeoutMs: 1_000,
+    fetchBackend: async (_url, options) => {
+      requestBody = String(options.body);
+      return new Response('unauthorized', { status: 401 });
+    },
+  });
+
+  const result = await service.synthesizeSpeech({
+    text: 'Read this',
+    overrides: { ttsFormat: 'wav' },
+  });
+
+  assert.deepEqual(JSON.parse(requestBody), {
+    model: 'tts-1',
+    voice: 'alloy',
+    input: 'Read this',
+    response_format: 'wav',
+  });
+  assert.deepEqual(result, {
+    ok: false,
+    status: 502,
+    error: 'Voice backend rejected the request (check the API key).',
+  });
+});
+
+test('blocks link-local metadata destinations before calling the fetch adapter', async () => {
+  let fetchCalls = 0;
+  const service = createVoiceService({
+    defaults: { ...defaults, baseUrl: 'http://169.254.169.254/latest' },
+    timeoutMs: 1_000,
+    fetchBackend: async () => {
+      fetchCalls += 1;
+      return new Response();
+    },
+  });
+
+  const result = await service.synthesizeSpeech({ text: 'hello', overrides: {} });
+
+  assert.deepEqual(result, { ok: false, status: 400, error: 'Invalid voice backend URL.' });
+  assert.equal(fetchCalls, 0);
+});

package/server/modules/voice/voice.module.ts

@@ -0,0 +1,47 @@
+import multer from 'multer';
+
+import { createVoiceRouter } from './voice.routes.js';
+import { createVoiceService } from './voice.service.js';
+
+const DEFAULT_VOICE_TIMEOUT_MS = 300_000;
+const parsedTimeoutMs = Number(process.env.VOICE_TIMEOUT_MS);
+const voiceTimeoutMs = Number.isFinite(parsedTimeoutMs) && parsedTimeoutMs > 0
+  ? parsedTimeoutMs
+  : DEFAULT_VOICE_TIMEOUT_MS;
+
+const voiceService = createVoiceService({
+  defaults: {
+    // The server-controlled URL is intentional: frontend-configured custom
+    // backends are called directly by the browser and never become SSRF input.
+    baseUrl: (process.env.VOICE_API_BASE_URL || '').replace(/\/$/, ''),
+    apiKey: process.env.VOICE_API_KEY || '',
+    sttModel: process.env.VOICE_STT_MODEL || 'whisper-1',
+    ttsModel: process.env.VOICE_TTS_MODEL || 'tts-1',
+    ttsVoice: process.env.VOICE_TTS_VOICE || 'alloy',
+  },
+  timeoutMs: voiceTimeoutMs,
+  fetchBackend: async (url, options) => {
+    const abortController = new AbortController();
+    const timeoutHandle = setTimeout(() => abortController.abort(), voiceTimeoutMs);
+    try {
+      return await fetch(url, {
+        redirect: 'manual',
+        ...options,
+        signal: abortController.signal,
+      });
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  },
+});
+
+const audioUpload = multer({
+  storage: multer.memoryStorage(),
+  limits: { fileSize: 25 * 1024 * 1024 },
+});
+
+/** Voice router assembled for the server entrypoint. */
+export const voiceRoutes = createVoiceRouter({
+  voiceService,
+  parseAudioUpload: audioUpload.single('audio'),
+});

package/server/modules/voice/voice.routes.ts

@@ -0,0 +1,113 @@
+import { Readable } from 'node:stream';
+
+import express from 'express';
+
+import type { VoiceRequestOverrides, VoiceService, VoiceServiceResult } from '@/shared/types.js';
+import { asyncHandler } from '@/shared/utils.js';
+
+type VoiceRouterDependencies = {
+  voiceService: VoiceService;
+  parseAudioUpload: express.RequestHandler;
+};
+
+function readHeaderValue(value: string | string[] | undefined): string | undefined {
+  const normalizedValue = Array.isArray(value) ? value[0] : value;
+  const trimmedValue = normalizedValue?.trim();
+  return trimmedValue || undefined;
+}
+
+function parseVoiceOverrides(request: express.Request): VoiceRequestOverrides {
+  return {
+    apiKey: readHeaderValue(request.headers['x-voice-api-key']),
+    sttModel: readHeaderValue(request.headers['x-voice-stt-model']),
+    ttsModel: readHeaderValue(request.headers['x-voice-tts-model']),
+    ttsVoice: readHeaderValue(request.headers['x-voice-tts-voice']),
+    ttsFormat: readHeaderValue(request.headers['x-voice-tts-format']),
+  };
+}
+
+function sendFailure<TValue>(
+  response: express.Response,
+  result: VoiceServiceResult<TValue>,
+): result is Extract<VoiceServiceResult<TValue>, { ok: false }> {
+  if (result.ok) {
+    return false;
+  }
+
+  response.status(result.status).json({ error: result.error });
+  return true;
+}
+
+/**
+ * Creates the transport-only router used by the Voice composition root. It is
+ * exported for Voice route tests; other modules consume only the composed
+ * router exposed from the Voice barrel.
+ */
+export function createVoiceRouter(dependencies: VoiceRouterDependencies): express.Router {
+  const router = express.Router();
+
+  router.get('/health', (_request, response) => {
+    response.json(dependencies.voiceService.getHealth());
+  });
+
+  router.post('/transcribe', (request, response, next) => {
+    dependencies.parseAudioUpload(request, response, (uploadError?: unknown) => {
+      if (uploadError) {
+        const message = uploadError instanceof Error ? uploadError.message : String(uploadError);
+        response.status(400).json({ error: message });
+        return;
+      }
+
+      // Multer uses a callback API, so bridge its parsed request into the async
+      // service call and forward unexpected rejections to Express middleware.
+      void (async () => {
+        if (!request.file) {
+          response.status(400).json({ error: 'No audio uploaded' });
+          return;
+        }
+
+        const result = await dependencies.voiceService.transcribe({
+          audio: {
+            bytes: request.file.buffer,
+            mimeType: request.file.mimetype || 'audio/webm',
+            fileName: request.file.originalname || 'recording.webm',
+          },
+          overrides: parseVoiceOverrides(request),
+        });
+
+        if (sendFailure(response, result)) {
+          return;
+        }
+
+        response.json(result.value);
+      })().catch(next);
+    });
+  });
+
+  router.post('/tts', asyncHandler(async (request, response) => {
+    const text = request.body?.text;
+    if (typeof text !== 'string' || !text.trim()) {
+      response.status(400).json({ error: 'text required' });
+      return;
+    }
+
+    const result = await dependencies.voiceService.synthesizeSpeech({
+      text,
+      overrides: parseVoiceOverrides(request),
+    });
+    if (sendFailure(response, result)) {
+      return;
+    }
+
+    response.setHeader('Content-Type', result.value.contentType);
+    response.setHeader('Cache-Control', 'no-store');
+    if (!result.value.body) {
+      response.end();
+      return;
+    }
+
+    Readable.fromWeb(result.value.body).on('error', (error) => response.destroy(error)).pipe(response);
+  }));
+
+  return router;
+}

package/server/modules/voice/voice.service.ts

@@ -0,0 +1,192 @@
+import type {
+  VoiceAudioUpload,
+  VoiceRequestOverrides,
+  VoiceService,
+  VoiceServiceResult,
+  VoiceSpeechPayload,
+} from '@/shared/types.js';
+
+type VoiceServiceDependencies = {
+  defaults: {
+    baseUrl: string;
+    apiKey: string;
+    sttModel: string;
+    ttsModel: string;
+    ttsVoice: string;
+  };
+  timeoutMs: number;
+  fetchBackend(url: string, options: RequestInit): Promise<Response>;
+};
+
+type ResolvedVoiceConfig = VoiceServiceDependencies['defaults'] & {
+  ttsFormat: string;
+};
+
+function resolveVoiceConfig(
+  defaults: VoiceServiceDependencies['defaults'],
+  overrides: VoiceRequestOverrides,
+): ResolvedVoiceConfig {
+  return {
+    baseUrl: defaults.baseUrl,
+    apiKey: overrides.apiKey || defaults.apiKey,
+    sttModel: overrides.sttModel || defaults.sttModel,
+    ttsModel: overrides.ttsModel || defaults.ttsModel,
+    ttsVoice: overrides.ttsVoice || defaults.ttsVoice,
+    ttsFormat: overrides.ttsFormat?.trim() ?? '',
+  };
+}
+
+function validateBackendBaseUrl(baseUrl: string): boolean {
+  try {
+    const parsedUrl = new URL(baseUrl);
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+      return false;
+    }
+
+    // Local and private backends are supported intentionally. Only link-local
+    // metadata addresses remain blocked as a defense in depth measure.
+    return parsedUrl.hostname !== '169.254.169.254'
+      && !parsedUrl.hostname.startsWith('169.254.');
+  } catch {
+    return false;
+  }
+}
+
+function authorizationHeader(apiKey: string): Record<string, string> {
+  return apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
+}
+
+function backendFailure(status: number, responseText?: string): VoiceServiceResult<never> {
+  if (status === 401 || status === 403) {
+    return {
+      ok: false,
+      status: 502,
+      error: 'Voice backend rejected the request (check the API key).',
+    };
+  }
+
+  return {
+    ok: false,
+    status,
+    error: responseText || 'voice backend error',
+  };
+}
+
+function unreachableBackendFailure(error: unknown, timeoutMs: number): VoiceServiceResult<never> {
+  if (error instanceof Error && error.name === 'AbortError') {
+    return {
+      ok: false,
+      status: 504,
+      error: `Voice backend timed out after ${Math.round(timeoutMs / 1000)}s. Check your voice backend.`,
+    };
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    ok: false,
+    status: 502,
+    error: `Voice backend unreachable: ${message}`,
+  };
+}
+
+function validateConfiguredBackend(config: ResolvedVoiceConfig): VoiceServiceResult<never> | null {
+  if (!config.baseUrl) {
+    return { ok: false, status: 503, error: 'No voice backend configured' };
+  }
+
+  if (!validateBackendBaseUrl(config.baseUrl)) {
+    return { ok: false, status: 400, error: 'Invalid voice backend URL.' };
+  }
+
+  return null;
+}
+
+function createTranscriptionFormData(audio: VoiceAudioUpload, sttModel: string): FormData {
+  const formData = new FormData();
+  formData.append('file', new Blob([audio.bytes], { type: audio.mimeType }), audio.fileName);
+  formData.append('model', sttModel);
+  return formData;
+}
+
+/**
+ * Creates the Voice application service used by the Voice composition root and
+ * its unit tests. The outbound request function and server configuration are
+ * required so the service never reads globals or creates production defaults.
+ */
+export function createVoiceService(dependencies: VoiceServiceDependencies): VoiceService {
+  return {
+    getHealth: () => ({ configured: Boolean(dependencies.defaults.baseUrl) }),
+
+    async transcribe(input) {
+      const config = resolveVoiceConfig(dependencies.defaults, input.overrides);
+      const configurationFailure = validateConfiguredBackend(config);
+      if (configurationFailure) {
+        return configurationFailure;
+      }
+
+      try {
+        const response = await dependencies.fetchBackend(
+          `${config.baseUrl}/audio/transcriptions`,
+          {
+            method: 'POST',
+            headers: authorizationHeader(config.apiKey),
+            body: createTranscriptionFormData(input.audio, config.sttModel),
+          },
+        );
+        const responseText = await response.text();
+        if (!response.ok) {
+          return backendFailure(response.status, responseText);
+        }
+
+        try {
+          const parsed = JSON.parse(responseText) as { text?: unknown };
+          return {
+            ok: true,
+            value: { text: typeof parsed.text === 'string' ? parsed.text : '' },
+          };
+        } catch {
+          return { ok: true, value: { text: responseText } };
+        }
+      } catch (error) {
+        return unreachableBackendFailure(error, dependencies.timeoutMs);
+      }
+    },
+
+    async synthesizeSpeech(input) {
+      const config = resolveVoiceConfig(dependencies.defaults, input.overrides);
+      const configurationFailure = validateConfiguredBackend(config);
+      if (configurationFailure) {
+        return configurationFailure;
+      }
+
+      try {
+        const response = await dependencies.fetchBackend(`${config.baseUrl}/audio/speech`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...authorizationHeader(config.apiKey),
+          },
+          body: JSON.stringify({
+            model: config.ttsModel,
+            voice: config.ttsVoice,
+            input: input.text,
+            ...(config.ttsFormat ? { response_format: config.ttsFormat } : {}),
+          }),
+        });
+
+        if (!response.ok) {
+          const responseText = await response.text().catch(() => 'tts failed');
+          return backendFailure(response.status, responseText);
+        }
+
+        const value: VoiceSpeechPayload = {
+          contentType: response.headers.get('content-type') || 'audio/mpeg',
+          body: response.body,
+        };
+        return { ok: true, value };
+      } catch (error) {
+        return unreachableBackendFailure(error, dependencies.timeoutMs);
+      }
+    },
+  };
+}

package/server/modules/websocket/README.md

@@ -19,7 +19,7 @@ Shared chat client registry and open-state constant used by other modules.
 
 ## Why Dependency Injection Is Used
 
-The module receives runtime-specific functions from `server/index.js` instead of importing legacy runtime files directly.
+The module receives runtime-specific functions from `server/index.ts` instead of importing legacy runtime files directly.
 
 Benefits:
 
@@ -117,8 +117,8 @@ The frontend only ever knows the **app session id** (allocated by
 `POST /api/providers/sessions` or discovered via the session index). The
 provider-native id (JSONL file name, CLI resume id) stays inside the backend:
 
-1. `chat.send` resolves the app id to `{ provider, provider_session_id, project_path }` from the sessions DB.
-2. The provider runtime receives the provider-native id for resume.
+1. `chat.send` resolves the app id to `{ provider, project_path }` from the sessions DB and passes the **app session id** to the provider runtime.
+2. The provider runtime resolves the provider-native id from the sessions DB itself (`sessionsService.resolveProviderSessionId`) at the exact points its CLI/SDK needs it (resume flags, provider-owned databases). Runtimes key their process maps by the app session id, so abort and pending-approval lookups use app ids too.
 3. The `ChatSessionWriter` remaps every outbound event back to the app id, and turns `session_created` announcements into a DB mapping update instead of forwarding them.
 
 ### Chat Message Dispatch
@@ -129,10 +129,10 @@ flowchart TD
   B -->|invalid| C[send kind:protocol_error]
   B -->|ok| D{data.type}
 
-  D -->|chat.send| E[resolve session row -> startRun -> spawnFns provider]
-  D -->|chat.abort| F[abortFns provider + synthetic complete]
+  D -->|chat.send| E[resolve session row -> startRun -> providerRuntimeService.run]
+  D -->|chat.abort| F[providerRuntimeService.abort + synthetic complete]
   D -->|chat.subscribe| G[chat_subscribed ack + attach socket + replay events seq > lastSeq]
-  D -->|chat.permission-response| H[resolveToolApproval]
+  D -->|chat.permission-response| H[providerRuntimeService.resolveToolApproval]
   D -->|other| I[send kind:protocol_error]
 ```
 
@@ -269,5 +269,5 @@ To add a new websocket route:
 1. Add a new handler service under `services/`.
 2. Extend `WebSocketServerDependencies` in `websocket-server.service.ts` if needed.
 3. Add a new pathname branch in the router.
-4. Wire dependency injection from `server/index.js`.
+4. Wire dependency injection from `server/index.ts`.
 5. Keep `index.ts` as barrel-only export surface.

package/server/modules/websocket/services/chat-session-writer.service.ts

@@ -32,8 +32,8 @@ type ChatSessionWriterOptions = {
  *
  * It exposes the exact same surface as `WebSocketWriter` (`send`,
  * `setSessionId`, `getSessionId`, `updateWebSocket`, `userId`,
- * `isWebSocketWriter`) so the provider runtimes (`claude-sdk.js`,
- * `cursor-cli.js`, ...) need zero changes — but everything that flows through
+ * `isWebSocketWriter`) so the provider runtime adapters need zero changes —
+ * but everything that flows through
  * it is translated from the provider's world into the app's protocol:
  *
  * - `session_created` events are swallowed and turned into a provider-id