@vauban-org/agent-sdk 0.16.0

package/src/router/provider-router.ts

@@ -0,0 +1,319 @@
+/**
+ * provider-router — Anthropic → Groq cascade for agent loops.
+ *
+ * Contract:
+ *   1. Prefer Anthropic if configured; on rate-limit (429) or timeout, fall
+ *      back to Groq. On both failing, invoke `queueRetryFn` (BullMQ owns
+ *      retry scheduling) then throw.
+ *   2. Normalize tool-call shape across providers to `{name, args:object}`.
+ *      Anthropic returns `tool_use` blocks with parsed `input`; Groq returns
+ *      OpenAI-style `tool_calls[].function.arguments` as a JSON string.
+ *   3. `usage.inputTokens` / `usage.outputTokens` are always finite numbers.
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+
+// ─── Public contract ──────────────────────────────────────────────────────
+
+export interface ProviderRouterRequest {
+  messages: Array<{ role: string; content: string }>;
+  tools?: unknown[];
+  maxTokens?: number;
+}
+
+export interface ProviderRouterResponse {
+  content: string;
+  toolCalls: Array<{ name: string; args: unknown }>;
+  usage: { inputTokens: number; outputTokens: number };
+  provider: string;
+  latencyMs: number;
+}
+
+export interface ProviderRouter {
+  complete(request: ProviderRouterRequest): Promise<ProviderRouterResponse>;
+}
+
+export interface ProviderRouterOptions {
+  preferAnthropic?: boolean;
+  anthropicApiKey?: string;
+  groqApiKey?: string;
+  queueRetryFn?: (req: unknown) => Promise<void>;
+  model?: { anthropic?: string; groq?: string };
+  /** Injected for tests — Anthropic SDK client. */
+  anthropicClient?: AnthropicLike;
+  /** Injected for tests — fetch used to call Groq. */
+  fetchImpl?: typeof fetch;
+}
+
+// Narrow structural type so tests can inject a mock without pulling the full SDK.
+export interface AnthropicLike {
+  messages: {
+    create(params: Record<string, unknown>): Promise<unknown>;
+  };
+}
+
+// ─── Error taxonomy ───────────────────────────────────────────────────────
+
+export class ProviderRouterError extends Error {
+  constructor(
+    message: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "ProviderRouterError";
+  }
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────
+
+export function createProviderRouter(
+  opts?: ProviderRouterOptions,
+): ProviderRouter {
+  const preferAnthropic = opts?.preferAnthropic ?? true;
+  const anthropicApiKey =
+    opts?.anthropicApiKey ?? process.env.ANTHROPIC_API_KEY;
+  const groqApiKey = opts?.groqApiKey ?? process.env.GROQ_API_KEY;
+  const anthropicModel = opts?.model?.anthropic ?? "claude-sonnet-4-6";
+  const groqModel = opts?.model?.groq ?? "llama-3.3-70b-versatile";
+  const fetchImpl = opts?.fetchImpl ?? fetch;
+
+  const anthropicClient: AnthropicLike | null =
+    opts?.anthropicClient ??
+    (anthropicApiKey
+      ? (new Anthropic({ apiKey: anthropicApiKey }) as unknown as AnthropicLike)
+      : null);
+
+  const useAnthropic = preferAnthropic && anthropicClient !== null;
+  if (preferAnthropic && anthropicClient === null) {
+    console.info("[provider-router] Anthropic not configured, routing to Groq");
+  }
+
+  return {
+    async complete(request) {
+      let anthropicErr: unknown = null;
+
+      if (useAnthropic && anthropicClient !== null) {
+        try {
+          return await callAnthropic(anthropicClient, request, anthropicModel);
+        } catch (err) {
+          anthropicErr = err;
+          if (!isAnthropicFallbackEligible(err)) {
+            throw new ProviderRouterError(
+              `Anthropic call failed (non-retryable): ${(err as Error)?.message ?? String(err)}`,
+              err,
+            );
+          }
+          console.warn(
+            `[provider-router] Anthropic failed (${classifyAnthropicErr(err)}), falling back to Groq`,
+          );
+        }
+      }
+
+      if (!groqApiKey) {
+        if (opts?.queueRetryFn) {
+          await opts.queueRetryFn(request).catch(() => {
+            /* queue best-effort */
+          });
+        }
+        throw new ProviderRouterError(
+          "All providers unavailable: Anthropic failed and Groq API key missing",
+          anthropicErr,
+        );
+      }
+
+      try {
+        return await callGroq(fetchImpl, groqApiKey, request, groqModel);
+      } catch (err) {
+        console.warn("[provider-router] Groq failed, queueing retry");
+        if (opts?.queueRetryFn) {
+          await opts.queueRetryFn(request).catch(() => {
+            /* queue best-effort */
+          });
+        }
+        throw new ProviderRouterError(
+          `All providers failed. Last error: ${(err as Error)?.message ?? String(err)}`,
+          err,
+        );
+      }
+    },
+  };
+}
+
+// ─── Anthropic path ───────────────────────────────────────────────────────
+
+async function callAnthropic(
+  client: AnthropicLike,
+  request: ProviderRouterRequest,
+  model: string,
+): Promise<ProviderRouterResponse> {
+  const start = Date.now();
+
+  const { system, messages } = splitAnthropicMessages(request.messages);
+
+  const params: Record<string, unknown> = {
+    model,
+    max_tokens: request.maxTokens ?? 4096,
+    messages,
+  };
+  if (system) params.system = system;
+  if (request.tools && request.tools.length > 0) params.tools = request.tools;
+
+  const raw = (await client.messages.create(params)) as {
+    content?: Array<
+      | { type: "text"; text: string }
+      | { type: "tool_use"; name: string; input: unknown }
+    >;
+    usage?: { input_tokens?: number; output_tokens?: number };
+  };
+
+  let text = "";
+  const toolCalls: Array<{ name: string; args: unknown }> = [];
+  for (const block of raw.content ?? []) {
+    if (block.type === "text") {
+      text += block.text;
+    } else if (block.type === "tool_use") {
+      toolCalls.push({ name: block.name, args: block.input });
+    }
+  }
+
+  return {
+    content: text,
+    toolCalls,
+    usage: {
+      inputTokens: raw.usage?.input_tokens ?? 0,
+      outputTokens: raw.usage?.output_tokens ?? 0,
+    },
+    provider: "anthropic",
+    latencyMs: Date.now() - start,
+  };
+}
+
+function splitAnthropicMessages(
+  input: Array<{ role: string; content: string }>,
+): {
+  system: string | undefined;
+  messages: Array<{ role: "user" | "assistant"; content: string }>;
+} {
+  const systemParts: string[] = [];
+  const messages: Array<{ role: "user" | "assistant"; content: string }> = [];
+  for (const m of input) {
+    if (m.role === "system") {
+      systemParts.push(m.content);
+    } else if (m.role === "user" || m.role === "assistant") {
+      messages.push({ role: m.role, content: m.content });
+    } else if (m.role === "tool") {
+      // Collapse tool results into user messages for Anthropic simple path.
+      messages.push({ role: "user", content: `[tool] ${m.content}` });
+    }
+  }
+  return {
+    system: systemParts.length > 0 ? systemParts.join("\n\n") : undefined,
+    messages,
+  };
+}
+
+function classifyAnthropicErr(err: unknown): string {
+  const e = err as { status?: number; name?: string; message?: string };
+  if (e?.status === 429) return "rate_limit_429";
+  if (e?.status !== undefined && e.status >= 500) return `server_${e.status}`;
+  if (e?.name === "AbortError" || /timeout/i.test(e?.message ?? "")) {
+    return "timeout";
+  }
+  return "error";
+}
+
+function isAnthropicFallbackEligible(err: unknown): boolean {
+  const e = err as { status?: number; name?: string; message?: string };
+  if (e?.status === 429) return true;
+  if (e?.status !== undefined && e.status >= 500) return true;
+  if (
+    e?.name === "AbortError" ||
+    /timeout|ETIMEDOUT|ECONNRESET/i.test(e?.message ?? "")
+  ) {
+    return true;
+  }
+  return false;
+}
+
+// ─── Groq path ────────────────────────────────────────────────────────────
+
+async function callGroq(
+  fetchImpl: typeof fetch,
+  apiKey: string,
+  request: ProviderRouterRequest,
+  model: string,
+): Promise<ProviderRouterResponse> {
+  const start = Date.now();
+
+  const body: Record<string, unknown> = {
+    model,
+    max_tokens: request.maxTokens ?? 4096,
+    messages: request.messages.map((m) => ({
+      role: m.role === "tool" ? "user" : m.role,
+      content: m.role === "tool" ? `[tool] ${m.content}` : m.content,
+    })),
+  };
+  if (request.tools && request.tools.length > 0) body.tools = request.tools;
+
+  const res = await fetchImpl(
+    "https://api.groq.com/openai/v1/chat/completions",
+    {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(body),
+    },
+  );
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new ProviderRouterError(
+      `Groq HTTP ${res.status}: ${text.slice(0, 200)}`,
+    );
+  }
+
+  const raw = (await res.json()) as {
+    choices?: Array<{
+      message?: {
+        content?: string | null;
+        tool_calls?: Array<{
+          function?: { name?: string; arguments?: string };
+        }>;
+      };
+    }>;
+    usage?: { prompt_tokens?: number; completion_tokens?: number };
+  };
+
+  const msg = raw.choices?.[0]?.message;
+  const content = msg?.content ?? "";
+  const toolCalls: Array<{ name: string; args: unknown }> = [];
+  for (const tc of msg?.tool_calls ?? []) {
+    const name = tc.function?.name;
+    if (!name) continue;
+    let args: unknown = {};
+    const rawArgs = tc.function?.arguments;
+    if (typeof rawArgs === "string" && rawArgs.length > 0) {
+      try {
+        args = JSON.parse(rawArgs);
+      } catch {
+        args = { __raw: rawArgs };
+      }
+    } else if (rawArgs) {
+      args = rawArgs;
+    }
+    toolCalls.push({ name, args });
+  }
+
+  return {
+    content,
+    toolCalls,
+    usage: {
+      inputTokens: raw.usage?.prompt_tokens ?? 0,
+      outputTokens: raw.usage?.completion_tokens ?? 0,
+    },
+    provider: "groq",
+    latencyMs: Date.now() - start,
+  };
+}

package/src/runs/health.ts

@@ -0,0 +1,84 @@
+/**
+ * Runs health + anomaly REST clients — @vauban-org/agent-sdk v0.5.3.
+ *
+ * Wraps:
+ *   GET /api/agents/:id/health         → AgentHealth
+ *   GET /api/agents/:id/anomalies      → Anomaly[]
+ *   GET /api/router/circuit-breakers   → CircuitBreakerSnapshot[]
+ *
+ * Sprint: command-center:sprint-523:quick-6
+ */
+
+import type { AgentHealth, Anomaly, CircuitBreakerSnapshot } from "./types.js";
+import type { SubscribeHandle, SubscribeToRunOptions } from "./subscribe.js";
+import { subscribeToRun } from "./subscribe.js";
+
+export interface RunsClientOptions {
+  baseUrl: string;
+  getToken?: () => Promise<string>;
+}
+
+async function apiFetch<T>(
+  url: string,
+  getToken: (() => Promise<string>) | undefined,
+): Promise<T> {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+  };
+  if (getToken) {
+    const token = await getToken();
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  const response = await fetch(url, { headers });
+  if (!response.ok) {
+    throw new Error(`RunsClient: HTTP ${response.status} — ${url}`);
+  }
+  return response.json() as Promise<T>;
+}
+
+export interface RunsClient {
+  getHealth(agentId: string, window?: "24h" | "7d" | "30d"): Promise<AgentHealth>;
+  getAnomalies(agentId: string): Promise<Anomaly[]>;
+  getCircuitBreakers(): Promise<CircuitBreakerSnapshot[]>;
+  subscribeToRun(runId: string, opts: Omit<SubscribeToRunOptions, "baseUrl" | "getToken">): Promise<SubscribeHandle>;
+}
+
+interface AnomaliesResponse {
+  agent_id: string;
+  anomalies: Anomaly[];
+}
+
+interface CircuitBreakersResponse {
+  circuit_breakers: CircuitBreakerSnapshot[];
+}
+
+export function createRunsClient(opts: RunsClientOptions): RunsClient {
+  const base = opts.baseUrl.replace(/\/$/, "");
+
+  return {
+    async getHealth(agentId, window = "24h") {
+      const url = `${base}/api/agents/${encodeURIComponent(agentId)}/health?window=${window}`;
+      return apiFetch<AgentHealth>(url, opts.getToken);
+    },
+
+    async getAnomalies(agentId) {
+      const url = `${base}/api/agents/${encodeURIComponent(agentId)}/anomalies`;
+      const res = await apiFetch<AnomaliesResponse>(url, opts.getToken);
+      return res.anomalies;
+    },
+
+    async getCircuitBreakers() {
+      const url = `${base}/api/router/circuit-breakers`;
+      const res = await apiFetch<CircuitBreakersResponse>(url, opts.getToken);
+      return res.circuit_breakers;
+    },
+
+    subscribeToRun(runId, subOpts) {
+      return subscribeToRun(runId, {
+        ...subOpts,
+        baseUrl: base,
+        getToken: opts.getToken,
+      });
+    },
+  };
+}

package/src/runs/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./subscribe.js";
+export * from "./health.js";

package/src/runs/subscribe.ts

@@ -0,0 +1,263 @@
+/**
+ * subscribeToRun — SSE client for /api/runs/:id/stream.
+ *
+ * Uses fetch + ReadableStream for uniform Node 18+ / browser support.
+ * EventSource is NOT used — it lacks custom headers (needed for auth tokens)
+ * and behaves differently across runtimes.
+ *
+ * Protocol:
+ *   - Events are SSE-formatted: "event: NAME\nid: ID\ndata: JSON\n\n"
+ *   - last-event-id is forwarded via "Last-Event-ID" header on reconnect
+ *   - Auto-reconnect on stream close (max 3 retries, exponential backoff)
+ *   - AbortSignal propagated; close() aborts the controller
+ *
+ * Sprint: command-center:sprint-523:quick-6
+ */
+
+import type {
+  RunStep,
+  RunStreamEventName,
+  RunStreamEvent,
+} from "./types.js";
+
+export interface SubscribeToRunOptions {
+  baseUrl: string;
+  getToken?: () => Promise<string>;
+  /** UUID of the last step_id received — enables resume catch-up. */
+  lastEventId?: string;
+  signal?: AbortSignal;
+  onStep?: (step: RunStep, event: "step_existing" | "step_new") => void;
+  onComplete?: (data: { status: string; duration_ms?: number }) => void;
+  onError?: (err: Error) => void;
+}
+
+export interface SubscribeHandle {
+  close: () => void;
+}
+
+const MAX_RETRIES = 3;
+const BASE_BACKOFF_MS = 1_000;
+
+/**
+ * Parse a single SSE block (delimited by "\n\n") into a RunStreamEvent.
+ * Returns null if the block is incomplete or unrecognised.
+ */
+function parseSseBlock(block: string): RunStreamEvent | null {
+  let eventName: RunStreamEventName | null = null;
+  let eventId: string | undefined;
+  let dataLine: string | undefined;
+
+  for (const raw of block.split("\n")) {
+    const line = raw.trimEnd();
+    if (line.startsWith("event: ")) {
+      eventName = line.slice("event: ".length) as RunStreamEventName;
+    } else if (line.startsWith("id: ")) {
+      eventId = line.slice("id: ".length);
+    } else if (line.startsWith("data: ")) {
+      dataLine = line.slice("data: ".length);
+    }
+  }
+
+  if (!eventName || dataLine === undefined) return null;
+
+  let data: RunStreamEvent["data"];
+  if (dataLine === "") {
+    data = undefined;
+  } else {
+    try {
+      data = JSON.parse(dataLine) as RunStreamEvent["data"];
+    } catch {
+      return null;
+    }
+  }
+
+  return { name: eventName, id: eventId, data };
+}
+
+/**
+ * Stream the SSE response body, emitting parsed events via callbacks.
+ * Returns the last event id seen (for reconnect headers).
+ */
+async function streamResponse(
+  response: Response,
+  opts: SubscribeToRunOptions,
+  lastEventIdRef: { value: string | undefined },
+  abortSignal: AbortSignal,
+): Promise<"complete" | "reconnect"> {
+  const body = response.body;
+  if (!body) {
+    throw new Error("Response body is null — cannot stream SSE");
+  }
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+
+  try {
+    while (!abortSignal.aborted) {
+      const { done, value } = await reader.read();
+      if (done) return "reconnect";
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // Split on double-newline (SSE event boundary).
+      const blocks = buffer.split("\n\n");
+      // Keep the last (possibly incomplete) chunk in the buffer.
+      buffer = blocks.pop() ?? "";
+
+      for (const block of blocks) {
+        if (!block.trim()) continue;
+        const event = parseSseBlock(block);
+        if (!event) continue;
+
+        // Track last event id for resume.
+        if (event.id) lastEventIdRef.value = event.id;
+
+        switch (event.name) {
+          case "step_existing":
+          case "step_new": {
+            if (opts.onStep && event.data && typeof event.data === "object" && "id" in event.data) {
+              opts.onStep(event.data as RunStep, event.name);
+            }
+            break;
+          }
+          case "run_complete": {
+            if (opts.onComplete) {
+              const d = event.data as { status: string; duration_ms?: number } | undefined;
+              opts.onComplete(d ?? { status: "unknown" });
+            }
+            return "complete";
+          }
+          case "error": {
+            const d = event.data as { error: string } | undefined;
+            if (opts.onError) {
+              opts.onError(new Error(d?.error ?? "stream_error"));
+            }
+            break;
+          }
+          case "ping":
+            // Heartbeat — no action needed.
+            break;
+          default:
+            // Unknown event names are silently ignored per SSE spec.
+            break;
+        }
+      }
+    }
+    return "reconnect";
+  } finally {
+    reader.cancel().catch(() => {
+      // Ignore cancel errors — stream may already be closed.
+    });
+  }
+}
+
+export async function subscribeToRun(
+  runId: string,
+  opts: SubscribeToRunOptions,
+): Promise<SubscribeHandle> {
+  const controller = new AbortController();
+
+  // Merge caller's signal with our internal controller.
+  const mergedSignal = opts.signal
+    ? AbortSignal.any
+      ? AbortSignal.any([opts.signal, controller.signal])
+      : (() => {
+          const ac = new AbortController();
+          opts.signal!.addEventListener("abort", () => ac.abort());
+          controller.signal.addEventListener("abort", () => ac.abort());
+          return ac.signal;
+        })()
+    : controller.signal;
+
+  const lastEventIdRef: { value: string | undefined } = {
+    value: opts.lastEventId,
+  };
+
+  // Run the connection loop in the background; do not await.
+  void (async () => {
+    let retries = 0;
+
+    while (!mergedSignal.aborted && retries <= MAX_RETRIES) {
+      const url = `${opts.baseUrl.replace(/\/$/, "")}/api/runs/${runId}/stream`;
+
+      const headers: Record<string, string> = {
+        Accept: "text/event-stream",
+        "Cache-Control": "no-cache",
+      };
+
+      if (opts.getToken) {
+        try {
+          const token = await opts.getToken();
+          headers["Authorization"] = `Bearer ${token}`;
+        } catch (err) {
+          opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+          break;
+        }
+      }
+
+      if (lastEventIdRef.value) {
+        headers["Last-Event-ID"] = lastEventIdRef.value;
+      }
+
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: "GET",
+          headers,
+          signal: mergedSignal,
+        });
+      } catch (err) {
+        if (mergedSignal.aborted) break;
+        opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        // Backoff before retry.
+        retries++;
+        if (retries > MAX_RETRIES) break;
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(resolve, BASE_BACKOFF_MS * 2 ** (retries - 1));
+          mergedSignal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+          }, { once: true });
+        });
+        continue;
+      }
+
+      if (!response.ok) {
+        opts.onError?.(new Error(`HTTP ${response.status}: ${response.statusText}`));
+        break;
+      }
+
+      try {
+        const outcome = await streamResponse(response, opts, lastEventIdRef, mergedSignal);
+        if (outcome === "complete" || mergedSignal.aborted) break;
+        // "reconnect" — retry after backoff.
+        retries++;
+        if (retries > MAX_RETRIES) break;
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(resolve, BASE_BACKOFF_MS * 2 ** (retries - 1));
+          mergedSignal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+          }, { once: true });
+        });
+      } catch (err) {
+        if (mergedSignal.aborted) break;
+        opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        retries++;
+        if (retries > MAX_RETRIES) break;
+        await new Promise<void>((resolve) => {
+          const timer = setTimeout(resolve, BASE_BACKOFF_MS * 2 ** (retries - 1));
+          mergedSignal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+          }, { once: true });
+        });
+      }
+    }
+  })();
+
+  return {
+    close: () => controller.abort(),
+  };
+}