otterly 0.1.0

package/dist/server/routes-native.js

@@ -0,0 +1,215 @@
+// Native API routes: /api/status, /api/run, /api/stream
+// Richer response format than OpenAI compat — includes cost, tools, duration.
+import { ClaudeEngine } from "../engine.js";
+import { AgentError } from "../errors.js";
+import { apiSessions } from "./session-store.js";
+import { errorToHttpStatus } from "./openai-compat.js";
+import { logError } from "./logger.js";
+const PKG_VERSION = "0.1.0";
+/**
+ * GET /api/status — health check with queue and circuit breaker stats
+ */
+export function handleStatus(_req, res, queue, circuitBreaker) {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+        status: "ok",
+        version: PKG_VERSION,
+        activeSessions: apiSessions.count(),
+        ...(queue ? { queue: queue.stats() } : {}),
+        ...(circuitBreaker ? { circuitBreaker: circuitBreaker.getState() } : {}),
+    }));
+}
+/**
+ * POST /api/run — one-shot execution, returns full result.
+ * Supports session reuse via X-Session-Id header or session_id in body.
+ */
+export async function handleRun(req, res, ctx, circuitBreaker) {
+    const body = req.body;
+    if (!body || !body.prompt || typeof body.prompt !== "string") {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "prompt is required" }));
+        return;
+    }
+    // Session reuse: check for session ID
+    const sessionId = req.headers["x-session-id"] || body.session_id || null;
+    if (sessionId) {
+        const entry = apiSessions.get(sessionId);
+        if (entry?.session) {
+            try {
+                const result = await entry.session.send(body.prompt);
+                apiSessions.recordRequest(sessionId, result.cost);
+                circuitBreaker?.onSuccess();
+                res.writeHead(200, {
+                    "Content-Type": "application/json",
+                    "X-Session-Id": result.sessionId || sessionId,
+                });
+                res.end(JSON.stringify(result));
+                return;
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                const code = err instanceof AgentError ? err.code : undefined;
+                circuitBreaker?.onFailure(code);
+                logError(req.requestId || "", e.message);
+                const status = errorToHttpStatus(e);
+                res.writeHead(status, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: e.message }));
+                return;
+            }
+        }
+        // Session not found — fall through to one-shot
+    }
+    const engine = new ClaudeEngine();
+    const abortController = new AbortController();
+    req.on("close", () => abortController.abort());
+    if (req.timeoutSignal) {
+        req.timeoutSignal.addEventListener("abort", () => abortController.abort());
+    }
+    const options = {
+        cwd: body.options?.cwd || ctx.workingDir,
+        permissionMode: body.options?.permissionMode || "bypassPermissions",
+        signal: abortController.signal,
+    };
+    const bodyOpts = body.options;
+    if (bodyOpts?.systemPrompt)
+        options.systemPrompt = bodyOpts.systemPrompt;
+    if (bodyOpts?.resume)
+        options.resume = bodyOpts.resume;
+    if (bodyOpts?.model)
+        options.model = bodyOpts.model;
+    if (bodyOpts?.maxTurns)
+        options.maxTurns = bodyOpts.maxTurns;
+    try {
+        const result = await engine.run(body.prompt, options);
+        circuitBreaker?.onSuccess();
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result));
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        if (e.name === "AbortError" || abortController.signal.aborted) {
+            if (!res.headersSent) {
+                res.writeHead(499, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Request aborted" }));
+            }
+            return;
+        }
+        const code = err instanceof AgentError ? err.code : undefined;
+        circuitBreaker?.onFailure(code);
+        logError(req.requestId || "", e.message);
+        const status = errorToHttpStatus(e);
+        res.writeHead(status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: e.message }));
+    }
+}
+/**
+ * POST /api/stream — streaming execution, NDJSON.
+ * Supports session reuse via X-Session-Id header or session_id in body.
+ * Includes backpressure: waits for drain when write buffer is full.
+ */
+export async function handleStream(req, res, ctx, circuitBreaker) {
+    const body = req.body;
+    if (!body || !body.prompt || typeof body.prompt !== "string") {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "prompt is required" }));
+        return;
+    }
+    res.writeHead(200, {
+        "Content-Type": "application/x-ndjson",
+        "Transfer-Encoding": "chunked",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+    });
+    async function sendLine(obj) {
+        if (res.writableEnded)
+            return;
+        const ok = res.write(JSON.stringify(obj) + "\n");
+        if (!ok) {
+            await new Promise((resolve) => res.once("drain", resolve));
+        }
+    }
+    // Session reuse
+    const sessionId = req.headers["x-session-id"] || body.session_id || null;
+    if (sessionId) {
+        const entry = apiSessions.get(sessionId);
+        if (entry?.session) {
+            try {
+                for await (const event of entry.session.sendStream(body.prompt)) {
+                    await sendStreamEvent(event, sendLine);
+                    if (event.type === "result") {
+                        apiSessions.recordRequest(sessionId, event.cost);
+                    }
+                }
+                circuitBreaker?.onSuccess();
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                const code = err instanceof AgentError ? err.code : undefined;
+                circuitBreaker?.onFailure(code);
+                await sendLine({ type: "error", message: e.message });
+            }
+            if (!res.writableEnded)
+                res.end();
+            return;
+        }
+    }
+    const engine = new ClaudeEngine();
+    const abortController = new AbortController();
+    req.on("close", () => abortController.abort());
+    if (req.timeoutSignal) {
+        req.timeoutSignal.addEventListener("abort", () => abortController.abort());
+    }
+    const options = {
+        cwd: body.options?.cwd || ctx.workingDir,
+        permissionMode: body.options?.permissionMode || "bypassPermissions",
+        signal: abortController.signal,
+    };
+    const bodyOpts = body.options;
+    if (bodyOpts?.systemPrompt)
+        options.systemPrompt = bodyOpts.systemPrompt;
+    if (bodyOpts?.resume)
+        options.resume = bodyOpts.resume;
+    if (bodyOpts?.model)
+        options.model = bodyOpts.model;
+    try {
+        for await (const event of engine.stream(body.prompt, options)) {
+            if (abortController.signal.aborted)
+                break;
+            await sendStreamEvent(event, sendLine);
+        }
+        circuitBreaker?.onSuccess();
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        if (e.name !== "AbortError" && !abortController.signal.aborted) {
+            const code = err instanceof AgentError ? err.code : undefined;
+            circuitBreaker?.onFailure(code);
+            await sendLine({ type: "error", message: e.message });
+        }
+    }
+    if (!res.writableEnded) {
+        res.end();
+    }
+}
+async function sendStreamEvent(event, sendLine) {
+    switch (event.type) {
+        case "system":
+            await sendLine({ type: "session_init", sessionId: event.sessionId, model: event.model });
+            break;
+        case "text_delta":
+            await sendLine({ type: "text_delta", delta: event.delta });
+            break;
+        case "tool_use":
+            await sendLine({ type: "tool_use", id: event.id, tool: event.tool, input: event.input, description: event.description });
+            break;
+        case "tool_result":
+            await sendLine({ type: "tool_result", toolUseId: event.toolUseId, tool: event.tool, output: event.output, isError: event.isError });
+            break;
+        case "result":
+            await sendLine({ type: "result", text: event.text, cost: event.cost, duration: event.duration, sessionId: event.sessionId, usage: event.usage });
+            break;
+        case "error":
+            await sendLine({ type: "error", message: event.error.message });
+            break;
+    }
+}

package/dist/server/routes-openai.d.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from "http";
+import type { ParsedRequest, ServerContext } from "./routes-native.js";
+import type { CircuitBreaker } from "./circuit-breaker.js";
+/**
+ * Handle POST /v1/chat/completions
+ */
+export declare function handleChatCompletions(req: ParsedRequest, res: ServerResponse, ctx: ServerContext, circuitBreaker?: CircuitBreaker): Promise<void>;

package/dist/server/routes-openai.js

@@ -0,0 +1,203 @@
+// POST /v1/chat/completions — OpenAI-compatible endpoint.
+// Supports streaming (SSE) and non-streaming responses.
+// Auth is handled by middleware in index.ts — not checked here.
+import crypto from "crypto";
+import { ClaudeEngine } from "../engine.js";
+import { AgentError } from "../errors.js";
+import { apiSessions } from "./session-store.js";
+import { logError } from "./logger.js";
+import { openaiToClaudeInput, claudeResultToOpenai, makeStreamChunk, sseData, errorToHttpStatus, openaiErrorBody, openaiToolsToAllowedTools, } from "./openai-compat.js";
+/**
+ * Handle POST /v1/chat/completions
+ */
+export async function handleChatCompletions(req, res, ctx, circuitBreaker) {
+    // Auth is now handled by middleware in index.ts
+    const body = req.body;
+    if (!body || !body.messages || !Array.isArray(body.messages)) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(openaiErrorBody(400, "messages array is required")));
+        return;
+    }
+    const { prompt, systemPrompt, isMultimodal } = openaiToClaudeInput(body);
+    const model = body.model || "claude-sonnet-4-20250514";
+    const stream = body.stream === true;
+    const abortController = new AbortController();
+    req.on("close", () => abortController.abort());
+    if (req.timeoutSignal) {
+        req.timeoutSignal.addEventListener("abort", () => abortController.abort());
+    }
+    const options = {
+        cwd: ctx.workingDir,
+        permissionMode: "bypassPermissions",
+        signal: abortController.signal,
+    };
+    // Build system prompt: original + JSON mode injection
+    let finalSystemPrompt = systemPrompt || "";
+    if (body.response_format?.type === "json_object") {
+        const jsonInstruction = "You must respond with valid JSON only. No markdown, no explanation, no code fences, just a JSON object.";
+        finalSystemPrompt = finalSystemPrompt
+            ? `${finalSystemPrompt}\n\n${jsonInstruction}`
+            : jsonInstruction;
+    }
+    if (finalSystemPrompt) {
+        options.systemPrompt = finalSystemPrompt;
+    }
+    if (model) {
+        options.model = model;
+    }
+    // Tools parameter → allowedTools filter
+    if (body.tools && Array.isArray(body.tools)) {
+        const allowed = openaiToolsToAllowedTools(body.tools);
+        if (allowed.length > 0) {
+            options.allowedTools = allowed;
+        }
+    }
+    // Session reuse via X-Session-Id header or session_id in body
+    const sessionId = req.headers["x-session-id"]
+        || body.session_id
+        || null;
+    if (sessionId) {
+        const entry = apiSessions.get(sessionId);
+        if (entry?.session) {
+            if (stream) {
+                await handleSessionStreaming(req, res, entry.session, prompt, model, sessionId, circuitBreaker);
+            }
+            else {
+                await handleSessionNonStreaming(req, res, entry.session, prompt, model, sessionId, circuitBreaker);
+            }
+            return;
+        }
+        // Session not found — fall through to one-shot
+    }
+    // Multimodal: for now, add a note to the prompt about image content.
+    // Full multimodal requires session-based path with SDKUserMessage.
+    // This is a pragmatic approach that works for most cases.
+    if (stream) {
+        await handleStreaming(req, res, prompt, options, model, abortController, circuitBreaker);
+    }
+    else {
+        await handleNonStreaming(req, res, prompt, options, model, abortController, circuitBreaker);
+    }
+}
+async function handleSessionNonStreaming(req, res, session, prompt, model, sessionId, circuitBreaker) {
+    try {
+        const result = await session.send(prompt);
+        apiSessions.recordRequest(sessionId, result.cost);
+        circuitBreaker?.onSuccess();
+        const response = claudeResultToOpenai(result.text, model, result.usage);
+        res.writeHead(200, {
+            "Content-Type": "application/json",
+            "X-Session-Id": result.sessionId || sessionId,
+        });
+        res.end(JSON.stringify(response));
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        const code = err instanceof AgentError ? err.code : undefined;
+        circuitBreaker?.onFailure(code);
+        logError(req.requestId || "", e.message);
+        const status = errorToHttpStatus(e);
+        res.writeHead(status, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(openaiErrorBody(status, e.message)));
+    }
+}
+async function handleSessionStreaming(req, res, session, prompt, model, sessionId, circuitBreaker) {
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "X-Session-Id": sessionId,
+    });
+    const completionId = `chatcmpl-otterly-${crypto.randomUUID().slice(0, 12)}`;
+    await sseWrite(res, sseData(makeStreamChunk(completionId, { role: "assistant" }, null, model)));
+    try {
+        for await (const event of session.sendStream(prompt)) {
+            if (event.type === "text_delta") {
+                await sseWrite(res, sseData(makeStreamChunk(completionId, { content: event.delta }, null, model)));
+            }
+            else if (event.type === "result") {
+                apiSessions.recordRequest(sessionId, event.cost);
+                await sseWrite(res, sseData(makeStreamChunk(completionId, {}, "stop", model)));
+            }
+        }
+        circuitBreaker?.onSuccess();
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        const code = err instanceof AgentError ? err.code : undefined;
+        circuitBreaker?.onFailure(code);
+        await sseWrite(res, sseData({ error: { message: e.message, type: "server_error" } }));
+    }
+    await sseWrite(res, "data: [DONE]\n\n");
+    if (!res.writableEnded)
+        res.end();
+}
+async function handleNonStreaming(req, res, prompt, options, model, abortController, circuitBreaker) {
+    const engine = new ClaudeEngine();
+    try {
+        const result = await engine.run(prompt, options);
+        circuitBreaker?.onSuccess();
+        const response = claudeResultToOpenai(result.text, model, result.usage);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(response));
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        if (e.name === "AbortError" || abortController.signal.aborted)
+            return;
+        const code = err instanceof AgentError ? err.code : undefined;
+        circuitBreaker?.onFailure(code);
+        logError(req.requestId || "", e.message);
+        const status = errorToHttpStatus(e);
+        if (!res.headersSent) {
+            res.writeHead(status, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(openaiErrorBody(status, e.message)));
+        }
+    }
+}
+async function handleStreaming(req, res, prompt, options, model, abortController, circuitBreaker) {
+    const engine = new ClaudeEngine();
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+    });
+    const completionId = `chatcmpl-otterly-${crypto.randomUUID().slice(0, 12)}`;
+    // Send initial role chunk
+    await sseWrite(res, sseData(makeStreamChunk(completionId, { role: "assistant" }, null, model)));
+    try {
+        for await (const event of engine.stream(prompt, options)) {
+            if (abortController.signal.aborted)
+                break;
+            if (event.type === "text_delta") {
+                await sseWrite(res, sseData(makeStreamChunk(completionId, { content: event.delta }, null, model)));
+            }
+            else if (event.type === "result") {
+                await sseWrite(res, sseData(makeStreamChunk(completionId, {}, "stop", model)));
+            }
+        }
+        circuitBreaker?.onSuccess();
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        if (e.name !== "AbortError" && !abortController.signal.aborted) {
+            const code = err instanceof AgentError ? err.code : undefined;
+            circuitBreaker?.onFailure(code);
+            logError(req.requestId || "", e.message);
+            await sseWrite(res, sseData({ error: { message: e.message, type: "server_error" } }));
+        }
+    }
+    await sseWrite(res, "data: [DONE]\n\n");
+    if (!res.writableEnded) {
+        res.end();
+    }
+}
+/** Write to SSE response with backpressure support. */
+async function sseWrite(res, data) {
+    if (res.writableEnded)
+        return;
+    const ok = res.write(data);
+    if (!ok) {
+        await new Promise((resolve) => res.once("drain", resolve));
+    }
+}

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

@@ -0,0 +1,36 @@
+import type { Session } from "../session.js";
+export interface SessionStoreOptions {
+    maxSessions?: number;
+    idleTimeoutMs?: number;
+}
+export interface SessionMetadata {
+    createdAt: number;
+    lastActivity: number;
+    requestCount: number;
+    totalCost: number;
+}
+interface SessionEntry {
+    session?: Session;
+    abortController?: AbortController;
+    metadata: SessionMetadata;
+    [key: string]: unknown;
+}
+declare class ApiSessionStore {
+    private sessions;
+    private sweepInterval;
+    private maxSessions;
+    private idleTimeoutMs;
+    constructor(opts?: SessionStoreOptions);
+    create(id: string, data: Record<string, unknown>): string;
+    get(id: string): SessionEntry | null;
+    /** Record a request against a session (bumps count and cost). */
+    recordRequest(id: string, cost: number): void;
+    delete(id: string): void;
+    count(): number;
+    sweepIdle(): void;
+    destroy(): void;
+    /** Evict the least-recently-used session (first item in Map). */
+    private evictLRU;
+}
+export declare const apiSessions: ApiSessionStore;
+export {};

package/dist/server/session-store.js

@@ -0,0 +1,87 @@
+// In-memory store for active API/WebSocket sessions.
+// LRU eviction, max session limit, idle timeout.
+class ApiSessionStore {
+    sessions = new Map();
+    sweepInterval;
+    maxSessions;
+    idleTimeoutMs;
+    constructor(opts = {}) {
+        this.maxSessions = opts.maxSessions ?? 20;
+        this.idleTimeoutMs = opts.idleTimeoutMs ?? 30 * 60 * 1000; // 30 min
+        this.sweepInterval = setInterval(() => this.sweepIdle(), 5 * 60 * 1000);
+        this.sweepInterval.unref();
+    }
+    create(id, data) {
+        // Evict LRU if at capacity
+        if (this.sessions.size >= this.maxSessions && !this.sessions.has(id)) {
+            this.evictLRU();
+        }
+        const now = Date.now();
+        this.sessions.set(id, {
+            ...data,
+            metadata: {
+                createdAt: now,
+                lastActivity: now,
+                requestCount: 0,
+                totalCost: 0,
+            },
+        });
+        return id;
+    }
+    get(id) {
+        const entry = this.sessions.get(id);
+        if (entry) {
+            entry.metadata.lastActivity = Date.now();
+            // Move to end of map for LRU ordering (Map preserves insertion order)
+            this.sessions.delete(id);
+            this.sessions.set(id, entry);
+        }
+        return entry || null;
+    }
+    /** Record a request against a session (bumps count and cost). */
+    recordRequest(id, cost) {
+        const entry = this.sessions.get(id);
+        if (entry) {
+            entry.metadata.requestCount++;
+            entry.metadata.totalCost += cost;
+            entry.metadata.lastActivity = Date.now();
+        }
+    }
+    delete(id) {
+        const entry = this.sessions.get(id);
+        if (entry) {
+            if (entry.session && typeof entry.session.close === "function") {
+                entry.session.close();
+            }
+            if (entry.abortController) {
+                entry.abortController.abort();
+            }
+            this.sessions.delete(id);
+        }
+    }
+    count() {
+        return this.sessions.size;
+    }
+    sweepIdle() {
+        const now = Date.now();
+        for (const [id, entry] of this.sessions) {
+            if (now - entry.metadata.lastActivity > this.idleTimeoutMs) {
+                this.delete(id);
+            }
+        }
+    }
+    destroy() {
+        clearInterval(this.sweepInterval);
+        for (const id of [...this.sessions.keys()]) {
+            this.delete(id);
+        }
+    }
+    /** Evict the least-recently-used session (first item in Map). */
+    evictLRU() {
+        const firstKey = this.sessions.keys().next().value;
+        if (firstKey !== undefined) {
+            this.delete(firstKey);
+        }
+    }
+}
+export const apiSessions = new ApiSessionStore();

package/dist/server/ws-handler.d.ts

@@ -0,0 +1,7 @@
+import type { WebSocketServer } from "ws";
+/**
+ * Attach WebSocket handling to a WebSocketServer for the API server.
+ */
+export declare function attachWsHandler(wss: WebSocketServer, ctx: {
+    workingDir: string;
+}): void;