@causyne/agent 0.0.0-stage → 1.10.0

package/src/providers/base.js

@@ -0,0 +1,328 @@
+import { canonicalModelId } from '../modelIds.js';
+
+// Fields the agent loop attaches to messages for its own bookkeeping. They must
+// never reach a provider API, which rejects unknown message properties.
+const INTERNAL_MESSAGE_FIELDS = ['cacheAnchor', 'spillPath'];
+
+// Container formats each vendor actually accepts for audio input. Kept here so
+
+// instead of three drifting copies.
+const AUDIO_MIME_BY_FORMAT = {
+  wav: 'audio/wav',
+  mp3: 'audio/mpeg',
+  m4a: 'audio/mp4',
+  aac: 'audio/aac',
+  ogg: 'audio/ogg',
+  flac: 'audio/flac',
+  webm: 'audio/webm'
+};
+
+/** Map a container format token to the MIME type a provider expects. */
+export function mimeTypeForAudioFormat(format) {
+  return AUDIO_MIME_BY_FORMAT[String(format || '').toLowerCase()] || 'audio/wav';
+}
+
+/**
+ * Map a MIME type to the short format token OpenAI's input_audio wants.
+ *
+ * OpenAI accepts only 'wav' and 'mp3'. Anything else is reported honestly as
+ * itself so the provider layer can reject it with a clear message rather than
+ * mislabelling an m4a as an mp3 and letting the vendor fail on decode — which
+ * is exactly what the previous hardcoded format:'mp3' did.
+ */
+export function audioFormatForMimeType(mimeType) {
+  const mime = String(mimeType || '').toLowerCase().split(';')[0].trim();
+  for (const [format, candidate] of Object.entries(AUDIO_MIME_BY_FORMAT)) {
+    if (candidate === mime) return format;
+  }
+  if (mime === 'audio/mp3') return 'mp3';
+  if (mime === 'audio/x-wav' || mime === 'audio/wave') return 'wav';
+  if (mime === 'audio/x-m4a') return 'm4a';
+  return 'wav';
+}
+
+/** True for an audio content block in either the OpenAI or the Gemini shape. */
+export function isAudioBlock(block) {
+  if (!block) return false;
+  if (block.type === 'input_audio') return true;
+  return Boolean(block.inlineData && String(block.inlineData.mimeType || '').startsWith('audio/'));
+}
+
+export class LLMProvider {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    // Normalised here rather than at each caller: this is the last hop before
+    // the request payload and every provider extends this class, so a bad id
+    
+    // written before this existed) is corrected exactly once. A dotted
+    // Anthropic id used to match none of anthropic.js's capability lists,
+    // which silently disabled thinking and tool search and sent `temperature`
+    // to models that reject it. See src/modelIds.js.
+    this.model = canonicalModelId(config.model);
+    this.baseUrl = config.baseUrl; // For openai-compatible endpoints
+
+    // Model-id prefixes this provider can send images to. Vision is a property
+    // of the *model*, not the vendor, so each provider declares its own list —
+    // the same pattern AnthropicProvider uses for tool search. A single '*'
+    // means every model this provider serves accepts images.
+    //
+    // This replaced a flat `supportsVision = false` on the base class that only
+    // OpenAI and Anthropic ever overrode, which silently culled `screenshot`
+    // and `vision_inspect_ui` from the catalogue on seven of ten providers and
+    // made the mandatory visual-verification step of the anti-slop directive
+    // impossible to satisfy on any of them.
+    this.visionModels = [];
+
+    
+    this.imagePayloadFormat = 'openai';
+
+    // An explicit config value always wins. Custom OpenAI-compatible endpoints
+    // serve models this list cannot possibly know about.
+    this.visionOverride = typeof config.supportsVision === 'boolean'
+      ? config.supportsVision
+      : null;
+
+    // Model-id prefixes this provider can send AUDIO to. Same shape and same
+    // reasoning as visionModels above — audio is a property of the model, not
+    // the vendor. It is deliberately NOT derived from visionModels: the two
+    // capabilities diverge sharply. OpenAI serves images on every model but
+    // accepts input_audio only on the gpt-4o-audio / gpt-audio family, and
+    // Anthropic reads images on every model while accepting no audio at all.
+    // Defaulting audio to the vision list would 400 on both.
+    this.audioModels = [];
+
+    
+    this.audioPayloadFormat = 'openai';
+
+    // Hard ceiling on a single audio clip for this provider, applied as the
+    
+    
+    
+    this.maxAudioSeconds = null;
+    this.maxAudioBytes = null;
+
+    this.audioOverride = typeof config.supportsAudio === 'boolean'
+      ? config.supportsAudio
+      : null;
+  }
+
+  get supportsVision() {
+    if (this.visionOverride !== null) return this.visionOverride;
+    const model = (this.model || '').toLowerCase();
+    return this.visionModels.some(prefix => prefix === '*' || model.includes(prefix));
+  }
+
+  /**
+   * A model from this same provider that CAN take audio, or null.
+   *
+   * Exists because "the selected model cannot process audio" is a dead end for
+   * the user unless something names the way out. Meta is the case that forced
+   * it: the model they recommend, Muse Spark 1.3, is the one that cannot hear.
+   */
+  audioAlternative() {
+    return null;
+  }
+
+  /**
+   * Turn a clip into text, or null when this provider has no way to.
+   *
+   * A provider whose chat model cannot hear may still ship a dedicated
+   * speech-to-text model on the same key — Meta does, and it is the whole answer
+   * to Muse Spark 1.3 being both the recommended model and the deaf one.
+   * Returning null means "no route", not "it failed"; a thrown error means the
+   * route existed and did not work, which the caller reports differently.
+   */
+  async transcribeAudio() {
+    return null;
+  }
+
+  
+  get canTranscribe() {
+    return false;
+  }
+
+  get supportsAudio() {
+    if (this.audioOverride !== null) return this.audioOverride;
+    const model = (this.model || '').toLowerCase();
+    return this.audioModels.some(prefix => prefix === '*' || model.includes(prefix));
+  }
+
+  /**
+   * Send a chat request to the LLM.
+   * @param {Array} messages - [{ role: 'system'|'user'|'assistant', content: '...' }]
+   * @param {Object} options - { temperature, maxTokens, jsonMode, tools }
+   * @returns {Promise<{ content: string, usage: { promptTokens: number, completionTokens: number } }>}
+   */
+  async chat(messages, options = {}) {
+    throw new Error('chat() must be implemented by provider');
+  }
+
+  /**
+   * Prepare a message list for this specific model.
+   *
+   * Providers used to hardcode "strip every image block" because their whole
+   * vendor was assumed blind. Now that vision is decided per model, that blanket
+   * strip would delete images from models that can actually read them — so the
+   * decision is made here, once, against supportsVision.
+   */
+  prepareMessages(messages) {
+    const clean = this.stripInternalFields(messages);
+
+    // Vision and audio are decided separately. A model can read images and not
+    // hear audio (most of them), so the two strips cannot share one branch —
+    // an audio-blind vision model used to keep its input_audio block and 400.
+    const shaped = this.supportsVision
+      ? clean.map(msg => this.normalizeImageBlocks(msg))
+      : clean.map(msg => this.flattenToTextOnly(msg));
+
+    return this.supportsAudio
+      ? shaped.map(msg => this.normalizeAudioBlocks(msg))
+      : shaped.map(msg => this.stripAudioBlocks(msg));
+  }
+
+  /**
+   * Translate audio blocks into this provider's wire shape.
+   *
+   * The agent loop emits the OpenAI `input_audio` shape as the canonical form;
+   * Gemini needs `inlineData`. History replayed from an earlier session — or
+   * from before a provider switch — can carry either, so both are accepted.
+   */
+  normalizeAudioBlocks(msg) {
+    if (!Array.isArray(msg.content)) return msg;
+
+    const content = msg.content.map(block => {
+      if (!block) return block;
+
+      if (this.audioPayloadFormat === 'gemini') {
+        if (block.type === 'input_audio') {
+          return {
+            inlineData: {
+              mimeType: mimeTypeForAudioFormat(block.input_audio?.format),
+              data: block.input_audio?.data
+            }
+          };
+        }
+        return block;
+      }
+
+      // OpenAI shape. Convert a Gemini-shaped block back if one is replayed.
+      if (block.inlineData && String(block.inlineData.mimeType || '').startsWith('audio/')) {
+        return {
+          type: 'input_audio',
+          input_audio: {
+            data: block.inlineData.data,
+            format: audioFormatForMimeType(block.inlineData.mimeType)
+          }
+        };
+      }
+      return block;
+    });
+
+    return { ...msg, content };
+  }
+
+  /**
+   * Drop audio from a model that cannot hear, leaving a visible marker.
+   *
+   * Silently deleting it was the old behaviour and it was the worst possible
+   * one: the user recorded a clip, the model answered as though it had heard
+   * nothing, and nothing anywhere said why. Images already got a placeholder;
+   * audio now gets the same courtesy.
+   */
+  stripAudioBlocks(msg) {
+    if (!Array.isArray(msg.content)) return msg;
+    if (!msg.content.some(isAudioBlock)) return msg;
+
+    const content = msg.content
+      .filter(block => !isAudioBlock(block))
+      .concat([{
+        type: 'text',
+        text: '[Audio content removed — the selected model cannot process audio. Causyne transcribed the request on-device instead where possible.]'
+      }]);
+
+    return { ...msg, content };
+  }
+
+  /**
+   * Translate image blocks into this provider's wire shape. The agent loop emits
+   * whichever shape imagePayloadFormat asks for, but history replayed from an
+   * earlier session — or from before a provider switch — can carry the other.
+   */
+  normalizeImageBlocks(msg) {
+    if (!Array.isArray(msg.content)) return msg;
+    if (this.imagePayloadFormat !== 'openai') return msg;
+
+    const content = msg.content.map(block => {
+      if (block && block.type === 'image' && block.source?.type === 'base64') {
+        return {
+          type: 'image_url',
+          image_url: { url: `data:${block.source.media_type};base64,${block.source.data}` }
+        };
+      }
+      return block;
+    });
+
+    return { ...msg, content };
+  }
+
+  /**
+   * Collapse multimodal content to plain text for a model that cannot see.
+   *
+   * Audio blocks are deliberately preserved here rather than filtered out:
+   * this runs before the audio strip in prepareMessages, and a model that is
+   * blind is not necessarily deaf. Flattening to a bare string at this point
+   * would destroy an audio block that the audio branch was about to keep.
+   */
+  flattenToTextOnly(msg) {
+    if (!Array.isArray(msg.content)) return msg;
+
+    const audioBlocks = this.supportsAudio ? msg.content.filter(isAudioBlock) : [];
+
+    const textParts = msg.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text);
+
+    const text = textParts.join('\n') ||
+      '[Image content removed — not supported by this model]';
+
+    if (audioBlocks.length === 0) return { ...msg, content: text };
+
+    return { ...msg, content: [{ type: 'text', text }, ...audioBlocks] };
+  }
+
+  /** Remove internal bookkeeping fields before sending messages upstream. */
+  stripInternalFields(messages) {
+    return messages.map(msg => {
+      let needsCopy = false;
+      for (const field of INTERNAL_MESSAGE_FIELDS) {
+        if (field in msg) { needsCopy = true; break; }
+      }
+      if (!needsCopy) return msg;
+
+      const clean = { ...msg };
+      for (const field of INTERNAL_MESSAGE_FIELDS) delete clean[field];
+      return clean;
+    });
+  }
+
+  // Normalize usage across different provider response formats.
+  //
+  // Cached prompt tokens are surfaced separately because they are billed at a
+  // fraction of the base input rate: OpenAI-style APIs report them under
+  // prompt_tokens_details.cached_tokens, DeepSeek under prompt_cache_hit_tokens.
+  
+  // disfavour once caching starts working.
+  normalizeUsage(rawUsage) {
+    const promptTokens = rawUsage?.prompt_tokens || 0;
+    const cachedPromptTokens =
+      rawUsage?.prompt_tokens_details?.cached_tokens ??
+      rawUsage?.prompt_cache_hit_tokens ??
+      0;
+
+    return {
+      promptTokens,
+      completionTokens: rawUsage?.completion_tokens || 0,
+      cachedPromptTokens: Math.min(cachedPromptTokens, promptTokens)
+    };
+  }
+}

package/src/providers/dashscope-byok.js

@@ -0,0 +1,86 @@
+import { canonicalModelId } from '../modelIds.js';
+import { DEFAULT_MODEL_BY_PROVIDER } from '../modelCatalogue.js';
+import { LLMProvider } from './base.js';
+
+// Direct DashScope API connection for BYOK (unlike dashscope.js which is the proxy for Free Demo)
+export class DashscopeByokProvider extends LLMProvider {
+  constructor(config) {
+    super(config);
+    // Use International/Singapore endpoint by default, allow override via config
+    let url = config.baseUrl || 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions';
+    if (url.endsWith('/v1')) url += '/chat/completions';
+    else if (url.endsWith('/v1/')) url += 'chat/completions';
+    
+    this.baseUrl = url;
+    this.model = canonicalModelId(config.model || DEFAULT_MODEL_BY_PROVIDER['dashscope-byok']);
+    this.apiKey = config.apiKey;
+    this.visionModels = ['-vl-', '-vl', 'qwen3.6', 'qwen3.7', 'kimi-k2.5', 'kimi-k2.7'];
+    // Qwen exposes audio on the omni and dedicated audio families only; the
+    // -vl- vision models are image-in, text-out and reject an audio block.
+    this.audioModels = ['-omni', 'qwen-audio', 'qwen2-audio'];
+  }
+
+  async chat(messages, options = {}) {
+    const ALLOWED = [
+      "qwen3.7-max", "qwen3.7-plus", "kimi-k2.7-code", "kimi-k2.6", 
+      "kimi-k2.5", "kimi-k2-thinking", "Moonshot-Kimi-K2-Instruct", 
+      "deepseek-v4-flash", "deepseek-v4-pro"
+    ];
+    let activeModel = this.model;
+    if (!ALLOWED.includes(activeModel)) {
+      activeModel = 'qwen3.7-plus';
+    }
+
+    const sanitizedMessages = this.prepareMessages(messages);
+
+    const payload = {
+      model: activeModel,
+      messages: sanitizedMessages,
+      temperature: options.temperature || 0.1,
+    };
+
+    if (options.jsonMode) {
+      payload.response_format = { type: 'json_object' };
+    }
+    
+    if (options.tools) {
+      payload.tools = options.tools.map(tool => ({
+        type: 'function',
+        function: tool.function ? tool.function : tool
+      }));
+      payload.tool_choice = "auto";
+    }
+
+    const response = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(payload)
+    });
+
+    if (!response.ok) {
+      const errorData = await response.text();
+      
+      // Enterprise Error Handling: Detect Workspace-bound API Key configuration errors
+      if (response.status === 401 && this.apiKey && this.apiKey.startsWith('sk-ws-')) {
+        if (!this.baseUrl.includes('ws-')) {
+          throw new Error(`\n❌ QWEN WORKSPACE CONFIGURATION ERROR ❌\n\nYou are using a Workspace-bound API Key (starts with sk-ws-), but you haven't configured your Workspace Base URL!\n\nAlibaba requires a specific URL for these keys.\n\n🛠️ HOW TO FIX THIS:\n1. Open your computer terminal.\n2. Run command: causyne-agent config\n3. When asked for 'Custom Base URL', paste your Workspace URL from Alibaba (e.g. https://{Your-Workspace-ID}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions).\n\nAlternatively, use a Standard API Key (starts with sk-) which does not require a custom URL.`);
+        }
+      }
+      
+      throw new Error(`Qwen DashScope API Error (${response.status}): ${errorData}`);
+    }
+
+    const data = await response.json();
+    const content = data.choices[0].message.content;
+    const toolCalls = data.choices[0].message.tool_calls;
+    
+    return {
+      content: content || '',
+      toolCalls: (toolCalls && toolCalls.length > 0) ? toolCalls : undefined,
+      usage: this.normalizeUsage(data.usage)
+    };
+  }
+}

package/src/providers/deepseek.js

@@ -0,0 +1,80 @@
+import { canonicalModelId } from '../modelIds.js';
+import { DEFAULT_MODEL_BY_PROVIDER } from '../modelCatalogue.js';
+import { LLMProvider } from './base.js';
+
+export class DeepSeekProvider extends LLMProvider {
+  constructor(config) {
+    super(config);
+    this.baseUrl = 'https://api.deepseek.com/v1/chat/completions';
+    this.model = canonicalModelId(config.model || DEFAULT_MODEL_BY_PROVIDER['deepseek']);
+    // The deepseek-chat line is text-only; only the VL builds accept images.
+    this.visionModels = ['-vl'];
+    // DeepSeek exposes no audio input endpoint.
+    this.audioModels = [];
+  }
+
+  async chat(messages, options = {}) {
+    const sanitizedMessages = this.prepareMessages(messages);
+
+    const payload = {
+      model: this.model,
+      messages: sanitizedMessages,
+      temperature: options.temperature || 0.1,
+    };
+
+    if (options.jsonMode) {
+      payload.response_format = { type: 'json_object' };
+    }
+    
+    let targetUrl = this.baseUrl;
+    let headers = {
+      'Content-Type': 'application/json'
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    } else {
+      throw new Error("API key is required.");
+    }
+
+    if (options.tools) {
+      payload.tools = options.tools.map(tool => ({
+        type: 'function',
+        function: tool.function ? tool.function : tool
+      }));
+      payload.tool_choice = "auto";
+    }
+
+    const response = await fetch(targetUrl, {
+      method: 'POST',
+      headers: headers,
+      body: JSON.stringify(payload)
+    });
+
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(`DeepSeek API Error (${response.status}): ${errorData}`);
+    }
+
+    const data = await response.json();
+    let content = '';
+    let toolCalls = [];
+    
+    // Support both direct DeepSeek API format and our Cloudflare Proxy format
+    if (data.reply !== undefined) {
+        // Proxy Format
+        content = data.reply || '';
+        toolCalls = data.tool_calls || [];
+    } else if (data.choices && data.choices[0] && data.choices[0].message) {
+        // Direct API Format
+        content = data.choices[0].message.content || '';
+        toolCalls = data.choices[0].message.tool_calls || [];
+    }
+    
+    return {
+      content: content,
+      toolCalls: (toolCalls && toolCalls.length > 0) ? toolCalls : undefined,
+      usage: this.normalizeUsage(data.usage || { prompt_tokens: 0, completion_tokens: 0 })
+    };
+  }
+}

package/src/providers/factory.js

@@ -0,0 +1,37 @@
+// Provider construction, in one place.
+//
+
+
+// ("can the selected model hear?"), and a second copy would drift the moment a
+
+
+import { OpenAIProvider } from './openai.js';
+import { AnthropicProvider } from './anthropic.js';
+import { GeminiProvider } from './gemini.js';
+import { OllamaProvider } from './ollama.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+import { DeepSeekProvider } from './deepseek.js';
+import { QwenByokProvider } from './qwen-byok.js';
+import { DashscopeByokProvider } from './dashscope-byok.js';
+import { XAIProvider } from './xai.js';
+import { MoonshotProvider } from './moonshot.js';
+import { MuseProvider } from './muse.js';
+
+export function createProvider(config) {
+  const p = config.provider?.toLowerCase();
+  if (p === 'openai') return new OpenAIProvider(config);
+  if (p === 'anthropic') return new AnthropicProvider(config);
+  if (p === 'gemini') return new GeminiProvider(config);
+  if (p === 'ollama') return new OllamaProvider(config);
+  if (p === 'deepseek') return new DeepSeekProvider(config);
+  if (p === 'dashscope-byok' || p === 'dashscope') return new DashscopeByokProvider(config);
+  if (p === 'qwen') return new QwenByokProvider(config);
+  if (p === 'openai-compatible') return new OpenAICompatibleProvider(config);
+  if (p === 'xai' || p === 'grok') return new XAIProvider(config);
+  if (p === 'moonshot' || p === 'kimi') return new MoonshotProvider(config);
+  // Meta Model API. 'meta' and 'muse' both reach it: the vendor is Meta, the
+  // model family is Muse, and users say either.
+  if (p === 'muse' || p === 'meta') return new MuseProvider(config);
+
+  throw new Error("API Key Required. Causyne is a 100% Sovereign BYOK Engine. Please configure your API Provider and Key in Settings.");
+}