edgecrab-sdk 0.1.0

package/dist/cli.mjs

@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// 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
+import { randomUUID } from "crypto";
+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 ?? 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 = 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 = 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;
+    }
+  }
+};
+
+// src/cli.ts
+var { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    "base-url": { type: "string" },
+    "api-key": { type: "string" },
+    model: { type: "string", short: "m", default: "anthropic/claude-sonnet-4-20250514" },
+    system: { type: "string", short: "s" },
+    temperature: { type: "string", short: "t" },
+    stream: { type: "boolean", default: false },
+    version: { type: "boolean", short: "v" },
+    help: { type: "boolean", short: "h" }
+  }
+});
+if (values.version) {
+  const pkg = await import("./package-UHAPSKPH.mjs").catch(() => ({ default: { version: "0.1.0" } }));
+  console.log(`edgecrab-sdk ${pkg.default.version}`);
+  process.exit(0);
+}
+var command = positionals[0];
+var messageArgs = positionals.slice(1);
+if (values.help || !command) {
+  console.log(`Usage: edgecrab <command> [options] [args...]
+
+Commands:
+  chat <message>    Send a message to the agent
+  models            List available models
+  health            Check API health
+
+Options:
+  --base-url <url>    API server URL (env: EDGECRAB_BASE_URL)
+  --api-key <key>     Bearer token (env: EDGECRAB_API_KEY)
+  -m, --model <id>    Model to use (default: anthropic/claude-sonnet-4-20250514)
+  -s, --system <msg>  System prompt
+  -t, --temperature   Sampling temperature
+  --stream            Stream the response
+  -v, --version       Show version
+  -h, --help          Show this help
+`);
+  process.exit(values.help ? 0 : 1);
+}
+var clientOpts = {
+  baseUrl: values["base-url"] ?? process.env.EDGECRAB_BASE_URL,
+  apiKey: values["api-key"] ?? process.env.EDGECRAB_API_KEY
+};
+try {
+  switch (command) {
+    case "chat": {
+      const message = messageArgs.join(" ");
+      if (!message) {
+        console.error("Error: no message provided");
+        process.exit(1);
+      }
+      const agent = new Agent({
+        ...clientOpts,
+        model: values.model,
+        systemPrompt: values.system,
+        temperature: values.temperature ? parseFloat(values.temperature) : void 0,
+        streaming: values.stream,
+        onToken: values.stream ? (token) => process.stdout.write(token) : void 0
+      });
+      if (values.stream) {
+        for await (const token of agent.stream(message)) {
+          process.stdout.write(token);
+        }
+        process.stdout.write("\n");
+      } else {
+        const reply = await agent.chat(message);
+        console.log(reply);
+      }
+      break;
+    }
+    case "models": {
+      const client = new EdgeCrabClient(clientOpts);
+      const models = await client.listModels();
+      for (const m of models) {
+        console.log(`  ${m.id}${m.owned_by ? `  (by ${m.owned_by})` : ""}`);
+      }
+      break;
+    }
+    case "health": {
+      const client = new EdgeCrabClient(clientOpts);
+      const h = await client.health();
+      console.log(JSON.stringify(h, null, 2));
+      break;
+    }
+    default:
+      console.error(`Unknown command: ${command}`);
+      process.exit(1);
+  }
+} catch (err) {
+  if (err instanceof EdgeCrabError) {
+    console.error(`Error: ${err.message}`);
+  } else {
+    console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  process.exit(1);
+}