zoe-agent 0.3.1

package/dist/gateway/gateway.js

@@ -0,0 +1,537 @@
+/**
+ * Zoe Gateway — MCPGateway engine
+ *
+ * Core engine that manages MCP and REST targets, routes requests,
+ * and exposes injectable tools for the agent loop.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { GatewayError } from '../core/errors.js';
+import { scoreRelevance } from './semantic-scorer.js';
+export class MCPGateway {
+    targets = new Map();
+    mcpClients = new Map();
+    auditLogs = [];
+    routes = [];
+    adminTargets = new Set();
+    injectableToolsCache = null;
+    invalidateToolsCache() {
+        this.injectableToolsCache = null;
+    }
+    settings;
+    config;
+    hooks;
+    constructor(settings, config, hooks = {}) {
+        this.settings = settings;
+        this.config = config;
+        this.hooks = hooks;
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────
+    async initialize() {
+        const stored = this.settings.getTargets();
+        for (const [name, target] of Object.entries(stored)) {
+            this.targets.set(name, target);
+        }
+        // Restore admin target status from persistence
+        const adminNames = this.settings.getAdminTargets();
+        let pruned = false;
+        for (const name of adminNames) {
+            if (this.targets.has(name)) {
+                this.adminTargets.add(name);
+            }
+            else {
+                await this.settings.removeAdminTarget(name);
+                pruned = true;
+            }
+        }
+        this.routes = this.settings.getRoutes();
+        for (const [name, target] of this.targets) {
+            if (!target.enabled || target.kind !== 'mcp')
+                continue;
+            try {
+                await this.connectMcpClient(name, target);
+            }
+            catch {
+                // Non-fatal: target fails to connect at startup
+            }
+        }
+    }
+    async shutdown() {
+        for (const [, client] of this.mcpClients) {
+            try {
+                await client.close();
+            }
+            catch {
+                // Best-effort close
+            }
+        }
+        this.mcpClients.clear();
+    }
+    // ── Audit ────────────────────────────────────────────────────────────
+    audit(agent, target, operation, status, durationMs, success) {
+        const record = {
+            timestamp: Date.now(),
+            agent,
+            target,
+            operation,
+            status,
+            durationMs,
+            success,
+        };
+        this.auditLogs.push(record);
+        if (this.auditLogs.length > this.config.maxAuditLogsInMemory) {
+            this.auditLogs.shift();
+        }
+        if (this.hooks.onAudit) {
+            try {
+                const result = this.hooks.onAudit(record);
+                if (result instanceof Promise) {
+                    result.catch(() => { });
+                }
+            }
+            catch {
+                // Non-fatal hook error
+            }
+        }
+    }
+    getAuditLogs(targetFilter, limit) {
+        let logs = this.auditLogs;
+        if (targetFilter) {
+            logs = logs.filter((r) => r.target === targetFilter);
+        }
+        if (limit !== undefined && limit < logs.length) {
+            logs = logs.slice(-limit);
+        }
+        return logs;
+    }
+    getUsageSummary() {
+        const summary = {};
+        for (const [name] of this.targets) {
+            summary[name] = { calls: 0, errors: 0 };
+        }
+        for (const log of this.auditLogs) {
+            if (!summary[log.target]) {
+                summary[log.target] = { calls: 0, errors: 0 };
+            }
+            summary[log.target].calls++;
+            if (!log.success) {
+                summary[log.target].errors++;
+            }
+        }
+        return summary;
+    }
+    // ── Target management ────────────────────────────────────────────────
+    async registerTarget(name, target, isAdmin = false) {
+        if (!target || !['mcp', 'rest'].includes(target.kind)) {
+            throw new GatewayError(`Invalid target: kind must be 'mcp' or 'rest'`, name, false);
+        }
+        if (isAdmin) {
+            this.adminTargets.add(name);
+            await this.settings.addAdminTarget(name);
+        }
+        this.targets.set(name, target);
+        await this.settings.saveTarget(name, target);
+        this.invalidateToolsCache();
+    }
+    async unregisterTarget(name) {
+        const client = this.mcpClients.get(name);
+        if (client) {
+            try {
+                await client.close();
+            }
+            catch {
+                // Best-effort
+            }
+            this.mcpClients.delete(name);
+        }
+        this.routes = this.routes.filter((r) => r.target !== name);
+        await this.settings.saveRoutes(this.routes);
+        const deleted = this.targets.delete(name);
+        if (deleted) {
+            await this.settings.deleteTarget(name);
+            this.invalidateToolsCache();
+        }
+        this.adminTargets.delete(name);
+        await this.settings.removeAdminTarget(name);
+        return deleted;
+    }
+    async toggleTarget(name, enabled) {
+        const target = this.targets.get(name);
+        if (!target)
+            return false;
+        target.enabled = enabled;
+        await this.settings.saveTarget(name, target);
+        this.invalidateToolsCache();
+        return true;
+    }
+    getTargets() {
+        return Object.fromEntries(this.targets);
+    }
+    // ── Routes ───────────────────────────────────────────────────────────
+    async addRoute(pattern, target, priority) {
+        const dupe = this.routes.find((r) => r.pattern === pattern && r.target === target);
+        if (dupe)
+            return;
+        this.routes.push({ pattern, target, priority });
+        this.routes.sort((a, b) => b.priority - a.priority);
+        await this.settings.saveRoutes(this.routes);
+    }
+    async removeRoute(pattern, target) {
+        this.routes = this.routes.filter((r) => !(r.pattern === pattern && r.target === target));
+        await this.settings.saveRoutes(this.routes);
+    }
+    routeRequest(request) {
+        const lower = request.toLowerCase();
+        for (const route of this.routes) {
+            if (lower.includes(route.pattern.toLowerCase())) {
+                return `-> ${route.target} (route: '${route.pattern}')`;
+            }
+        }
+        let bestTarget = null;
+        let bestScore = 0;
+        for (const [name, target] of this.targets) {
+            if (!target.enabled)
+                continue;
+            const text = [target.description, ...target.tags].join(' ');
+            const score = scoreRelevance(request, text);
+            if (score > bestScore) {
+                bestScore = score;
+                bestTarget = name;
+            }
+        }
+        if (bestTarget && bestScore > 0) {
+            return `-> ${bestTarget} (tag match)`;
+        }
+        const available = Array.from(this.targets.keys());
+        return available.length > 0
+            ? `No route matched. Available: ${available.join(', ')}`
+            : 'No targets registered.';
+    }
+    // ── MCP client connection ────────────────────────────────────────────
+    async connectMcpClient(targetName, target) {
+        const cached = this.mcpClients.get(targetName);
+        if (cached)
+            return cached;
+        const client = new Client({ name: 'zoe-gateway', version: '0.1.0' }, { capabilities: { sampling: {} } });
+        if (this.hooks.onSamplingRequest) {
+            client.setRequestHandler(CreateMessageRequestSchema, (request) => this.hooks.onSamplingRequest(request));
+        }
+        // Resolve env with B3 credential trust guard
+        const env = { ...process.env };
+        if (target.env) {
+            for (const [k, v] of Object.entries(target.env)) {
+                if (v.startsWith('credential:') && v.length > 11) {
+                    // B3: only resolve credential refs for admin targets
+                    if (this.adminTargets.has(targetName)) {
+                        const key = v.substring(11);
+                        const cred = this.settings.getCredential(key);
+                        if (cred) {
+                            env[k] = cred;
+                        }
+                    }
+                }
+                else {
+                    env[k] = v;
+                }
+            }
+        }
+        if (target.transport === 'stdio') {
+            if (!target.command) {
+                throw new GatewayError(`MCP target "${targetName}" missing command for stdio transport`, targetName, false);
+            }
+            const transport = new StdioClientTransport({ command: target.command, args: target.args, env });
+            await client.connect(transport);
+        }
+        else if (target.transport === 'sse' || target.transport === 'http') {
+            if (!target.url) {
+                throw new GatewayError(`MCP target "${targetName}" missing url for ${target.transport} transport`, targetName, false);
+            }
+            // Resolve auth headers for SSE/HTTP transport
+            // B3 trust guard: only resolve credentialRef for admin-registered targets
+            const headers = {};
+            if (target.auth?.credentialRef) {
+                const cred = this.adminTargets.has(targetName) ? this.settings.getCredential(target.auth.credentialRef) : undefined;
+                if (cred) {
+                    if (target.auth.type === 'bearer')
+                        headers['Authorization'] = `Bearer ${cred}`;
+                    else if (target.auth.type === 'header' && target.auth.name)
+                        headers[target.auth.name] = cred;
+                    else if (target.auth.type === 'basic')
+                        headers['Authorization'] = `Basic ${Buffer.from(cred).toString('base64')}`;
+                }
+            }
+            const transport = new SSEClientTransport(new URL(target.url), { requestInit: { headers } });
+            await client.connect(transport);
+        }
+        else {
+            throw new GatewayError(`MCP target "${targetName}" has unsupported transport: ${target.transport}`, targetName, false);
+        }
+        // Auto-discover capabilities
+        const capabilities = target.capabilities ?? {};
+        try {
+            const toolsResult = await client.listTools();
+            capabilities.tools = toolsResult.tools;
+        }
+        catch {
+            capabilities.tools = [];
+        }
+        try {
+            const resourcesResult = await client.listResources();
+            capabilities.resources = resourcesResult.resources;
+        }
+        catch {
+            capabilities.resources = [];
+        }
+        try {
+            const promptsResult = await client.listPrompts();
+            capabilities.prompts = promptsResult.prompts;
+        }
+        catch {
+            capabilities.prompts = [];
+        }
+        target.capabilities = capabilities;
+        this.mcpClients.set(targetName, client);
+        return client;
+    }
+    // ── MCP tool call ────────────────────────────────────────────────────
+    async callMcpTool(agent, targetName, toolName, args) {
+        const target = this.targets.get(targetName);
+        if (!target) {
+            throw new GatewayError(`Target not found: ${targetName}`, targetName, false);
+        }
+        if (!target.enabled) {
+            throw new GatewayError(`Target is disabled: ${targetName}`, targetName, false);
+        }
+        if (target.kind !== 'mcp') {
+            throw new GatewayError(`Target "${targetName}" is not an MCP target`, targetName, false);
+        }
+        const start = Date.now();
+        try {
+            const client = await this.connectMcpClient(targetName, target);
+            const result = await client.callTool({ name: toolName, arguments: args });
+            this.audit(agent, targetName, `tool:${toolName}`, 'success', Date.now() - start, true);
+            return result;
+        }
+        catch (err) {
+            // Evict cached client for lazy reconnect
+            this.mcpClients.delete(targetName);
+            this.audit(agent, targetName, `tool:${toolName}`, 'error', Date.now() - start, false);
+            if (err instanceof GatewayError)
+                throw err;
+            throw new GatewayError(err instanceof Error ? err.message : String(err), targetName, true);
+        }
+    }
+    // ── REST proxy ───────────────────────────────────────────────────────
+    async callRest(agent, targetName, reqPath, method, query, body) {
+        const target = this.targets.get(targetName);
+        if (!target) {
+            throw new GatewayError(`Target not found: ${targetName}`, targetName, false);
+        }
+        if (!target.enabled) {
+            throw new GatewayError(`Target is disabled: ${targetName}`, targetName, false);
+        }
+        if (target.kind !== 'rest') {
+            throw new GatewayError(`Target "${targetName}" is not a REST target`, targetName, false);
+        }
+        const url = new URL(reqPath, target.baseUrl);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                url.searchParams.set(k, v);
+            }
+        }
+        const headers = { ...target.defaultHeaders };
+        // B3 trust guard: only resolve credentialRef for admin-registered targets
+        if (target.auth.type !== 'none' && target.auth.credentialRef) {
+            const cred = this.adminTargets.has(targetName) ? this.settings.getCredential(target.auth.credentialRef) : undefined;
+            if (cred) {
+                switch (target.auth.type) {
+                    case 'bearer':
+                        headers['Authorization'] = `Bearer ${cred}`;
+                        break;
+                    case 'header':
+                        headers[target.auth.name ?? 'X-API-Key'] = cred;
+                        break;
+                    case 'query':
+                        url.searchParams.set(target.auth.name ?? 'api_key', cred);
+                        break;
+                    case 'basic':
+                        headers['Authorization'] = `Basic ${Buffer.from(cred).toString('base64')}`;
+                        break;
+                }
+            }
+        }
+        const start = Date.now();
+        try {
+            const response = await fetch(url.toString(), {
+                method,
+                headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            const text = await response.text();
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+            this.audit(agent, targetName, `${method} ${reqPath}`, response.ok ? 'success' : `http:${response.status}`, Date.now() - start, response.ok);
+            if (!response.ok) {
+                throw new GatewayError(`REST call to ${targetName} failed: ${response.status} ${text}`, targetName, response.status >= 500);
+            }
+            return data;
+        }
+        catch (err) {
+            if (err instanceof GatewayError)
+                throw err;
+            this.audit(agent, targetName, `${method} ${reqPath}`, 'error', Date.now() - start, false);
+            throw new GatewayError(err instanceof Error ? err.message : String(err), targetName, true);
+        }
+    }
+    // ── MCP resource read ────────────────────────────────────────────────
+    async readResource(agent, targetName, uri) {
+        const target = this.targets.get(targetName);
+        if (!target) {
+            throw new GatewayError(`Target not found: ${targetName}`, targetName, false);
+        }
+        if (!target.enabled) {
+            throw new GatewayError(`Target is disabled: ${targetName}`, targetName, false);
+        }
+        if (target.kind !== 'mcp') {
+            throw new GatewayError(`Target "${targetName}" is not an MCP target`, targetName, false);
+        }
+        const start = Date.now();
+        try {
+            const client = await this.connectMcpClient(targetName, target);
+            const result = await client.readResource({ uri });
+            this.audit(agent, targetName, `resource:${uri}`, 'success', Date.now() - start, true);
+            return result;
+        }
+        catch (err) {
+            this.mcpClients.delete(targetName);
+            this.audit(agent, targetName, `resource:${uri}`, 'error', Date.now() - start, false);
+            if (err instanceof GatewayError)
+                throw err;
+            throw new GatewayError(err instanceof Error ? err.message : String(err), targetName, true);
+        }
+    }
+    // ── MCP prompt get ───────────────────────────────────────────────────
+    async getPrompt(agent, targetName, name, args) {
+        const target = this.targets.get(targetName);
+        if (!target) {
+            throw new GatewayError(`Target not found: ${targetName}`, targetName, false);
+        }
+        if (!target.enabled) {
+            throw new GatewayError(`Target is disabled: ${targetName}`, targetName, false);
+        }
+        if (target.kind !== 'mcp') {
+            throw new GatewayError(`Target "${targetName}" is not an MCP target`, targetName, false);
+        }
+        const start = Date.now();
+        try {
+            const client = await this.connectMcpClient(targetName, target);
+            const result = await client.getPrompt({ name, arguments: args });
+            this.audit(agent, targetName, `prompt:${name}`, 'success', Date.now() - start, true);
+            return result;
+        }
+        catch (err) {
+            this.mcpClients.delete(targetName);
+            this.audit(agent, targetName, `prompt:${name}`, 'error', Date.now() - start, false);
+            if (err instanceof GatewayError)
+                throw err;
+            throw new GatewayError(err instanceof Error ? err.message : String(err), targetName, true);
+        }
+    }
+    // ── Injectable tools ─────────────────────────────────────────────────
+    getRoutes() {
+        return [...this.routes];
+    }
+    listCredentialKeys() {
+        return this.settings.listCredentialKeys();
+    }
+    async setCredential(key, value) {
+        return this.settings.setCredential(key, value);
+    }
+    async deleteCredential(key) {
+        return this.settings.deleteCredential(key);
+    }
+    getInjectableTools() {
+        if (this.injectableToolsCache)
+            return this.injectableToolsCache;
+        const tools = this.buildInjectableTools();
+        this.injectableToolsCache = tools;
+        return tools;
+    }
+    buildInjectableTools() {
+        const tools = [];
+        for (const [targetName, target] of this.targets) {
+            if (!target.enabled)
+                continue;
+            if (target.kind === 'mcp') {
+                const mcpTools = target.capabilities?.tools ?? [];
+                for (const tool of mcpTools) {
+                    const toolDef = tool;
+                    const prefixedName = `${targetName}__${toolDef.name}`;
+                    tools.push({
+                        name: prefixedName,
+                        risk: 'communications',
+                        definition: {
+                            type: 'function',
+                            function: {
+                                name: prefixedName,
+                                description: toolDef.description ?? `MCP tool ${toolDef.name} on ${targetName}`,
+                                parameters: toolDef.inputSchema ?? {
+                                    type: 'object',
+                                    properties: {},
+                                    required: [],
+                                },
+                            },
+                        },
+                        handler: async (args, config) => {
+                            const agent = config?.agentName ?? 'zoe';
+                            const result = await this.callMcpTool(agent, targetName, toolDef.name, args);
+                            return typeof result === 'string' ? result : JSON.stringify(result);
+                        },
+                    });
+                }
+            }
+            if (target.kind === 'rest') {
+                for (const op of target.operations) {
+                    const prefixedName = `${targetName}__${op.opId}`;
+                    tools.push({
+                        name: prefixedName,
+                        risk: 'communications',
+                        definition: {
+                            type: 'function',
+                            function: {
+                                name: prefixedName,
+                                description: op.summary ?? `${op.method} ${op.path} on ${targetName}`,
+                                parameters: {
+                                    type: 'object',
+                                    properties: {
+                                        path: { type: 'string', description: 'Request path' },
+                                        query: {
+                                            type: 'object',
+                                            description: 'Query parameters',
+                                            additionalProperties: { type: 'string' },
+                                        },
+                                        body: { type: 'object', description: 'Request body' },
+                                    },
+                                    required: ['path'],
+                                },
+                            },
+                        },
+                        handler: async (args, config) => {
+                            const agent = config?.agentName ?? 'zoe';
+                            const result = await this.callRest(agent, targetName, args.path ?? op.path, op.method, args.query, args.body);
+                            return typeof result === 'string' ? result : JSON.stringify(result);
+                        },
+                    });
+                }
+            }
+        }
+        return tools;
+    }
+}

package/dist/gateway/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Zoe Gateway — Public API
+ *
+ * Barrel export for the gateway subsystem.
+ */
+export { MCPGateway } from './gateway.js';
+export { createGatewayTools } from './tool-factory.js';
+export { importOpenApiSpec } from './openapi-importer.js';
+export { GatewaySettingsAdapter } from './settings-adapter.js';
+export { scoreRelevance } from './semantic-scorer.js';
+export type { AuthType, McpTransportType, RestTarget, McpTarget, Target, AuditRecord, GatewayHooks, GatewayConfig, } from './types.js';
+import { MCPGateway } from './gateway.js';
+import { GatewaySettingsAdapter } from './settings-adapter.js';
+import type { GatewayConfig, GatewayHooks } from './types.js';
+/**
+ * Create and initialize a gateway instance.
+ * Returns null if gateway is disabled in settings.
+ *
+ * The caller creates and owns the GatewaySettingsAdapter.
+ */
+export declare function createGateway(config: GatewayConfig, settingsAdapter: GatewaySettingsAdapter, hooks?: GatewayHooks): Promise<MCPGateway | null>;

package/dist/gateway/index.js

@@ -0,0 +1,31 @@
+/**
+ * Zoe Gateway — Public API
+ *
+ * Barrel export for the gateway subsystem.
+ */
+export { MCPGateway } from './gateway.js';
+export { createGatewayTools } from './tool-factory.js';
+export { importOpenApiSpec } from './openapi-importer.js';
+export { GatewaySettingsAdapter } from './settings-adapter.js';
+export { scoreRelevance } from './semantic-scorer.js';
+import { MCPGateway } from './gateway.js';
+import { createGatewayTools } from './tool-factory.js';
+import { registerTool } from '../core/tool-executor.js';
+/**
+ * Create and initialize a gateway instance.
+ * Returns null if gateway is disabled in settings.
+ *
+ * The caller creates and owns the GatewaySettingsAdapter.
+ */
+export async function createGateway(config, settingsAdapter, hooks) {
+    if (!config.enabled)
+        return null;
+    const gateway = new MCPGateway(settingsAdapter, config, hooks);
+    await gateway.initialize();
+    // Register proxy tools in static registry
+    const tools = createGatewayTools(gateway);
+    for (const tool of tools) {
+        registerTool(tool);
+    }
+    return gateway;
+}

package/dist/gateway/openapi-importer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Zoe Gateway — OpenAPI/Swagger spec importer
+ *
+ * Fetches an OpenAPI spec (JSON or YAML), extracts operations,
+ * and registers the result as a REST target on the gateway.
+ */
+import type { MCPGateway } from './gateway.js';
+export declare function importOpenApiSpec(gateway: MCPGateway, name: string, specUrl: string, options?: {
+    baseUrl?: string;
+    tagFilter?: string[];
+    isAdmin?: boolean;
+}): Promise<{
+    imported: number;
+    operations: string[];
+}>;

package/dist/gateway/openapi-importer.js

@@ -0,0 +1,66 @@
+/**
+ * Zoe Gateway — OpenAPI/Swagger spec importer
+ *
+ * Fetches an OpenAPI spec (JSON or YAML), extracts operations,
+ * and registers the result as a REST target on the gateway.
+ */
+import * as yaml from 'js-yaml';
+export async function importOpenApiSpec(gateway, name, specUrl, options) {
+    const response = await fetch(specUrl);
+    if (!response.ok)
+        throw new Error(`Failed to fetch spec: HTTP ${response.status}`);
+    const raw = await response.text();
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch {
+        spec = yaml.load(raw);
+    }
+    const baseUrl = options?.baseUrl ?? spec.servers?.[0]?.url ?? '';
+    if (!baseUrl)
+        throw new Error('No base URL found in spec and none provided');
+    const operations = [];
+    const paths = spec.paths ?? {};
+    for (const [routePath, methods] of Object.entries(paths)) {
+        for (const [method, op] of Object.entries(methods)) {
+            if (['get', 'post', 'put', 'patch', 'delete'].includes(method.toLowerCase())) {
+                operations.push({
+                    opId: op.operationId ?? `${method}_${routePath.replace(/[/{}/]/g, '_')}`,
+                    method: method.toUpperCase(),
+                    path: routePath,
+                    summary: op.summary ?? `${method.toUpperCase()} ${routePath}`,
+                });
+            }
+        }
+    }
+    const filtered = options?.tagFilter
+        ? operations.filter(op => {
+            const opData = (spec.paths?.[op.path]?.[op.method.toLowerCase()]);
+            const opTags = opData?.tags ?? [];
+            return options.tagFilter.some(t => opTags.includes(t));
+        })
+        : operations;
+    const allTags = [];
+    for (const [, methods] of Object.entries(paths)) {
+        for (const [, op] of Object.entries(methods)) {
+            if (op.tags)
+                allTags.push(...op.tags);
+        }
+    }
+    const tags = [...new Set(allTags)];
+    const target = {
+        kind: 'rest',
+        baseUrl,
+        description: spec.info?.title ?? name,
+        auth: { type: 'none' },
+        defaultHeaders: {},
+        operations: filtered,
+        tags,
+        enabled: true,
+    };
+    // Register as admin only when called from REST/CLI (isAdmin param).
+    // Agent tool calls pass isAdmin=false to prevent trust guard bypass.
+    await gateway.registerTarget(name, target, options?.isAdmin ?? true);
+    return { imported: filtered.length, operations: filtered.map(o => o.opId) };
+}

package/dist/gateway/semantic-scorer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Zoe Gateway — Semantic Scorer
+ *
+ * Keyword-based relevance scoring for tool injection.
+ * Zero dependencies, deterministic, fast.
+ */
+export declare function scoreRelevance(query: string, text: string): number;