web-agent-bridge 2.3.1 → 2.5.0

package/server/observability/index.js

@@ -0,0 +1,394 @@
+'use strict';
+
+/**
+ * WAB Observability - Structured Logger, Distributed Tracer, Metrics Collector
+ * 
+ * Provides production-grade observability:
+ * - Structured logging (JSON)
+ * - Distributed tracing (OpenTelemetry-compatible spans)
+ * - Metrics (counters, gauges, histograms)
+ * - Correlation via traceId/spanId
+ */
+
+const crypto = require('crypto');
+
+// ─── Structured Logger ──────────────────────────────────────────────────────
+
+const LogLevel = { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3, FATAL: 4 };
+const LogLevelNames = ['DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+
+class Logger {
+  constructor(options = {}) {
+    this._level = LogLevel[options.level?.toUpperCase()] ?? LogLevel.INFO;
+    this._buffer = [];
+    this._maxBuffer = options.maxBuffer || 10000;
+    this._sinks = [];  // output sinks (console, file, API, etc.)
+    this._context = options.context || {};
+
+    // Default: console sink
+    if (options.console !== false) {
+      this._sinks.push(this._consoleSink.bind(this));
+    }
+  }
+
+  child(context) {
+    const childLogger = new Logger({ level: LogLevelNames[this._level], maxBuffer: 0, console: false });
+    childLogger._context = { ...this._context, ...context };
+    childLogger._sinks = this._sinks;
+    childLogger._buffer = this._buffer;
+    childLogger._maxBuffer = this._maxBuffer;
+    return childLogger;
+  }
+
+  addSink(sink) { this._sinks.push(sink); }
+
+  debug(msg, data) { this._log(LogLevel.DEBUG, msg, data); }
+  info(msg, data)  { this._log(LogLevel.INFO, msg, data); }
+  warn(msg, data)  { this._log(LogLevel.WARN, msg, data); }
+  error(msg, data) { this._log(LogLevel.ERROR, msg, data); }
+  fatal(msg, data) { this._log(LogLevel.FATAL, msg, data); }
+
+  _log(level, msg, data) {
+    if (level < this._level) return;
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level: LogLevelNames[level],
+      message: msg,
+      ...this._context,
+      ...(data || {}),
+    };
+
+    // Buffer
+    this._buffer.push(entry);
+    if (this._buffer.length > this._maxBuffer) {
+      this._buffer.splice(0, this._buffer.length - Math.floor(this._maxBuffer * 0.8));
+    }
+
+    // Flush to sinks
+    for (const sink of this._sinks) {
+      try { sink(entry); } catch (_) { /* sink error, ignore */ }
+    }
+  }
+
+  _consoleSink(entry) {
+    const { timestamp, level, message, ...rest } = entry;
+    const meta = Object.keys(rest).length > 0 ? ` ${JSON.stringify(rest)}` : '';
+    const fn = level === 'ERROR' || level === 'FATAL' ? console.error
+      : level === 'WARN' ? console.warn : console.log;
+    fn(`[${timestamp}] [${level}] ${message}${meta}`);
+  }
+
+  query(filter = {}, limit = 100) {
+    let results = this._buffer;
+    if (filter.level) results = results.filter(e => e.level === filter.level);
+    if (filter.traceId) results = results.filter(e => e.traceId === filter.traceId);
+    if (filter.agentId) results = results.filter(e => e.agentId === filter.agentId);
+    if (filter.since) results = results.filter(e => new Date(e.timestamp).getTime() >= filter.since);
+    if (filter.message) {
+      const re = new RegExp(filter.message, 'i');
+      results = results.filter(e => re.test(e.message));
+    }
+    return results.slice(-limit);
+  }
+}
+
+// ─── Distributed Tracer ─────────────────────────────────────────────────────
+
+class Tracer {
+  constructor() {
+    this._traces = new Map();   // traceId → { spans, metadata }
+    this._maxTraces = 5000;
+    this._stats = { traces: 0, spans: 0, errors: 0 };
+  }
+
+  /**
+   * Start a new trace
+   */
+  startTrace(name, metadata = {}) {
+    const traceId = `trace_${crypto.randomBytes(16).toString('hex')}`;
+    const rootSpan = this._createSpan(traceId, name, null, metadata);
+
+    this._traces.set(traceId, {
+      id: traceId,
+      name,
+      rootSpanId: rootSpan.id,
+      spans: new Map([[rootSpan.id, rootSpan]]),
+      metadata,
+      startedAt: Date.now(),
+      completedAt: null,
+      status: 'active',
+    });
+
+    this._stats.traces++;
+    this._enforceLimit();
+    return { traceId, spanId: rootSpan.id, span: rootSpan };
+  }
+
+  /**
+   * Start a child span within a trace
+   */
+  startSpan(traceId, name, parentSpanId = null, metadata = {}) {
+    const trace = this._traces.get(traceId);
+    if (!trace) return null;
+
+    const span = this._createSpan(traceId, name, parentSpanId || trace.rootSpanId, metadata);
+    trace.spans.set(span.id, span);
+    this._stats.spans++;
+    return span;
+  }
+
+  /**
+   * End a span
+   */
+  endSpan(traceId, spanId, result = {}) {
+    const trace = this._traces.get(traceId);
+    if (!trace) return;
+
+    const span = trace.spans.get(spanId);
+    if (!span) return;
+
+    span.endedAt = Date.now();
+    span.duration = span.endedAt - span.startedAt;
+    span.status = result.error ? 'error' : 'ok';
+    span.result = result;
+
+    if (result.error) this._stats.errors++;
+
+    // Check if all spans are done → complete trace
+    let allDone = true;
+    for (const [, s] of trace.spans) {
+      if (!s.endedAt) { allDone = false; break; }
+    }
+    if (allDone) {
+      trace.completedAt = Date.now();
+      trace.status = 'completed';
+    }
+  }
+
+  /**
+   * Add event to a span (point-in-time annotation)
+   */
+  addEvent(traceId, spanId, name, attributes = {}) {
+    const trace = this._traces.get(traceId);
+    if (!trace) return;
+    const span = trace.spans.get(spanId);
+    if (!span) return;
+    span.events.push({ name, attributes, timestamp: Date.now() });
+  }
+
+  /**
+   * Get full trace
+   */
+  getTrace(traceId) {
+    const trace = this._traces.get(traceId);
+    if (!trace) return null;
+
+    return {
+      id: trace.id,
+      name: trace.name,
+      metadata: trace.metadata,
+      status: trace.status,
+      startedAt: trace.startedAt,
+      completedAt: trace.completedAt,
+      duration: trace.completedAt ? trace.completedAt - trace.startedAt : Date.now() - trace.startedAt,
+      spans: Array.from(trace.spans.values()).map(s => ({
+        id: s.id,
+        name: s.name,
+        parentId: s.parentId,
+        status: s.status,
+        duration: s.duration,
+        startedAt: s.startedAt,
+        endedAt: s.endedAt,
+        events: s.events,
+        attributes: s.attributes,
+        result: s.result,
+      })),
+    };
+  }
+
+  /**
+   * List recent traces
+   */
+  listTraces(limit = 50, filter = {}) {
+    const results = [];
+    for (const [, trace] of this._traces) {
+      if (filter.status && trace.status !== filter.status) continue;
+      if (filter.name && !trace.name.includes(filter.name)) continue;
+      if (filter.since && trace.startedAt < filter.since) continue;
+      results.push({
+        id: trace.id,
+        name: trace.name,
+        status: trace.status,
+        spanCount: trace.spans.size,
+        startedAt: trace.startedAt,
+        duration: trace.completedAt ? trace.completedAt - trace.startedAt : Date.now() - trace.startedAt,
+      });
+      if (results.length >= limit) break;
+    }
+    return results;
+  }
+
+  getStats() {
+    return { ...this._stats, activeTraces: this._traces.size };
+  }
+
+  _createSpan(traceId, name, parentId, metadata) {
+    return {
+      id: `span_${crypto.randomBytes(8).toString('hex')}`,
+      traceId,
+      name,
+      parentId,
+      attributes: metadata,
+      events: [],
+      startedAt: Date.now(),
+      endedAt: null,
+      duration: null,
+      status: 'active',
+      result: null,
+    };
+  }
+
+  _enforceLimit() {
+    if (this._traces.size <= this._maxTraces) return;
+    // Remove oldest completed traces
+    const sorted = Array.from(this._traces.entries())
+      .filter(([, t]) => t.status === 'completed')
+      .sort((a, b) => a[1].startedAt - b[1].startedAt);
+    const toRemove = sorted.slice(0, Math.floor(this._maxTraces * 0.2));
+    for (const [id] of toRemove) this._traces.delete(id);
+  }
+
+  cleanup(maxAge = 3600_000) {
+    const cutoff = Date.now() - maxAge;
+    for (const [id, trace] of this._traces) {
+      if (trace.status === 'completed' && trace.completedAt < cutoff) {
+        this._traces.delete(id);
+      }
+    }
+  }
+}
+
+// ─── Metrics Collector ──────────────────────────────────────────────────────
+
+class MetricsCollector {
+  constructor() {
+    this._counters = new Map();     // name → value
+    this._gauges = new Map();       // name → value
+    this._histograms = new Map();   // name → { values, sum, count, min, max }
+    this._timeSeries = new Map();   // name → [{ value, timestamp }]
+    this._maxTimeSeries = 1000;
+  }
+
+  // Counter (monotonically increasing)
+  increment(name, value = 1, labels = {}) {
+    const key = this._key(name, labels);
+    this._counters.set(key, (this._counters.get(key) || 0) + value);
+    this._recordTimeSeries(key, this._counters.get(key));
+  }
+
+  getCounter(name, labels = {}) {
+    return this._counters.get(this._key(name, labels)) || 0;
+  }
+
+  // Gauge (can go up or down)
+  gauge(name, value, labels = {}) {
+    const key = this._key(name, labels);
+    this._gauges.set(key, value);
+    this._recordTimeSeries(key, value);
+  }
+
+  getGauge(name, labels = {}) {
+    return this._gauges.get(this._key(name, labels)) || 0;
+  }
+
+  // Histogram (distribution of values)
+  observe(name, value, labels = {}) {
+    const key = this._key(name, labels);
+    let hist = this._histograms.get(key);
+    if (!hist) {
+      hist = { values: [], sum: 0, count: 0, min: Infinity, max: -Infinity };
+      this._histograms.set(key, hist);
+    }
+    hist.values.push(value);
+    hist.sum += value;
+    hist.count++;
+    if (value < hist.min) hist.min = value;
+    if (value > hist.max) hist.max = value;
+
+    // Keep last 10000 values for percentile calculations
+    if (hist.values.length > 10000) {
+      hist.values = hist.values.slice(-5000);
+    }
+  }
+
+  getHistogram(name, labels = {}) {
+    const key = this._key(name, labels);
+    const hist = this._histograms.get(key);
+    if (!hist) return null;
+
+    const sorted = [...hist.values].sort((a, b) => a - b);
+    return {
+      count: hist.count,
+      sum: hist.sum,
+      avg: hist.sum / hist.count,
+      min: hist.min,
+      max: hist.max,
+      p50: sorted[Math.floor(sorted.length * 0.5)] || 0,
+      p90: sorted[Math.floor(sorted.length * 0.9)] || 0,
+      p95: sorted[Math.floor(sorted.length * 0.95)] || 0,
+      p99: sorted[Math.floor(sorted.length * 0.99)] || 0,
+    };
+  }
+
+  // Time series for dashboards
+  getTimeSeries(name, labels = {}, since) {
+    const key = this._key(name, labels);
+    const series = this._timeSeries.get(key) || [];
+    if (since) return series.filter(p => p.timestamp >= since);
+    return series;
+  }
+
+  // Snapshot (all metrics)
+  snapshot() {
+    const result = { counters: {}, gauges: {}, histograms: {} };
+    for (const [k, v] of this._counters) result.counters[k] = v;
+    for (const [k, v] of this._gauges) result.gauges[k] = v;
+    for (const [k] of this._histograms) result.histograms[k] = this.getHistogram(k);
+    return result;
+  }
+
+  /**
+   * Timer helper: returns a function to call when done
+   */
+  startTimer(name, labels = {}) {
+    const start = process.hrtime.bigint();
+    return () => {
+      const duration = Number(process.hrtime.bigint() - start) / 1e6; // ms
+      this.observe(name, duration, labels);
+      return duration;
+    };
+  }
+
+  _key(name, labels) {
+    const labelStr = Object.entries(labels).sort().map(([k, v]) => `${k}=${v}`).join(',');
+    return labelStr ? `${name}{${labelStr}}` : name;
+  }
+
+  _recordTimeSeries(key, value) {
+    if (!this._timeSeries.has(key)) this._timeSeries.set(key, []);
+    const series = this._timeSeries.get(key);
+    series.push({ value, timestamp: Date.now() });
+    if (series.length > this._maxTimeSeries) {
+      series.splice(0, series.length - Math.floor(this._maxTimeSeries * 0.8));
+    }
+  }
+}
+
+// ─── Singletons ─────────────────────────────────────────────────────────────
+
+const logger = new Logger({ level: process.env.LOG_LEVEL || 'INFO', console: false });
+const tracer = new Tracer();
+const metrics = new MetricsCollector();
+
+module.exports = { Logger, Tracer, MetricsCollector, logger, tracer, metrics, LogLevel };

package/server/protocol/capabilities.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/**
+ * WAB Protocol (WABP) - Capabilities Negotiation
+ * 
+ * Dynamic capability negotiation between agents and sites.
+ * Agents request capabilities → sites grant/deny based on policies.
+ */
+
+const crypto = require('crypto');
+
+// ─── Capability Grant ───────────────────────────────────────────────────────
+
+class CapabilityGrant {
+  constructor(agentId, capabilities, constraints = {}) {
+    this.id = `grant_${crypto.randomBytes(16).toString('hex')}`;
+    this.agentId = agentId;
+    this.capabilities = new Set(capabilities);
+    this.constraints = {
+      maxCalls: constraints.maxCalls || Infinity,
+      expiresAt: constraints.expiresAt || (Date.now() + 3600_000),
+      allowedDomains: constraints.allowedDomains || ['*'],
+      rateLimit: constraints.rateLimit || { maxPerMinute: 60 },
+      ipRestriction: constraints.ipRestriction || null,
+    };
+    this.usage = { calls: 0, lastUsed: 0 };
+    this.revoked = false;
+    this.createdAt = Date.now();
+  }
+
+  has(capability) {
+    if (this.revoked) return false;
+    if (Date.now() > this.constraints.expiresAt) return false;
+    if (this.usage.calls >= this.constraints.maxCalls) return false;
+    return this.capabilities.has(capability);
+  }
+
+  use(capability) {
+    if (!this.has(capability)) return false;
+    this.usage.calls++;
+    this.usage.lastUsed = Date.now();
+    return true;
+  }
+
+  revoke() {
+    this.revoked = true;
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      agentId: this.agentId,
+      capabilities: [...this.capabilities],
+      constraints: this.constraints,
+      usage: this.usage,
+      revoked: this.revoked,
+      createdAt: this.createdAt,
+    };
+  }
+}
+
+// ─── Capability Negotiator ──────────────────────────────────────────────────
+
+class CapabilityNegotiator {
+  constructor() {
+    this._grants = new Map();      // grantId → CapabilityGrant
+    this._agentGrants = new Map(); // agentId → Set<grantId>
+    this._policies = new Map();    // siteId → policy object
+  }
+
+  /**
+   * Set site-level capability policy
+   */
+  setPolicy(siteId, policy) {
+    this._policies.set(siteId, {
+      allowedCapabilities: new Set(policy.allowedCapabilities || []),
+      deniedCapabilities: new Set(policy.deniedCapabilities || []),
+      requireApproval: new Set(policy.requireApproval || []),
+      maxGrantDuration: policy.maxGrantDuration || 3600_000,
+      defaultRateLimit: policy.defaultRateLimit || { maxPerMinute: 60 },
+      autoGrant: policy.autoGrant !== false,
+    });
+  }
+
+  /**
+   * Negotiate capabilities for an agent
+   * Returns: { granted: string[], denied: string[], pending: string[], grant: CapabilityGrant }
+   */
+  negotiate(agentId, requestedCapabilities, siteId, constraints = {}) {
+    const policy = this._policies.get(siteId);
+    const granted = [];
+    const denied = [];
+    const pending = [];
+
+    for (const cap of requestedCapabilities) {
+      if (policy) {
+        if (policy.deniedCapabilities.has(cap)) {
+          denied.push(cap);
+        } else if (policy.requireApproval.has(cap)) {
+          pending.push(cap);
+        } else if (policy.allowedCapabilities.has(cap) || policy.allowedCapabilities.has('*')) {
+          granted.push(cap);
+        } else if (policy.autoGrant) {
+          granted.push(cap);
+        } else {
+          denied.push(cap);
+        }
+      } else {
+        // No policy = grant low-risk capabilities only
+        const riskLevel = _getCapabilityRisk(cap);
+        if (riskLevel === 'low') granted.push(cap);
+        else if (riskLevel === 'medium') pending.push(cap);
+        else denied.push(cap);
+      }
+    }
+
+    let grant = null;
+    if (granted.length > 0) {
+      const maxDuration = policy ? policy.maxGrantDuration : 3600_000;
+      grant = new CapabilityGrant(agentId, granted, {
+        ...constraints,
+        expiresAt: Date.now() + Math.min(constraints.duration || maxDuration, maxDuration),
+        rateLimit: policy ? policy.defaultRateLimit : constraints.rateLimit,
+      });
+      this._grants.set(grant.id, grant);
+      if (!this._agentGrants.has(agentId)) this._agentGrants.set(agentId, new Set());
+      this._agentGrants.get(agentId).add(grant.id);
+    }
+
+    return { granted, denied, pending, grant };
+  }
+
+  /**
+   * Check if agent has capability via any active grant
+   */
+  check(agentId, capability) {
+    const grantIds = this._agentGrants.get(agentId);
+    if (!grantIds) return false;
+    for (const gid of grantIds) {
+      const grant = this._grants.get(gid);
+      if (grant && grant.has(capability)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Use a capability (decrements usage counter)
+   */
+  use(agentId, capability) {
+    const grantIds = this._agentGrants.get(agentId);
+    if (!grantIds) return false;
+    for (const gid of grantIds) {
+      const grant = this._grants.get(gid);
+      if (grant && grant.use(capability)) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Revoke all grants for an agent
+   */
+  revokeAgent(agentId) {
+    const grantIds = this._agentGrants.get(agentId);
+    if (!grantIds) return;
+    for (const gid of grantIds) {
+      const grant = this._grants.get(gid);
+      if (grant) grant.revoke();
+    }
+    this._agentGrants.delete(agentId);
+  }
+
+  /**
+   * Get all active grants for an agent
+   */
+  getGrants(agentId) {
+    const grantIds = this._agentGrants.get(agentId);
+    if (!grantIds) return [];
+    const grants = [];
+    for (const gid of grantIds) {
+      const grant = this._grants.get(gid);
+      if (grant && !grant.revoked && Date.now() <= grant.constraints.expiresAt) {
+        grants.push(grant.toJSON());
+      }
+    }
+    return grants;
+  }
+
+  /**
+   * Cleanup expired grants
+   */
+  cleanup() {
+    const now = Date.now();
+    for (const [gid, grant] of this._grants) {
+      if (grant.revoked || now > grant.constraints.expiresAt) {
+        this._grants.delete(gid);
+        const agentGrants = this._agentGrants.get(grant.agentId);
+        if (agentGrants) {
+          agentGrants.delete(gid);
+          if (agentGrants.size === 0) this._agentGrants.delete(grant.agentId);
+        }
+      }
+    }
+  }
+}
+
+// ─── Risk Assessment ────────────────────────────────────────────────────────
+
+const _riskMap = {
+  'browser.read': 'low', 'browser.scroll': 'low', 'browser.screenshot': 'low',
+  'browser.click': 'medium', 'browser.fill': 'medium', 'browser.navigate': 'medium',
+  'browser.execute': 'high',
+  'data.extract': 'low', 'data.compare': 'low', 'data.store': 'medium',
+  'agent.communicate': 'medium', 'agent.spawn': 'high', 'agent.delegate': 'high',
+  'system.api': 'high', 'system.webhook': 'high', 'system.schedule': 'medium',
+  'commerce.price': 'low', 'commerce.negotiate': 'high', 'commerce.purchase': 'critical',
+  'ai.infer': 'medium', 'ai.vision': 'low', 'ai.embed': 'low',
+};
+
+function _getCapabilityRisk(capability) {
+  return _riskMap[capability] || 'high';
+}
+
+module.exports = { CapabilityGrant, CapabilityNegotiator };