otterly 0.1.0

package/dist/server/ws-handler.js

@@ -0,0 +1,155 @@
+// WebSocket handler for /ws — multi-turn sessions.
+// Each connection gets its own otterly Session.
+// Includes heartbeats: ping/pong with 30s interval, 10s timeout.
+import crypto from "crypto";
+import { ClaudeEngine } from "../engine.js";
+import { apiSessions } from "./session-store.js";
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+/**
+ * Attach WebSocket handling to a WebSocketServer for the API server.
+ */
+export function attachWsHandler(wss, ctx) {
+    // Heartbeat sweep: ping all connections every 30s
+    const heartbeatInterval = setInterval(() => {
+        for (const ws of wss.clients) {
+            const extWs = ws;
+            const state = extWs._otterlyState;
+            if (state && !state.isAlive) {
+                // No pong received since last ping — terminate
+                ws.terminate();
+                continue;
+            }
+            if (state) {
+                state.isAlive = false;
+            }
+            ws.ping();
+        }
+    }, HEARTBEAT_INTERVAL_MS);
+    heartbeatInterval.unref();
+    wss.on("close", () => {
+        clearInterval(heartbeatInterval);
+    });
+    wss.on("connection", (ws) => {
+        const connId = crypto.randomUUID().slice(0, 8);
+        const state = {
+            session: null,
+            engine: new ClaudeEngine({ cwd: ctx.workingDir, permissionMode: "bypassPermissions" }),
+            isAlive: true,
+        };
+        // Attach state to ws for heartbeat access
+        ws._otterlyState = state;
+        apiSessions.create(connId, { state });
+        function send(obj) {
+            if (ws.readyState === 1) {
+                ws.send(JSON.stringify(obj));
+            }
+        }
+        // Pong handler: mark connection as alive
+        ws.on("pong", () => {
+            state.isAlive = true;
+        });
+        ws.on("message", async (raw) => {
+            state.isAlive = true; // any message counts as alive
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString());
+            }
+            catch {
+                send({ kind: "error", code: "INVALID_JSON", message: "Invalid JSON" });
+                return;
+            }
+            if (msg.type === "chat") {
+                await handleChat(msg, state, send, ctx);
+            }
+            else if (msg.type === "cancel") {
+                if (state.session) {
+                    state.session.close();
+                    state.session = null;
+                }
+                send({ kind: "status", status: "ready" });
+            }
+            else if (msg.type === "resume") {
+                // Close existing session and create new one with resume
+                if (state.session) {
+                    state.session.close();
+                }
+                const opts = {
+                    cwd: ctx.workingDir,
+                    permissionMode: "bypassPermissions",
+                };
+                if (msg.sessionId) {
+                    opts.resume = msg.sessionId;
+                }
+                state.session = state.engine.session(opts);
+                send({ kind: "status", status: "ready" });
+            }
+            else if (msg.type === "new_session") {
+                if (state.session) {
+                    state.session.close();
+                    state.session = null;
+                }
+                send({ kind: "status", status: "ready" });
+            }
+        });
+        ws.on("close", () => {
+            if (state.session) {
+                state.session.close();
+                state.session = null;
+            }
+            apiSessions.delete(connId);
+        });
+    });
+}
+async function handleChat(msg, state, send, ctx) {
+    const text = msg.text || "";
+    if (!text) {
+        send({ kind: "error", code: "EMPTY_MESSAGE", message: "text is required" });
+        return;
+    }
+    // Create session if not exists
+    if (!state.session) {
+        const opts = {
+            cwd: msg.options?.cwd || ctx.workingDir,
+            permissionMode: msg.options?.permissionMode || "bypassPermissions",
+        };
+        if (msg.options?.systemPrompt)
+            opts.systemPrompt = msg.options.systemPrompt;
+        if (msg.options?.model)
+            opts.model = msg.options.model;
+        state.session = state.engine.session(opts);
+    }
+    send({ kind: "status", status: "thinking" });
+    try {
+        for await (const event of state.session.sendStream(text)) {
+            const payload = eventToWsPayload(event);
+            if (payload)
+                send(payload);
+        }
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        send({ kind: "error", code: "UNKNOWN", message: e.message });
+    }
+    send({ kind: "status", status: "ready" });
+}
+function eventToWsPayload(event) {
+    switch (event.type) {
+        case "system":
+            return { kind: "session_init", sessionId: event.sessionId, model: event.model };
+        case "text_delta":
+            return { kind: "text_delta", delta: event.delta };
+        case "text":
+            return { kind: "text", text: event.text };
+        case "tool_use":
+            return { kind: "tool_use", id: event.id, tool: event.tool, input: event.input, description: event.description };
+        case "tool_result":
+            return { kind: "tool_result", toolUseId: event.toolUseId, tool: event.tool, output: event.output, isError: event.isError };
+        case "result":
+            return { kind: "result", text: event.text, cost: event.cost, duration: event.duration, sessionId: event.sessionId, usage: event.usage };
+        case "error":
+            return { kind: "error", code: "EXECUTION_ERROR", message: event.error.message };
+        default:
+            return null;
+    }
+}

package/dist/session.d.ts

@@ -0,0 +1,43 @@
+import type { AgentEvent, AgentResult, EngineOptions } from "./types.js";
+type QueryFn = (args: {
+    prompt: unknown;
+    options: Record<string, unknown>;
+}) => AsyncIterable<Record<string, unknown>>;
+/**
+ * Multi-turn session that keeps conversation context alive across send() calls.
+ *
+ * Uses the SDK's streaming input mode: an async generator yields user messages
+ * on demand, and the SDK processes them within one long-lived query() call.
+ *
+ * Internally, the SDK iteration runs in the background. Events are queued and
+ * pulled by sendStream(). After a result event, sendStream() returns but the
+ * background loop continues — allowing the SDK to call prompt.next() and await
+ * the next user message.
+ */
+export declare class Session {
+    private options;
+    private queryFn;
+    private messageResolve;
+    private abortController;
+    private ctx;
+    private _sessionId;
+    private closed;
+    private started;
+    private eventQueue;
+    private eventWaiter;
+    private backgroundDone;
+    private backgroundError;
+    constructor(queryFn: QueryFn, options: EngineOptions);
+    /** Session ID from the SDK. Available after first send(). */
+    get id(): string | null;
+    /** Send a message and collect the full result. */
+    send(prompt: string): Promise<AgentResult>;
+    /** Send a message and stream events. */
+    sendStream(prompt: string): AsyncGenerator<AgentEvent>;
+    /** End the session and clean up. */
+    close(): void;
+    private pushEvent;
+    private pullEvent;
+    private startBackground;
+}
+export {};

package/dist/session.js

@@ -0,0 +1,255 @@
+import { normalizeEvents, createEventContext } from "./events.js";
+import { classifyError, AgentError } from "./errors.js";
+import { wrapPermissionHandler } from "./permissions.js";
+/**
+ * Multi-turn session that keeps conversation context alive across send() calls.
+ *
+ * Uses the SDK's streaming input mode: an async generator yields user messages
+ * on demand, and the SDK processes them within one long-lived query() call.
+ *
+ * Internally, the SDK iteration runs in the background. Events are queued and
+ * pulled by sendStream(). After a result event, sendStream() returns but the
+ * background loop continues — allowing the SDK to call prompt.next() and await
+ * the next user message.
+ */
+export class Session {
+    options;
+    queryFn;
+    messageResolve = null;
+    abortController;
+    ctx;
+    _sessionId = null;
+    closed = false;
+    started = false;
+    // Event queue: background iteration pushes events, sendStream() pulls them
+    eventQueue = [];
+    eventWaiter = null;
+    backgroundDone = false;
+    backgroundError = null;
+    constructor(queryFn, options) {
+        this.queryFn = queryFn;
+        this.options = options;
+        this.abortController = new AbortController();
+        this.ctx = createEventContext();
+        if (options.signal) {
+            options.signal.addEventListener("abort", () => this.abortController.abort());
+        }
+    }
+    /** Session ID from the SDK. Available after first send(). */
+    get id() {
+        return this._sessionId;
+    }
+    /** Send a message and collect the full result. */
+    async send(prompt) {
+        const tools = [];
+        let resultText = "";
+        let cost = 0;
+        let duration = 0;
+        let sessionId = "";
+        let usage = { input_tokens: 0, output_tokens: 0 };
+        const pendingToolUses = new Map();
+        for await (const event of this.sendStream(prompt)) {
+            switch (event.type) {
+                case "text":
+                    resultText = event.text;
+                    break;
+                case "tool_use":
+                    pendingToolUses.set(event.id, { tool: event.tool, input: event.input });
+                    break;
+                case "tool_result": {
+                    const pending = pendingToolUses.get(event.toolUseId);
+                    tools.push({
+                        tool: pending?.tool || event.tool,
+                        input: pending?.input || {},
+                        output: event.output,
+                        isError: event.isError,
+                    });
+                    pendingToolUses.delete(event.toolUseId);
+                    break;
+                }
+                case "result":
+                    resultText = event.text || resultText;
+                    cost = event.cost;
+                    duration = event.duration;
+                    sessionId = event.sessionId;
+                    usage = event.usage;
+                    break;
+                case "error":
+                    throw event.error instanceof AgentError
+                        ? event.error
+                        : classifyError(event.error);
+            }
+        }
+        return { text: resultText, cost, duration, sessionId, usage, tools };
+    }
+    /** Send a message and stream events. */
+    async *sendStream(prompt) {
+        if (this.closed) {
+            throw new AgentError("ABORTED", "Session has been closed.");
+        }
+        if (!this.started) {
+            // First call: start the query with the prompt baked into the message stream
+            this.started = true;
+            this.startBackground(prompt);
+        }
+        else {
+            // Subsequent calls: feed the message into the running generator
+            if (!this.messageResolve) {
+                // Wait a tick — the background loop may be about to set messageResolve
+                await new Promise((r) => setTimeout(r, 0));
+            }
+            if (!this.messageResolve) {
+                throw new AgentError("UNKNOWN", "Session is busy processing. Wait for the previous send() to complete.");
+            }
+            this.messageResolve({
+                type: "user",
+                message: { role: "user", content: prompt },
+            });
+            this.messageResolve = null;
+        }
+        // Pull events from the queue until we get a result or error
+        while (true) {
+            const event = await this.pullEvent();
+            if (event === null)
+                break;
+            if (event.type === "system") {
+                this._sessionId = event.sessionId;
+            }
+            yield event;
+            if (event.type === "result" || event.type === "error") {
+                return;
+            }
+        }
+    }
+    /** End the session and clean up. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.messageResolve) {
+            this.messageResolve(null);
+            this.messageResolve = null;
+        }
+        this.abortController.abort();
+        this.backgroundDone = true;
+        // Unblock any pending pullEvent()
+        if (this.eventWaiter) {
+            this.eventWaiter(null);
+            this.eventWaiter = null;
+        }
+    }
+    pushEvent(event) {
+        if (this.eventWaiter) {
+            const waiter = this.eventWaiter;
+            this.eventWaiter = null;
+            waiter(event);
+        }
+        else if (event !== null) {
+            this.eventQueue.push(event);
+        }
+    }
+    pullEvent() {
+        if (this.eventQueue.length > 0) {
+            return Promise.resolve(this.eventQueue.shift());
+        }
+        if (this.backgroundDone) {
+            if (this.backgroundError) {
+                return Promise.reject(classifyError(this.backgroundError));
+            }
+            return Promise.resolve(null);
+        }
+        return new Promise((resolve) => {
+            this.eventWaiter = resolve;
+        });
+    }
+    startBackground(firstPrompt) {
+        const self = this;
+        async function* messageStream() {
+            yield {
+                type: "user",
+                message: { role: "user", content: firstPrompt },
+            };
+            while (true) {
+                const msg = await new Promise((resolve) => {
+                    self.messageResolve = resolve;
+                });
+                if (msg === null)
+                    return;
+                yield msg;
+            }
+        }
+        const queryOptions = {
+            abortController: this.abortController,
+            cwd: this.options.cwd || process.cwd(),
+            permissionMode: this.options.permissionMode || "bypassPermissions",
+            includePartialMessages: true,
+        };
+        if (this.options.model)
+            queryOptions.model = this.options.model;
+        if (this.options.maxTurns)
+            queryOptions.maxTurns = this.options.maxTurns;
+        if (this.options.allowedTools)
+            queryOptions.allowedTools = this.options.allowedTools;
+        if (this.options.disallowedTools)
+            queryOptions.disallowedTools = this.options.disallowedTools;
+        if (this.options.mcpServers)
+            queryOptions.mcpServers = this.options.mcpServers;
+        if (this.options.effort)
+            queryOptions.effort = this.options.effort;
+        if (this.options.resume)
+            queryOptions.resume = this.options.resume;
+        if (this.options.systemPrompt)
+            queryOptions.systemPrompt = this.options.systemPrompt;
+        if (this.options.onPermission) {
+            queryOptions.permissionMode = "default";
+            queryOptions.canUseTool = wrapPermissionHandler(this.options.onPermission);
+        }
+        // Run the iteration in the background — push events to the queue
+        (async () => {
+            let queryInstance;
+            try {
+                queryInstance = this.queryFn({
+                    prompt: messageStream(),
+                    options: queryOptions,
+                });
+            }
+            catch (err) {
+                this.backgroundError = err instanceof Error ? err : new Error(String(err));
+                this.pushEvent({
+                    type: "error",
+                    error: classifyError(this.backgroundError),
+                });
+                this.backgroundDone = true;
+                this.pushEvent(null);
+                return;
+            }
+            try {
+                for await (const raw of queryInstance) {
+                    if (this.abortController.signal.aborted)
+                        break;
+                    const events = normalizeEvents(raw, this.ctx);
+                    for (const event of events) {
+                        this.pushEvent(event);
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof Error &&
+                    (err.name === "AbortError" || this.abortController.signal.aborted)) {
+                    // Cancelled — don't push error
+                }
+                else {
+                    this.backgroundError = err instanceof Error ? err : new Error(String(err));
+                    this.pushEvent({
+                        type: "error",
+                        error: classifyError(this.backgroundError),
+                    });
+                }
+            }
+            finally {
+                this.backgroundDone = true;
+                this.pushEvent(null);
+            }
+        })();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan";
+export interface EngineOptions {
+    /** Working directory for file operations. Defaults to process.cwd() */
+    cwd?: string;
+    /** Model to use (e.g. "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Permission mode. Defaults to "bypassPermissions" (autopilot) */
+    permissionMode?: PermissionMode;
+    /** Custom system prompt */
+    systemPrompt?: string;
+    /** Max agent turns before stopping */
+    maxTurns?: number;
+    /** Tool whitelist — only these tools can be used */
+    allowedTools?: string[];
+    /** Tool blacklist — these tools are blocked */
+    disallowedTools?: string[];
+    /** MCP server configurations */
+    mcpServers?: Record<string, unknown>;
+    /** AbortSignal to cancel the operation */
+    signal?: AbortSignal;
+    /** Custom permission handler. When set, permissionMode should be "default" to enable prompting */
+    onPermission?: PermissionHandler;
+    /** Session ID to resume a previous conversation */
+    resume?: string;
+    /** Reasoning effort level */
+    effort?: "low" | "medium" | "high";
+}
+export interface ToolRequest {
+    tool: string;
+    input: Record<string, unknown>;
+    reason?: string;
+}
+export interface PermissionDecision {
+    allow: boolean;
+    updatedInput?: Record<string, unknown>;
+    message?: string;
+}
+export type PermissionHandler = (request: ToolRequest) => PermissionDecision | Promise<PermissionDecision>;
+export interface TextEvent {
+    type: "text";
+    text: string;
+}
+export interface TextDeltaEvent {
+    type: "text_delta";
+    delta: string;
+}
+export interface ToolUseEvent {
+    type: "tool_use";
+    id: string;
+    tool: string;
+    input: Record<string, unknown>;
+    description: string;
+}
+export interface ToolResultEvent {
+    type: "tool_result";
+    toolUseId: string;
+    tool: string;
+    output: string;
+    isError: boolean;
+}
+export interface SystemEvent {
+    type: "system";
+    sessionId: string;
+    model: string;
+    cwd: string;
+    tools: string[];
+}
+export interface ErrorEvent {
+    type: "error";
+    error: Error;
+}
+export interface ResultEvent {
+    type: "result";
+    text: string;
+    cost: number;
+    duration: number;
+    sessionId: string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+}
+export type AgentEvent = TextEvent | TextDeltaEvent | ToolUseEvent | ToolResultEvent | SystemEvent | ErrorEvent | ResultEvent;
+export interface ToolExecution {
+    tool: string;
+    input: Record<string, unknown>;
+    output: string;
+    isError: boolean;
+}
+export interface AgentResult {
+    text: string;
+    cost: number;
+    duration: number;
+    sessionId: string;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    tools: ToolExecution[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// ── Configuration ──
+export {};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "otterly",
+  "version": "0.1.0",
+  "description": "Ollama-simple SDK for Claude Code. Drop a coding agent into your app in one line.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "otterly": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server/index.js",
+      "types": "./dist/server/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-code": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-code": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-code": "^1.0.128",
+    "@types/node": "^25.6.2",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "claude-api",
+    "anthropic",
+    "coding-agent",
+    "ai",
+    "sdk",
+    "local",
+    "agent",
+    "otterly",
+    "openai-compatible",
+    "inference-server"
+  ],
+  "author": "Harsh Joshi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/josharsh/otterly.git"
+  }
+}