otterly 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Harsh Joshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# otterly
+
+Drop a Claude Code agent into your app in one line. Like Ollama, but instead of running a model for inference, you get a full coding agent that reads, writes, and runs code on your local machine.
+
+```bash
+npm install otterly @anthropic-ai/claude-code
+```
+
+```typescript
+import { claude } from 'otterly';
+
+const result = await claude.run("Add error handling to server.ts", {
+  cwd: "./my-project",
+});
+
+console.log(result.text);   // "I've added try-catch blocks to all route handlers..."
+console.log(result.cost);   // 0.03
+```
+
+## Requirements
+
+- Node.js 18+
+- Claude Code installed and authenticated (`claude login`)
+- `@anthropic-ai/claude-code` installed as a peer dependency
+
+## Usage
+
+### One-shot
+
+Run a task, get the result. Simplest way to use it.
+
+```typescript
+import { claude } from 'otterly';
+
+const result = await claude.run("Fix the login bug in auth.ts", {
+  cwd: "./my-project",
+});
+
+console.log(result.text);       // Final output text
+console.log(result.cost);       // Cost in USD
+console.log(result.duration);   // Duration in ms
+console.log(result.sessionId);  // Save this to resume later
+console.log(result.tools);      // Every tool that was used
+```
+
+### Streaming
+
+Get real-time events as Claude works.
+
+```typescript
+import { claude } from 'otterly';
+
+for await (const event of claude.stream("Refactor the auth module", { cwd: "." })) {
+  switch (event.type) {
+    case "text_delta":
+      process.stdout.write(event.delta);
+      break;
+    case "tool_use":
+      console.log(`\n> ${event.description}`);
+      break;
+    case "tool_result":
+      if (event.isError) console.error(`Tool error: ${event.output}`);
+      break;
+    case "result":
+      console.log(`\nDone! Cost: $${event.cost}`);
+      break;
+  }
+}
+```
+
+### Multi-turn Sessions
+
+Keep conversation context alive across multiple messages.
+
+```typescript
+import { claude } from 'otterly';
+
+const session = claude.session({ cwd: "./my-project" });
+
+const r1 = await session.send("Create a REST API for users");
+console.log(r1.text);
+
+const r2 = await session.send("Now add authentication to it");
+console.log(r2.text);
+
+const r3 = await session.send("Write tests for the auth middleware");
+console.log(r3.text);
+
+// Save the session ID to resume later
+console.log(session.id);
+
+session.close();
+```
+
+Resume a previous session:
+
+```typescript
+const session = claude.session({
+  cwd: "./my-project",
+  resume: "previous-session-id",
+});
+
+await session.send("What did we work on last time?");
+```
+
+### Custom Permissions
+
+By default, otterly runs in autopilot mode (no permission prompts). You can control what Claude is allowed to do.
+
+```typescript
+import { claude, READONLY } from 'otterly';
+
+// Read-only: Claude can read files but can't modify anything
+const analysis = await claude.run("Analyze the codebase architecture", {
+  cwd: ".",
+  onPermission: READONLY,
+});
+
+// Custom: fine-grained control
+const result = await claude.run("Deploy to staging", {
+  cwd: ".",
+  onPermission: ({ tool, input }) => {
+    // Allow file reads and edits
+    if (["Read", "Edit", "Write", "Glob", "Grep"].includes(tool)) {
+      return { allow: true };
+    }
+    // Allow specific commands only
+    if (tool === "Bash" && input.command?.includes("npm run deploy")) {
+      return { allow: true };
+    }
+    // Deny everything else
+    return { allow: false, message: `${tool} not allowed in this context` };
+  },
+});
+```
+
+### Custom Engine Instance
+
+Set defaults for all calls.
+
+```typescript
+import { ClaudeEngine } from 'otterly';
+
+const engine = new ClaudeEngine({
+  cwd: "./my-project",
+  model: "claude-sonnet-4-20250514",
+  maxTurns: 10,
+});
+
+// All calls inherit the defaults
+const r1 = await engine.run("Fix lint errors");
+const r2 = await engine.run("Add missing types");
+```
+
+### Abort / Timeout
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 30_000); // 30s timeout
+
+const result = await claude.run("Refactor the entire test suite", {
+  cwd: ".",
+  signal: controller.signal,
+});
+```
+
+## Event Types
+
+When using `stream()` or `session.sendStream()`, you receive these events:
+
+| Event | Fields | Description |
+|-------|--------|-------------|
+| `text` | `text` | Complete text from an assistant message block |
+| `text_delta` | `delta` | Streaming text chunk (arrives in real-time) |
+| `tool_use` | `id`, `tool`, `input`, `description` | Claude is using a tool |
+| `tool_result` | `toolUseId`, `tool`, `output`, `isError` | Tool execution result |
+| `system` | `sessionId`, `model`, `cwd`, `tools` | Session initialized |
+| `result` | `text`, `cost`, `duration`, `sessionId`, `usage` | Turn complete |
+| `error` | `error` | Something went wrong |
+
+## Error Handling
+
+Errors are classified with a `code` field for programmatic handling:
+
+```typescript
+import { claude, AgentError } from 'otterly';
+
+try {
+  await claude.run("Do something");
+} catch (err) {
+  if (err instanceof AgentError) {
+    switch (err.code) {
+      case "NOT_AUTHENTICATED":
+        console.log("Run `claude login` to authenticate");
+        break;
+      case "RATE_LIMITED":
+        console.log("Wait and retry");
+        break;
+      case "SDK_NOT_FOUND":
+        console.log("npm install @anthropic-ai/claude-code");
+        break;
+      case "BILLING":
+        console.log("Check your Anthropic account");
+        break;
+      case "NETWORK":
+        console.log("Check your internet connection");
+        break;
+      case "ABORTED":
+        console.log("Operation was cancelled");
+        break;
+    }
+  }
+}
+```
+
+## Options
+
+```typescript
+interface EngineOptions {
+  cwd?: string;                    // Working directory (default: process.cwd())
+  model?: string;                  // Model to use
+  permissionMode?: PermissionMode; // "default" | "acceptEdits" | "bypassPermissions" | "plan"
+  systemPrompt?: string;           // Custom system prompt
+  maxTurns?: number;               // Max agent turns
+  allowedTools?: string[];         // Tool whitelist
+  disallowedTools?: string[];      // Tool blacklist
+  mcpServers?: Record<string, any>;// MCP server configs
+  signal?: AbortSignal;            // Cancellation signal
+  onPermission?: PermissionHandler;// Custom permission handler
+  resume?: string;                 // Session ID to resume
+  effort?: "low" | "medium" | "high"; // Reasoning effort
+}
+```
+
+## How It Works
+
+otterly wraps the `@anthropic-ai/claude-code` SDK's `query()` function. It piggybacks on your existing Claude Code installation — if you've run `claude login`, you're already authenticated. No API keys to manage.
+
+1. **`run()`** calls `query()` with your prompt, collects all events, returns the final result
+2. **`stream()`** calls `query()` and yields normalized events as they arrive
+3. **`session()`** uses the SDK's streaming input mode — an async generator that yields user messages on demand, keeping conversation context alive across turns in a single long-lived `query()` call
+
+No API keys. No server. No HTTP. No WebSocket. The SDK runs in-process using your local Claude Code auth.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// `otterly serve` — CLI entry point.
+// Uses node:util parseArgs (built-in since Node 18). No commander dependency.
+import { parseArgs } from "node:util";
+import { startApiServer } from "./server/index.js";
+const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+        port: { type: "string", short: "p", default: "11434" },
+        dir: { type: "string", short: "d", default: process.cwd() },
+        "max-concurrent": { type: "string", default: "5" },
+        "max-queue": { type: "string", default: "50" },
+        "rate-limit": { type: "string", default: "60" },
+        help: { type: "boolean", short: "h", default: false },
+    },
+});
+const command = positionals[0] || "serve";
+if (values.help || command === "help") {
+    console.log(`
+  otterly — local inference server for Claude Code
+
+  Usage:
+    otterly serve [options]     Start the API server
+    otterly help                Show this help
+
+  Options:
+    -p, --port <number>         Port to listen on (default: 11434)
+    -d, --dir <path>            Working directory for Claude (default: cwd)
+    --max-concurrent <number>   Max concurrent requests (default: 5)
+    --max-queue <number>        Max queued requests (default: 50)
+    --rate-limit <number>       Requests per minute per client (default: 60)
+    -h, --help                  Show this help
+
+  Environment:
+    OTTERLY_API_KEY       Set to require Bearer auth on all requests
+
+  Endpoints:
+    POST /v1/chat/completions   OpenAI-compatible (use any OpenAI client)
+    POST /api/run               Native one-shot execution
+    POST /api/stream            Native NDJSON streaming
+    GET  /api/status            Health check + queue/circuit stats
+    WS   /ws                    Multi-turn WebSocket sessions
+`);
+    process.exit(0);
+}
+if (command === "serve") {
+    startApiServer({
+        port: parseInt(values.port, 10),
+        workingDir: values.dir,
+        maxConcurrent: parseInt(values["max-concurrent"], 10),
+        maxQueueSize: parseInt(values["max-queue"], 10),
+        requestsPerMinute: parseInt(values["rate-limit"], 10),
+    }).then((handle) => {
+        // Graceful shutdown on SIGTERM/SIGINT
+        let shutdownInitiated = false;
+        const onSignal = async () => {
+            if (shutdownInitiated) {
+                console.log("\nForced exit.");
+                process.exit(1);
+            }
+            shutdownInitiated = true;
+            await handle.shutdown(10_000);
+            process.exit(0);
+        };
+        process.on("SIGTERM", onSignal);
+        process.on("SIGINT", onSignal);
+    }).catch((err) => {
+        console.error("Failed to start:", err.message);
+        process.exit(1);
+    });
+}
+else {
+    console.error(`Unknown command: ${command}. Run 'otterly help' for usage.`);
+    process.exit(1);
+}

package/dist/engine.d.ts

@@ -0,0 +1,38 @@
+import type { AgentEvent, AgentResult, EngineOptions } from "./types.js";
+import { Session } from "./session.js";
+export declare class ClaudeEngine {
+    private defaults;
+    constructor(defaults?: Partial<EngineOptions>);
+    private mergeOptions;
+    /**
+     * Run a prompt and get the final result. Blocks until complete.
+     *
+     * ```ts
+     * const result = await claude.run("Fix the login bug", { cwd: "./app" });
+     * console.log(result.text, result.cost);
+     * ```
+     */
+    run(prompt: string, options?: EngineOptions): Promise<AgentResult>;
+    /**
+     * Stream events from a prompt in real-time.
+     *
+     * ```ts
+     * for await (const event of claude.stream("Refactor auth", { cwd: "." })) {
+     *   if (event.type === "text_delta") process.stdout.write(event.delta);
+     *   if (event.type === "tool_use") console.log(`Using ${event.tool}...`);
+     * }
+     * ```
+     */
+    stream(prompt: string, options?: EngineOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Create a multi-turn session. Context persists across send() calls.
+     *
+     * ```ts
+     * const session = claude.session({ cwd: "./my-project" });
+     * await session.send("Create a REST API");
+     * await session.send("Now add auth to it");
+     * session.close();
+     * ```
+     */
+    session(options?: EngineOptions): Session;
+}

package/dist/engine.js

@@ -0,0 +1,169 @@
+import { normalizeEvents, createEventContext } from "./events.js";
+import { classifyError, AgentError } from "./errors.js";
+import { wrapPermissionHandler } from "./permissions.js";
+import { Session } from "./session.js";
+let cachedQueryFn = null;
+async function resolveSDK() {
+    if (cachedQueryFn)
+        return cachedQueryFn;
+    // Try the primary SDK first, then the alternative package name
+    for (const pkg of ["@anthropic-ai/claude-code", "@anthropic-ai/claude-agent-sdk"]) {
+        try {
+            const mod = await import(pkg);
+            const fn = mod.query || mod.default?.query;
+            if (typeof fn === "function") {
+                cachedQueryFn = fn;
+                return cachedQueryFn;
+            }
+        }
+        catch {
+            // Try next
+        }
+    }
+    throw new AgentError("SDK_NOT_FOUND", "Could not find Claude Code SDK. Install it:\n  npm install @anthropic-ai/claude-code");
+}
+export class ClaudeEngine {
+    defaults;
+    constructor(defaults) {
+        this.defaults = defaults || {};
+    }
+    mergeOptions(options) {
+        return { ...this.defaults, ...options };
+    }
+    /**
+     * Run a prompt and get the final result. Blocks until complete.
+     *
+     * ```ts
+     * const result = await claude.run("Fix the login bug", { cwd: "./app" });
+     * console.log(result.text, result.cost);
+     * ```
+     */
+    async run(prompt, options) {
+        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.stream(prompt, options)) {
+            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 };
+    }
+    /**
+     * Stream events from a prompt in real-time.
+     *
+     * ```ts
+     * for await (const event of claude.stream("Refactor auth", { cwd: "." })) {
+     *   if (event.type === "text_delta") process.stdout.write(event.delta);
+     *   if (event.type === "tool_use") console.log(`Using ${event.tool}...`);
+     * }
+     * ```
+     */
+    async *stream(prompt, options) {
+        const opts = this.mergeOptions(options);
+        const queryFn = await resolveSDK();
+        const abortController = new AbortController();
+        if (opts.signal) {
+            opts.signal.addEventListener("abort", () => abortController.abort());
+        }
+        const queryOptions = {
+            abortController,
+            cwd: opts.cwd || process.cwd(),
+            permissionMode: opts.permissionMode || "bypassPermissions",
+            includePartialMessages: true,
+        };
+        if (opts.model)
+            queryOptions.model = opts.model;
+        if (opts.maxTurns)
+            queryOptions.maxTurns = opts.maxTurns;
+        if (opts.allowedTools)
+            queryOptions.allowedTools = opts.allowedTools;
+        if (opts.disallowedTools)
+            queryOptions.disallowedTools = opts.disallowedTools;
+        if (opts.mcpServers)
+            queryOptions.mcpServers = opts.mcpServers;
+        if (opts.effort)
+            queryOptions.effort = opts.effort;
+        if (opts.resume)
+            queryOptions.resume = opts.resume;
+        if (opts.systemPrompt)
+            queryOptions.systemPrompt = opts.systemPrompt;
+        if (opts.onPermission) {
+            queryOptions.permissionMode = "default";
+            queryOptions.canUseTool = wrapPermissionHandler(opts.onPermission);
+        }
+        const ctx = createEventContext();
+        try {
+            const queryInstance = queryFn({ prompt, options: queryOptions });
+            for await (const raw of queryInstance) {
+                if (abortController.signal.aborted)
+                    break;
+                const events = normalizeEvents(raw, ctx);
+                for (const event of events) {
+                    yield event;
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                (err.name === "AbortError" || abortController.signal.aborted)) {
+                return;
+            }
+            throw classifyError(err);
+        }
+    }
+    /**
+     * Create a multi-turn session. Context persists across send() calls.
+     *
+     * ```ts
+     * const session = claude.session({ cwd: "./my-project" });
+     * await session.send("Create a REST API");
+     * await session.send("Now add auth to it");
+     * session.close();
+     * ```
+     */
+    session(options) {
+        const opts = this.mergeOptions(options);
+        // Session needs the query function — resolve it lazily on first send()
+        // We wrap it in a lazy resolver to avoid top-level await
+        let resolvedFn = null;
+        const lazyQueryFn = async function* (args) {
+            if (!resolvedFn) {
+                resolvedFn = await resolveSDK();
+            }
+            yield* resolvedFn(args);
+        };
+        return new Session(lazyQueryFn, opts);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type ErrorCode = "NOT_AUTHENTICATED" | "RATE_LIMITED" | "BILLING" | "NETWORK" | "ABORTED" | "SDK_NOT_FOUND" | "UNKNOWN";
+export declare class AgentError extends Error {
+    code: ErrorCode;
+    original?: Error;
+    constructor(code: ErrorCode, message: string, original?: Error);
+}
+export declare function classifyError(err: unknown): AgentError;

package/dist/errors.js

@@ -0,0 +1,32 @@
+export class AgentError extends Error {
+    code;
+    original;
+    constructor(code, message, original) {
+        super(message);
+        this.name = "AgentError";
+        this.code = code;
+        this.original = original;
+    }
+}
+export function classifyError(err) {
+    if (err instanceof AgentError)
+        return err;
+    const e = err instanceof Error ? err : new Error(String(err));
+    const msg = e.message || String(err);
+    if (msg.includes("ANTHROPIC_API_KEY") || msg.includes("authentication") || msg.includes("not logged in") || msg.includes("claude login")) {
+        return new AgentError("NOT_AUTHENTICATED", "Not authenticated. Run `claude login` to sign in.", e);
+    }
+    if (msg.includes("rate_limit") || msg.includes("429")) {
+        return new AgentError("RATE_LIMITED", "Rate limited by the API. Wait a moment and try again.", e);
+    }
+    if (msg.includes("billing") || msg.includes("402")) {
+        return new AgentError("BILLING", "Billing issue with your API key. Check your Anthropic account.", e);
+    }
+    if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
+        return new AgentError("NETWORK", "Network error. Check your internet connection.", e);
+    }
+    if (e.name === "AbortError" || msg.includes("aborted")) {
+        return new AgentError("ABORTED", "Operation was cancelled.", e);
+    }
+    return new AgentError("UNKNOWN", msg, e);
+}

package/dist/events.d.ts

@@ -0,0 +1,13 @@
+import type { AgentEvent } from "./types.js";
+export interface EventContext {
+    sessionId: string | null;
+    toolNames: Map<string, string>;
+    accumulatedText: string;
+}
+export declare function createEventContext(): EventContext;
+/**
+ * Normalize a raw SDK message into clean AgentEvent(s).
+ * Returns an array because one SDK message can contain multiple content blocks.
+ */
+export declare function normalizeEvents(raw: Record<string, unknown>, ctx: EventContext): AgentEvent[];
+export declare function describeToolUse(name: string, input: Record<string, unknown>): string;