@openagents-org/agent-connector 0.1.0

package/src/index.js

@@ -0,0 +1,198 @@
+'use strict';
+
+const { Config } = require('./config');
+const { EnvManager } = require('./env');
+const { Registry } = require('./registry');
+const { Installer } = require('./installer');
+const { Daemon } = require('./daemon');
+const { WorkspaceClient } = require('./workspace-client');
+
+/**
+ * Main entry point for the agent-connector library.
+ * Provides agent management, configuration, and lifecycle control.
+ */
+class AgentConnector {
+  constructor(opts = {}) {
+    const configDir = opts.configDir || AgentConnector.defaultConfigDir();
+    this.config = new Config(configDir);
+    this.env = new EnvManager(configDir);
+    this.registry = new Registry(configDir, opts.registryUrl);
+    this.installer = new Installer(this.registry, configDir);
+    this.workspace = new WorkspaceClient(opts.workspaceEndpoint);
+    this._configDir = configDir;
+  }
+
+  static defaultConfigDir() {
+    const os = require('os');
+    const path = require('path');
+    return path.join(os.homedir(), '.openagents');
+  }
+
+  // -- Registry --
+
+  async getCatalog() {
+    const catalog = await this.registry.getCatalog();
+    return catalog.map((entry) => ({
+      ...entry,
+      installed: this.installer.isInstalled(entry.name),
+    }));
+  }
+
+  getEnvFields(agentType) {
+    return this.registry.getEnvFields(agentType);
+  }
+
+  // -- Install / Uninstall --
+
+  async install(agentType) {
+    return this.installer.install(agentType);
+  }
+
+  async uninstall(agentType) {
+    return this.installer.uninstall(agentType);
+  }
+
+  isInstalled(agentType) {
+    return this.installer.isInstalled(agentType);
+  }
+
+  // -- Agent CRUD --
+
+  listAgents() {
+    const agents = this.config.getAgents();
+    const networks = this.config.getNetworks();
+    return agents.map((a) => {
+      const agentEnv = this.env.load(a.type);
+      const network = networks.find((n) => n.slug === a.network || n.id === a.network);
+      return {
+        name: a.name,
+        type: a.type || 'openclaw',
+        role: a.role || 'worker',
+        network: a.network || null,
+        networkName: network ? (network.name || network.slug) : null,
+        path: a.path || null,
+        env: { ...agentEnv, ...(a.env || {}) },
+      };
+    });
+  }
+
+  addAgent({ name, type, role, path }) {
+    this.config.addAgent({ name, type: type || 'openclaw', role: role || 'worker', path });
+    return { success: true };
+  }
+
+  removeAgent(name) {
+    this.config.removeAgent(name);
+    return { success: true };
+  }
+
+  // -- Env config --
+
+  getAgentEnv(agentType) {
+    return this.env.load(agentType);
+  }
+
+  saveAgentEnv(agentType, env) {
+    this.env.save(agentType, env);
+    return { success: true };
+  }
+
+  resolveAgentEnv(agentType, saved) {
+    return this.env.resolve(agentType, saved, this.registry);
+  }
+
+  // -- Workspace --
+
+  listWorkspaces() {
+    return this.config.getNetworks().map((n) => ({
+      id: n.id,
+      slug: n.slug,
+      name: n.name || n.slug,
+      endpoint: n.endpoint || '',
+    }));
+  }
+
+  connectWorkspace(agentName, networkSlug) {
+    this.config.setAgentNetwork(agentName, networkSlug);
+    return { success: true };
+  }
+
+  disconnectWorkspace(agentName) {
+    this.config.setAgentNetwork(agentName, null);
+    return { success: true };
+  }
+
+  // -- Daemon lifecycle --
+
+  /**
+   * Create a Daemon instance for this connector's config.
+   */
+  createDaemon() {
+    return new Daemon(this.config, this.env, this.registry);
+  }
+
+  /**
+   * Start daemon in background (daemonize).
+   */
+  startDaemon(foregroundArgs) {
+    Daemon.daemonize(this._configDir, foregroundArgs);
+  }
+
+  /**
+   * Stop running daemon.
+   */
+  stopDaemon() {
+    return Daemon.stopDaemon(this._configDir);
+  }
+
+  /**
+   * Get daemon PID if running, null otherwise.
+   */
+  getDaemonPid() {
+    return Daemon.readDaemonPid(this._configDir);
+  }
+
+  /**
+   * Get agent status from daemon status file.
+   */
+  getDaemonStatus() {
+    return this.config.getStatus();
+  }
+
+  /**
+   * Send a command to the running daemon via daemon.cmd file.
+   */
+  sendDaemonCommand(cmd) {
+    this.config.writeCommand(cmd);
+  }
+
+  /**
+   * Get daemon logs, optionally filtered by agent name.
+   */
+  getLogs(agentName, lines = 200) {
+    return this.config.getLogs(agentName, lines);
+  }
+
+  // -- Workspace API --
+
+  async createWorkspace(opts) {
+    return this.workspace.createWorkspace(opts);
+  }
+
+  async joinWorkspace(agentName, token, opts) {
+    return this.workspace.joinNetwork(agentName, token, opts);
+  }
+
+  async resolveToken(token) {
+    return this.workspace.resolveToken(token);
+  }
+
+  // -- LLM test --
+
+  async testLLM(env) {
+    const { testLLMConnection } = require('./utils');
+    return testLLMConnection(env);
+  }
+}
+
+module.exports = { AgentConnector, Daemon, WorkspaceClient };

package/src/installer.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, exec } = require('child_process');
+
+/**
+ * Manages installation and uninstallation of agent runtimes.
+ *
+ * Install markers are stored in two places for compatibility with the Python SDK:
+ *   1. ~/.openagents/installed_agents.json  (JSON array of names)
+ *   2. ~/.openagents/installed/<name>       (empty marker files)
+ */
+class Installer {
+  constructor(registry, configDir) {
+    this.registry = registry;
+    this.configDir = configDir;
+    this.markersFile = path.join(configDir, 'installed_agents.json');
+    this.markersDir = path.join(configDir, 'installed');
+  }
+
+  /**
+   * Get the current platform key: 'macos', 'linux', or 'windows'.
+   */
+  static platform() {
+    const p = process.platform;
+    if (p === 'darwin') return 'macos';
+    if (p === 'win32') return 'windows';
+    return 'linux';
+  }
+
+  /**
+   * Check if an agent type is installed.
+   * Checks binary on PATH first, then marker files.
+   */
+  isInstalled(agentType) {
+    if (this._whichBinary(agentType)) return true;
+    return this._hasMarker(agentType);
+  }
+
+  /**
+   * Find the binary path for an agent type.
+   */
+  which(agentType) {
+    return this._whichBinary(agentType);
+  }
+
+  /**
+   * Install an agent runtime.
+   * @returns {Promise<{success: boolean, output: string}>}
+   */
+  async install(agentType) {
+    const entry = this.registry.getEntry(agentType);
+    if (!entry || !entry.install) {
+      throw new Error(`No install definition for agent type: ${agentType}`);
+    }
+
+    const cmd = this._getInstallCommand(entry.install);
+    if (!cmd) {
+      throw new Error(`No install command for ${agentType} on ${Installer.platform()}`);
+    }
+
+    const output = await this._execShell(cmd);
+    this._markInstalled(agentType);
+    return { success: true, output };
+  }
+
+  /**
+   * Uninstall an agent runtime.
+   * @returns {Promise<{success: boolean, output: string}>}
+   */
+  async uninstall(agentType) {
+    const entry = this.registry.getEntry(agentType);
+    if (!entry || !entry.install) {
+      throw new Error(`No install definition for agent type: ${agentType}`);
+    }
+
+    const installCmd = this._getInstallCommand(entry.install);
+    const uninstallCmd = this._deriveUninstallCommand(installCmd);
+    if (!uninstallCmd) {
+      throw new Error(`Cannot derive uninstall command for ${agentType}`);
+    }
+
+    const output = await this._execShell(uninstallCmd);
+    this._markUninstalled(agentType);
+    return { success: true, output };
+  }
+
+  /**
+   * Get install command for current platform.
+   */
+  _getInstallCommand(installCfg) {
+    const plat = Installer.platform();
+    return installCfg[plat] || installCfg.command || null;
+  }
+
+  /**
+   * Derive uninstall command from install command.
+   */
+  _deriveUninstallCommand(installCmd) {
+    if (!installCmd) return null;
+
+    // npm install -g <pkg> → npm uninstall -g <pkg>
+    if (installCmd.includes('npm install')) {
+      return installCmd
+        .replace('npm install -g', 'npm uninstall -g')
+        .replace('npm install', 'npm uninstall')
+        .replace(/@latest/g, '')
+        .replace(/@[\d.]+/g, '');
+    }
+
+    // pip install <pkg> → pip uninstall -y <pkg>
+    if (installCmd.includes('pip install') || installCmd.includes('pip3 install')) {
+      return installCmd
+        .replace('pip install', 'pip uninstall -y')
+        .replace('pip3 install', 'pip3 uninstall -y');
+    }
+
+    // pipx install <pkg> → pipx uninstall <pkg>
+    if (installCmd.includes('pipx install')) {
+      return installCmd.replace('pipx install', 'pipx uninstall');
+    }
+
+    return null;
+  }
+
+  /**
+   * Find a binary on PATH.
+   */
+  _whichBinary(agentType) {
+    const entry = this.registry.getEntry(agentType);
+    const binary = entry && entry.install ? entry.install.binary : agentType;
+    if (!binary) return null;
+
+    try {
+      const cmd = process.platform === 'win32' ? `where ${binary}` : `which ${binary}`;
+      const result = execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      return result.split('\n')[0] || null;
+    } catch {
+      return null;
+    }
+  }
+
+  // -- Markers --
+
+  _hasMarker(agentType) {
+    // Check per-agent marker file first (faster)
+    try {
+      if (fs.existsSync(path.join(this.markersDir, agentType))) return true;
+    } catch {}
+
+    // Check JSON markers file
+    try {
+      if (fs.existsSync(this.markersFile)) {
+        const data = JSON.parse(fs.readFileSync(this.markersFile, 'utf-8'));
+        if (Array.isArray(data) && data.includes(agentType)) return true;
+      }
+    } catch {}
+
+    return false;
+  }
+
+  _markInstalled(agentType) {
+    // JSON file
+    try {
+      fs.mkdirSync(this.configDir, { recursive: true });
+      let markers = [];
+      try {
+        markers = JSON.parse(fs.readFileSync(this.markersFile, 'utf-8'));
+        if (!Array.isArray(markers)) markers = [];
+      } catch {}
+      if (!markers.includes(agentType)) {
+        markers.push(agentType);
+        markers.sort();
+      }
+      fs.writeFileSync(this.markersFile, JSON.stringify(markers), 'utf-8');
+    } catch {}
+
+    // Per-agent marker file
+    try {
+      fs.mkdirSync(this.markersDir, { recursive: true });
+      fs.writeFileSync(path.join(this.markersDir, agentType), '', 'utf-8');
+    } catch {}
+  }
+
+  _markUninstalled(agentType) {
+    // JSON file
+    try {
+      if (fs.existsSync(this.markersFile)) {
+        let markers = JSON.parse(fs.readFileSync(this.markersFile, 'utf-8'));
+        if (Array.isArray(markers)) {
+          markers = markers.filter((m) => m !== agentType);
+          fs.writeFileSync(this.markersFile, JSON.stringify(markers), 'utf-8');
+        }
+      }
+    } catch {}
+
+    // Per-agent marker file
+    try {
+      const markerFile = path.join(this.markersDir, agentType);
+      if (fs.existsSync(markerFile)) fs.unlinkSync(markerFile);
+    } catch {}
+  }
+
+  // -- Shell exec --
+
+  _execShell(cmd, timeoutMs = 300000) {
+    return new Promise((resolve, reject) => {
+      exec(cmd, {
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        shell: true,
+        env: { ...process.env },
+      }, (error, stdout, stderr) => {
+        const output = ((stdout || '') + '\n' + (stderr || '')).trim();
+        if (error) {
+          const err = new Error(output || error.message);
+          err.exitCode = error.code;
+          reject(err);
+        } else {
+          resolve(output);
+        }
+      });
+    });
+  }
+}
+
+module.exports = { Installer };

package/src/registry.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_REGISTRY_URL = 'https://endpoint.openagents.org/v1/agent-registry';
+const CACHE_FILE = 'agent_catalog.json';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Agent registry — fetches the catalog of available agent types.
+ *
+ * Priority: remote API → local cache (24h) → bundled registry.json
+ */
+class Registry {
+  constructor(configDir, registryUrl) {
+    this.configDir = configDir;
+    this.registryUrl = registryUrl || DEFAULT_REGISTRY_URL;
+    this.cacheFile = path.join(configDir, CACHE_FILE);
+    this._catalog = null; // in-memory cache
+  }
+
+  /**
+   * Get the full agent catalog. Tries remote, then cache, then bundled.
+   * @returns {Promise<object[]>}
+   */
+  async getCatalog() {
+    if (this._catalog) return this._catalog;
+
+    // Try cache first (avoids network on every call)
+    const cached = this._loadCache();
+    if (cached) {
+      this._catalog = cached;
+      // Refresh in background if stale (but still return cached)
+      this._refreshInBackground();
+      return cached;
+    }
+
+    // No cache — try remote
+    const remote = await this._fetchRemote();
+    if (remote) {
+      this._catalog = remote;
+      return remote;
+    }
+
+    // Fallback to bundled
+    this._catalog = this._loadBundled();
+    return this._catalog;
+  }
+
+  /**
+   * Get catalog synchronously (cache or bundled only, no network).
+   */
+  getCatalogSync() {
+    if (this._catalog) return this._catalog;
+    const cached = this._loadCache();
+    if (cached) { this._catalog = cached; return cached; }
+    this._catalog = this._loadBundled();
+    return this._catalog;
+  }
+
+  /**
+   * Get env field definitions for an agent type.
+   */
+  getEnvFields(agentType) {
+    const catalog = this.getCatalogSync();
+    const entry = catalog.find((e) => e.name === agentType);
+    return entry ? (entry.env_config || []) : [];
+  }
+
+  /**
+   * Get resolve_env rules for an agent type.
+   */
+  getResolveRules(agentType) {
+    const catalog = this.getCatalogSync();
+    const entry = catalog.find((e) => e.name === agentType);
+    if (!entry || !entry.resolve_env) return [];
+    return entry.resolve_env.rules || [];
+  }
+
+  /**
+   * Get a single catalog entry by name.
+   */
+  getEntry(agentType) {
+    const catalog = this.getCatalogSync();
+    return catalog.find((e) => e.name === agentType) || null;
+  }
+
+  /**
+   * Force refresh from remote API.
+   */
+  async refresh() {
+    const remote = await this._fetchRemote();
+    if (remote) this._catalog = remote;
+    return this._catalog || this.getCatalogSync();
+  }
+
+  // -- Internal --
+
+  _loadCache() {
+    try {
+      if (!fs.existsSync(this.cacheFile)) return null;
+      const stat = fs.statSync(this.cacheFile);
+      if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) return null;
+      const data = JSON.parse(fs.readFileSync(this.cacheFile, 'utf-8'));
+      return Array.isArray(data) ? data : null;
+    } catch {
+      return null;
+    }
+  }
+
+  _saveCache(data) {
+    try {
+      fs.mkdirSync(this.configDir, { recursive: true });
+      fs.writeFileSync(this.cacheFile, JSON.stringify(data, null, 2), 'utf-8');
+    } catch {}
+  }
+
+  _loadBundled() {
+    try {
+      const bundledPath = path.join(__dirname, '..', 'registry.json');
+      if (fs.existsSync(bundledPath)) {
+        return JSON.parse(fs.readFileSync(bundledPath, 'utf-8'));
+      }
+    } catch {}
+    return [];
+  }
+
+  async _fetchRemote() {
+    try {
+      const data = await httpGetJson(this.registryUrl, 5000);
+      // API returns { data: [...] } or directly [...]
+      const catalog = Array.isArray(data) ? data : (data.data || []);
+      if (catalog.length > 0) {
+        this._saveCache(catalog);
+      }
+      return catalog;
+    } catch {
+      return null;
+    }
+  }
+
+  _refreshInBackground() {
+    // Check if cache is older than TTL
+    try {
+      const stat = fs.statSync(this.cacheFile);
+      if (Date.now() - stat.mtimeMs < CACHE_TTL_MS) return;
+    } catch {
+      return;
+    }
+    // Fire and forget
+    this._fetchRemote().catch(() => {});
+  }
+}
+
+/**
+ * Simple HTTP GET that returns parsed JSON. No external dependencies.
+ */
+function httpGetJson(url, timeoutMs = 5000) {
+  return new Promise((resolve, reject) => {
+    const parsedUrl = new URL(url);
+    const transport = parsedUrl.protocol === 'https:' ? require('https') : require('http');
+
+    const req = transport.get(url, { timeout: timeoutMs }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow redirect
+        httpGetJson(res.headers.location, timeoutMs).then(resolve, reject);
+        return;
+      }
+      if (res.statusCode >= 400) {
+        reject(new Error(`HTTP ${res.statusCode}`));
+        res.resume();
+        return;
+      }
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(e); }
+      });
+    });
+
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('Timeout')); });
+  });
+}
+
+module.exports = { Registry };

package/src/utils.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * Test an LLM connection by sending a minimal inference request.
+ *
+ * Supports OpenAI-compatible and Anthropic APIs.
+ *
+ * @param {object} env - Env vars (LLM_API_KEY, LLM_BASE_URL, LLM_MODEL, etc.)
+ * @returns {Promise<{success: boolean, model?: string, response?: string, error?: string}>}
+ */
+function testLLMConnection(env) {
+  const https = require('https');
+  const http = require('http');
+
+  const apiKey = env.LLM_API_KEY || env.OPENAI_API_KEY || env.ANTHROPIC_API_KEY || '';
+  if (!apiKey) return Promise.resolve({ success: false, error: 'No API key provided' });
+
+  let baseUrl = (env.LLM_BASE_URL || env.OPENAI_BASE_URL || 'https://api.openai.com/v1').replace(/\/$/, '');
+  const model = env.LLM_MODEL || env.OPENCLAW_MODEL || '';
+  const isAnthropic = baseUrl.includes('anthropic');
+
+  if (!isAnthropic && !baseUrl.endsWith('/v1')) {
+    baseUrl += '/v1';
+  }
+
+  return new Promise((resolve) => {
+    let url, headers, body;
+
+    if (isAnthropic) {
+      url = 'https://api.anthropic.com/v1/messages';
+      headers = {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      };
+      body = JSON.stringify({
+        model: model || 'claude-sonnet-4-20250514',
+        max_tokens: 32,
+        messages: [{ role: 'user', content: 'Say hi in 5 words.' }],
+      });
+    } else {
+      url = baseUrl + '/chat/completions';
+      headers = {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      };
+      body = JSON.stringify({
+        model: model || 'gpt-4o-mini',
+        max_tokens: 32,
+        messages: [{ role: 'user', content: 'Say hi in 5 words.' }],
+      });
+    }
+
+    const parsedUrl = new URL(url);
+    const transport = parsedUrl.protocol === 'https:' ? https : http;
+
+    const req = transport.request(url, {
+      method: 'POST',
+      headers: { ...headers, 'Content-Length': Buffer.byteLength(body) },
+      timeout: 15000,
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          let text, usedModel;
+          if (isAnthropic) {
+            text = (parsed.content || [{}])[0].text || '';
+            usedModel = parsed.model || model || '?';
+          } else {
+            text = (parsed.choices || [{}])[0]?.message?.content || '';
+            usedModel = parsed.model || model || '?';
+          }
+          if (res.statusCode >= 400) {
+            resolve({ success: false, error: `HTTP ${res.statusCode}: ${data.slice(0, 200)}` });
+          } else {
+            resolve({ success: true, model: usedModel, response: text.slice(0, 80) });
+          }
+        } catch {
+          resolve({ success: false, error: `Invalid response: ${data.slice(0, 200)}` });
+        }
+      });
+    });
+
+    req.on('error', (e) => resolve({ success: false, error: e.message }));
+    req.on('timeout', () => { req.destroy(); resolve({ success: false, error: 'Request timed out' }); });
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { testLLMConnection };