@causyne/agent 0.0.0-stage → 1.10.1

package/src/providers/openai-compatible.js

@@ -0,0 +1,84 @@
+import { canonicalModelId } from '../modelIds.js';
+import { DEFAULT_MODEL_BY_PROVIDER } from '../modelCatalogue.js';
+import { LLMProvider } from './base.js';
+
+export class OpenAICompatibleProvider extends LLMProvider {
+  constructor(config) {
+    super(config);
+
+    // A custom endpoint can serve anything, so guessing from the model id would
+    // be wrong as often as right. config.supportsAudio is the deliberate opt-in,
+    // exactly as config.supportsVision already is for images.
+    this.audioModels = [];
+    // 'low' | 'medium' | 'high' | 'off'. Unset means: do not send the parameter.
+    this.reasoningEffort = config.reasoningEffort || null;
+    this.baseUrl = config.baseUrl || 'https://api.openai.com/v1/chat/completions';
+    this.model = canonicalModelId(config.model || DEFAULT_MODEL_BY_PROVIDER['openai']);
+  }
+
+  async chat(messages, options = {}) {
+    const preparedMessages = this.prepareMessages(messages);
+    const payload = {
+      model: this.model,
+      messages: preparedMessages,
+      temperature: options.temperature || 0.1,
+    };
+
+    // Reasoning models take an effort dial. Sending it to a model that does not
+    // support it is rejected, so it only goes out when the user configured it —
+    // a custom OpenAI-compatible endpoint may serve anything, and this provider
+    // cannot know the model list in advance.
+    if (this.reasoningEffort && this.reasoningEffort !== 'off') {
+      payload.reasoning_effort = this.reasoningEffort;
+    }
+
+    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();
+      throw new Error(`OpenAI-Compatible API Error (${response.status}): ${errorData}`);
+    }
+
+    const data = await response.json();
+    let content = '';
+    let toolCalls = [];
+
+    let reasoningContent = '';
+
+    if (data.choices && data.choices[0] && data.choices[0].message) {
+      const message = data.choices[0].message;
+      content = message.content || '';
+      toolCalls = message.tool_calls || [];
+      // DeepSeek and several compatible endpoints return the chain of thought
+      // in a sibling field. It was being discarded, so the reasoning the user
+      // paid for never reached them.
+      reasoningContent = message.reasoning_content || message.reasoning || '';
+    }
+
+    return {
+      content: content,
+      toolCalls: (toolCalls && toolCalls.length > 0) ? toolCalls : undefined,
+      reasoningContent: reasoningContent || undefined,
+      usage: this.normalizeUsage(data.usage || { prompt_tokens: 0, completion_tokens: 0 })
+    };
+  }
+}

package/src/providers/openai.js

@@ -0,0 +1,20 @@
+import { canonicalModelId } from '../modelIds.js';
+import { DEFAULT_MODEL_BY_PROVIDER } from '../modelCatalogue.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+
+export class OpenAIProvider extends OpenAICompatibleProvider {
+  constructor(config) {
+    super(config);
+    this.baseUrl = 'https://api.openai.com/v1/chat/completions';
+    this.model = canonicalModelId(config.model || DEFAULT_MODEL_BY_PROVIDER['openai']);
+    this.visionModels = ['*'];
+    this.imagePayloadFormat = 'openai';
+    // Vision is '*' but audio is emphatically NOT. OpenAI accepts input_audio
+    // only on the audio-capable families; the text models reject the block
+    // outright, so copying visionModels here would 400 on every ordinary chat
+    // model. Audio input is also limited to wav and mp3 containers, which is
+    
+    this.audioModels = ['gpt-4o-audio', 'gpt-4o-mini-audio', 'gpt-audio', 'gpt-realtime'];
+    this.audioPayloadFormat = 'openai';
+  }
+}

package/src/providers/qwen-byok.js

@@ -0,0 +1,76 @@
+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 QwenByokProvider 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['qwen']);
+    this.apiKey = config.apiKey;
+    this.visionModels = ['-vl-', '-vl', 'qwen3.6', 'qwen3.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 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' };
+    }
+    
+    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/xai.js

@@ -0,0 +1,73 @@
+import { canonicalModelId } from '../modelIds.js';
+import { DEFAULT_MODEL_BY_PROVIDER } from '../modelCatalogue.js';
+import { LLMProvider } from './base.js';
+
+export class XAIProvider extends LLMProvider {
+  constructor(config) {
+    super(config);
+    this.baseUrl = 'https://api.x.ai/v1/chat/completions';
+    this.model = canonicalModelId(config.model || DEFAULT_MODEL_BY_PROVIDER['xai']);
+    this.visionModels = ['grok-4', 'vision'];
+    // Grok has no audio input block on the chat completions API.
+    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 headers = {
+      'Content-Type': 'application/json'
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    } else {
+      // EXPLICIT BYOK CONSTRAINT
+      throw new Error(`xAI (Grok) API requires a valid API key (BYOK mode). Please set it in your configuration.`);
+    }
+
+    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: headers,
+      body: JSON.stringify(payload)
+    });
+
+    if (!response.ok) {
+      const errorData = await response.text();
+      throw new Error(`xAI API Error (${response.status}): ${errorData}`);
+    }
+
+    const data = await response.json();
+    let content = '';
+    let toolCalls = [];
+    
+    if (data.choices && data.choices[0] && data.choices[0].message) {
+        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/provisioning/capabilityConsent.js

@@ -0,0 +1,24 @@
+// Consent state for capability groups, readable without loading the installer.
+//
+// Three states matter and only three: granted (true), declined (false), and
+// never asked (absent). Collapsing "declined" into "not granted" would make the
+// agent re-ask forever, which is how a consent prompt becomes noise the user
+// learns to dismiss.
+
+import { loadConfig } from '../config.js';
+
+export function consentMap() {
+  try {
+    return loadConfig().capabilityConsent || {};
+  } catch (e) {
+    return {};
+  }
+}
+
+export function isGroupGranted(group) {
+  return consentMap()[group] === true;
+}
+
+export function isGroupDeclined(group) {
+  return consentMap()[group] === false;
+}

package/src/provisioning/capabilityProvisioner.js

@@ -0,0 +1,271 @@
+
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'url';
+import { loadConfig, saveConfig } from '../config.js';
+import { isGroupGranted, isGroupDeclined } from './capabilityConsent.js';
+import { causyneHome } from '../utils/paths.js';
+
+const CAPABILITY_DIR = path.join(causyneHome(), 'capabilities');
+
+// Groups exist so consent is asked once per capability a human recognises
+// ("let it see the screen"), not once per npm package. Names stay in value
+// position — see the D-5 note above.
+const GROUP_PACKAGES = {
+  vision: [
+    ['puppeteer-core', '25.8.0'],
+    ['screenshot-desktop', '1.15.6']
+  ],
+  ocr: [
+    ['tesseract.js', '7.0.0']
+  ],
+  system: [
+    ['systeminformation', '5.33.1']
+  ],
+  desktop: [
+    ['clipboardy', '5.3.2'],
+    ['open', '11.0.1'],
+    ['trash', '10.1.1']
+  ],
+  archive: [
+    ['archiver', '8.0.0'],
+    ['extract-zip', '2.0.1']
+  ]
+};
+
+// What the user is actually agreeing to. This text reaches the approval prompt
+
+// than listing package names.
+export const GROUP_DESCRIPTIONS = {
+  vision: 'drive a browser and capture the screen, so the agent can look at what it built',
+  ocr: 'read text out of images and screenshots',
+  system: 'list running processes and read system load',
+  desktop: 'use the clipboard, open files in their default application, and delete to the recycle bin',
+  archive: 'create and extract zip archives'
+};
+
+export const GROUP_NAMES = Object.keys(GROUP_PACKAGES);
+
+/** Which group owns a package, or null when the package is not ours. */
+export function groupForPackage(packageName) {
+  for (const [group, packages] of Object.entries(GROUP_PACKAGES)) {
+    if (packages.some(([name]) => name === packageName)) return group;
+  }
+  return null;
+}
+
+function manifestFor(groups) {
+  const dependencies = [];
+  for (const group of groups) {
+    for (const entry of GROUP_PACKAGES[group] || []) dependencies.push(entry);
+  }
+  return {
+    name: 'causyne-capabilities-env',
+    version: '1.0.0',
+    private: true,
+    // Keys are produced at runtime; the names above never sit in key position.
+    dependencies: Object.fromEntries(dependencies)
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Consent
+// ---------------------------------------------------------------------------
+
+
+export function grantedGroups() {
+  return GROUP_NAMES.filter(isGroupGranted);
+}
+
+export function grantGroup(group) {
+  if (!GROUP_PACKAGES[group]) return false;
+  const config = loadConfig();
+  config.capabilityConsent = { ...(config.capabilityConsent || {}), [group]: true };
+  saveConfig(config);
+  return true;
+}
+
+export { isGroupGranted, isGroupDeclined };
+
+export function revokeGroup(group) {
+  const config = loadConfig();
+  config.capabilityConsent = { ...(config.capabilityConsent || {}), [group]: false };
+  saveConfig(config);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Availability
+// ---------------------------------------------------------------------------
+
+/** True when the package is already on disk in the sovereign directory. */
+export function isPackageInstalled(packageName) {
+  return fs.existsSync(path.join(CAPABILITY_DIR, 'node_modules', packageName));
+}
+
+export function isGroupInstalled(group) {
+  const packages = GROUP_PACKAGES[group] || [];
+  return packages.length > 0 && packages.every(([name]) => isPackageInstalled(name));
+}
+
+/**
+ * Whether a group can be used right now, and if not, why.
+ *
+ * Deliberately three states, not two. "Not granted" is a question for the user;
+ * "granted but not installed" is work the agent can do; "unavailable" is a
+ * dead end the model should route around rather than retry.
+ */
+export function groupStatus(group) {
+  if (!GROUP_PACKAGES[group]) return { state: 'unknown', group };
+  if (isGroupInstalled(group)) return { state: 'ready', group };
+  if (isGroupGranted(group)) return { state: 'granted-not-installed', group };
+  return { state: 'needs-consent', group, description: GROUP_DESCRIPTIONS[group] };
+}
+
+// ---------------------------------------------------------------------------
+// Provisioning
+// ---------------------------------------------------------------------------
+
+/**
+ * Install every granted group into ~/.causyne/capabilities.
+ *
+ * Runs `npm i` from a written manifest with no explicit package arguments, so a
+ * lockfile is produced and the resulting tree can be audited with `npm audit` —
+ * the same correction finding D-4 forced on the cortex provisioner, where
+ * `--no-save` had left a tree that could not be checked at all.
+ *
+ * @param {string[]} groups groups to ensure are present, added to those already granted
+ */
+export async function provisionCapabilities(groups = []) {
+  const target = [...new Set([...grantedGroups(), ...groups])].filter(g => GROUP_PACKAGES[g]);
+  if (target.length === 0) return { installed: [], skipped: true };
+
+  if (!fs.existsSync(CAPABILITY_DIR)) {
+    fs.mkdirSync(CAPABILITY_DIR, { recursive: true, mode: 0o700 });
+  }
+
+  const manifestPath = path.join(CAPABILITY_DIR, 'package.json');
+  const desired = JSON.stringify(manifestFor(target), null, 2);
+
+  let needsInstall = true;
+  if (fs.existsSync(manifestPath)) {
+    try { needsInstall = fs.readFileSync(manifestPath, 'utf8') !== desired; } catch (e) {}
+  }
+  if (needsInstall) fs.writeFileSync(manifestPath, desired);
+
+  if (!fs.existsSync(path.join(CAPABILITY_DIR, 'package-lock.json'))) needsInstall = true;
+  for (const group of target) {
+    if (!isGroupInstalled(group)) { needsInstall = true; break; }
+  }
+
+  if (!needsInstall) return { installed: target, skipped: true };
+
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  execFileSync(
+    npm,
+    ['install', '--ignore-scripts', '--no-fund'],
+    { cwd: CAPABILITY_DIR, stdio: 'inherit' }
+  );
+  return { installed: target, skipped: false };
+}
+
+/**
+ * The call every capability-backed tool makes first.
+ *
+ * Returns a plain verdict rather than throwing, because the caller has to turn
+ * it into an honest tool result: the model must learn that the capability is
+ * unavailable, not that something crashed.
+ */
+export async function ensureCapability(group) {
+  const status = groupStatus(group);
+  if (status.state === 'ready') return { ok: true, group };
+  if (status.state === 'unknown') return { ok: false, group, reason: `Unknown capability group "${group}".` };
+
+  if (status.state === 'needs-consent') {
+    return {
+      ok: false,
+      group,
+      requiresConsent: true,
+      reason: `This tool needs the "${group}" capability — permission to ${GROUP_DESCRIPTIONS[group]}. ` +
+              `It has not been granted yet, so the tool cannot run. To enable it, call ` +
+              `manage_local_dependencies with action "grant_capability" and group "${group}"; ` +
+              `that request goes to the user for approval.`
+    };
+  }
+
+  // Granted but not yet on disk — do the work now.
+  try {
+    await provisionCapabilities([group]);
+  } catch (e) {
+    return { ok: false, group, reason: `The "${group}" capability could not be prepared: ${e.message}` };
+  }
+  return isGroupInstalled(group)
+    ? { ok: true, group }
+    : { ok: false, group, reason: `The "${group}" capability is unavailable in this environment.` };
+}
+
+/**
+ * Load a provisioned module.
+ *
+ * Mirrors requireCortexModule: resolve through Node's own resolver against the
+ * sovereign directory so `main`/`exports` are honoured, then import a real file
+ * URL. Passing a package DIRECTORY to import() throws ERR_UNSUPPORTED_DIR_IMPORT,
+ * which is the bug that silently disabled the entire V5 Cortex once already.
+ */
+export async function requireCapabilityModule(packageName) {
+  const modulePath = path.join(CAPABILITY_DIR, 'node_modules', packageName);
+  if (!fs.existsSync(modulePath)) {
+    throw new Error(`Capability module ${packageName} is not provisioned.`);
+  }
+
+  const capabilityRequire = createRequire(path.join(CAPABILITY_DIR, 'package.json'));
+  let entryPoint;
+  try {
+    entryPoint = capabilityRequire.resolve(packageName);
+  } catch (resolveError) {
+    const manifestPath = path.join(modulePath, 'package.json');
+    let mainField = 'index.js';
+    if (fs.existsSync(manifestPath)) {
+      try {
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        mainField = manifest.main || manifest.module || 'index.js';
+      } catch (e) {}
+    }
+    entryPoint = path.join(modulePath, mainField);
+    if (!fs.existsSync(entryPoint)) {
+      throw new Error(`Capability module ${packageName} has no resolvable entry point: ${resolveError.message}`);
+    }
+  }
+
+  const mod = await import(pathToFileURL(entryPoint).href);
+  return mod.default || mod;
+}
+
+/**
+ * Load a package, preferring one that is already reachable from the agent's own
+ * install (a developer running from source may simply have it) and falling back
+ * to the sovereign directory. Tools call this instead of a bare dynamic import.
+ */
+export async function loadCapabilityPackage(packageName) {
+  try {
+    const local = await import(packageName);
+    return local.default || local;
+  } catch (e) {
+    try {
+      return await requireCapabilityModule(packageName);
+    } catch (capabilityError) {
+      // Some packages already exist in the Cortex tree as pinned overrides
+      // (sharp, for one). Reuse them rather than installing a second copy that
+      // could drift to a different version than the one that was audited.
+      const { requireCortexModule } = await import('../cortex/provisioner.js');
+      return requireCortexModule(packageName);
+    }
+  }
+}
+
+export function capabilityDirectory() {
+  return CAPABILITY_DIR;
+}

package/src/provisioning/capabilityTools.js

@@ -0,0 +1,29 @@
+// Which catalogue tools depend on which capability group.
+//
+// Kept separate from capabilityProvisioner.js so that registry.js — which runs
+// on every single LLM call — can consult it without pulling in the install
+// machinery, the config vault, or execSafe.
+//
+// A tool appears here only when the capability is REQUIRED for it to do
+// anything. fs_delete is deliberately absent: it prefers the OS recycle bin but
+// has a real safe-rename fallback, so it works with no capability at all.
+
+import { isGroupDeclined } from './capabilityConsent.js';
+
+export const TOOLS_BY_GROUP = {
+  vision: ['browser_act', 'screenshot', 'vision_inspect_ui', 'game_canvas_audit', 'game_web_runtime_inspector'],
+  ocr: [],
+  system: ['process_list'],
+  desktop: ['clipboard', 'desktop_open'],
+  archive: ['archive']
+};
+
+/** Catalogue names the user has explicitly declined the capability for. */
+export function declinedToolNames() {
+  const declined = new Set();
+  for (const [group, tools] of Object.entries(TOOLS_BY_GROUP)) {
+    if (!isGroupDeclined(group)) continue;
+    for (const name of tools) declined.add(name);
+  }
+  return declined;
+}