zoe-agent 0.3.1

package/dist/adapters/server/index.js

@@ -0,0 +1,255 @@
+/**
+ * Zoe Remote Server — Entry Point
+ *
+ * Creates an HTTP server with REST endpoints and WebSocket support
+ * for real-time streaming conversations with LLM providers.
+ *
+ * Default port: 7337
+ */
+import * as http from "http";
+import * as fs from "fs";
+import * as path from "path";
+import { homedir } from "os";
+import { configureProviders, resolveFromEnv } from "../../core/provider-resolver.js";
+import { serverGenerateText, serverStreamText } from "./server-core.js";
+import { createRestHandler } from "./rest.js";
+import { setupWebSocket, closeWebSocket } from "./websocket.js";
+import { getOtherClients } from "./ws-handlers.js";
+import { ServerSessionManager } from "./session-store.js";
+import { SettingsManager } from "../../core/settings-manager.js";
+import { loadMergedConfig, getConfigPaths, loadJsonConfig } from "../../core/config.js";
+import { MODEL_CATALOG } from "../../models-catalog.js";
+// ── Helpers ────────────────────────────────────────────────────────────
+function resolveVersion() {
+    try {
+        // Try relative to dist/ first (production), then src/ (development)
+        const pkgPath = path.join(import.meta.dirname ?? ".", "..", "..", "package.json");
+        const raw = fs.readFileSync(pkgPath, "utf-8");
+        return JSON.parse(raw).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function resolvePort(options) {
+    if (options?.port)
+        return options.port;
+    const fromEnv = parseInt(process.env.ZOE_PORT ?? process.env.PORT ?? "", 10);
+    if (!isNaN(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    return 7337;
+}
+// ── Provider initialization ────────────────────────────────────────────
+function initializeProvidersFromEnv() {
+    const config = resolveFromEnv();
+    if (config) {
+        configureProviders(config);
+    }
+}
+function listModels() {
+    const result = {
+        openai: [],
+        anthropic: [],
+        glm: [],
+        "openai-compatible": [],
+    };
+    for (const [provider, entries] of Object.entries(MODEL_CATALOG)) {
+        if (provider in result) {
+            result[provider] = entries.map((e) => e.id);
+        }
+    }
+    return result;
+}
+/**
+ * Cached skill list — populated asynchronously at startup.
+ */
+let cachedSkillList = [];
+/**
+ * Initialize the skill registry and cache the skill metadata list.
+ * Called once during server startup.
+ */
+export async function initializeSkills() {
+    try {
+        const { getSkillRegistry } = await import("../../skills/index.js");
+        const registry = getSkillRegistry();
+        if (registry) {
+            cachedSkillList = registry.getMetadata().map((s) => ({
+                name: s.name,
+                description: s.description,
+                tags: s.tags,
+            }));
+        }
+    }
+    catch {
+        // Skills system not available — keep empty list
+    }
+}
+function listSkills() {
+    return cachedSkillList;
+}
+// ── CORS helper ────────────────────────────────────────────────────────
+function addCORSHeaders(req, res) {
+    const origin = req.headers.origin ?? "*";
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Zoe-API-Key");
+    res.setHeader("Access-Control-Max-Age", "86400");
+}
+function isPreflight(req) {
+    return req.method === "OPTIONS";
+}
+function handlePreflight(_req, res) {
+    res.writeHead(204);
+    res.end();
+}
+// ── Server creation ────────────────────────────────────────────────────
+/**
+ * Create and return the Zoe HTTP server (not yet listening).
+ *
+ * This sets up REST endpoints, WebSocket upgrade handling,
+ * session management, and CORS support.
+ */
+export async function createServer(options) {
+    const version = resolveVersion();
+    const startTime = Date.now();
+    // Initialize providers from environment
+    initializeProvidersFromEnv();
+    const serverPermissionLevel = options?.permissionLevel ?? "moderate";
+    // Resolve session directory
+    const sessionDir = process.env.ZOE_SESSION_DIR ??
+        path.join(process.cwd(), ".zoe", "sessions");
+    const sessionTTL = (options?.sessionTTL ?? parseInt(process.env.ZOE_SESSION_TTL ?? "86400", 10)) * 1000;
+    // Create session manager
+    const sessionManager = new ServerSessionManager({
+        sessionDir,
+        sessionTTL,
+    });
+    sessionManager.startCleanup();
+    // Create settings handler context (shared by REST and WS)
+    const configPaths = getConfigPaths();
+    const mergedConfig = loadMergedConfig();
+    const projectConfig = loadJsonConfig(configPaths.local);
+    const globalConfig = loadJsonConfig(configPaths.global);
+    const settingsManager = new SettingsManager({
+        config: mergedConfig,
+        projectConfigPath: configPaths.local,
+        globalConfigPath: configPaths.global,
+        projectConfig: projectConfig.config,
+        globalConfig: globalConfig.config,
+    });
+    const settingsHandlerContext = {
+        settingsManager,
+        getOtherClients,
+    };
+    // Initialize gateway (if enabled)
+    let gatewayHandler;
+    let gatewayMiddleware;
+    try {
+        const gwEnabled = settingsManager.get("gateway.enabled").value;
+        if (gwEnabled) {
+            const gatewayConfig = {
+                enabled: true,
+                semanticTopK: settingsManager.get("gateway.semanticTopK").value,
+                defaultRateLimitPerMin: settingsManager.get("gateway.defaultRateLimitPerMin").value,
+                maxAuditLogsInMemory: settingsManager.get("gateway.maxAuditLogs").value,
+            };
+            const { GatewaySettingsAdapter } = await import("../../gateway/settings-adapter.js");
+            const gatewayStorageDir = process.env.ZOE_GATEWAY_DIR ?? path.join(homedir(), ".zoe");
+            const gwSettingsAdapter = new GatewaySettingsAdapter(gatewayStorageDir);
+            await gwSettingsAdapter.initialize();
+            // Use createGateway factory — registers 10 proxy tools in static registry
+            const { createGateway } = await import("../../gateway/index.js");
+            const gatewayInstance = await createGateway(gatewayConfig, gwSettingsAdapter);
+            if (gatewayInstance) {
+                const { createGatewayRestHandler } = await import("./rest-gateway.js");
+                gatewayHandler = createGatewayRestHandler({ gateway: gatewayInstance, settingsAdapter: gwSettingsAdapter });
+                // Wire semantic injection middleware
+                const { semanticToolInjectionMiddleware } = await import("../../core/middleware/semantic-tools.js");
+                gatewayMiddleware = [semanticToolInjectionMiddleware(gatewayInstance, gatewayConfig.semanticTopK)];
+            }
+        }
+    }
+    catch (e) {
+        console.error("[server] Gateway initialization failed:", e instanceof Error ? e.message : String(e));
+    }
+    // Create REST handler context
+    const restCtx = {
+        version,
+        startTime,
+        sessionManager,
+        generateText: (opts) => serverGenerateText(opts, serverPermissionLevel, gatewayMiddleware),
+        listModels,
+        listSkills,
+        settingsHandlerContext,
+        gatewayHandler,
+    };
+    const restHandler = createRestHandler(restCtx);
+    // Create HTTP server
+    const enableCors = options?.cors ?? true;
+    const server = http.createServer((req, res) => {
+        // CORS
+        if (enableCors) {
+            addCORSHeaders(req, res);
+        }
+        // Preflight
+        if (isPreflight(req)) {
+            handlePreflight(req, res);
+            return;
+        }
+        // Delegate to REST handler
+        restHandler(req, res);
+    });
+    // Create WebSocket handler context
+    const wsCtx = {
+        sessionManager,
+        streamText: (opts) => {
+            serverStreamText(opts, serverPermissionLevel, gatewayMiddleware).catch((err) => {
+                opts.onError({
+                    code: "STREAM_ERROR",
+                    message: err instanceof Error ? err.message : "Stream failed",
+                });
+                opts.onDone({
+                    text: "",
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0, cost: 0 },
+                    finishReason: "error",
+                });
+            });
+        },
+        listModels,
+        listSkills,
+        maxPermissionLevel: options?.maxPermissionLevel,
+        settingsHandlerContext,
+    };
+    // Set up WebSocket (async, but we wait for it)
+    await setupWebSocket(server, wsCtx);
+    // Graceful shutdown handler
+    const shutdown = () => {
+        console.log("[server] Shutting down...");
+        sessionManager.stopCleanup();
+        closeWebSocket();
+        server.close(() => {
+            console.log("[server] Server closed.");
+            process.exit(0);
+        });
+        // Force exit after 5 seconds if connections don't close
+        setTimeout(() => process.exit(0), 5000);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    return server;
+}
+// ── Convenience starter ────────────────────────────────────────────────
+/**
+ * Create and start listening. Returns the running server.
+ */
+export async function startServer(options) {
+    const server = await createServer(options);
+    const port = resolvePort(options);
+    const host = options?.host ?? "0.0.0.0";
+    return new Promise((resolve) => {
+        server.listen(port, host, () => {
+            console.log(`[zoe] Server listening on ${host}:${port}`);
+            resolve(server);
+        });
+    });
+}

package/dist/adapters/server/rest-gateway.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Zoe Server — Gateway REST Route Handlers
+ *
+ * Handles all /v1/gateway/* REST endpoints for target management,
+ * audit logs, usage summaries, credentials, routes, and OpenAPI imports.
+ */
+import type { IncomingMessage, ServerResponse } from "http";
+import type { MCPGateway } from "../../gateway/gateway.js";
+import type { GatewaySettingsAdapter } from "../../gateway/settings-adapter.js";
+export declare function createGatewayRestHandler(ctx: {
+    gateway: MCPGateway;
+    settingsAdapter: GatewaySettingsAdapter;
+}): (req: IncomingMessage, res: ServerResponse, path: string, method: string) => Promise<void>;

package/dist/adapters/server/rest-gateway.js

@@ -0,0 +1,218 @@
+/**
+ * Zoe Server — Gateway REST Route Handlers
+ *
+ * Handles all /v1/gateway/* REST endpoints for target management,
+ * audit logs, usage summaries, credentials, routes, and OpenAPI imports.
+ */
+import { authMiddleware, hasScope } from "./auth.js";
+// ── Helpers ────────────────────────────────────────────────────────────
+function sendJSON(res, statusCode, data) {
+    const body = JSON.stringify(data);
+    res.writeHead(statusCode, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+function sendError(res, statusCode, code, message) {
+    sendJSON(res, statusCode, { error: { code, message } });
+}
+function parseBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+async function parseJsonBody(req, res) {
+    let body;
+    try {
+        body = JSON.parse(await parseBody(req));
+    }
+    catch {
+        sendError(res, 400, "BAD_REQUEST", "Invalid JSON in request body");
+        return null;
+    }
+    return body;
+}
+function requireAuth(req, res, scope) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return false;
+    }
+    if (!hasScope(key, scope)) {
+        sendError(res, 403, "FORBIDDEN", `API key lacks '${scope}' scope`);
+        return false;
+    }
+    return true;
+}
+function matchGatewayRoute(path, method) {
+    if (method === "GET" && path === "/v1/gateway/targets") {
+        return { handler: "list_targets" };
+    }
+    if (method === "GET" && path === "/v1/gateway/audit") {
+        return { handler: "audit" };
+    }
+    if (method === "GET" && path === "/v1/gateway/usage") {
+        return { handler: "usage" };
+    }
+    if (method === "POST" && path === "/v1/gateway/targets") {
+        return { handler: "register_target" };
+    }
+    const toggleMatch = path.match(/^\/v1\/gateway\/targets\/([^/]+)\/toggle$/);
+    if (method === "PATCH" && toggleMatch) {
+        return { handler: "toggle_target", name: decodeURIComponent(toggleMatch[1]) };
+    }
+    const targetDeleteMatch = path.match(/^\/v1\/gateway\/targets\/([^/]+)$/);
+    if (method === "DELETE" && targetDeleteMatch) {
+        return { handler: "unregister_target", name: decodeURIComponent(targetDeleteMatch[1]) };
+    }
+    if (method === "GET" && path === "/v1/gateway/credentials") {
+        return { handler: "get_credentials" };
+    }
+    const credMatch = path.match(/^\/v1\/gateway\/credentials\/(.+)$/);
+    if (method === "PUT" && credMatch) {
+        return { handler: "put_credential", key: decodeURIComponent(credMatch[1]) };
+    }
+    if (method === "POST" && path === "/v1/gateway/routes") {
+        return { handler: "add_route" };
+    }
+    if (method === "POST" && path === "/v1/gateway/import-openapi") {
+        return { handler: "import_openapi" };
+    }
+    return null;
+}
+// ── Main handler factory ───────────────────────────────────────────────
+export function createGatewayRestHandler(ctx) {
+    const { gateway, settingsAdapter } = ctx;
+    return async function handleGatewayRoute(req, res, urlPath, method) {
+        const route = matchGatewayRoute(urlPath, method);
+        if (!route) {
+            sendError(res, 404, "NOT_FOUND", `No gateway route for ${method} ${urlPath}`);
+            return;
+        }
+        try {
+            switch (route.handler) {
+                case "list_targets": {
+                    if (!requireAuth(req, res, "agent:read"))
+                        return;
+                    sendJSON(res, 200, { targets: gateway.getTargets() });
+                    break;
+                }
+                case "audit": {
+                    if (!requireAuth(req, res, "agent:read"))
+                        return;
+                    sendJSON(res, 200, { logs: gateway.getAuditLogs() });
+                    break;
+                }
+                case "usage": {
+                    if (!requireAuth(req, res, "agent:read"))
+                        return;
+                    sendJSON(res, 200, { usage: gateway.getUsageSummary() });
+                    break;
+                }
+                case "register_target": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    const body = await parseJsonBody(req, res);
+                    if (!body)
+                        return;
+                    if (!body.name || !body.target) {
+                        sendError(res, 400, "BAD_REQUEST", "Fields 'name' and 'target' are required");
+                        return;
+                    }
+                    await gateway.registerTarget(body.name, body.target, true);
+                    sendJSON(res, 201, { ok: true });
+                    break;
+                }
+                case "toggle_target": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    const body = await parseJsonBody(req, res);
+                    if (!body)
+                        return;
+                    if (typeof body.enabled !== "boolean") {
+                        sendError(res, 400, "BAD_REQUEST", "Field 'enabled' must be a boolean");
+                        return;
+                    }
+                    const ok = await gateway.toggleTarget(route.name, body.enabled);
+                    if (!ok) {
+                        sendError(res, 404, "NOT_FOUND", `Target '${route.name}' not found`);
+                        return;
+                    }
+                    sendJSON(res, 200, { ok: true });
+                    break;
+                }
+                case "unregister_target": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    const deleted = await gateway.unregisterTarget(route.name);
+                    if (!deleted) {
+                        sendError(res, 404, "NOT_FOUND", `Target '${route.name}' not found`);
+                        return;
+                    }
+                    sendJSON(res, 200, { ok: true });
+                    break;
+                }
+                case "get_credentials": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    sendJSON(res, 200, { keys: settingsAdapter.listCredentialKeys() });
+                    break;
+                }
+                case "put_credential": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    const body = await parseJsonBody(req, res);
+                    if (!body)
+                        return;
+                    if (!body.value) {
+                        sendError(res, 400, "BAD_REQUEST", "Field 'value' is required");
+                        return;
+                    }
+                    await settingsAdapter.setCredential(route.key, body.value);
+                    sendJSON(res, 200, { ok: true });
+                    break;
+                }
+                case "add_route": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    const body = await parseJsonBody(req, res);
+                    if (!body)
+                        return;
+                    if (!body.pattern || !body.target) {
+                        sendError(res, 400, "BAD_REQUEST", "Fields 'pattern' and 'target' are required");
+                        return;
+                    }
+                    await gateway.addRoute(body.pattern, body.target, body.priority ?? 0);
+                    sendJSON(res, 201, { ok: true });
+                    break;
+                }
+                case "import_openapi": {
+                    if (!requireAuth(req, res, "admin"))
+                        return;
+                    const body = await parseJsonBody(req, res);
+                    if (!body)
+                        return;
+                    if (!body.name || !body.specUrl) {
+                        sendError(res, 400, "BAD_REQUEST", "Fields 'name' and 'specUrl' are required");
+                        return;
+                    }
+                    const { importOpenApiSpec } = await import("../../gateway/openapi-importer.js");
+                    const result = await importOpenApiSpec(gateway, body.name, body.specUrl, { baseUrl: body.baseUrl, isAdmin: true });
+                    sendJSON(res, 201, result);
+                    break;
+                }
+                default:
+                    sendError(res, 404, "NOT_FOUND", "Unknown gateway endpoint");
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Gateway request failed";
+            console.error("[rest-gateway] Error:", message);
+            sendError(res, 500, "INTERNAL_ERROR", message);
+        }
+    };
+}

package/dist/adapters/server/rest.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Zoe Server — REST Endpoint Handlers
+ *
+ * Processes incoming HTTP requests and routes them to the appropriate
+ * handler. All responses are JSON with proper Content-Type headers.
+ */
+import type { IncomingMessage, ServerResponse } from "http";
+import type { ProviderType, SkillMetadata, GenerateTextResult } from "../../core/types.js";
+import { ServerSessionManager } from "./session-store.js";
+import { type SettingsHandlerContext } from "./settings-handlers.js";
+export interface RestHandlerContext {
+    version: string;
+    startTime: number;
+    sessionManager: ServerSessionManager;
+    /** Generate text using the SDK */
+    generateText: (options: {
+        message: string;
+        model?: string;
+        provider?: ProviderType;
+        tools?: string[];
+        maxSteps?: number;
+        skills?: string[];
+    }) => Promise<GenerateTextResult>;
+    /** List available models grouped by provider */
+    listModels: () => Record<ProviderType, string[]>;
+    /** List available skill metadata */
+    listSkills: () => SkillMetadata[];
+    /** Settings handler context — required for settings/provider routes */
+    settingsHandlerContext?: SettingsHandlerContext;
+    /** Gateway REST handler — delegated for all /v1/gateway/* routes */
+    gatewayHandler?: (req: IncomingMessage, res: ServerResponse, path: string, method: string) => Promise<void>;
+}
+/**
+ * Creates the main REST request handler.
+ * Returns a function compatible with http.createServer().
+ */
+export declare function createRestHandler(ctx: RestHandlerContext): (req: IncomingMessage, res: ServerResponse) => Promise<void>;