zoe-agent 0.3.1

package/dist/adapters/server/rest.js

@@ -0,0 +1,341 @@
+/**
+ * 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 { authMiddleware, hasScope } from "./auth.js";
+import { hashKey } from "./session-store.js";
+import { handleGetSettings, handlePatchSettings, handleGetSettingsSchema, handlePostProvider, handlePatchProvider, handleDeleteProvider, } from "./settings-handlers.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);
+    });
+}
+function matchRoute(url, method) {
+    // Strip query string
+    const path = url.split("?")[0];
+    if (method === "GET" && path === "/v1/health") {
+        return { handler: "health", params: {} };
+    }
+    if (method === "GET" && path === "/v1/models") {
+        return { handler: "models", params: {} };
+    }
+    if (method === "GET" && path === "/v1/skills") {
+        return { handler: "skills", params: {} };
+    }
+    if (method === "POST" && path === "/v1/chat") {
+        return { handler: "chat", params: {} };
+    }
+    // Settings routes
+    if (method === "GET" && path === "/v1/settings/schema") {
+        return { handler: "settings_schema", params: {} };
+    }
+    if (method === "GET" && path === "/v1/settings") {
+        return { handler: "settings", params: {} };
+    }
+    if (method === "PATCH" && path === "/v1/settings") {
+        return { handler: "settings_patch", params: {} };
+    }
+    const settingsCategoryMatch = path.match(/^\/v1\/settings\/([a-z]+)$/);
+    if (settingsCategoryMatch) {
+        if (method === "GET")
+            return { handler: "settings", params: { category: settingsCategoryMatch[1] } };
+        if (method === "PATCH")
+            return { handler: "settings_patch", params: { category: settingsCategoryMatch[1] } };
+    }
+    // Provider routes
+    if (method === "POST" && path === "/v1/providers") {
+        return { handler: "provider_post", params: {} };
+    }
+    const providerMatch = path.match(/^\/v1\/providers\/([a-z-]+)$/);
+    if (providerMatch) {
+        if (method === "PATCH")
+            return { handler: "provider_patch", params: { type: providerMatch[1] } };
+        if (method === "DELETE")
+            return { handler: "provider_delete", params: { type: providerMatch[1] } };
+    }
+    // GET /v1/sessions/:id
+    const sessionMatch = path.match(/^\/v1\/sessions\/([a-f0-9-]+)$/);
+    if (method === "GET" && sessionMatch) {
+        return { handler: "session", params: { id: sessionMatch[1] } };
+    }
+    // Gateway routes — delegate to gateway handler
+    if (path.startsWith("/v1/gateway")) {
+        return { handler: "gateway", params: { path, method } };
+    }
+    return null;
+}
+// ── Main request handler ───────────────────────────────────────────────
+/**
+ * Creates the main REST request handler.
+ * Returns a function compatible with http.createServer().
+ */
+export function createRestHandler(ctx) {
+    return async function handleRequest(req, res) {
+        const route = matchRoute(req.url ?? "/", req.method ?? "GET");
+        if (!route) {
+            sendError(res, 404, "NOT_FOUND", `No route for ${req.method} ${req.url}`);
+            return;
+        }
+        try {
+            switch (route.handler) {
+                case "health":
+                    await handleHealth(req, res, ctx);
+                    break;
+                case "models":
+                    await handleModels(req, res, ctx);
+                    break;
+                case "skills":
+                    await handleSkills(req, res, ctx);
+                    break;
+                case "chat":
+                    await handleChat(req, res, ctx);
+                    break;
+                case "session":
+                    await handleGetSession(req, res, ctx, route.params.id);
+                    break;
+                case "settings":
+                    await handleSettingsGet(req, res, ctx, route.params.category);
+                    break;
+                case "settings_schema":
+                    await handleSettingsSchema(req, res, ctx);
+                    break;
+                case "settings_patch":
+                    await handleSettingsPatch(req, res, ctx, route.params.category);
+                    break;
+                case "provider_post":
+                    await handleProviderPost(req, res, ctx);
+                    break;
+                case "provider_patch":
+                    await handleProviderPatch(req, res, ctx, route.params.type);
+                    break;
+                case "provider_delete":
+                    await handleProviderDelete(req, res, ctx, route.params.type);
+                    break;
+                case "gateway":
+                    if (!ctx.gatewayHandler) {
+                        sendError(res, 503, "SERVICE_UNAVAILABLE", "Gateway not configured");
+                        break;
+                    }
+                    await ctx.gatewayHandler(req, res, route.params.path, route.params.method);
+                    break;
+                default:
+                    sendError(res, 404, "NOT_FOUND", "Unknown endpoint");
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Internal server error";
+            console.error("[rest] Unhandled error:", message);
+            sendError(res, 500, "INTERNAL_ERROR", message);
+        }
+    };
+}
+// ── Individual handlers ────────────────────────────────────────────────
+async function handleHealth(_req, res, ctx) {
+    sendJSON(res, 200, {
+        status: "ok",
+        version: ctx.version,
+        uptime: Math.floor((Date.now() - ctx.startTime) / 1000),
+    });
+}
+async function handleModels(req, res, ctx) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    sendJSON(res, 200, { models: ctx.listModels() });
+}
+async function handleSkills(req, res, ctx) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    sendJSON(res, 200, { skills: ctx.listSkills() });
+}
+async function handleChat(req, res, ctx) {
+    // Auth
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    if (!hasScope(key, "agent:run")) {
+        sendError(res, 403, "FORBIDDEN", "API key lacks 'agent:run' scope");
+        return;
+    }
+    // Parse body
+    let body;
+    try {
+        body = await parseBody(req);
+    }
+    catch {
+        sendError(res, 400, "BAD_REQUEST", "Failed to read request body");
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        sendError(res, 400, "BAD_REQUEST", "Invalid JSON in request body");
+        return;
+    }
+    // Validate
+    if (!parsed.message || typeof parsed.message !== "string") {
+        sendError(res, 400, "BAD_REQUEST", "Field 'message' is required and must be a string");
+        return;
+    }
+    // Execute
+    try {
+        const result = await ctx.generateText({
+            message: parsed.message,
+            model: parsed.model,
+            provider: parsed.provider,
+            tools: parsed.tools,
+            maxSteps: parsed.maxSteps ?? 10,
+            skills: parsed.skills,
+        });
+        sendJSON(res, 200, {
+            text: result.text,
+            toolCalls: result.toolCalls,
+            usage: result.usage,
+            finishReason: result.finishReason,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Generation failed";
+        const isProviderError = message.includes("not configured") || message.includes("API key");
+        sendJSON(res, isProviderError ? 502 : 500, {
+            error: {
+                code: isProviderError ? "PROVIDER_ERROR" : "GENERATION_ERROR",
+                message,
+            },
+        });
+    }
+}
+async function handleGetSession(req, res, ctx, sessionId) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    if (!hasScope(key, "agent:read")) {
+        sendError(res, 403, "FORBIDDEN", "API key lacks 'agent:read' scope");
+        return;
+    }
+    const session = await ctx.sessionManager.getSession(sessionId, hashKey(key.key));
+    if (!session) {
+        sendError(res, 404, "NOT_FOUND", `Session ${sessionId} not found`);
+        return;
+    }
+    sendJSON(res, 200, session);
+}
+// ── Settings handler wrappers ────────────────────────────────────────────
+// Note: These require a SettingsHandlerContext with settingsManager.
+// The server setup code must extend RestHandlerContext or provide settingsManager separately.
+// For now, these check for settingsManager availability and return 503 if not configured.
+function getSettingsCtx(ctx) {
+    return ctx.settingsHandlerContext ?? null;
+}
+async function handleSettingsGet(req, res, ctx, category) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    req.apiKey = key;
+    const sCtx = getSettingsCtx(ctx);
+    if (!sCtx) {
+        sendError(res, 503, "SERVICE_UNAVAILABLE", "Settings not configured");
+        return;
+    }
+    await handleGetSettings(req, res, sCtx, category);
+}
+async function handleSettingsSchema(req, res, ctx) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    req.apiKey = key;
+    const sCtx = getSettingsCtx(ctx);
+    if (!sCtx) {
+        sendError(res, 503, "SERVICE_UNAVAILABLE", "Settings not configured");
+        return;
+    }
+    await handleGetSettingsSchema(req, res, sCtx);
+}
+async function handleSettingsPatch(req, res, ctx, category) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    req.apiKey = key;
+    const sCtx = getSettingsCtx(ctx);
+    if (!sCtx) {
+        sendError(res, 503, "SERVICE_UNAVAILABLE", "Settings not configured");
+        return;
+    }
+    await handlePatchSettings(req, res, sCtx, category);
+}
+async function handleProviderPost(req, res, ctx) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    req.apiKey = key;
+    const sCtx = getSettingsCtx(ctx);
+    if (!sCtx) {
+        sendError(res, 503, "SERVICE_UNAVAILABLE", "Settings not configured");
+        return;
+    }
+    await handlePostProvider(req, res, sCtx);
+}
+async function handleProviderPatch(req, res, ctx, type) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    req.apiKey = key;
+    const sCtx = getSettingsCtx(ctx);
+    if (!sCtx) {
+        sendError(res, 503, "SERVICE_UNAVAILABLE", "Settings not configured");
+        return;
+    }
+    await handlePatchProvider(req, res, sCtx, type);
+}
+async function handleProviderDelete(req, res, ctx, type) {
+    const key = authMiddleware(req);
+    if (!key) {
+        sendError(res, 401, "UNAUTHORIZED", "Missing or invalid API key");
+        return;
+    }
+    req.apiKey = key;
+    const sCtx = getSettingsCtx(ctx);
+    if (!sCtx) {
+        sendError(res, 503, "SERVICE_UNAVAILABLE", "Settings not configured");
+        return;
+    }
+    await handleDeleteProvider(req, res, sCtx, type);
+}

package/dist/adapters/server/server-core.d.ts

@@ -0,0 +1,55 @@
+import type { ProviderType, GenerateTextResult, Usage, PermissionLevel, ApproveToolFn } from "../../core/types.js";
+import type { Middleware } from "../../core/middleware.js";
+/**
+ * Server-side generateText using core agent loop directly.
+ */
+export declare function serverGenerateText(options: {
+    message: string;
+    model?: string;
+    provider?: ProviderType;
+    tools?: string[];
+    maxSteps?: number;
+    skills?: string[];
+}, permissionLevel: PermissionLevel, middleware?: Middleware[]): Promise<GenerateTextResult>;
+/**
+ * Server-side streamText using core agent loop directly.
+ */
+export declare function serverStreamText(opts: {
+    message: string;
+    model?: string;
+    provider?: ProviderType;
+    tools?: string[];
+    maxSteps?: number;
+    skills?: string[];
+    sessionId?: string;
+    permissionLevel?: PermissionLevel;
+    approveTool?: ApproveToolFn;
+    onText: (delta: string) => void;
+    onToolCall: (info: {
+        name: string;
+        args: Record<string, unknown>;
+        callId: string;
+    }) => void;
+    onToolResult: (info: {
+        callId: string;
+        output: string;
+        success: boolean;
+    }) => void;
+    onStep: (step: {
+        type: string;
+        content?: string;
+        timestamp: number;
+    }) => void;
+    onError: (error: {
+        code: string;
+        message: string;
+        provider?: string;
+        tool?: string;
+    }) => void;
+    onDone: (result: {
+        text: string;
+        usage: Usage;
+        finishReason: string;
+    }) => void;
+    signal?: AbortSignal;
+}, serverPermissionLevel: PermissionLevel, middleware?: Middleware[]): Promise<void>;

package/dist/adapters/server/server-core.js

@@ -0,0 +1,121 @@
+import { runAgentLoop } from "../../core/agent-loop.js";
+import { createHookExecutor } from "../../core/hooks.js";
+import { resolveTools, getAllToolDefinitions } from "../../core/tool-executor.js";
+import { generateId, now } from "../../core/message-convert.js";
+import { getProvider } from "../../core/provider-resolver.js";
+/**
+ * Server-side generateText using core agent loop directly.
+ */
+export async function serverGenerateText(options, permissionLevel, middleware) {
+    // Resolve provider
+    const { provider: llmProvider, model } = await getProvider(options.provider);
+    // Resolve tools
+    const toolDefs = options.tools ? resolveTools(options.tools) : getAllToolDefinitions();
+    // Hooks
+    const hooks = createHookExecutor();
+    // Build message list
+    const messages = [];
+    messages.push({
+        id: generateId(),
+        role: "user",
+        content: options.message,
+        timestamp: now(),
+    });
+    // Run the agent loop
+    const result = await runAgentLoop({
+        provider: llmProvider,
+        model: options.model ?? model,
+        messages,
+        toolDefs,
+        maxSteps: options.maxSteps ?? 5,
+        hooks,
+        permissionLevel,
+        middleware,
+        config: { agentName: "server" },
+    });
+    // Extract final text from last assistant message
+    const lastAssistant = [...result.messages]
+        .reverse()
+        .find((m) => m.role === "assistant" && m.content);
+    const text = lastAssistant?.content ?? "";
+    return {
+        text,
+        steps: result.steps,
+        toolCalls: result.toolCalls,
+        usage: result.usage,
+        finishReason: result.finishReason,
+        messages: result.messages,
+    };
+}
+/**
+ * Server-side streamText using core agent loop directly.
+ */
+export async function serverStreamText(opts, serverPermissionLevel, middleware) {
+    try {
+        // Resolve provider
+        const { provider: llmProvider, model } = await getProvider(opts.provider);
+        // Resolve tools
+        const toolDefs = opts.tools ? resolveTools(opts.tools) : getAllToolDefinitions();
+        // Hooks
+        const hooks = createHookExecutor();
+        // Build message list
+        const messages = [];
+        messages.push({
+            id: generateId(),
+            role: "user",
+            content: opts.message,
+            timestamp: now(),
+        });
+        // Accumulate text for the final result
+        let accumulatedText = "";
+        // Run the agent loop with onStep callbacks
+        const result = await runAgentLoop({
+            provider: llmProvider,
+            model: opts.model ?? model,
+            messages,
+            toolDefs,
+            maxSteps: opts.maxSteps ?? 5,
+            hooks,
+            permissionLevel: opts.permissionLevel ?? serverPermissionLevel,
+            approveTool: opts.approveTool,
+            signal: opts.signal,
+            middleware,
+            config: { agentName: "server" },
+            onStep: (step) => {
+                if (step.type === "text" && step.content) {
+                    accumulatedText += step.content;
+                    opts.onText(step.content);
+                }
+                if (step.type === "tool_call" && step.toolCall) {
+                    opts.onToolCall({
+                        name: step.toolCall.name,
+                        args: step.toolCall.args,
+                        callId: step.toolCall.id,
+                    });
+                    opts.onToolResult({
+                        callId: step.toolCall.id,
+                        output: step.toolCall.result,
+                        success: !step.toolCall.result.startsWith("Error:"),
+                    });
+                }
+                opts.onStep(step);
+            },
+        });
+        opts.onDone({
+            text: accumulatedText,
+            usage: result.usage,
+            finishReason: result.finishReason,
+        });
+    }
+    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",
+        });
+    }
+}

package/dist/adapters/server/session-store.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 type { ProviderType, Message, SessionData, PersistenceBackend } from "../../core/types.js";
+export interface ServerSessionManagerOptions {
+    /** Session TTL in milliseconds (default: 24 hours) */
+    sessionTTL?: number;
+    /** Inactivity timeout in milliseconds (default: 30 minutes) */
+    inactivityTimeout?: number;
+    /** Max concurrent sessions per API key (default: 5) */
+    maxSessionsPerKey?: number;
+    /** Cleanup interval in milliseconds (default: 5 minutes) */
+    cleanupInterval?: number;
+    /** Directory for file-based session storage (ignored when `backend` is set) */
+    sessionDir?: string;
+    /** Custom persistence backend (overrides sessionDir) */
+    backend?: PersistenceBackend;
+}
+export declare function hashKey(key: string): string;
+export declare class ServerSessionManager {
+    private sessions;
+    private sessionTTL;
+    private inactivityTimeout;
+    private maxSessionsPerKey;
+    private cleanupInterval;
+    private backend;
+    private cleanupTimer;
+    constructor(options?: ServerSessionManagerOptions);
+    /**
+     * Start the periodic cleanup timer.
+     */
+    startCleanup(): void;
+    /**
+     * Stop the periodic cleanup timer.
+     */
+    stopCleanup(): void;
+    /**
+     * 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.
+     */
+    createSession(apiKey: string, provider?: ProviderType, model?: string): Promise<SessionData>;
+    /**
+     * 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.
+     */
+    getSession(id: string, apiKeyHash: string): Promise<SessionData | null>;
+    /**
+     * Add a message to an existing session.
+     * Updates the last-activity timestamp.
+     */
+    addMessage(sessionId: string, message: Message): void;
+    /**
+     * Delete a session by ID.
+     */
+    deleteSession(id: string): void;
+    /**
+     * Get all active (non-expired) sessions.
+     */
+    getActiveSessions(): SessionData[];
+    /**
+     * Remove expired sessions from memory and backend.
+     */
+    cleanup(): void;
+    private getSessionsByKey;
+    private isExpired;
+    private persistSession;
+    private persistSessionAsync;
+    private loadSessionFromBackend;
+    private verifyOwnership;
+}