edgecrab-sdk 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# edgecrab-sdk
+
+[![npm](https://img.shields.io/npm/v/edgecrab-sdk.svg)](https://www.npmjs.com/package/edgecrab-sdk)
+[![Node](https://img.shields.io/badge/node-18%2B-green.svg)](https://nodejs.org)
+
+Node.js SDK for **EdgeCrab** — a Rust-native autonomous coding agent.
+
+## Install
+
+```bash
+npm install edgecrab-sdk
+```
+
+## Quick Start
+
+### Agent API (recommended)
+
+```typescript
+import { Agent } from 'edgecrab-sdk';
+
+const agent = new Agent({
+  model: 'anthropic/claude-sonnet-4-20250514',
+  systemPrompt: 'You are a helpful coding assistant',
+  apiKey: 'your-api-key', // optional
+});
+
+// Simple chat with conversation history
+const reply = await agent.chat('Explain Rust ownership');
+console.log(reply);
+
+// Continue the conversation
+const followUp = await agent.chat('Give me an example');
+console.log(followUp);
+```
+
+### Full conversation run
+
+```typescript
+const result = await agent.run('Refactor this function for better error handling');
+console.log(result.response);
+console.log(`Turns: ${result.turnsUsed}, Tokens: ${result.usage.total_tokens}`);
+```
+
+### Streaming
+
+```typescript
+for await (const token of agent.stream('Write a haiku about Rust')) {
+  process.stdout.write(token);
+}
+```
+
+### Low-level client
+
+```typescript
+import { EdgeCrabClient } from 'edgecrab-sdk';
+
+const client = new EdgeCrabClient({
+  baseUrl: 'http://127.0.0.1:8642',
+  apiKey: 'your-key',
+});
+
+const resp = await client.createCompletion(
+  [{ role: 'user', content: 'Hello' }],
+  { model: 'anthropic/claude-sonnet-4-20250514' },
+);
+console.log(resp.choices[0].message.content);
+```
+
+## CLI
+
+```bash
+edgecrab chat "What is the meaning of life?"
+edgecrab chat --model gpt-4 --system "Be concise" "Explain monads"
+edgecrab chat --stream "Tell me a story"
+edgecrab models
+edgecrab health
+```
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `EDGECRAB_BASE_URL` | API server URL (default: `http://127.0.0.1:8642`) |
+| `EDGECRAB_API_KEY` | Bearer token for authentication |
+
+## API Reference
+
+### `Agent`
+
+| Method | Description |
+|---|---|
+| `chat(message)` | Send a message, return reply string. Maintains history. |
+| `run(message)` | Full conversation run — returns `AgentResult` |
+| `stream(message)` | Async generator yielding tokens |
+| `addMessage(role, content)` | Inject a message into history |
+| `reset()` | Clear history and start a new session |
+| `getMessages()` | Get conversation history |
+| `getTurnCount()` | Number of completed turns |
+| `getUsage()` | Accumulated token usage |
+| `listModels()` | List available models |
+| `health()` | Check server health |
+
+### `EdgeCrabClient`
+
+Lower-level HTTP client with `chat()`, `createCompletion()`, `streamCompletion()`, `listModels()`, `health()`.
+
+## Links
+
+- [GitHub](https://github.com/raphaelmansuy/edgecrab)
+- [Python SDK](https://github.com/raphaelmansuy/edgecrab/tree/main/sdks/python)
+- [EdgeCrab Documentation](https://github.com/raphaelmansuy/edgecrab/tree/main/docs)

package/dist/chunk-QUOGGCXF.mjs

@@ -0,0 +1,300 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "http://127.0.0.1:8642";
+var DEFAULT_TIMEOUT = 12e4;
+var EdgeCrabError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "EdgeCrabError";
+    this.statusCode = statusCode;
+  }
+};
+function buildHeaders(apiKey) {
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+  return headers;
+}
+var EdgeCrabClient = class {
+  baseUrl;
+  headers;
+  timeout;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.headers = buildHeaders(options.apiKey);
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  }
+  /** Simple chat — send a message, get a reply string. */
+  async chat(message, options) {
+    const messages = [];
+    if (options?.system) {
+      messages.push({ role: "system", content: options.system });
+    }
+    messages.push({ role: "user", content: message });
+    const resp = await this.createCompletion(messages, {
+      model: options?.model,
+      temperature: options?.temperature,
+      maxTokens: options?.maxTokens
+    });
+    return resp.choices?.[0]?.message?.content ?? "";
+  }
+  /** Create a chat completion (non-streaming). */
+  async createCompletion(messages, options) {
+    const body = {
+      model: options?.model ?? "anthropic/claude-sonnet-4-20250514",
+      messages,
+      stream: false
+    };
+    if (options?.temperature !== void 0) body.temperature = options.temperature;
+    if (options?.maxTokens !== void 0) body.max_tokens = options.maxTokens;
+    if (options?.tools) body.tools = options.tools;
+    const response = await this.fetchJSON(
+      "/v1/chat/completions",
+      { method: "POST", body: JSON.stringify(body) }
+    );
+    return response;
+  }
+  /** Create a streaming chat completion. Returns an async iterator of chunks. */
+  async *streamCompletion(messages, options) {
+    const body = {
+      model: options?.model ?? "anthropic/claude-sonnet-4-20250514",
+      messages,
+      stream: true
+    };
+    if (options?.temperature !== void 0) body.temperature = options.temperature;
+    if (options?.maxTokens !== void 0) body.max_tokens = options.maxTokens;
+    if (options?.tools) body.tools = options.tools;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: this.headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const text = await response.text();
+        throw new EdgeCrabError(`API error ${response.status}: ${text}`, response.status);
+      }
+      if (!response.body) {
+        throw new EdgeCrabError("No response body for streaming request");
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed.startsWith("data: ")) continue;
+          const payload = trimmed.slice(6);
+          if (payload === "[DONE]") return;
+          yield JSON.parse(payload);
+        }
+      }
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /** List available models. */
+  async listModels() {
+    const data = await this.fetchJSON("/v1/models");
+    if (Array.isArray(data)) return data;
+    return data.data ?? [];
+  }
+  /** Check server health. */
+  async health() {
+    return this.fetchJSON("/v1/health");
+  }
+  async fetchJSON(path, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        ...init,
+        headers: { ...this.headers, ...init?.headers ?? {} },
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const text = await response.text();
+        let detail = text;
+        try {
+          const json = JSON.parse(text);
+          detail = json?.error?.message ?? text;
+        } catch {
+        }
+        throw new EdgeCrabError(`API error ${response.status}: ${detail}`, response.status);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/agent.ts
+import { randomUUID } from "crypto";
+var Agent = class {
+  model;
+  systemPrompt;
+  maxTurns;
+  temperature;
+  maxTokens;
+  streaming;
+  sessionId;
+  // Callbacks
+  onToken;
+  onToolCall;
+  onTurn;
+  messages = [];
+  turnCount = 0;
+  totalUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+  client;
+  constructor(options = {}) {
+    this.model = options.model ?? "anthropic/claude-sonnet-4-20250514";
+    this.systemPrompt = options.systemPrompt;
+    this.maxTurns = options.maxTurns ?? 50;
+    this.temperature = options.temperature;
+    this.maxTokens = options.maxTokens;
+    this.streaming = options.streaming ?? false;
+    this.sessionId = options.sessionId ?? randomUUID();
+    this.onToken = options.onToken;
+    this.onToolCall = options.onToolCall;
+    this.onTurn = options.onTurn;
+    const baseUrl = options.baseUrl ?? process.env.EDGECRAB_BASE_URL ?? "http://127.0.0.1:8642";
+    const apiKey = options.apiKey ?? process.env.EDGECRAB_API_KEY;
+    this.client = new EdgeCrabClient({
+      baseUrl,
+      apiKey,
+      timeout: options.timeout ? options.timeout * 1e3 : void 0
+    });
+    if (this.systemPrompt) {
+      this.messages.push({ role: "system", content: this.systemPrompt });
+    }
+  }
+  /** Send a message and return the assistant's text reply. Maintains history. */
+  async chat(message) {
+    this.messages.push({ role: "user", content: message });
+    this.turnCount++;
+    if (this.streaming && this.onToken) {
+      return this.chatStreaming();
+    }
+    const resp = await this.client.createCompletion(this.messages, {
+      model: this.model,
+      temperature: this.temperature,
+      maxTokens: this.maxTokens
+    });
+    const assistantMsg = this.extractResponse(resp);
+    this.accumulateUsage(resp.usage);
+    this.onTurn?.(this.turnCount, assistantMsg);
+    return assistantMsg.content;
+  }
+  async chatStreaming() {
+    const collected = [];
+    for await (const chunk of this.client.streamCompletion(this.messages, {
+      model: this.model,
+      temperature: this.temperature,
+      maxTokens: this.maxTokens
+    })) {
+      for (const choice of chunk.choices) {
+        if (choice.delta.content) {
+          collected.push(choice.delta.content);
+          this.onToken?.(choice.delta.content);
+        }
+      }
+    }
+    const fullText = collected.join("");
+    const assistantMsg = { role: "assistant", content: fullText };
+    this.messages.push(assistantMsg);
+    this.onTurn?.(this.turnCount, assistantMsg);
+    return fullText;
+  }
+  /** Run a full agent conversation. Returns a structured AgentResult. */
+  async run(message) {
+    const response = await this.chat(message);
+    return {
+      response,
+      messages: [...this.messages],
+      sessionId: this.sessionId,
+      model: this.model,
+      turnsUsed: this.turnCount,
+      finishedNaturally: true,
+      usage: { ...this.totalUsage }
+    };
+  }
+  /** Stream response tokens as an async iterable. */
+  async *stream(message) {
+    this.messages.push({ role: "user", content: message });
+    this.turnCount++;
+    const collected = [];
+    for await (const chunk of this.client.streamCompletion(this.messages, {
+      model: this.model,
+      temperature: this.temperature,
+      maxTokens: this.maxTokens
+    })) {
+      for (const choice of chunk.choices) {
+        if (choice.delta.content) {
+          collected.push(choice.delta.content);
+          yield choice.delta.content;
+        }
+      }
+    }
+    this.messages.push({ role: "assistant", content: collected.join("") });
+  }
+  /** Manually inject a message into the conversation history. */
+  addMessage(role, content) {
+    this.messages.push({ role, content });
+  }
+  /** Reset conversation state for a new session. */
+  reset() {
+    this.messages = [];
+    this.turnCount = 0;
+    this.totalUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+    this.sessionId = randomUUID();
+    if (this.systemPrompt) {
+      this.messages.push({ role: "system", content: this.systemPrompt });
+    }
+  }
+  /** Current conversation history (copy). */
+  getMessages() {
+    return [...this.messages];
+  }
+  /** Number of user turns completed. */
+  getTurnCount() {
+    return this.turnCount;
+  }
+  /** Accumulated token usage. */
+  getUsage() {
+    return { ...this.totalUsage };
+  }
+  /** List available models from the server. */
+  async listModels() {
+    return this.client.listModels();
+  }
+  /** Check server health. */
+  async health() {
+    return this.client.health();
+  }
+  extractResponse(resp) {
+    const msg = resp.choices?.[0]?.message ?? { role: "assistant", content: "" };
+    this.messages.push(msg);
+    return msg;
+  }
+  accumulateUsage(usage) {
+    if (usage) {
+      this.totalUsage.prompt_tokens += usage.prompt_tokens;
+      this.totalUsage.completion_tokens += usage.completion_tokens;
+      this.totalUsage.total_tokens += usage.total_tokens;
+    }
+  }
+};
+
+export {
+  EdgeCrabError,
+  EdgeCrabClient,
+  Agent
+};