otterly 0.1.0

package/dist/server/middleware.d.ts

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from "http";
+import type { ServerContext } from "./routes-native.js";
+export declare function checkAuth(req: IncomingMessage, ctx: ServerContext): boolean;
+export interface RateLimiterOptions {
+    requestsPerMinute?: number;
+}
+export declare class RateLimiter {
+    private requestsPerMinute;
+    private buckets;
+    private cleanupInterval;
+    constructor(opts?: RateLimiterOptions);
+    /** Returns true if allowed, false if rate-limited. */
+    allow(key: string): boolean;
+    /** Get the client key from a request (IP-based). */
+    keyFor(req: IncomingMessage): string;
+    destroy(): void;
+    private cleanup;
+}
+export declare function sendAuthError(res: ServerResponse, format: "openai" | "native"): void;
+export declare function sendRateLimitError(res: ServerResponse, format: "openai" | "native"): void;

package/dist/server/middleware.js

@@ -0,0 +1,80 @@
+// Shared auth check and token-bucket rate limiter.
+// ── Auth ──
+export function checkAuth(req, ctx) {
+    if (!ctx.apiKey)
+        return true;
+    const authHeader = req.headers["authorization"] || "";
+    const token = authHeader.replace(/^Bearer\s+/i, "");
+    return token === ctx.apiKey;
+}
+export class RateLimiter {
+    requestsPerMinute;
+    buckets = new Map();
+    cleanupInterval;
+    constructor(opts = {}) {
+        this.requestsPerMinute = opts.requestsPerMinute ?? 60;
+        // Sweep stale buckets every 5 minutes
+        this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+        this.cleanupInterval.unref();
+    }
+    /** Returns true if allowed, false if rate-limited. */
+    allow(key) {
+        const now = Date.now();
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = { tokens: this.requestsPerMinute, lastRefill: now };
+            this.buckets.set(key, bucket);
+        }
+        // Refill tokens based on elapsed time
+        const elapsed = now - bucket.lastRefill;
+        const refill = (elapsed / 60_000) * this.requestsPerMinute;
+        bucket.tokens = Math.min(this.requestsPerMinute, bucket.tokens + refill);
+        bucket.lastRefill = now;
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    /** Get the client key from a request (IP-based). */
+    keyFor(req) {
+        return req.headers["x-forwarded-for"]?.split(",")[0]?.trim()
+            || req.socket.remoteAddress
+            || "unknown";
+    }
+    destroy() {
+        clearInterval(this.cleanupInterval);
+    }
+    cleanup() {
+        const now = Date.now();
+        const staleMs = 10 * 60 * 1000; // 10 minutes
+        for (const [key, bucket] of this.buckets) {
+            if (now - bucket.lastRefill > staleMs) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+}
+// ── Middleware helpers ──
+export function sendAuthError(res, format) {
+    res.writeHead(401, { "Content-Type": "application/json" });
+    if (format === "openai") {
+        res.end(JSON.stringify({
+            error: { message: "Invalid API key", type: "authentication_error", code: 401 },
+        }));
+    }
+    else {
+        res.end(JSON.stringify({ error: "Invalid API key" }));
+    }
+}
+export function sendRateLimitError(res, format) {
+    res.writeHead(429, { "Content-Type": "application/json" });
+    if (format === "openai") {
+        res.end(JSON.stringify({
+            error: { message: "Rate limit exceeded. Try again later.", type: "rate_limit_error", code: 429 },
+        }));
+    }
+    else {
+        res.end(JSON.stringify({ error: "Rate limit exceeded. Try again later." }));
+    }
+}

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

@@ -0,0 +1,110 @@
+import type { AgentResult } from "../types.js";
+export interface OpenAIContentPart {
+    type: "text" | "image_url";
+    text?: string;
+    image_url?: {
+        url: string;
+        detail?: string;
+    };
+}
+export interface OpenAIChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string | OpenAIContentPart[];
+}
+export interface OpenAIToolFunction {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+export interface OpenAITool {
+    type: "function";
+    function: OpenAIToolFunction;
+}
+export interface OpenAIChatRequest {
+    model?: string;
+    messages: OpenAIChatMessage[];
+    stream?: boolean;
+    temperature?: number;
+    max_tokens?: number;
+    response_format?: {
+        type: "text" | "json_object";
+    };
+    tools?: OpenAITool[];
+    tool_choice?: string | Record<string, unknown>;
+}
+export interface OpenAIChatResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        message: {
+            role: "assistant";
+            content: string;
+        };
+        finish_reason: "stop";
+    }>;
+    usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+export interface OpenAIStreamChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string;
+        };
+        finish_reason: string | null;
+    }>;
+}
+/**
+ * Convert OpenAI chat messages into a prompt string + systemPrompt
+ * for the otterly engine. Detects multimodal content.
+ */
+export declare function openaiToClaudeInput(body: OpenAIChatRequest): {
+    prompt: string;
+    systemPrompt: string | null;
+    isMultimodal: boolean;
+};
+/**
+ * Map OpenAI tools parameter to Claude Code allowedTools names.
+ * Level 1: treat tool function names as direct Claude Code tool name filters.
+ */
+export declare function openaiToolsToAllowedTools(tools: OpenAITool[]): string[];
+/**
+ * Build a non-streaming OpenAI chat completion response.
+ */
+export declare function claudeResultToOpenai(text: string, model: string, usage?: AgentResult["usage"]): OpenAIChatResponse;
+/**
+ * Build a streaming SSE chunk.
+ */
+export declare function makeStreamChunk(id: string, delta: {
+    role?: string;
+    content?: string;
+}, finishReason: string | null, model: string): OpenAIStreamChunk;
+/**
+ * Format a chunk as an SSE data line.
+ */
+export declare function sseData(obj: unknown): string;
+/**
+ * Map error to HTTP status code.
+ */
+export declare function errorToHttpStatus(err: unknown): number;
+/**
+ * Build an OpenAI-style error response body.
+ */
+export declare function openaiErrorBody(status: number, message: string): {
+    error: {
+        message: string;
+        type: string;
+        code: number;
+    };
+};

package/dist/server/openai-compat.js

@@ -0,0 +1,158 @@
+// OpenAI format <-> otterly format translation.
+// Pure functions, no I/O.
+import crypto from "crypto";
+// ── Conversion Functions ──
+/**
+ * Convert OpenAI chat messages into a prompt string + systemPrompt
+ * for the otterly engine. Detects multimodal content.
+ */
+export function openaiToClaudeInput(body) {
+    const messages = body.messages || [];
+    let systemPrompt = null;
+    const conversationParts = [];
+    let isMultimodal = false;
+    for (const msg of messages) {
+        if (msg.role === "system") {
+            systemPrompt = typeof msg.content === "string" ? msg.content : "";
+        }
+        else if (msg.role === "user") {
+            if (typeof msg.content === "string") {
+                conversationParts.push(msg.content);
+            }
+            else if (Array.isArray(msg.content)) {
+                // Multimodal content: extract text parts, note image presence
+                const textParts = [];
+                for (const part of msg.content) {
+                    if (part.type === "text" && part.text) {
+                        textParts.push(part.text);
+                    }
+                    else if (part.type === "image_url") {
+                        isMultimodal = true;
+                        textParts.push("[Image provided]");
+                    }
+                }
+                conversationParts.push(textParts.join("\n"));
+            }
+        }
+        else if (msg.role === "assistant") {
+            const text = typeof msg.content === "string" ? msg.content : "";
+            conversationParts.push(`[Previous assistant response]: ${text}`);
+        }
+    }
+    let prompt;
+    if (conversationParts.length <= 1) {
+        prompt = conversationParts[0] || "";
+    }
+    else {
+        const context = conversationParts.slice(0, -1).join("\n\n");
+        const lastMessage = conversationParts[conversationParts.length - 1];
+        prompt = `Previous conversation context:\n${context}\n\n---\n\nCurrent message:\n${lastMessage}`;
+    }
+    return { prompt, systemPrompt, isMultimodal };
+}
+/**
+ * Map OpenAI tools parameter to Claude Code allowedTools names.
+ * Level 1: treat tool function names as direct Claude Code tool name filters.
+ */
+export function openaiToolsToAllowedTools(tools) {
+    // Known Claude Code tool names
+    const KNOWN_TOOLS = new Set([
+        "Read", "Write", "Edit", "MultiEdit", "Bash", "Glob", "Grep",
+        "WebFetch", "WebSearch", "Task", "NotebookEdit", "AskUserQuestion",
+    ]);
+    const allowed = [];
+    for (const tool of tools) {
+        const name = tool.function?.name;
+        if (name && KNOWN_TOOLS.has(name)) {
+            allowed.push(name);
+        }
+    }
+    return allowed;
+}
+// ── Response Builders ──
+/**
+ * Build a non-streaming OpenAI chat completion response.
+ */
+export function claudeResultToOpenai(text, model, usage) {
+    const id = `chatcmpl-otterly-${crypto.randomUUID().slice(0, 12)}`;
+    const inputTokens = usage?.input_tokens || 0;
+    const outputTokens = usage?.output_tokens || 0;
+    return {
+        id,
+        object: "chat.completion",
+        created: Math.floor(Date.now() / 1000),
+        model: model || "claude-sonnet-4-20250514",
+        choices: [
+            {
+                index: 0,
+                message: { role: "assistant", content: text || "" },
+                finish_reason: "stop",
+            },
+        ],
+        usage: {
+            prompt_tokens: inputTokens,
+            completion_tokens: outputTokens,
+            total_tokens: inputTokens + outputTokens,
+        },
+    };
+}
+/**
+ * Build a streaming SSE chunk.
+ */
+export function makeStreamChunk(id, delta, finishReason, model) {
+    return {
+        id,
+        object: "chat.completion.chunk",
+        created: Math.floor(Date.now() / 1000),
+        model: model || "claude-sonnet-4-20250514",
+        choices: [
+            {
+                index: 0,
+                delta,
+                finish_reason: finishReason,
+            },
+        ],
+    };
+}
+/**
+ * Format a chunk as an SSE data line.
+ */
+export function sseData(obj) {
+    return `data: ${JSON.stringify(obj)}\n\n`;
+}
+/**
+ * Map error to HTTP status code.
+ */
+export function errorToHttpStatus(err) {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    if (msg.includes("anthropic_api_key") || msg.includes("authentication") || msg.includes("not_authenticated") || msg.includes("not logged in")) {
+        return 401;
+    }
+    if (msg.includes("rate_limit") || msg.includes("429"))
+        return 429;
+    if (msg.includes("billing") || msg.includes("402"))
+        return 402;
+    if (msg.includes("econnrefused") || msg.includes("fetch failed") || msg.includes("network"))
+        return 502;
+    if (msg.includes("abort"))
+        return 499;
+    return 500;
+}
+/**
+ * Build an OpenAI-style error response body.
+ */
+export function openaiErrorBody(status, message) {
+    const typeMap = {
+        401: "authentication_error",
+        429: "rate_limit_error",
+        402: "billing_error",
+        502: "network_error",
+    };
+    return {
+        error: {
+            message,
+            type: typeMap[status] || "server_error",
+            code: status,
+        },
+    };
+}

package/dist/server/request-queue.d.ts

@@ -0,0 +1,33 @@
+export interface QueueOptions {
+    maxConcurrent?: number;
+    maxQueueSize?: number;
+    queueTimeoutMs?: number;
+}
+export interface QueueStats {
+    running: number;
+    queued: number;
+    maxConcurrent: number;
+    maxQueueSize: number;
+    totalProcessed: number;
+    totalRejected: number;
+}
+export declare class RequestQueue {
+    private maxConcurrent;
+    private maxQueueSize;
+    private queueTimeoutMs;
+    private running;
+    private queue;
+    private totalProcessed;
+    private totalRejected;
+    constructor(opts?: QueueOptions);
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    stats(): QueueStats;
+    private acquire;
+    private release;
+}
+export declare class QueueFullError extends Error {
+    constructor();
+}
+export declare class QueueTimeoutError extends Error {
+    constructor();
+}

package/dist/server/request-queue.js

@@ -0,0 +1,79 @@
+// Semaphore-based concurrency limiter with bounded queue.
+// Prevents fork-bombing when many requests arrive simultaneously.
+export class RequestQueue {
+    maxConcurrent;
+    maxQueueSize;
+    queueTimeoutMs;
+    running = 0;
+    queue = [];
+    totalProcessed = 0;
+    totalRejected = 0;
+    constructor(opts = {}) {
+        this.maxConcurrent = opts.maxConcurrent ?? 5;
+        this.maxQueueSize = opts.maxQueueSize ?? 50;
+        this.queueTimeoutMs = opts.queueTimeoutMs ?? 30_000;
+    }
+    async run(fn) {
+        await this.acquire();
+        try {
+            const result = await fn();
+            this.totalProcessed++;
+            return result;
+        }
+        finally {
+            this.release();
+        }
+    }
+    stats() {
+        return {
+            running: this.running,
+            queued: this.queue.length,
+            maxConcurrent: this.maxConcurrent,
+            maxQueueSize: this.maxQueueSize,
+            totalProcessed: this.totalProcessed,
+            totalRejected: this.totalRejected,
+        };
+    }
+    acquire() {
+        if (this.running < this.maxConcurrent) {
+            this.running++;
+            return Promise.resolve();
+        }
+        if (this.queue.length >= this.maxQueueSize) {
+            this.totalRejected++;
+            return Promise.reject(new QueueFullError());
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const idx = this.queue.findIndex((e) => e.resolve === resolve);
+                if (idx !== -1)
+                    this.queue.splice(idx, 1);
+                this.totalRejected++;
+                reject(new QueueTimeoutError());
+            }, this.queueTimeoutMs);
+            this.queue.push({ resolve, reject, timer });
+        });
+    }
+    release() {
+        if (this.queue.length > 0) {
+            const next = this.queue.shift();
+            clearTimeout(next.timer);
+            next.resolve();
+        }
+        else {
+            this.running--;
+        }
+    }
+}
+export class QueueFullError extends Error {
+    constructor() {
+        super("Server is at capacity. Try again later.");
+        this.name = "QueueFullError";
+    }
+}
+export class QueueTimeoutError extends Error {
+    constructor() {
+        super("Request timed out waiting in queue.");
+        this.name = "QueueTimeoutError";
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { IncomingMessage, ServerResponse } from "http";
+import type { RequestQueue } from "./request-queue.js";
+import type { CircuitBreaker } from "./circuit-breaker.js";
+export interface ServerContext {
+    workingDir: string;
+    apiKey: string | null;
+}
+export interface ParsedRequest extends IncomingMessage {
+    body?: Record<string, unknown>;
+    requestId?: string;
+    startTime?: number;
+    timeoutSignal?: AbortSignal;
+}
+/**
+ * GET /api/status — health check with queue and circuit breaker stats
+ */
+export declare function handleStatus(_req: IncomingMessage, res: ServerResponse, queue?: RequestQueue, circuitBreaker?: CircuitBreaker): void;
+/**
+ * POST /api/run — one-shot execution, returns full result.
+ * Supports session reuse via X-Session-Id header or session_id in body.
+ */
+export declare function handleRun(req: ParsedRequest, res: ServerResponse, ctx: ServerContext, circuitBreaker?: CircuitBreaker): Promise<void>;
+/**
+ * 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 declare function handleStream(req: ParsedRequest, res: ServerResponse, ctx: ServerContext, circuitBreaker?: CircuitBreaker): Promise<void>;