web-agent-bridge 2.2.0 → 2.3.1

package/sdk/agent-mesh.js

@@ -0,0 +1,449 @@
+/**
+ * WABAgentMesh — SDK Client for the Private Agent Mesh
+ *
+ * High-level client for agents to join the mesh, communicate,
+ * share knowledge, participate in votes, and learn from decisions.
+ * Includes automatic heartbeat, reconnection, and response validation.
+ */
+
+class WABAgentMesh {
+  /**
+   * @param {object} options
+   * @param {string} options.serverUrl - WAB server URL
+   * @param {string} options.role - Agent role (e.g., 'monitor', 'optimizer')
+   * @param {string} [options.displayName] - Human-readable agent name
+   * @param {string[]} [options.capabilities] - List of capabilities
+   * @param {string} [options.siteId] - Site identifier
+   * @param {number} [options.heartbeatInterval=30000] - Heartbeat interval in ms
+   */
+  constructor(options = {}) {
+    this.serverUrl = (options.serverUrl || '').replace(/\/$/, '');
+    this.role = options.role || 'agent';
+    this.displayName = options.displayName || null;
+    this.capabilities = options.capabilities || [];
+    this.siteId = options.siteId || null;
+    this.heartbeatInterval = options.heartbeatInterval || 30000;
+
+    this.agentId = null;
+    this._heartbeatTimer = null;
+    this._retryCount = 0;
+    this._maxRetries = 5;
+    this._listeners = {};
+  }
+
+  // ─── Lifecycle ───────────────────────────────────────────────────
+
+  /**
+   * Join the mesh. Registers the agent and starts heartbeat.
+   * @returns {Promise<object>} Registered agent data
+   */
+  async join() {
+    const res = await this._post('/api/mesh/agents', {
+      siteId: this.siteId,
+      role: this.role,
+      displayName: this.displayName,
+      capabilities: this.capabilities,
+    });
+    const data = await this._json(res);
+    this.agentId = data.agent.id;
+    this._retryCount = 0;
+    this._startHeartbeat();
+    this._emit('joined', data.agent);
+    return data.agent;
+  }
+
+  /**
+   * Leave the mesh. Deregisters and stops heartbeat.
+   */
+  async leave() {
+    this._stopHeartbeat();
+    if (this.agentId) {
+      try {
+        await this._delete(`/api/mesh/agents/${this.agentId}`);
+      } catch (_) { /* ignore errors during cleanup */ }
+      this._emit('left', { agentId: this.agentId });
+      this.agentId = null;
+    }
+  }
+
+  /**
+   * Destroy the client — leave mesh and clean up all resources.
+   */
+  async destroy() {
+    await this.leave();
+    this._listeners = {};
+  }
+
+  // ─── Messaging ─────────────────────────────────────────────────
+
+  /**
+   * Publish a message to a channel.
+   */
+  async publish(type, subject, payload = {}, options = {}) {
+    this._requireJoined();
+    const res = await this._post('/api/mesh/messages', {
+      channelName: options.channel || 'general',
+      senderId: this.agentId,
+      targetId: options.targetId || null,
+      type,
+      subject,
+      payload,
+      priority: options.priority || 0,
+      ttl: options.ttl,
+    });
+    return (await this._json(res)).message;
+  }
+
+  /**
+   * Get messages for this agent.
+   */
+  async getMessages(limit = 50) {
+    this._requireJoined();
+    const res = await this._get(`/api/mesh/messages?agentId=${this.agentId}&limit=${limit}`);
+    return (await this._json(res)).messages;
+  }
+
+  /**
+   * Acknowledge a message.
+   */
+  async acknowledge(messageId) {
+    const res = await this._post(`/api/mesh/messages/${encodeURIComponent(messageId)}/acknowledge`);
+    return (await this._json(res));
+  }
+
+  /**
+   * Get unread count and breakdown by channel.
+   */
+  async getUnread() {
+    this._requireJoined();
+    const res = await this._get(`/api/mesh/agents/${this.agentId}/unread`);
+    return await this._json(res);
+  }
+
+  /**
+   * Broadcast an alert to all agents.
+   */
+  async alert(subject, details, priority = 2) {
+    this._requireJoined();
+    const res = await this._post('/api/mesh/alert', {
+      senderId: this.agentId, subject, details, priority,
+    });
+    return (await this._json(res)).message;
+  }
+
+  /**
+   * Share a tactic with the mesh.
+   */
+  async shareTactic(name, tactic) {
+    this._requireJoined();
+    const res = await this._post('/api/mesh/tactic', {
+      senderId: this.agentId, name, tactic,
+    });
+    return (await this._json(res)).message;
+  }
+
+  /**
+   * Request help from other agents.
+   */
+  async requestHelp(problem, context = {}) {
+    this._requireJoined();
+    const res = await this._post('/api/mesh/help', {
+      senderId: this.agentId, problem, context,
+    });
+    return (await this._json(res)).message;
+  }
+
+  // ─── Knowledge ─────────────────────────────────────────────────
+
+  /**
+   * Share knowledge with the mesh.
+   */
+  async shareKnowledge(type, key, value, options = {}) {
+    this._requireJoined();
+    const res = await this._post('/api/mesh/knowledge', {
+      agentId: this.agentId,
+      type,
+      domain: options.domain,
+      key,
+      value,
+      confidence: options.confidence,
+      source: options.source,
+    });
+    return (await this._json(res)).knowledge;
+  }
+
+  /**
+   * Query knowledge by domain and/or type.
+   */
+  async queryKnowledge(params = {}) {
+    const qs = new URLSearchParams();
+    if (params.domain) qs.set('domain', params.domain);
+    if (params.type) qs.set('type', params.type);
+    if (params.agentId) qs.set('agentId', params.agentId);
+    if (params.limit) qs.set('limit', params.limit);
+    const res = await this._get(`/api/mesh/knowledge?${qs.toString()}`);
+    return (await this._json(res)).knowledge;
+  }
+
+  /**
+   * Search knowledge by keyword.
+   */
+  async searchKnowledge(query, limit = 20) {
+    const res = await this._get(`/api/mesh/knowledge/search/${encodeURIComponent(query)}?limit=${limit}`);
+    return (await this._json(res)).knowledge;
+  }
+
+  /**
+   * Get knowledge domains with counts.
+   */
+  async getKnowledgeDomains() {
+    const res = await this._get('/api/mesh/knowledge-domains');
+    return (await this._json(res)).domains;
+  }
+
+  /**
+   * Verify a knowledge entry.
+   */
+  async verifyKnowledge(knowledgeId, confidence) {
+    this._requireJoined();
+    const res = await this._post(`/api/mesh/knowledge/${encodeURIComponent(knowledgeId)}/verify`, {
+      verifierId: this.agentId, confidence,
+    });
+    return await this._json(res);
+  }
+
+  // ─── Voting ────────────────────────────────────────────────────
+
+  /**
+   * Create a vote for other agents to participate in.
+   */
+  async createVote(subject, options, deadlineSeconds = 60) {
+    this._requireJoined();
+    const res = await this._post('/api/mesh/votes', {
+      senderId: this.agentId, subject, options, deadlineSeconds,
+    });
+    return (await this._json(res)).vote;
+  }
+
+  /**
+   * Cast a vote on an existing vote message.
+   */
+  async castVote(voteMessageId, choice, weight = 1, reason = '') {
+    this._requireJoined();
+    const res = await this._post(`/api/mesh/votes/${encodeURIComponent(voteMessageId)}/cast`, {
+      voterId: this.agentId, choice, weight, reason,
+    });
+    return (await this._json(res)).result;
+  }
+
+  /**
+   * Get the tally for a vote.
+   */
+  async tallyVote(voteMessageId) {
+    const res = await this._get(`/api/mesh/votes/${encodeURIComponent(voteMessageId)}/tally`);
+    return (await this._json(res)).tally;
+  }
+
+  // ─── Learning Integration ─────────────────────────────────────
+
+  /**
+   * Record a decision for learning.
+   */
+  async recordDecision(domain, action, context = {}, features = {}) {
+    const res = await this._post('/api/mesh/learning/decisions', {
+      siteId: this.siteId || 'default',
+      agentId: this.agentId || this.role,
+      domain, action, context, features,
+    });
+    return await this._json(res);
+  }
+
+  /**
+   * Provide feedback on a decision.
+   */
+  async feedback(decisionId, outcome, reward) {
+    const res = await this._post('/api/mesh/learning/feedback', {
+      decisionId, outcome, reward,
+    });
+    return await this._json(res);
+  }
+
+  /**
+   * Get a recommendation for the best action.
+   */
+  async recommend(domain, actions, context = {}) {
+    const res = await this._post('/api/mesh/learning/recommend', {
+      siteId: this.siteId || 'default',
+      agentId: this.agentId || this.role,
+      domain, actions, context,
+    });
+    return await this._json(res);
+  }
+
+  /**
+   * Get learning stats.
+   */
+  async getLearningStats() {
+    const res = await this._get(`/api/mesh/learning/stats?siteId=${this.siteId || 'default'}&agentId=${this.agentId || this.role}`);
+    return (await this._json(res)).stats;
+  }
+
+  // ─── Symphony Integration ─────────────────────────────────────
+
+  /**
+   * Execute a symphony composition.
+   */
+  async compose(template, inputData = {}, schema = null) {
+    const res = await this._post('/api/mesh/symphony/compose', {
+      siteId: this.siteId || 'default',
+      template, inputData, schema,
+    });
+    return await this._json(res);
+  }
+
+  /**
+   * Get available symphony templates.
+   */
+  async getTemplates() {
+    const res = await this._get('/api/mesh/symphony/templates');
+    return (await this._json(res)).templates;
+  }
+
+  // ─── Mesh Info ─────────────────────────────────────────────────
+
+  /**
+   * Get all active agents in the mesh.
+   */
+  async getAgents(role = null) {
+    const qs = role ? `?role=${encodeURIComponent(role)}` : '';
+    const res = await this._get(`/api/mesh/agents${qs}`);
+    return (await this._json(res)).agents;
+  }
+
+  /**
+   * Get mesh stats.
+   */
+  async getStats() {
+    const res = await this._get('/api/mesh/stats');
+    return (await this._json(res)).stats;
+  }
+
+  /**
+   * Update own agent metadata.
+   */
+  async updateMeta(metadata) {
+    this._requireJoined();
+    const res = await this._patch(`/api/mesh/agents/${this.agentId}/meta`, { metadata });
+    return await this._json(res);
+  }
+
+  /**
+   * Set own status.
+   */
+  async setStatus(status) {
+    this._requireJoined();
+    const res = await this._put(`/api/mesh/agents/${this.agentId}/status`, { status });
+    return await this._json(res);
+  }
+
+  // ─── Events ────────────────────────────────────────────────────
+
+  on(event, fn) {
+    if (!this._listeners[event]) this._listeners[event] = [];
+    this._listeners[event].push(fn);
+    return this;
+  }
+
+  off(event, fn) {
+    if (!this._listeners[event]) return this;
+    this._listeners[event] = this._listeners[event].filter((f) => f !== fn);
+    return this;
+  }
+
+  _emit(event, data) {
+    if (this._listeners[event]) {
+      for (const fn of this._listeners[event]) {
+        try { fn(data); } catch (e) { console.error(`[WABAgentMesh] listener error on ${event}:`, e.message); }
+      }
+    }
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────
+
+  _requireJoined() {
+    if (!this.agentId) throw new Error('Agent not joined. Call join() first.');
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this._heartbeatTimer = setInterval(async () => {
+      try {
+        await this._post(`/api/mesh/agents/${this.agentId}/heartbeat`);
+        this._retryCount = 0;
+      } catch (e) {
+        this._retryCount++;
+        this._emit('heartbeat-error', { retryCount: this._retryCount, error: e.message });
+        if (this._retryCount >= this._maxRetries) {
+          this._stopHeartbeat();
+          this._emit('disconnected', { reason: 'heartbeat-failed', retries: this._retryCount });
+        }
+      }
+    }, this.heartbeatInterval);
+  }
+
+  _stopHeartbeat() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+  }
+
+  async _post(path, body) {
+    const fetch = globalThis.fetch || require('node-fetch');
+    return fetch(`${this.serverUrl}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  }
+
+  async _get(path) {
+    const fetch = globalThis.fetch || require('node-fetch');
+    return fetch(`${this.serverUrl}${path}`);
+  }
+
+  async _put(path, body) {
+    const fetch = globalThis.fetch || require('node-fetch');
+    return fetch(`${this.serverUrl}${path}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async _patch(path, body) {
+    const fetch = globalThis.fetch || require('node-fetch');
+    return fetch(`${this.serverUrl}${path}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+  }
+
+  async _delete(path) {
+    const fetch = globalThis.fetch || require('node-fetch');
+    return fetch(`${this.serverUrl}${path}`, { method: 'DELETE' });
+  }
+
+  async _json(res) {
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      let msg;
+      try { msg = JSON.parse(text).error; } catch (_) { msg = text || res.statusText; }
+      throw new Error(`WABAgentMesh HTTP ${res.status}: ${msg}`);
+    }
+    return res.json();
+  }
+}
+
+module.exports = { WABAgentMesh };

package/sdk/commander.js

@@ -0,0 +1,262 @@
+/**
+ * WABCommander — SDK Client for the Commander Agent System
+ *
+ * Provides a high-level API for launching missions, managing edge nodes,
+ * running local AI inference, and orchestrating distributed tasks.
+ * Works in both browser and Node.js environments.
+ */
+
+class WABCommander {
+  /**
+   * @param {object} options
+   * @param {string} options.serverUrl - WAB server URL
+   * @param {string} [options.siteId='default'] - Site identifier
+   */
+  constructor(options = {}) {
+    this.serverUrl = (options.serverUrl || '').replace(/\/$/, '');
+    this.siteId = options.siteId || 'default';
+    this._base = `${this.serverUrl}/api/commander`;
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // MISSIONS
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /** Launch a mission (create + execute in one call). */
+  async launchMission(goal, options = {}) {
+    return this._post('/missions/launch', {
+      siteId: this.siteId, goal,
+      title: options.title, strategy: options.strategy,
+      priority: options.priority, context: options.context,
+    });
+  }
+
+  /** Create a mission plan without executing it. */
+  async createMission(goal, options = {}) {
+    return this._post('/missions', {
+      siteId: this.siteId, goal,
+      title: options.title, strategy: options.strategy,
+      priority: options.priority, context: options.context,
+    });
+  }
+
+  /** Execute an existing mission by ID. */
+  async executeMission(missionId) {
+    return this._post(`/missions/${missionId}/execute`);
+  }
+
+  /** Get a mission by ID. */
+  async getMission(missionId) {
+    return this._get(`/missions/${missionId}`);
+  }
+
+  /** Get mission tasks. */
+  async getMissionTasks(missionId) {
+    return this._get(`/missions/${missionId}/tasks`);
+  }
+
+  /** List missions. */
+  async listMissions(options = {}) {
+    const params = new URLSearchParams({ siteId: this.siteId });
+    if (options.active) params.set('active', 'true');
+    if (options.limit) params.set('limit', String(options.limit));
+    return this._get(`/missions?${params}`);
+  }
+
+  /** Get available decomposition strategies. */
+  async getStrategies() {
+    return this._get('/strategies');
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // AGENTS
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /** Register a commander agent. */
+  async registerAgent(agentType, options = {}) {
+    return this._post('/agents', {
+      siteId: this.siteId, agentType,
+      displayName: options.displayName,
+      capabilities: options.capabilities,
+      modelInfo: options.modelInfo,
+      hardware: options.hardware,
+    });
+  }
+
+  /** List commander agents. */
+  async listAgents(capability) {
+    const params = new URLSearchParams({ siteId: this.siteId });
+    if (capability) params.set('capability', capability);
+    return this._get(`/agents?${params}`);
+  }
+
+  /** Send agent heartbeat. */
+  async agentHeartbeat(agentId) {
+    return this._post(`/agents/${agentId}/heartbeat`);
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // EDGE COMPUTING
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /** Register this device as an edge node. */
+  async registerEdgeNode(hostname, hardware = {}, capabilities = []) {
+    return this._post('/edge/nodes', {
+      siteId: this.siteId, hostname, hardware, capabilities,
+    });
+  }
+
+  /** List edge nodes. */
+  async listEdgeNodes(availableOnly = false) {
+    const params = new URLSearchParams({ siteId: this.siteId });
+    if (availableOnly) params.set('available', 'true');
+    return this._get(`/edge/nodes?${params}`);
+  }
+
+  /** Send node heartbeat. */
+  async nodeHeartbeat(nodeId, currentLoad = 0) {
+    return this._post(`/edge/nodes/${nodeId}/heartbeat`, { currentLoad });
+  }
+
+  /** Remove an edge node. */
+  async removeEdgeNode(nodeId) {
+    return this._delete(`/edge/nodes/${nodeId}`);
+  }
+
+  /** Submit a task to the edge computing queue. */
+  async submitEdgeTask(taskType, payload, options = {}) {
+    return this._post('/edge/tasks', {
+      taskType, payload,
+      priority: options.priority,
+      missionId: options.missionId,
+      encrypt: options.encrypt,
+      encryptionKey: options.encryptionKey,
+    });
+  }
+
+  /** Distribute queued tasks to available nodes. */
+  async distributeEdgeTasks() {
+    return this._post('/edge/distribute', { siteId: this.siteId });
+  }
+
+  /** Complete a task (called by executing node). */
+  async completeEdgeTask(taskId, result, success = true) {
+    return this._post(`/edge/tasks/${taskId}/complete`, { result, success });
+  }
+
+  /** Get tasks for a specific node. */
+  async getNodeTasks(nodeId) {
+    return this._get(`/edge/tasks?nodeId=${nodeId}`);
+  }
+
+  /** List edge swarms. */
+  async listSwarms(capability) {
+    const params = new URLSearchParams({ siteId: this.siteId });
+    if (capability) params.set('capability', capability);
+    return this._get(`/edge/swarms?${params}`);
+  }
+
+  /** Get edge computing stats. */
+  async getEdgeStats() {
+    return this._get(`/edge/stats?siteId=${this.siteId}`);
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // LOCAL AI
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /** Discover local AI models (Ollama, llama.cpp, etc.). */
+  async discoverModels(customEndpoints = []) {
+    return this._post('/local-ai/discover', {
+      siteId: this.siteId, customEndpoints,
+    });
+  }
+
+  /** Register a local model manually. */
+  async registerModel(provider, modelName, endpoint, capabilities, contextWindow) {
+    return this._post('/local-ai/models', {
+      siteId: this.siteId, provider, modelName, endpoint, capabilities, contextWindow,
+    });
+  }
+
+  /** Run local AI inference. */
+  async infer(prompt, options = {}) {
+    return this._post('/local-ai/infer', {
+      siteId: this.siteId, prompt,
+      capability: options.capability,
+      modelId: options.modelId,
+      systemPrompt: options.systemPrompt,
+      temperature: options.temperature,
+      maxTokens: options.maxTokens,
+    });
+  }
+
+  /** List local models. */
+  async listModels(availableOnly = false) {
+    const params = new URLSearchParams({ siteId: this.siteId });
+    if (availableOnly) params.set('available', 'true');
+    return this._get(`/local-ai/models?${params}`);
+  }
+
+  /** Update model status. */
+  async updateModelStatus(modelId, status) {
+    return this._patch(`/local-ai/models/${modelId}`, { status });
+  }
+
+  /** Get local AI stats. */
+  async getLocalAIStats() {
+    return this._get(`/local-ai/stats?siteId=${this.siteId}`);
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // UNIFIED STATS
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  /** Get unified stats across commander, edge, and local AI. */
+  async getStats() {
+    return this._get(`/stats?siteId=${this.siteId}`);
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // HTTP helpers
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  async _get(path) {
+    const res = await fetch(`${this._base}${path}`);
+    if (!res.ok) throw new Error(`GET ${path} failed: ${res.status}`);
+    return res.json();
+  }
+
+  async _post(path, body = {}) {
+    const res = await fetch(`${this._base}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`POST ${path} failed: ${res.status}`);
+    return res.json();
+  }
+
+  async _patch(path, body = {}) {
+    const res = await fetch(`${this._base}${path}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`PATCH ${path} failed: ${res.status}`);
+    return res.json();
+  }
+
+  async _delete(path) {
+    const res = await fetch(`${this._base}${path}`, { method: 'DELETE' });
+    if (!res.ok) throw new Error(`DELETE ${path} failed: ${res.status}`);
+    return res.json();
+  }
+}
+
+// Universal export
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = WABCommander;
+} else if (typeof window !== 'undefined') {
+  window.WABCommander = WABCommander;
+}