opc-agent 4.1.24 → 4.2.1

package/dist/core/gateway-registry.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Tool Gateway — Remote managed tool provider pattern.
+ *
+ * Inspired by Hermes Agent v0.10's Tool Gateway feature.
+ * Allows agents to access remote tool services (web search, image gen, TTS,
+ * browser automation) through a unified gateway, removing the need for
+ * individual API keys per tool.
+ *
+ * Key features:
+ * - Subscription-based tool access (single API key → multiple tools)
+ * - Per-tool opt-in/opt-out via configuration
+ * - Auto-detection of gateway availability
+ * - Fallback to direct API keys when gateway unavailable
+ * - Usage tracking and quota enforcement
+ *
+ * Usage:
+ *   const gw = new ToolGateway({ endpoint: 'https://tools.example.com', apiKey: '...' });
+ *   await gw.connect();
+ *   const result = await gw.invoke('web-search', { query: 'hello' });
+ */
+import { EventEmitter } from 'events';
+export interface ToolGatewayConfig {
+    /** Gateway endpoint URL */
+    endpoint: string;
+    /** API key / subscription token for the gateway */
+    apiKey: string;
+    /** Tools to enable (empty = all available) */
+    enabledTools?: string[];
+    /** Timeout for gateway calls (ms, default 60s) */
+    timeout?: number;
+    /** Whether to prefer gateway over direct API keys */
+    preferGateway?: boolean;
+    /** Retry config */
+    retry?: {
+        maxRetries?: number;
+        backoffMs?: number;
+    };
+}
+export interface GatewayTool {
+    id: string;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    category: 'search' | 'generation' | 'browser' | 'tts' | 'utility' | string;
+    quotaRemaining?: number;
+    available: boolean;
+}
+export interface GatewayInvocation {
+    toolId: string;
+    input: Record<string, unknown>;
+    requestId?: string;
+}
+export interface GatewayResult {
+    toolId: string;
+    requestId: string;
+    status: 'success' | 'error' | 'quota_exceeded' | 'unavailable';
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+    quotaRemaining?: number;
+}
+export interface GatewayStatus {
+    connected: boolean;
+    endpoint: string;
+    tools: GatewayTool[];
+    subscription?: {
+        tier: string;
+        quotaUsed: number;
+        quotaTotal: number;
+        resetAt?: string;
+    };
+}
+export declare class ToolGateway extends EventEmitter {
+    private config;
+    private tools;
+    private connected;
+    private logger;
+    private invocationCount;
+    constructor(config: ToolGatewayConfig);
+    /** Connect to gateway and discover available tools */
+    connect(): Promise<GatewayStatus>;
+    /** Invoke a tool through the gateway */
+    invoke(toolId: string, input: Record<string, unknown>): Promise<GatewayResult>;
+    /** Get a tool definition (for MCP/tool schema exposure) */
+    getTool(toolId: string): GatewayTool | undefined;
+    /** List all available tools */
+    listTools(): GatewayTool[];
+    /** Get current status */
+    getStatus(): GatewayStatus;
+    /** Check if gateway should be preferred over direct API call */
+    shouldUseGateway(toolId: string): boolean;
+    /** Disconnect from gateway */
+    disconnect(): void;
+    get isConnected(): boolean;
+    get totalInvocations(): number;
+    private request;
+    private generateRequestId;
+}
+export declare class ToolGatewayRegistry {
+    private gateways;
+    private toolToGateway;
+    private logger;
+    /** Register a gateway */
+    register(name: string, gateway: ToolGateway): void;
+    /** Find which gateway provides a tool */
+    findGateway(toolId: string): ToolGateway | undefined;
+    /** Invoke a tool, auto-routing to the right gateway */
+    invoke(toolId: string, input: Record<string, unknown>): Promise<GatewayResult>;
+    /** List all tools across all gateways */
+    listAllTools(): Array<GatewayTool & {
+        gateway: string;
+    }>;
+    /** Disconnect all gateways */
+    disconnectAll(): void;
+}
+//# sourceMappingURL=gateway-registry.d.ts.map

package/dist/core/gateway-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-registry.d.ts","sourceRoot":"","sources":["../../src/core/gateway-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/gateway-registry.js

@@ -0,0 +1,280 @@
+"use strict";
+/**
+ * Tool Gateway — Remote managed tool provider pattern.
+ *
+ * Inspired by Hermes Agent v0.10's Tool Gateway feature.
+ * Allows agents to access remote tool services (web search, image gen, TTS,
+ * browser automation) through a unified gateway, removing the need for
+ * individual API keys per tool.
+ *
+ * Key features:
+ * - Subscription-based tool access (single API key → multiple tools)
+ * - Per-tool opt-in/opt-out via configuration
+ * - Auto-detection of gateway availability
+ * - Fallback to direct API keys when gateway unavailable
+ * - Usage tracking and quota enforcement
+ *
+ * Usage:
+ *   const gw = new ToolGateway({ endpoint: 'https://tools.example.com', apiKey: '...' });
+ *   await gw.connect();
+ *   const result = await gw.invoke('web-search', { query: 'hello' });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolGatewayRegistry = exports.ToolGateway = void 0;
+const events_1 = require("events");
+const logger_1 = require("./logger");
+// ─── Tool Gateway ────────────────────────────────────────────
+class ToolGateway extends events_1.EventEmitter {
+    config;
+    tools = new Map();
+    connected = false;
+    logger = new logger_1.Logger('tool-gateway');
+    invocationCount = 0;
+    constructor(config) {
+        super();
+        this.config = {
+            endpoint: config.endpoint.replace(/\/$/, ''),
+            apiKey: config.apiKey,
+            enabledTools: config.enabledTools ?? [],
+            timeout: config.timeout ?? 60_000,
+            preferGateway: config.preferGateway ?? true,
+            retry: {
+                maxRetries: config.retry?.maxRetries ?? 2,
+                backoffMs: config.retry?.backoffMs ?? 1000,
+            },
+        };
+    }
+    /** Connect to gateway and discover available tools */
+    async connect() {
+        try {
+            const res = await this.request('GET', '/tools');
+            const data = res;
+            this.tools.clear();
+            for (const tool of data.tools) {
+                // If enabledTools is specified, only include those
+                if (this.config.enabledTools.length === 0 ||
+                    this.config.enabledTools.includes(tool.id)) {
+                    this.tools.set(tool.id, tool);
+                }
+            }
+            this.connected = true;
+            this.logger.info('Connected to tool gateway', {
+                endpoint: this.config.endpoint,
+                tools: this.tools.size,
+            });
+            this.emit('connected', this.getStatus());
+            return {
+                connected: true,
+                endpoint: this.config.endpoint,
+                tools: Array.from(this.tools.values()),
+                subscription: data.subscription,
+            };
+        }
+        catch (err) {
+            this.connected = false;
+            this.logger.error('Failed to connect to tool gateway', {
+                error: err.message,
+            });
+            throw err;
+        }
+    }
+    /** Invoke a tool through the gateway */
+    async invoke(toolId, input) {
+        if (!this.connected) {
+            throw new Error('Tool gateway not connected. Call connect() first.');
+        }
+        const tool = this.tools.get(toolId);
+        if (!tool) {
+            return {
+                toolId,
+                requestId: this.generateRequestId(),
+                status: 'unavailable',
+                error: `Tool "${toolId}" not available on this gateway`,
+                durationMs: 0,
+            };
+        }
+        if (!tool.available) {
+            return {
+                toolId,
+                requestId: this.generateRequestId(),
+                status: 'unavailable',
+                error: `Tool "${toolId}" is currently unavailable`,
+                durationMs: 0,
+            };
+        }
+        const requestId = this.generateRequestId();
+        const start = Date.now();
+        try {
+            const result = await this.request('POST', '/invoke', {
+                toolId,
+                input,
+                requestId,
+            });
+            const durationMs = Date.now() - start;
+            this.invocationCount++;
+            const gatewayResult = {
+                toolId,
+                requestId,
+                status: 'success',
+                output: result.output,
+                durationMs,
+                quotaRemaining: result.quotaRemaining,
+            };
+            // Update quota info
+            if (gatewayResult.quotaRemaining !== undefined) {
+                tool.quotaRemaining = gatewayResult.quotaRemaining;
+            }
+            this.emit('invocation', gatewayResult);
+            return gatewayResult;
+        }
+        catch (err) {
+            const durationMs = Date.now() - start;
+            const message = err.message;
+            const status = message.includes('quota') ? 'quota_exceeded' : 'error';
+            const gatewayResult = {
+                toolId,
+                requestId,
+                status,
+                error: message,
+                durationMs,
+            };
+            this.emit('invocation:error', gatewayResult);
+            return gatewayResult;
+        }
+    }
+    /** Get a tool definition (for MCP/tool schema exposure) */
+    getTool(toolId) {
+        return this.tools.get(toolId);
+    }
+    /** List all available tools */
+    listTools() {
+        return Array.from(this.tools.values());
+    }
+    /** Get current status */
+    getStatus() {
+        return {
+            connected: this.connected,
+            endpoint: this.config.endpoint,
+            tools: Array.from(this.tools.values()),
+        };
+    }
+    /** Check if gateway should be preferred over direct API call */
+    shouldUseGateway(toolId) {
+        if (!this.connected)
+            return false;
+        if (!this.config.preferGateway)
+            return false;
+        const tool = this.tools.get(toolId);
+        if (!tool || !tool.available)
+            return false;
+        if (tool.quotaRemaining !== undefined && tool.quotaRemaining <= 0)
+            return false;
+        return true;
+    }
+    /** Disconnect from gateway */
+    disconnect() {
+        this.connected = false;
+        this.tools.clear();
+        this.emit('disconnected');
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    get totalInvocations() {
+        return this.invocationCount;
+    }
+    // ─── Private helpers ─────────────────────────────────────────
+    async request(method, path, body) {
+        const url = `${this.config.endpoint}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.timeout);
+        let lastError;
+        const maxAttempts = 1 + (this.config.retry?.maxRetries ?? 0);
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                const res = await fetch(url, {
+                    method,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${this.config.apiKey}`,
+                        'X-Client': 'opc-agent',
+                    },
+                    body: body ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (!res.ok) {
+                    const errBody = await res.text().catch(() => '');
+                    throw new Error(`Gateway ${res.status}: ${errBody || res.statusText}`);
+                }
+                return await res.json();
+            }
+            catch (err) {
+                lastError = err;
+                if (attempt < maxAttempts - 1) {
+                    await new Promise(r => setTimeout(r, (this.config.retry?.backoffMs ?? 1000) * (attempt + 1)));
+                }
+            }
+        }
+        clearTimeout(timer);
+        throw lastError;
+    }
+    generateRequestId() {
+        return `gw_${++this.invocationCount}_${Date.now().toString(36)}`;
+    }
+}
+exports.ToolGateway = ToolGateway;
+// ─── Tool Gateway Registry (multi-gateway support) ───────────
+class ToolGatewayRegistry {
+    gateways = new Map();
+    toolToGateway = new Map();
+    logger = new logger_1.Logger('tool-gateway-registry');
+    /** Register a gateway */
+    register(name, gateway) {
+        this.gateways.set(name, gateway);
+        // Index tools → gateway
+        for (const tool of gateway.listTools()) {
+            this.toolToGateway.set(tool.id, name);
+        }
+        this.logger.info('Gateway registered', { name, tools: gateway.listTools().length });
+    }
+    /** Find which gateway provides a tool */
+    findGateway(toolId) {
+        const name = this.toolToGateway.get(toolId);
+        return name ? this.gateways.get(name) : undefined;
+    }
+    /** Invoke a tool, auto-routing to the right gateway */
+    async invoke(toolId, input) {
+        const gateway = this.findGateway(toolId);
+        if (!gateway) {
+            return {
+                toolId,
+                requestId: 'none',
+                status: 'unavailable',
+                error: `No gateway provides tool "${toolId}"`,
+                durationMs: 0,
+            };
+        }
+        return gateway.invoke(toolId, input);
+    }
+    /** List all tools across all gateways */
+    listAllTools() {
+        const result = [];
+        for (const [name, gw] of this.gateways) {
+            for (const tool of gw.listTools()) {
+                result.push({ ...tool, gateway: name });
+            }
+        }
+        return result;
+    }
+    /** Disconnect all gateways */
+    disconnectAll() {
+        for (const gw of this.gateways.values()) {
+            gw.disconnect();
+        }
+        this.gateways.clear();
+        this.toolToGateway.clear();
+    }
+}
+exports.ToolGatewayRegistry = ToolGatewayRegistry;
+//# sourceMappingURL=gateway-registry.js.map

package/dist/core/gateway-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-registry.js","sourceRoot":"","sources":["../../src/core/gateway-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/priority-queue.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Priority Queue / Fast Mode — Route requests through priority tiers
+ * for lower latency on supported providers.
+ *
+ * Inspired by Hermes Agent's /fast mode. Provides a priority-aware request
+ * queue that separates normal and fast-mode requests, ensuring fast-mode
+ * requests are processed first and routed to provider priority endpoints.
+ *
+ * Usage:
+ *   const pq = new PriorityQueue();
+ *   pq.enqueue({ id: 'req1', priority: 'fast', provider: 'openai', ... });
+ *   const next = pq.dequeue(); // Always returns highest priority first
+ */
+import { EventEmitter } from 'events';
+export type PriorityLevel = 'fast' | 'normal' | 'batch';
+export interface PriorityRequest {
+    id: string;
+    priority: PriorityLevel;
+    provider: string;
+    model: string;
+    payload: unknown;
+    enqueuedAt: number;
+    metadata?: Record<string, unknown>;
+}
+export interface PriorityConfig {
+    /** Maximum concurrent fast-mode requests per provider */
+    maxConcurrentFast?: number;
+    /** Maximum concurrent normal requests per provider */
+    maxConcurrentNormal?: number;
+    /** Timeout for fast-mode requests before fallback (ms, default 30s) */
+    fastTimeout?: number;
+    /** Providers that support priority routing */
+    supportedProviders?: string[];
+}
+export interface ProviderPriorityEndpoint {
+    provider: string;
+    priorityUrl?: string;
+    priorityHeader?: {
+        key: string;
+        value: string;
+    };
+    priorityParam?: {
+        key: string;
+        value: string;
+    };
+}
+export declare class PriorityQueue extends EventEmitter {
+    private queues;
+    private activeCounts;
+    private config;
+    private endpoints;
+    constructor(config?: PriorityConfig);
+    /** Register a custom priority endpoint for a provider */
+    registerEndpoint(endpoint: ProviderPriorityEndpoint): void;
+    /** Check if a provider supports priority routing */
+    supportsPriority(provider: string): boolean;
+    /** Get priority endpoint configuration for a provider */
+    getEndpoint(provider: string): ProviderPriorityEndpoint | undefined;
+    /** Enqueue a request */
+    enqueue(request: PriorityRequest): void;
+    /** Dequeue the next highest-priority request that can run */
+    dequeue(): PriorityRequest | undefined;
+    /** Mark a request as completed, freeing a concurrency slot */
+    complete(provider: string, priority: PriorityLevel): void;
+    /** Get queue lengths */
+    getStats(): {
+        fast: number;
+        normal: number;
+        batch: number;
+        total: number;
+        active: Record<string, {
+            fast: number;
+            normal: number;
+            batch: number;
+        }>;
+    };
+    /** Drain all requests (for shutdown) */
+    drain(): PriorityRequest[];
+    /** Determine effective priority for a request (auto-upgrade/downgrade) */
+    static resolvePriority(requested: PriorityLevel, provider: string, supportedProviders: string[]): PriorityLevel;
+    private canRun;
+    private incrementActive;
+}
+/**
+ * Tracks per-session fast mode toggle (like /fast command).
+ */
+export declare class FastModeManager {
+    private sessions;
+    /** Toggle fast mode for a session, returns new state */
+    toggle(sessionId: string): boolean;
+    /** Set fast mode explicitly */
+    set(sessionId: string, enabled: boolean): void;
+    /** Check if session has fast mode enabled */
+    isEnabled(sessionId: string): boolean;
+    /** Get priority level for a session */
+    getPriority(sessionId: string): PriorityLevel;
+    /** Clear all state */
+    reset(): void;
+}
+//# sourceMappingURL=priority-queue.d.ts.map

package/dist/core/priority-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"priority-queue.d.ts","sourceRoot":"","sources":["../../src/core/priority-queue.ts"],"names":[],"mappings":"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"}