otterly 0.1.0

package/dist/events.js

@@ -0,0 +1,168 @@
+export function createEventContext() {
+    return {
+        sessionId: null,
+        toolNames: new Map(),
+        accumulatedText: "",
+    };
+}
+/**
+ * Normalize a raw SDK message into clean AgentEvent(s).
+ * Returns an array because one SDK message can contain multiple content blocks.
+ */
+export function normalizeEvents(raw, ctx) {
+    const type = raw.type;
+    const events = [];
+    switch (type) {
+        case "system": {
+            if (raw.subtype === "init") {
+                const sessionId = raw.session_id;
+                ctx.sessionId = sessionId;
+                events.push({
+                    type: "system",
+                    sessionId,
+                    model: raw.model || "",
+                    cwd: raw.cwd || "",
+                    tools: raw.tools || [],
+                });
+            }
+            break;
+        }
+        case "assistant": {
+            const message = raw.message;
+            const content = (message?.content || []);
+            for (const block of content) {
+                if (block.type === "text") {
+                    events.push({
+                        type: "text",
+                        text: block.text,
+                    });
+                }
+                else if (block.type === "tool_use") {
+                    const id = block.id;
+                    const name = block.name;
+                    const input = (block.input || {});
+                    ctx.toolNames.set(id, name);
+                    events.push({
+                        type: "tool_use",
+                        id,
+                        tool: name,
+                        input,
+                        description: describeToolUse(name, input),
+                    });
+                }
+            }
+            break;
+        }
+        case "user": {
+            if (raw.tool_use_result !== undefined) {
+                const message = raw.message;
+                const content = (message?.content || []);
+                for (const block of content) {
+                    if (block.type === "tool_result") {
+                        const toolUseId = block.tool_use_id;
+                        events.push({
+                            type: "tool_result",
+                            toolUseId,
+                            tool: ctx.toolNames.get(toolUseId) || "unknown",
+                            output: extractToolResultText(block.content),
+                            isError: block.is_error || false,
+                        });
+                    }
+                }
+            }
+            break;
+        }
+        case "stream_event": {
+            const event = raw.event;
+            if (!event)
+                break;
+            if (event.type === "content_block_delta") {
+                const delta = event.delta;
+                if (delta?.type === "text_delta") {
+                    const text = delta.text;
+                    ctx.accumulatedText += text;
+                    events.push({
+                        type: "text_delta",
+                        delta: text,
+                    });
+                }
+            }
+            break;
+        }
+        case "result": {
+            if (raw.subtype === "success") {
+                events.push({
+                    type: "result",
+                    text: raw.result || "",
+                    cost: raw.total_cost_usd || 0,
+                    duration: raw.duration_ms || 0,
+                    sessionId: ctx.sessionId || "",
+                    usage: raw.usage || {
+                        input_tokens: 0,
+                        output_tokens: 0,
+                    },
+                });
+            }
+            else {
+                const errors = raw.errors;
+                const msg = errors ? errors.join("\n") : `Stopped: ${raw.subtype}`;
+                events.push({
+                    type: "error",
+                    error: new Error(msg),
+                });
+            }
+            break;
+        }
+    }
+    return events;
+}
+function truncate(str, max) {
+    return str.length > max ? str.slice(0, max) + "..." : str;
+}
+export function describeToolUse(name, input) {
+    switch (name) {
+        case "Read":
+            return `Reading file: ${input.file_path || "unknown"}`;
+        case "Write":
+            return `Writing file: ${input.file_path || "unknown"}`;
+        case "Edit":
+            return `Editing file: ${input.file_path || "unknown"}`;
+        case "MultiEdit":
+            return `Editing file: ${input.file_path || "unknown"}`;
+        case "Bash":
+            return `Running command: ${truncate(String(input.command || ""), 80)}`;
+        case "Glob":
+            return `Searching for files: ${input.pattern || ""}`;
+        case "Grep":
+            return `Searching content: ${truncate(String(input.pattern || ""), 60)}`;
+        case "WebFetch":
+            return `Fetching: ${input.url || ""}`;
+        case "WebSearch":
+            return `Searching: ${input.query || ""}`;
+        case "Task":
+            return `Running sub-task: ${input.description || ""}`;
+        case "NotebookEdit":
+            return `Editing notebook: ${input.notebook_path || "unknown"}`;
+        default:
+            return `Using tool: ${name}`;
+    }
+}
+function extractToolResultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((c) => {
+            if (typeof c === "string")
+                return c;
+            if (typeof c === "object" && c !== null && "type" in c) {
+                const obj = c;
+                if (obj.type === "text")
+                    return obj.text;
+            }
+            return JSON.stringify(c);
+        })
+            .join("\n");
+    }
+    return JSON.stringify(content);
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { ClaudeEngine } from "./engine.js";
+export { Session } from "./session.js";
+export { AUTOPILOT, READONLY } from "./permissions.js";
+export { AgentError, classifyError } from "./errors.js";
+export type { ErrorCode } from "./errors.js";
+export { describeToolUse } from "./events.js";
+export type { EngineOptions, PermissionMode, ToolRequest, PermissionDecision, PermissionHandler, TextEvent, TextDeltaEvent, ToolUseEvent, ToolResultEvent, SystemEvent, ErrorEvent, ResultEvent, AgentEvent, ToolExecution, AgentResult, } from "./types.js";
+export { startApiServer } from "./server/index.js";
+export type { ApiServerOptions, ApiServerHandle } from "./server/index.js";
+import { ClaudeEngine } from "./engine.js";
+/** Pre-instantiated default engine. Import and use directly. */
+export declare const claude: ClaudeEngine;

package/dist/index.js

@@ -0,0 +1,10 @@
+export { ClaudeEngine } from "./engine.js";
+export { Session } from "./session.js";
+export { AUTOPILOT, READONLY } from "./permissions.js";
+export { AgentError, classifyError } from "./errors.js";
+export { describeToolUse } from "./events.js";
+// Server exports
+export { startApiServer } from "./server/index.js";
+import { ClaudeEngine } from "./engine.js";
+/** Pre-instantiated default engine. Import and use directly. */
+export const claude = new ClaudeEngine();

package/dist/permissions.d.ts

@@ -0,0 +1,16 @@
+import type { PermissionHandler } from "./types.js";
+/** Always allow everything. Used internally when permissionMode is "bypassPermissions". */
+export declare const AUTOPILOT: PermissionHandler;
+/** Allow read-only tools, deny anything that modifies files or runs commands. */
+export declare const READONLY: PermissionHandler;
+/**
+ * Wrap our simple PermissionHandler into the SDK's canUseTool callback shape.
+ *
+ * SDK expects: (toolName, input, options) => { behavior, updatedInput?, message? }
+ * We accept: ({ tool, input, reason }) => { allow, updatedInput?, message? }
+ */
+export declare function wrapPermissionHandler(handler: PermissionHandler): (toolName: string, input: Record<string, unknown>, options: Record<string, unknown>) => Promise<{
+    behavior: string;
+    updatedInput?: Record<string, unknown>;
+    message?: string;
+}>;

package/dist/permissions.js

@@ -0,0 +1,43 @@
+/** Always allow everything. Used internally when permissionMode is "bypassPermissions". */
+export const AUTOPILOT = () => ({ allow: true });
+const READ_ONLY_TOOLS = new Set([
+    "Read",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "WebSearch",
+    "Task",
+    "AskUserQuestion",
+]);
+/** Allow read-only tools, deny anything that modifies files or runs commands. */
+export const READONLY = ({ tool }) => {
+    if (READ_ONLY_TOOLS.has(tool)) {
+        return { allow: true };
+    }
+    return { allow: false, message: `Read-only mode: ${tool} is not allowed` };
+};
+/**
+ * Wrap our simple PermissionHandler into the SDK's canUseTool callback shape.
+ *
+ * SDK expects: (toolName, input, options) => { behavior, updatedInput?, message? }
+ * We accept: ({ tool, input, reason }) => { allow, updatedInput?, message? }
+ */
+export function wrapPermissionHandler(handler) {
+    return async (toolName, input, options) => {
+        const decision = await handler({
+            tool: toolName,
+            input,
+            reason: options.decisionReason || undefined,
+        });
+        if (decision.allow) {
+            return {
+                behavior: "allow",
+                updatedInput: decision.updatedInput || input,
+            };
+        }
+        return {
+            behavior: "deny",
+            message: decision.message || "Denied by permission handler",
+        };
+    };
+}

package/dist/server/circuit-breaker.d.ts

@@ -0,0 +1,20 @@
+export type CircuitState = "closed" | "open" | "half-open";
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    cooldownMs?: number;
+}
+export declare class CircuitBreaker {
+    private state;
+    private consecutiveFailures;
+    private failureThreshold;
+    private cooldownMs;
+    private lastFailureTime;
+    constructor(opts?: CircuitBreakerOptions);
+    /** Check if request should proceed. Returns true if allowed. */
+    canProceed(): boolean;
+    /** Record a successful execution. */
+    onSuccess(): void;
+    /** Record a failure. Pass the error code from AgentError if available. */
+    onFailure(errorCode?: string): void;
+    getState(): CircuitState;
+}

package/dist/server/circuit-breaker.js

@@ -0,0 +1,54 @@
+// Circuit breaker: protects against cascading failures when the upstream API is down.
+// States: closed (normal) → open (failing, reject fast) → half-open (probe) → closed
+const TRIPPABLE_CODES = new Set(["NETWORK", "RATE_LIMITED"]);
+export class CircuitBreaker {
+    state = "closed";
+    consecutiveFailures = 0;
+    failureThreshold;
+    cooldownMs;
+    lastFailureTime = 0;
+    constructor(opts = {}) {
+        this.failureThreshold = opts.failureThreshold ?? 5;
+        this.cooldownMs = opts.cooldownMs ?? 30_000;
+    }
+    /** Check if request should proceed. Returns true if allowed. */
+    canProceed() {
+        if (this.state === "closed")
+            return true;
+        if (this.state === "open") {
+            // Check if cooldown has elapsed
+            if (Date.now() - this.lastFailureTime >= this.cooldownMs) {
+                this.state = "half-open";
+                return true; // allow one probe
+            }
+            return false;
+        }
+        // half-open: already allowing the probe, block others
+        return false;
+    }
+    /** Record a successful execution. */
+    onSuccess() {
+        this.consecutiveFailures = 0;
+        if (this.state === "half-open") {
+            this.state = "closed";
+        }
+    }
+    /** Record a failure. Pass the error code from AgentError if available. */
+    onFailure(errorCode) {
+        // Only trip on network/rate-limit errors, not auth or user errors
+        if (errorCode && !TRIPPABLE_CODES.has(errorCode))
+            return;
+        this.consecutiveFailures++;
+        this.lastFailureTime = Date.now();
+        if (this.state === "half-open") {
+            this.state = "open";
+            return;
+        }
+        if (this.consecutiveFailures >= this.failureThreshold) {
+            this.state = "open";
+        }
+    }
+    getState() {
+        return this.state;
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,19 @@
+import { type Server } from "http";
+import { WebSocketServer } from "ws";
+export interface ApiServerOptions {
+    port?: number;
+    workingDir?: string;
+    maxConcurrent?: number;
+    maxQueueSize?: number;
+    requestsPerMinute?: number;
+    requestTimeoutMs?: number;
+    streamTimeoutMs?: number;
+}
+export interface ApiServerHandle {
+    server: Server;
+    wss: WebSocketServer;
+    port: number;
+    close(): void;
+    shutdown(timeoutMs?: number): Promise<void>;
+}
+export declare function startApiServer(opts?: ApiServerOptions): Promise<ApiServerHandle>;

package/dist/server/index.js

@@ -0,0 +1,275 @@
+// API server: HTTP + WebSocket, no Express.
+// Mounts OpenAI-compatible and native routes on raw http.createServer.
+// Includes: middleware chain, request queue, timeouts, logging, graceful shutdown.
+import { createServer } from "http";
+import { WebSocketServer } from "ws";
+import { handleChatCompletions } from "./routes-openai.js";
+import { handleStatus, handleRun, handleStream } from "./routes-native.js";
+import { attachWsHandler } from "./ws-handler.js";
+import { apiSessions } from "./session-store.js";
+import { RequestQueue, QueueFullError, QueueTimeoutError } from "./request-queue.js";
+import { checkAuth, RateLimiter, sendAuthError, sendRateLimitError } from "./middleware.js";
+import { generateRequestId, logRequest, logResponse, logError } from "./logger.js";
+import { CircuitBreaker } from "./circuit-breaker.js";
+/**
+ * Parse JSON body from an incoming request. Returns parsed object or null on failure.
+ */
+function parseBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let size = 0;
+        const MAX = 20 * 1024 * 1024; // 20MB
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX) {
+                req.destroy();
+                resolve(null);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (chunks.length === 0) {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString()));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        req.on("error", () => resolve(null));
+    });
+}
+function jsonResponse(res, status, body) {
+    if (!res.headersSent) {
+        res.writeHead(status, { "Content-Type": "application/json" });
+    }
+    res.end(JSON.stringify(body));
+}
+function setCors(res) {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Session-Id");
+}
+export async function startApiServer(opts = {}) {
+    const port = opts.port ?? 11434;
+    const workingDir = opts.workingDir ?? process.cwd();
+    const apiKey = process.env.OTTERLY_API_KEY || null;
+    const requestTimeoutMs = opts.requestTimeoutMs ?? 5 * 60 * 1000; // 5 min one-shot
+    const streamTimeoutMs = opts.streamTimeoutMs ?? 10 * 60 * 1000; // 10 min streaming
+    const ctx = { workingDir, apiKey };
+    const queue = new RequestQueue({
+        maxConcurrent: opts.maxConcurrent,
+        maxQueueSize: opts.maxQueueSize,
+    });
+    const rateLimiter = new RateLimiter({ requestsPerMinute: opts.requestsPerMinute });
+    const circuitBreaker = new CircuitBreaker();
+    // Track in-flight requests for graceful shutdown
+    let inFlight = 0;
+    let shuttingDown = false;
+    let drainResolve = null;
+    const server = createServer(async (req, res) => {
+        const requestId = generateRequestId();
+        const startTime = Date.now();
+        res.setHeader("X-Request-Id", requestId);
+        setCors(res);
+        const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+        const path = url.pathname;
+        // Log request start for POST requests
+        if (req.method === "POST") {
+            logRequest(requestId, req.method, path);
+        }
+        // Preflight
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Reject new requests during shutdown
+        if (shuttingDown && req.method === "POST") {
+            jsonResponse(res, 503, { error: "Server is shutting down" });
+            return;
+        }
+        // GET /api/status — no auth, no rate limit, no queue
+        if (req.method === "GET" && path === "/api/status") {
+            handleStatus(req, res, queue, circuitBreaker);
+            return;
+        }
+        // ── POST routes: auth → rate limit → circuit breaker → queue ──
+        if (req.method !== "POST") {
+            jsonResponse(res, 404, { error: "Not found" });
+            return;
+        }
+        const isOpenai = path === "/v1/chat/completions";
+        const format = isOpenai ? "openai" : "native";
+        // Auth
+        if (!checkAuth(req, ctx)) {
+            sendAuthError(res, format);
+            logResponse(requestId, req.method, path, 401, Date.now() - startTime);
+            return;
+        }
+        // Rate limit
+        if (!rateLimiter.allow(rateLimiter.keyFor(req))) {
+            sendRateLimitError(res, format);
+            logResponse(requestId, req.method, path, 429, Date.now() - startTime);
+            return;
+        }
+        // Circuit breaker
+        if (!circuitBreaker.canProceed()) {
+            const status = 503;
+            jsonResponse(res, status, isOpenai
+                ? { error: { message: "Service temporarily unavailable", type: "server_error", code: status } }
+                : { error: "Service temporarily unavailable" });
+            logResponse(requestId, req.method, path, status, Date.now() - startTime);
+            return;
+        }
+        // Parse body
+        const parsed = req;
+        parsed.body = await parseBody(req) ?? undefined;
+        if (parsed.body === undefined) {
+            const status = 400;
+            jsonResponse(res, status, isOpenai
+                ? { error: { message: "Invalid JSON body", type: "invalid_request_error" } }
+                : { error: "Invalid JSON body" });
+            logResponse(requestId, req.method, path, status, Date.now() - startTime);
+            return;
+        }
+        // Attach requestId and timing context for route handlers
+        parsed.requestId = requestId;
+        parsed.startTime = startTime;
+        // Determine if streaming (affects timeout)
+        const isStream = path === "/api/stream"
+            || (isOpenai && parsed.body?.stream === true);
+        const timeoutMs = isStream ? streamTimeoutMs : requestTimeoutMs;
+        // Queue + execute with timeout
+        try {
+            await queue.run(async () => {
+                inFlight++;
+                try {
+                    await withTimeout(timeoutMs, parsed, async () => {
+                        if (isOpenai) {
+                            await handleChatCompletions(parsed, res, ctx, circuitBreaker);
+                        }
+                        else if (path === "/api/run") {
+                            await handleRun(parsed, res, ctx, circuitBreaker);
+                        }
+                        else if (path === "/api/stream") {
+                            await handleStream(parsed, res, ctx, circuitBreaker);
+                        }
+                        else {
+                            jsonResponse(res, 404, { error: "Not found" });
+                        }
+                    });
+                }
+                finally {
+                    inFlight--;
+                    const status = res.statusCode || 200;
+                    logResponse(requestId, req.method, path, status, Date.now() - startTime);
+                    if (inFlight === 0 && drainResolve)
+                        drainResolve();
+                }
+            });
+        }
+        catch (err) {
+            if (err instanceof QueueFullError) {
+                jsonResponse(res, 429, isOpenai
+                    ? { error: { message: err.message, type: "rate_limit_error", code: 429 } }
+                    : { error: err.message });
+                logResponse(requestId, req.method, path, 429, Date.now() - startTime);
+            }
+            else if (err instanceof QueueTimeoutError) {
+                jsonResponse(res, 408, isOpenai
+                    ? { error: { message: err.message, type: "timeout_error", code: 408 } }
+                    : { error: err.message });
+                logResponse(requestId, req.method, path, 408, Date.now() - startTime);
+            }
+            else if (!res.headersSent) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logError(requestId, msg);
+                jsonResponse(res, 500, isOpenai
+                    ? { error: { message: "Internal server error", type: "server_error", code: 500 } }
+                    : { error: "Internal server error" });
+            }
+        }
+    });
+    // Node built-in timeouts (safety net)
+    server.requestTimeout = 15 * 60 * 1000; // 15 min absolute max
+    server.headersTimeout = 30 * 1000; // 30s to receive headers
+    // WebSocket on /ws path
+    const wss = new WebSocketServer({ server, path: "/ws" });
+    attachWsHandler(wss, { workingDir });
+    async function shutdown(timeoutMs = 10_000) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log("\nShutting down gracefully...");
+        // Stop accepting new connections
+        server.close();
+        wss.close();
+        // Wait for in-flight to drain or timeout
+        if (inFlight > 0) {
+            console.log(`Waiting for ${inFlight} in-flight request(s)...`);
+            await Promise.race([
+                new Promise((resolve) => { drainResolve = resolve; }),
+                new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+            ]);
+        }
+        // Clean up
+        rateLimiter.destroy();
+        apiSessions.destroy();
+        console.log("Shutdown complete.");
+    }
+    return new Promise((resolve, reject) => {
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                console.error(`Port ${port} is in use. Try a different port with -p <port>.`);
+            }
+            reject(err);
+        });
+        server.listen(port, () => {
+            console.log(`\n  otterly serve — local inference server`);
+            console.log(`  ──────────────────────────────────────`);
+            console.log(`  OpenAI compat : http://localhost:${port}/v1/chat/completions`);
+            console.log(`  Native API    : http://localhost:${port}/api/run`);
+            console.log(`  Streaming     : http://localhost:${port}/api/stream`);
+            console.log(`  WebSocket     : ws://localhost:${port}/ws`);
+            console.log(`  Health        : http://localhost:${port}/api/status`);
+            console.log(`  Working dir   : ${workingDir}`);
+            if (apiKey) {
+                console.log(`  Auth          : API key required (OTTERLY_API_KEY)`);
+            }
+            else {
+                console.log(`  Auth          : none (set OTTERLY_API_KEY to enable)`);
+            }
+            console.log();
+            resolve({
+                server,
+                wss,
+                port,
+                close() {
+                    rateLimiter.destroy();
+                    apiSessions.destroy();
+                    wss.close();
+                    server.close();
+                },
+                shutdown,
+            });
+        });
+    });
+}
+/** Run a handler with an execution timeout. Aborts via the request's AbortController pattern. */
+async function withTimeout(timeoutMs, req, fn) {
+    // Attach a timeout abort controller that route handlers can pick up
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(), timeoutMs);
+    req.timeoutSignal = timeoutController.signal;
+    try {
+        await fn();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/server/logger.d.ts

@@ -0,0 +1,18 @@
+export type LogLevel = "info" | "warn" | "error";
+interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    requestId?: string;
+    method?: string;
+    path?: string;
+    status?: number;
+    durationMs?: number;
+    message?: string;
+    [key: string]: unknown;
+}
+export declare function generateRequestId(): string;
+export declare function log(level: LogLevel, fields: Omit<LogEntry, "timestamp" | "level">): void;
+export declare function logRequest(requestId: string, method: string, path: string): void;
+export declare function logResponse(requestId: string, method: string, path: string, status: number, durationMs: number): void;
+export declare function logError(requestId: string, message: string, extra?: Record<string, unknown>): void;
+export {};

package/dist/server/logger.js

@@ -0,0 +1,22 @@
+// Structured JSON logger. Writes JSON lines to stdout.
+import crypto from "crypto";
+export function generateRequestId() {
+    return crypto.randomUUID().slice(0, 8);
+}
+export function log(level, fields) {
+    const entry = {
+        timestamp: new Date().toISOString(),
+        level,
+        ...fields,
+    };
+    process.stdout.write(JSON.stringify(entry) + "\n");
+}
+export function logRequest(requestId, method, path) {
+    log("info", { requestId, method, path, message: "request_start" });
+}
+export function logResponse(requestId, method, path, status, durationMs) {
+    log("info", { requestId, method, path, status, durationMs, message: "request_end" });
+}
+export function logError(requestId, message, extra) {
+    log("error", { requestId, message, ...extra });
+}