edgecrab-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,518 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Agent: () => Agent,
+  AuthenticationError: () => AuthenticationError,
+  ConnectionError: () => ConnectionError,
+  EdgeCrabClient: () => EdgeCrabClient,
+  EdgeCrabError: () => EdgeCrabError,
+  InterruptedError: () => InterruptedError,
+  MaxTurnsExceededError: () => MaxTurnsExceededError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  TimeoutError: () => TimeoutError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/agent.ts
+var import_node_crypto = require("crypto");
+
+// src/client.ts
+var DEFAULT_BASE_URL = "http://127.0.0.1:8642";
+var DEFAULT_TIMEOUT = 12e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RETRY_BASE_DELAY = 1e3;
+var EdgeCrabError = class extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "EdgeCrabError";
+    this.statusCode = statusCode;
+  }
+};
+var AuthenticationError = class extends EdgeCrabError {
+  constructor(message, statusCode) {
+    super(message, statusCode);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends EdgeCrabError {
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(message, 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ServerError = class extends EdgeCrabError {
+  constructor(message, statusCode) {
+    super(message, statusCode);
+    this.name = "ServerError";
+  }
+};
+var TimeoutError = class extends EdgeCrabError {
+  constructor(message = "Request timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var ConnectionError = class extends EdgeCrabError {
+  constructor(message = "Could not connect to EdgeCrab server") {
+    super(message);
+    this.name = "ConnectionError";
+  }
+};
+var MaxTurnsExceededError = class extends EdgeCrabError {
+  maxTurns;
+  constructor(maxTurns) {
+    super(`Agent exceeded maximum turns (${maxTurns})`);
+    this.name = "MaxTurnsExceededError";
+    this.maxTurns = maxTurns;
+  }
+};
+var InterruptedError = class extends EdgeCrabError {
+  constructor() {
+    super("Agent conversation was interrupted");
+    this.name = "InterruptedError";
+  }
+};
+function classifyError(status, detail, headers) {
+  const msg = `API error ${status}: ${detail}`;
+  if (status === 401 || status === 403) return new AuthenticationError(msg, status);
+  if (status === 429) {
+    const ra = headers?.get("retry-after");
+    return new RateLimitError(msg, ra ? parseFloat(ra) : void 0);
+  }
+  if (status >= 500) return new ServerError(msg, status);
+  return new EdgeCrabError(msg, status);
+}
+function isRetryable(err) {
+  if (err instanceof ServerError || err instanceof TimeoutError || err instanceof ConnectionError)
+    return true;
+  if (err instanceof RateLimitError) return true;
+  if (err instanceof TypeError && String(err.message).includes("fetch")) return true;
+  return false;
+}
+function buildHeaders(apiKey) {
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`;
+  return headers;
+}
+var EdgeCrabClient = class {
+  baseUrl;
+  headers;
+  timeout;
+  maxRetries;
+  retryBaseDelay;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.headers = buildHeaders(options.apiKey);
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.retryBaseDelay = options.retryBaseDelay ?? DEFAULT_RETRY_BASE_DELAY;
+  }
+  /** 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;
+    return this.postWithRetry(body);
+  }
+  async postWithRetry(body) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await this.fetchJSON("/v1/chat/completions", {
+          method: "POST",
+          body: JSON.stringify(body)
+        });
+        return response;
+      } catch (err) {
+        lastError = err;
+        if (!isRetryable(err) || attempt === this.maxRetries) throw err;
+        let delay = this.retryBaseDelay * 2 ** attempt;
+        if (err instanceof RateLimitError && err.retryAfter) {
+          delay = Math.max(delay, err.retryAfter * 1e3);
+        }
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+    throw lastError;
+  }
+  /** 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 classifyError(response.status, text, response.headers);
+      }
+      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 classifyError(response.status, detail, response.headers);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/agent.ts
+var Agent = class _Agent {
+  model;
+  systemPrompt;
+  maxTurns;
+  temperature;
+  maxTokens;
+  streaming;
+  sessionId;
+  // Callbacks
+  onToken;
+  onToolCall;
+  onTurn;
+  onError;
+  messages = [];
+  turnCount = 0;
+  totalUsage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+  client;
+  interrupted = false;
+  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 ?? (0, import_node_crypto.randomUUID)();
+    this.onToken = options.onToken;
+    this.onToolCall = options.onToolCall;
+    this.onTurn = options.onTurn;
+    this.onError = options.onError;
+    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,
+      maxRetries: options.maxRetries
+    });
+    if (this.systemPrompt) {
+      this.messages.push({ role: "system", content: this.systemPrompt });
+    }
+  }
+  // ── Interrupt ───────────────────────────────────────────────────
+  /** Signal the agent to stop after the current turn. */
+  interrupt() {
+    this.interrupted = true;
+  }
+  /** Clear the interrupt flag so the agent can continue. */
+  clearInterrupt() {
+    this.interrupted = false;
+  }
+  /** Whether the agent has been interrupted. */
+  get isInterrupted() {
+    return this.interrupted;
+  }
+  // ── Chat ────────────────────────────────────────────────────────
+  /** Send a message and return the assistant's text reply. Maintains history. */
+  async chat(message) {
+    if (this.interrupted) throw new InterruptedError();
+    if (this.turnCount >= this.maxTurns) throw new MaxTurnsExceededError(this.maxTurns);
+    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
+    })) {
+      if (this.interrupted) break;
+      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 ─────────────────────────────────────────────────────────
+  /** Run a full agent conversation. Returns a structured AgentResult. */
+  async run(message, options) {
+    if (options?.conversationHistory) {
+      for (const msg of options.conversationHistory) {
+        this.messages.push(msg);
+      }
+    }
+    let response;
+    let wasInterrupted = false;
+    let wasMaxTurnsExceeded = false;
+    try {
+      response = await this.chat(message);
+    } catch (err) {
+      if (err instanceof InterruptedError) {
+        response = this.messages.length > 0 ? this.messages[this.messages.length - 1].content : "";
+        wasInterrupted = true;
+      } else if (err instanceof MaxTurnsExceededError) {
+        response = this.messages.length > 0 ? this.messages[this.messages.length - 1].content : "";
+        wasMaxTurnsExceeded = true;
+      } else {
+        throw err;
+      }
+    }
+    return {
+      response,
+      messages: [...this.messages],
+      sessionId: this.sessionId,
+      model: this.model,
+      turnsUsed: this.turnCount,
+      finishedNaturally: !wasInterrupted && !wasMaxTurnsExceeded,
+      interrupted: wasInterrupted,
+      maxTurnsExceeded: wasMaxTurnsExceeded,
+      usage: { ...this.totalUsage }
+    };
+  }
+  // ── Stream ──────────────────────────────────────────────────────
+  /** Stream response tokens as an async iterable. */
+  async *stream(message) {
+    if (this.interrupted) throw new InterruptedError();
+    if (this.turnCount >= this.maxTurns) throw new MaxTurnsExceededError(this.maxTurns);
+    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
+    })) {
+      if (this.interrupted) break;
+      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("") });
+  }
+  // ── Conversation management ─────────────────────────────────────
+  /** 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 = (0, import_node_crypto.randomUUID)();
+    this.interrupted = false;
+    if (this.systemPrompt) {
+      this.messages.push({ role: "system", content: this.systemPrompt });
+    }
+  }
+  // ── Conversation persistence ────────────────────────────────────
+  /** Export the current conversation state as a serializable object. */
+  exportConversation() {
+    return {
+      sessionId: this.sessionId,
+      model: this.model,
+      messages: [...this.messages],
+      turnCount: this.turnCount,
+      usage: { ...this.totalUsage }
+    };
+  }
+  /** Restore a conversation state from a previously exported object. */
+  importConversation(data) {
+    this.sessionId = data.sessionId ?? this.sessionId;
+    this.messages = [...data.messages ?? []];
+    this.turnCount = data.turnCount ?? 0;
+    if (data.usage) this.totalUsage = { ...data.usage };
+  }
+  /** Create a fork of this agent with an independent copy of the conversation. */
+  clone() {
+    const newAgent = new _Agent({
+      model: this.model,
+      systemPrompt: this.systemPrompt,
+      maxTurns: this.maxTurns,
+      temperature: this.temperature,
+      maxTokens: this.maxTokens,
+      streaming: this.streaming,
+      onToken: this.onToken,
+      onToolCall: this.onToolCall,
+      onTurn: this.onTurn,
+      onError: this.onError
+    });
+    newAgent.importConversation(this.exportConversation());
+    newAgent.sessionId = (0, import_node_crypto.randomUUID)();
+    return newAgent;
+  }
+  // ── Introspection ───────────────────────────────────────────────
+  /** 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();
+  }
+  // ── Internal ────────────────────────────────────────────────────
+  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;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Agent,
+  AuthenticationError,
+  ConnectionError,
+  EdgeCrabClient,
+  EdgeCrabError,
+  InterruptedError,
+  MaxTurnsExceededError,
+  RateLimitError,
+  ServerError,
+  TimeoutError
+});