zoe-agent 0.3.1

package/dist/adapters/server/standalone.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Zoe Server — Standalone Entry Point
+ *
+ * Starts the Zoe remote server as a standalone process.
+ * Suitable as a Docker CMD/ENTRYPOINT or direct CLI invocation.
+ *
+ * Usage:
+ *   node dist/adapters/server/standalone.js
+ *   node dist/adapters/server/standalone.js --generate-api-key
+ *
+ * Environment variables:
+ *   ZOE_PORT / PORT     — Port to listen on (default: 7337)
+ *   ZOE_HOST            — Host to bind to (default: "0.0.0.0")
+ *   ZOE_SESSION_DIR     — Directory for session storage
+ *   ZOE_SESSION_TTL     — Session TTL in seconds (default: 86400)
+ *   ZOE_API_KEYS_FILE   — Path to API key store file
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { startServer, initializeSkills } from "./index.js";
+import { generateApiKey } from "./auth.js";
+// ── Version ────────────────────────────────────────────────────────────
+function resolveVersion() {
+    try {
+        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";
+    }
+}
+// ── API Key Generation ─────────────────────────────────────────────────
+function handleGenerateApiKey() {
+    const filePath = process.env.ZOE_API_KEYS_FILE || undefined;
+    const entry = generateApiKey(["agent:run", "admin"], {
+        label: "cli-generated",
+        filePath,
+    });
+    process.stdout.write(`Generated API key:\n\n  ${entry.key}\n\n`);
+    process.stdout.write(`Scopes: ${entry.scopes.join(", ")}\n` +
+        `Created: ${entry.created}\n` +
+        `Stored in: ${filePath ?? "~/.zoe/server-keys.json"}\n`);
+    process.exit(0);
+}
+// ── Main ────────────────────────────────────────────────────────────────
+async function main() {
+    // Handle --generate-api-key flag
+    if (process.argv.includes("--generate-api-key")) {
+        handleGenerateApiKey();
+        return; // unreachable, but satisfies type checker
+    }
+    const version = resolveVersion();
+    // Resolve configuration from environment
+    const port = parseInt(process.env.ZOE_PORT ?? process.env.PORT ?? "", 10);
+    const host = process.env.ZOE_HOST ?? "0.0.0.0";
+    const sessionTTL = parseInt(process.env.ZOE_SESSION_TTL ?? "", 10);
+    const apiKeysFile = process.env.ZOE_API_KEYS_FILE;
+    // Expose API keys file path for the auth module if provided
+    if (apiKeysFile) {
+        process.env.ZOE_API_KEYS_FILE = apiKeysFile;
+    }
+    const options = {
+        host,
+        ...(isNaN(port) || port <= 0 ? {} : { port }),
+        ...(isNaN(sessionTTL) || sessionTTL <= 0 ? {} : { sessionTTL }),
+    };
+    process.stdout.write(`[zoe] Starting Zoe server v${version}\n`);
+    try {
+        // Initialize skills registry
+        await initializeSkills();
+        // Start server
+        const server = await startServer(options);
+        const actualPort = server.address()?.port ?? options.port ?? 7337;
+        process.stdout.write(`[zoe] Listening on ${host}:${actualPort}\n` +
+            `[zoe] Session TTL: ${isNaN(sessionTTL) || sessionTTL <= 0 ? 86400 : sessionTTL}s\n` +
+            `[zoe] API keys: ${apiKeysFile ?? "~/.zoe/server-keys.json"}\n`);
+        // Graceful shutdown
+        const shutdown = (signal) => {
+            process.stdout.write(`[zoe] Received ${signal}, shutting down...\n`);
+            server.close(() => {
+                process.stdout.write("[zoe] Server stopped.\n");
+                process.exit(0);
+            });
+            // Force exit after 5 seconds if connections don't drain
+            setTimeout(() => {
+                process.stdout.write("[zoe] Force exiting after 5s timeout.\n");
+                process.exit(0);
+            }, 5000);
+        };
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+        process.on("SIGINT", () => shutdown("SIGINT"));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("EADDRINUSE") ||
+            message.includes("EACCES")) {
+            process.stdout.write(`[zoe] Fatal: ${message}\n` +
+                `[zoe] Check that port ${isNaN(port) || port <= 0 ? 7337 : port} is available and you have permission to bind.\n`);
+        }
+        else if (message.includes("ENOENT") &&
+            message.includes("sessions")) {
+            process.stdout.write(`[zoe] Fatal: Cannot create session directory.\n` +
+                `[zoe] Ensure ZOE_SESSION_DIR (${process.env.ZOE_SESSION_DIR ?? "<cwd>/.zoe/sessions"}) is writable.\n`);
+        }
+        else {
+            process.stdout.write(`[zoe] Fatal error: ${message}\n`);
+        }
+        process.exit(1);
+    }
+}
+main();

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

@@ -0,0 +1,26 @@
+/**
+ * Zoe Server — WebSocket Protocol Handler
+ *
+ * Re-export hub. Setup and teardown functions live here;
+ * types and handlers are split into ws-types.ts and ws-handlers.ts.
+ *
+ * NOTE: Requires the `ws` npm package for Node.js. Install it via:
+ *   npm install ws
+ *   npm install -D @types/ws
+ *
+ * The module uses a dynamic import so it fails gracefully if `ws` is missing.
+ */
+import type { WSServer, WebSocketHandlerContext } from "./ws-types.js";
+export type { WebSocketHandlerContext } from "./ws-types.js";
+export { getActiveConnectionCount } from "./ws-handlers.js";
+/**
+ * Initialize the WebSocket server.
+ *
+ * Uses a dynamic import for the `ws` package. If it's not installed,
+ * logs a warning and returns null.
+ */
+export declare function setupWebSocket(server: import("http").Server, ctx: WebSocketHandlerContext): Promise<WSServer | null>;
+/**
+ * Close the WebSocket server and all active connections.
+ */
+export declare function closeWebSocket(): void;

package/dist/adapters/server/websocket.js

@@ -0,0 +1,68 @@
+/**
+ * Zoe Server — WebSocket Protocol Handler
+ *
+ * Re-export hub. Setup and teardown functions live here;
+ * types and handlers are split into ws-types.ts and ws-handlers.ts.
+ *
+ * NOTE: Requires the `ws` npm package for Node.js. Install it via:
+ *   npm install ws
+ *   npm install -D @types/ws
+ *
+ * The module uses a dynamic import so it fails gracefully if `ws` is missing.
+ */
+import { authMiddleware } from "./auth.js";
+import { handleConnection, closeAllConnections } from "./ws-handlers.js";
+export { getActiveConnectionCount } from "./ws-handlers.js";
+// ── Exported setup function ──────────────────────────────────────────
+let wss = null;
+/**
+ * Initialize the WebSocket server.
+ *
+ * Uses a dynamic import for the `ws` package. If it's not installed,
+ * logs a warning and returns null.
+ */
+export async function setupWebSocket(server, ctx) {
+    let wsModule;
+    try {
+        // @ts-expect-error — ws is an optional peer dependency
+        wsModule = (await import("ws"));
+    }
+    catch {
+        console.warn("[ws] The 'ws' package is not installed. WebSocket support is disabled.\n" +
+            "       Install it with: npm install ws");
+        return null;
+    }
+    wss = new wsModule.WebSocketServer({ noServer: true, path: "/ws" });
+    wss.on("connection", (ws, req) => {
+        handleConnection(ws, req, ctx);
+    });
+    // Handle HTTP upgrade requests
+    server.on("upgrade", (req, socket, head) => {
+        // Only handle /ws upgrades
+        const url = req.url?.split("?")[0];
+        if (url !== "/ws") {
+            return;
+        }
+        // Authenticate the upgrade request
+        const key = authMiddleware(req);
+        if (!key) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            wss.emit("connection", ws, req);
+        });
+    });
+    return wss;
+}
+/**
+ * Close the WebSocket server and all active connections.
+ */
+export function closeWebSocket() {
+    if (wss) {
+        closeAllConnections();
+        wss.close();
+        wss = null;
+    }
+}

package/dist/adapters/server/ws-handlers.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Zoe Server — WebSocket Protocol Handlers
+ *
+ * All handler functions, safeSend helper, and active connections registry.
+ * Extracted from websocket.ts for single-responsibility.
+ */
+import type { WebSocket, ServerMessage, WebSocketHandlerContext, ConnectionState } from "./ws-types.js";
+/**
+ * Get the number of currently active WebSocket connections.
+ */
+export declare function getActiveConnectionCount(): number;
+/**
+ * Get all connected WS clients (excluding the given one).
+ * Used by settings broadcast to notify other connections of changes.
+ */
+export declare function getOtherClients(excludeWs?: WebSocket): Array<{
+    ws: WebSocket;
+    state: ConnectionState;
+}>;
+export declare function safeSend(ws: WebSocket, message: ServerMessage): void;
+export declare function handleConnection(ws: WebSocket, req: import("http").IncomingMessage, ctx: WebSocketHandlerContext): void;
+/**
+ * Create an `approveTool` callback for the server adapter.
+ * Sends a `tool_approval_request` to the client and waits for a
+ * `tool_approval_response`. Falls back to auto-deny on timeout.
+ */
+export declare function createServerApproveTool(ws: WebSocket): import("../../core/types.js").ApproveToolFn;
+/**
+ * Close all active connections and clear the registry.
+ * Used by closeWebSocket() during shutdown.
+ */
+export declare function closeAllConnections(): void;