zoe-agent 0.3.1

package/dist/adapters/server/session-store.js

@@ -0,0 +1,272 @@
+/**
+ * Zoe Server — Server-side Session Management
+ *
+ * Wraps a PersistenceBackend for server-specific needs:
+ *  - TTL-based session expiration
+ *  - Per-API-key concurrency limits
+ *  - Periodic cleanup of stale sessions
+ *
+ * Raw storage is delegated to a PersistenceBackend (default: file-based).
+ * Server metadata (apiKeyHash, lastActivityAt) lives in memory and in
+ * the `metadata` field of SessionData.
+ */
+import { createPersistenceBackend } from "../../core/session-store.js";
+// ── Defaults ───────────────────────────────────────────────────────────
+const DEFAULT_SESSION_TTL = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_INACTIVITY_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_MAX_SESSIONS = 5;
+const DEFAULT_CLEANUP_INTERVAL = 5 * 60 * 1000; // 5 minutes
+// ── Helpers ────────────────────────────────────────────────────────────
+import * as crypto from "crypto";
+export function hashKey(key) {
+    return crypto.createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+// ── ServerSessionManager ───────────────────────────────────────────────
+export class ServerSessionManager {
+    sessions = new Map();
+    sessionTTL;
+    inactivityTimeout;
+    maxSessionsPerKey;
+    cleanupInterval;
+    backend;
+    cleanupTimer = null;
+    constructor(options) {
+        this.sessionTTL = options?.sessionTTL ?? DEFAULT_SESSION_TTL;
+        this.inactivityTimeout = options?.inactivityTimeout ?? DEFAULT_INACTIVITY_TIMEOUT;
+        this.maxSessionsPerKey = options?.maxSessionsPerKey ?? DEFAULT_MAX_SESSIONS;
+        this.cleanupInterval = options?.cleanupInterval ?? DEFAULT_CLEANUP_INTERVAL;
+        if (options?.backend) {
+            this.backend = options.backend;
+        }
+        else {
+            this.backend = createPersistenceBackend({
+                type: "file",
+                path: options?.sessionDir,
+            });
+        }
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────
+    /**
+     * Start the periodic cleanup timer.
+     */
+    startCleanup() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => this.cleanup(), this.cleanupInterval);
+        // Prevent the timer from keeping the process alive
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Stop the periodic cleanup timer.
+     */
+    stopCleanup() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    // ── CRUD ─────────────────────────────────────────────────────────────
+    /**
+     * Create a new session. Enforces per-API-key session limits.
+     * Returns the new SessionData or throws if the limit is exceeded.
+     * Awaits persistence — callers should await to ensure backend errors propagate.
+     */
+    async createSession(apiKey, provider, model) {
+        const keyHash = hashKey(apiKey);
+        // Enforce per-key limit
+        const existing = this.getSessionsByKey(keyHash);
+        if (existing.length >= this.maxSessionsPerKey) {
+            throw new Error(`Maximum concurrent sessions (${this.maxSessionsPerKey}) reached for this API key.`);
+        }
+        const id = crypto.randomUUID();
+        const now = Date.now();
+        const session = {
+            id,
+            messages: [],
+            createdAt: now,
+            updatedAt: now,
+            lastActivityAt: now,
+            apiKeyHash: keyHash,
+            provider,
+            model,
+        };
+        this.sessions.set(id, session);
+        await this.persistSessionAsync(session);
+        return {
+            id: session.id,
+            messages: session.messages,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            provider: session.provider,
+            model: session.model,
+        };
+    }
+    /**
+     * Get a session by its ID, verifying ownership via API key hash.
+     * Returns null if the session does not exist, has expired, or is not owned
+     * by the provided API key.
+     */
+    async getSession(id, apiKeyHash) {
+        let session = this.sessions.get(id);
+        if (!session) {
+            // Try loading from persistence backend
+            session = await this.loadSessionFromBackend(id);
+            if (!session)
+                return null;
+            this.sessions.set(id, session);
+        }
+        // Check expiration
+        if (this.isExpired(session)) {
+            this.deleteSession(id);
+            return null;
+        }
+        // Ownership verification — constant-time comparison to prevent timing attacks
+        if (!this.verifyOwnership(session, apiKeyHash)) {
+            return null;
+        }
+        return {
+            id: session.id,
+            messages: session.messages,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            provider: session.provider,
+            model: session.model,
+        };
+    }
+    /**
+     * Add a message to an existing session.
+     * Updates the last-activity timestamp.
+     */
+    addMessage(sessionId, message) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.messages.push(message);
+        session.updatedAt = Date.now();
+        session.lastActivityAt = Date.now();
+        this.persistSession(session);
+    }
+    /**
+     * Delete a session by ID.
+     */
+    deleteSession(id) {
+        this.sessions.delete(id);
+        this.backend.delete(id).catch(() => {
+            // Best-effort — don't crash on delete errors
+        });
+    }
+    /**
+     * Get all active (non-expired) sessions.
+     */
+    getActiveSessions() {
+        const active = [];
+        for (const [id, session] of this.sessions) {
+            if (!this.isExpired(session)) {
+                active.push({
+                    id: session.id,
+                    messages: session.messages,
+                    createdAt: session.createdAt,
+                    updatedAt: session.updatedAt,
+                    provider: session.provider,
+                    model: session.model,
+                });
+            }
+        }
+        return active;
+    }
+    /**
+     * Remove expired sessions from memory and backend.
+     */
+    cleanup() {
+        for (const [id, session] of this.sessions) {
+            if (this.isExpired(session)) {
+                this.deleteSession(id);
+            }
+        }
+    }
+    // ── Internal helpers ─────────────────────────────────────────────────
+    getSessionsByKey(keyHash) {
+        const result = [];
+        for (const session of this.sessions.values()) {
+            if (session.apiKeyHash === keyHash && !this.isExpired(session)) {
+                result.push(session);
+            }
+        }
+        return result;
+    }
+    isExpired(session) {
+        const now = Date.now();
+        // Absolute TTL
+        if (now - session.createdAt > this.sessionTTL) {
+            return true;
+        }
+        // Inactivity timeout
+        if (now - session.lastActivityAt > this.inactivityTimeout) {
+            return true;
+        }
+        return false;
+    }
+    persistSession(session) {
+        const data = {
+            id: session.id,
+            messages: session.messages,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            provider: session.provider,
+            model: session.model,
+            metadata: {
+                apiKeyHash: session.apiKeyHash,
+                lastActivityAt: session.lastActivityAt,
+            },
+        };
+        this.backend.save(session.id, data).catch(() => {
+            // Best-effort persistence — don't crash on write errors
+        });
+    }
+    async persistSessionAsync(session) {
+        const data = {
+            id: session.id,
+            messages: session.messages,
+            createdAt: session.createdAt,
+            updatedAt: session.updatedAt,
+            provider: session.provider,
+            model: session.model,
+            metadata: {
+                apiKeyHash: session.apiKeyHash,
+                lastActivityAt: session.lastActivityAt,
+            },
+        };
+        await this.backend.save(session.id, data);
+    }
+    async loadSessionFromBackend(id) {
+        try {
+            const data = await this.backend.load(id);
+            if (!data)
+                return null;
+            const metadata = data.metadata ?? {};
+            return {
+                id: data.id,
+                messages: data.messages,
+                createdAt: data.createdAt,
+                updatedAt: data.updatedAt,
+                provider: data.provider,
+                model: data.model,
+                apiKeyHash: metadata.apiKeyHash ?? "",
+                lastActivityAt: metadata.lastActivityAt ?? data.updatedAt,
+            };
+        }
+        catch (err) {
+            console.warn(`[session-store] Failed to load session ${id} from backend:`, err);
+            return null;
+        }
+    }
+    verifyOwnership(session, apiKeyHash) {
+        const a = Buffer.from(session.apiKeyHash, "utf-8");
+        const b = Buffer.from(apiKeyHash, "utf-8");
+        if (a.length !== b.length)
+            return false;
+        return crypto.timingSafeEqual(a, b);
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Zoe Server — Settings REST & WebSocket Handlers
+ *
+ * REST endpoints and WS message handlers for settings management.
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import { SettingsManager } from '../../core/settings-manager.js';
+import type { WebSocket, ConnectionState } from './ws-types.js';
+export interface SettingsHandlerContext {
+    settingsManager: SettingsManager;
+    /** Get all connected WS clients (excluding sender) */
+    getOtherClients: (excludeWs?: WebSocket) => Array<{
+        ws: WebSocket;
+        state: ConnectionState;
+    }>;
+}
+export declare function handleGetSettings(req: IncomingMessage, res: ServerResponse, ctx: SettingsHandlerContext, category?: string): Promise<void>;
+export declare function handlePatchSettings(req: IncomingMessage, res: ServerResponse, ctx: SettingsHandlerContext, category?: string): Promise<void>;
+export declare function handleGetSettingsSchema(req: IncomingMessage, res: ServerResponse, ctx: SettingsHandlerContext): Promise<void>;
+export declare function handlePostProvider(req: IncomingMessage, res: ServerResponse, ctx: SettingsHandlerContext): Promise<void>;
+export declare function handlePatchProvider(req: IncomingMessage, res: ServerResponse, ctx: SettingsHandlerContext, providerType: string): Promise<void>;
+export declare function handleDeleteProvider(req: IncomingMessage, res: ServerResponse, ctx: SettingsHandlerContext, providerType: string): Promise<void>;
+export declare function handleWsGetSettings(msg: any, ws: WebSocket, state: ConnectionState, ctx: SettingsHandlerContext): void;
+export declare function handleWsUpdateSettings(msg: any, ws: WebSocket, state: ConnectionState, ctx: SettingsHandlerContext): Promise<void>;

package/dist/adapters/server/settings-handlers.js

@@ -0,0 +1,360 @@
+/**
+ * Zoe Server — Settings REST & WebSocket Handlers
+ *
+ * REST endpoints and WS message handlers for settings management.
+ */
+import { SETTINGS_SCHEMA, SETTINGS_CATEGORIES } from '../../core/settings-schema.js';
+import { hasScope } from './auth.js';
+// ── Mutex ─────────────────────────────────────────────────────────────────
+class AsyncMutex {
+    queue = [];
+    locked = false;
+    async acquire() {
+        return new Promise((resolve) => {
+            const tryAcquire = () => {
+                if (!this.locked) {
+                    this.locked = true;
+                    resolve(() => {
+                        this.locked = false;
+                        if (this.queue.length > 0)
+                            this.queue.shift()();
+                    });
+                }
+                else {
+                    this.queue.push(tryAcquire);
+                }
+            };
+            tryAcquire();
+        });
+    }
+}
+const writeMutex = new AsyncMutex();
+// ── 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 requireScope(res, apiKey, scope) {
+    if (!apiKey || !hasScope(apiKey, scope)) {
+        sendError(res, 403, 'FORBIDDEN', `Requires ${scope} scope`);
+        return false;
+    }
+    return true;
+}
+function requireWsScope(state, scope) {
+    const apiKey = state.apiKey;
+    return !!apiKey && hasScope(apiKey, scope);
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        req.on('data', (chunk) => { data += chunk; });
+        req.on('end', () => {
+            try {
+                resolve(JSON.parse(data));
+            }
+            catch {
+                reject(new Error('Invalid JSON'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+const VALID_CATEGORIES = new Set(SETTINGS_CATEGORIES.map(c => c.key));
+const VALID_PROVIDER_TYPES = new Set(['openai', 'anthropic', 'glm', 'openai-compatible']);
+// ── REST Handlers ─────────────────────────────────────────────────────────
+export async function handleGetSettings(req, res, ctx, category) {
+    const apiKey = req.apiKey;
+    if (!requireScope(res, apiKey, 'agent:read'))
+        return;
+    if (category) {
+        if (!VALID_CATEGORIES.has(category)) {
+            sendError(res, 404, 'NOT_FOUND', `Unknown category: ${category}`);
+            return;
+        }
+        const all = ctx.settingsManager.listByCategory();
+        sendJSON(res, 200, { [category]: all[category] ?? [] });
+        return;
+    }
+    const all = ctx.settingsManager.listByCategory();
+    sendJSON(res, 200, all);
+}
+export async function handlePatchSettings(req, res, ctx, category) {
+    const apiKey = req.apiKey;
+    if (!requireScope(res, apiKey, 'admin'))
+        return;
+    const body = await readBody(req);
+    const updates = category ? { [category]: body } : body;
+    const applied = {};
+    const errors = [];
+    let requiresRestart = false;
+    const restartAffected = [];
+    const release = await writeMutex.acquire();
+    try {
+        for (const [cat, fields] of Object.entries(updates)) {
+            if (typeof fields !== 'object' || fields === null)
+                continue;
+            applied[cat] = {};
+            for (const [key, value] of Object.entries(fields)) {
+                const dotKey = category ? `${category}.${key}` : `${cat}.${key}`;
+                try {
+                    await ctx.settingsManager.set(dotKey, String(value));
+                    applied[cat][key] = ctx.settingsManager.get(dotKey).value;
+                    // Check restart requirement via schema
+                    const schema = SETTINGS_SCHEMA.get(dotKey);
+                    if (schema?.restartRequired) {
+                        requiresRestart = true;
+                        restartAffected.push(dotKey);
+                    }
+                }
+                catch (e) {
+                    errors.push({ field: dotKey, message: e.message });
+                }
+            }
+        }
+    }
+    finally {
+        release();
+    }
+    if (errors.length > 0) {
+        sendJSON(res, 422, {
+            error: { code: 'VALIDATION_ERROR', message: `${errors.length} field(s) failed validation`, details: errors },
+        });
+        return;
+    }
+    // Broadcast change notification
+    broadcastSettingsChange(ctx, Object.keys(updates), requiresRestart, restartAffected);
+    sendJSON(res, 200, { applied, requiresRestart, restartAffected });
+}
+export async function handleGetSettingsSchema(req, res, ctx) {
+    const apiKey = req.apiKey;
+    if (!requireScope(res, apiKey, 'agent:read'))
+        return;
+    // Build a simple JSON schema from SETTINGS_SCHEMA
+    const properties = {};
+    for (const [dotKey, schema] of SETTINGS_SCHEMA) {
+        const prop = {};
+        if (schema.type === 'number')
+            prop.type = 'integer';
+        else if (schema.type === 'boolean')
+            prop.type = 'boolean';
+        else if (schema.type === 'enum') {
+            prop.type = 'string';
+            prop.enum = schema.enumValues;
+        }
+        else
+            prop.type = 'string';
+        if (schema.secret)
+            prop.writeOnly = true;
+        if (schema.default !== undefined)
+            prop.default = schema.default;
+        properties[dotKey] = prop;
+    }
+    sendJSON(res, 200, {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        title: 'Zoe Agent Settings',
+        type: 'object',
+        properties,
+    });
+}
+export async function handlePostProvider(req, res, ctx) {
+    const apiKey = req.apiKey;
+    if (!requireScope(res, apiKey, 'admin'))
+        return;
+    const body = await readBody(req);
+    const providerType = body.type;
+    if (!providerType || !VALID_PROVIDER_TYPES.has(providerType)) {
+        sendError(res, 422, 'VALIDATION_ERROR', 'Invalid or missing provider type');
+        return;
+    }
+    // Check if already exists
+    const existingKey = `providers.${providerType === 'openai-compatible' ? 'openai-compat' : providerType}.apiKey`;
+    const existing = ctx.settingsManager.get(existingKey);
+    if (existing.value != null) {
+        sendError(res, 409, 'CONFLICT', `Provider "${providerType}" is already configured. Use PATCH to update.`);
+        return;
+    }
+    if (!body.apiKey) {
+        sendError(res, 422, 'VALIDATION_ERROR', 'apiKey is required');
+        return;
+    }
+    if (providerType === 'openai-compatible' && !body.baseUrl) {
+        sendError(res, 422, 'VALIDATION_ERROR', 'baseUrl is required for openai-compatible');
+        return;
+    }
+    const release = await writeMutex.acquire();
+    try {
+        await ctx.settingsManager.set(existingKey, body.apiKey);
+        if (body.model) {
+            const modelKey = `providers.${providerType === 'openai-compatible' ? 'openai-compat' : providerType}.model`;
+            await ctx.settingsManager.set(modelKey, body.model);
+        }
+        if (body.baseUrl && providerType === 'openai-compatible') {
+            await ctx.settingsManager.set('providers.openai-compat.baseUrl', body.baseUrl);
+        }
+    }
+    finally {
+        release();
+    }
+    broadcastSettingsChange(ctx, ['providers'], false, []);
+    sendJSON(res, 201, {
+        provider: { type: providerType, apiKey: ctx.settingsManager.get(existingKey).value },
+        requiresRestart: false,
+        restartAffected: [],
+    });
+}
+export async function handlePatchProvider(req, res, ctx, providerType) {
+    const apiKey = req.apiKey;
+    if (!requireScope(res, apiKey, 'admin'))
+        return;
+    if (!VALID_PROVIDER_TYPES.has(providerType)) {
+        sendError(res, 404, 'NOT_FOUND', `Unknown provider type: ${providerType}`);
+        return;
+    }
+    const body = await readBody(req);
+    const prefix = `providers.${providerType === 'openai-compatible' ? 'openai-compat' : providerType}`;
+    const release = await writeMutex.acquire();
+    try {
+        if (body.apiKey)
+            await ctx.settingsManager.set(`${prefix}.apiKey`, body.apiKey);
+        if (body.model)
+            await ctx.settingsManager.set(`${prefix}.model`, body.model);
+        if (body.baseUrl && providerType === 'openai-compatible')
+            await ctx.settingsManager.set(`${prefix}.baseUrl`, body.baseUrl);
+    }
+    finally {
+        release();
+    }
+    broadcastSettingsChange(ctx, ['providers'], false, []);
+    const result = { type: providerType };
+    result.apiKey = ctx.settingsManager.get(`${prefix}.apiKey`).value;
+    if (providerType === 'openai-compatible')
+        result.baseUrl = ctx.settingsManager.get(`${prefix}.baseUrl`).value;
+    if (body.model)
+        result.model = body.model;
+    sendJSON(res, 200, { provider: result, requiresRestart: false, restartAffected: [] });
+}
+export async function handleDeleteProvider(req, res, ctx, providerType) {
+    const apiKey = req.apiKey;
+    if (!requireScope(res, apiKey, 'admin'))
+        return;
+    if (!VALID_PROVIDER_TYPES.has(providerType)) {
+        sendError(res, 404, 'NOT_FOUND', `Unknown provider type: ${providerType}`);
+        return;
+    }
+    const prefix = `providers.${providerType === 'openai-compatible' ? 'openai-compat' : providerType}`;
+    // Check how many providers have keys configured
+    let configuredCount = 0;
+    for (const pType of ['openai', 'anthropic', 'glm', 'openai-compatible']) {
+        const p = `providers.${pType === 'openai-compatible' ? 'openai-compat' : pType}.apiKey`;
+        const val = ctx.settingsManager.get(p);
+        if (val.value != null)
+            configuredCount++;
+    }
+    if (configuredCount <= 1) {
+        sendError(res, 422, 'VALIDATION_ERROR', 'Cannot remove the last configured provider.');
+        return;
+    }
+    const release = await writeMutex.acquire();
+    try {
+        await ctx.settingsManager.reset(`${prefix}.apiKey`);
+        try {
+            await ctx.settingsManager.reset(`${prefix}.model`);
+        }
+        catch { /* may not exist */ }
+        try {
+            await ctx.settingsManager.reset(`${prefix}.baseUrl`);
+        }
+        catch { /* may not exist */ }
+    }
+    finally {
+        release();
+    }
+    broadcastSettingsChange(ctx, ['providers'], false, []);
+    sendJSON(res, 200, { removed: providerType, requiresRestart: false, restartAffected: [] });
+}
+// ── WS Handlers ───────────────────────────────────────────────────────────
+export function handleWsGetSettings(msg, ws, state, ctx) {
+    if (!requireWsScope(state, 'agent:read')) {
+        ws.send(JSON.stringify({ type: 'settings', id: msg.id, error: { code: 'FORBIDDEN', message: 'Requires agent:read scope' } }));
+        return;
+    }
+    const all = ctx.settingsManager.listByCategory();
+    const filtered = msg.category ? { [msg.category]: all[msg.category] ?? [] } : all;
+    ws.send(JSON.stringify({ type: 'settings', id: msg.id, settings: filtered }));
+}
+export async function handleWsUpdateSettings(msg, ws, state, ctx) {
+    if (!requireWsScope(state, 'admin')) {
+        ws.send(JSON.stringify({ type: 'settings_updated', id: msg.id, error: { code: 'FORBIDDEN', message: 'Requires admin scope' } }));
+        return;
+    }
+    const settings = msg.settings ?? {};
+    const applied = {};
+    const changedFields = [];
+    const errors = [];
+    let requiresRestart = false;
+    const restartAffected = [];
+    const release = await writeMutex.acquire();
+    try {
+        for (const [cat, fields] of Object.entries(settings)) {
+            if (typeof fields !== 'object' || fields === null)
+                continue;
+            applied[cat] = {};
+            for (const [key, value] of Object.entries(fields)) {
+                const dotKey = `${cat}.${key}`;
+                try {
+                    await ctx.settingsManager.set(dotKey, String(value));
+                    applied[cat][key] = ctx.settingsManager.get(dotKey).value;
+                    changedFields.push(dotKey);
+                    const schema = SETTINGS_SCHEMA.get(dotKey);
+                    if (schema?.restartRequired) {
+                        requiresRestart = true;
+                        restartAffected.push(dotKey);
+                    }
+                }
+                catch (e) {
+                    errors.push({ field: dotKey, message: e.message });
+                }
+            }
+        }
+    }
+    finally {
+        release();
+    }
+    if (errors.length > 0) {
+        ws.send(JSON.stringify({
+            type: 'settings_updated', id: msg.id,
+            error: { code: 'VALIDATION_ERROR', message: `${errors.length} field(s) failed validation`, details: errors },
+        }));
+        return;
+    }
+    // Respond to sender
+    ws.send(JSON.stringify({ type: 'settings_updated', id: msg.id, applied, requiresRestart, restartAffected }));
+    // Broadcast to others
+    broadcastSettingsChange(ctx, changedFields, requiresRestart, restartAffected, ws);
+}
+// ── Broadcast ─────────────────────────────────────────────────────────────
+function broadcastSettingsChange(ctx, changedFields, requiresRestart, restartAffected, excludeWs) {
+    const categories = new Set(changedFields.map(f => f.split('.')[0]));
+    const message = JSON.stringify({
+        type: 'settings_changed',
+        changedCategories: [...categories],
+        changedFields,
+        requiresRestart,
+        restartAffected,
+        timestamp: new Date().toISOString(),
+    });
+    for (const client of ctx.getOtherClients(excludeWs)) {
+        try {
+            client.ws.send(message);
+        }
+        catch { /* best-effort */ }
+    }
+}

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

@@ -0,0 +1,19 @@
+#!/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
+ */
+export {};