@vauban-org/agent-sdk 0.16.0

package/src/adapters/llm/cascade.ts

@@ -0,0 +1,109 @@
+/**
+ * CascadeAdapter — composition helper for LLMProviderPort.
+ *
+ * Tries providers in order. Falls back to the next provider on:
+ *   - Timeout (AbortError)
+ *   - 500-class errors (mapped to finishReason: "error")
+ *   - 429 after all retries (mapped to finishReason: "error")
+ *
+ * If all providers fail or return finishReason: "error",
+ * returns the canonical all-fail response.
+ *
+ * BYOM: no default model hardcoded.
+ */
+
+import type {
+  ChatRequest,
+  ChatResponse,
+  LLMProviderPort,
+  StreamDelta,
+} from "../../ports/llm-provider.js";
+
+const ALL_FAIL_RESPONSE: ChatResponse = {
+  content: "",
+  usage: { inputTokens: 0, outputTokens: 0 },
+  model: "",
+  finishReason: "error",
+};
+
+export interface CascadeAdapterConfig {
+  providers: LLMProviderPort[];
+}
+
+export class CascadeAdapter implements LLMProviderPort {
+  private readonly providers: LLMProviderPort[];
+
+  constructor(config: CascadeAdapterConfig) {
+    if (config.providers.length === 0) {
+      throw new Error("CascadeAdapter requires at least one provider");
+    }
+    this.providers = config.providers;
+  }
+
+  estimateCost(req: ChatRequest): { usd: number } {
+    // Use the first provider that supports estimateCost
+    for (const provider of this.providers) {
+      if (provider.estimateCost) {
+        return provider.estimateCost(req);
+      }
+    }
+    return { usd: 0 };
+  }
+
+  async complete(req: ChatRequest): Promise<ChatResponse> {
+    for (const provider of this.providers) {
+      if (req.abortSignal?.aborted) {
+        return { ...ALL_FAIL_RESPONSE };
+      }
+
+      let response: ChatResponse;
+      try {
+        response = await provider.complete(req);
+      } catch {
+        // Unexpected throw — treat as failure, try next
+        continue;
+      }
+
+      if (response.finishReason !== "error") {
+        return response;
+      }
+      // finishReason === "error" → try next provider
+    }
+
+    return { ...ALL_FAIL_RESPONSE };
+  }
+
+  async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {
+    for (const provider of this.providers) {
+      if (req.abortSignal?.aborted) {
+        return;
+      }
+
+      if (!provider.stream) {
+        // This provider doesn't support streaming — try next
+        continue;
+      }
+
+      let hadContent = false;
+      let errored = false;
+
+      try {
+        for await (const chunk of provider.stream(req)) {
+          if (req.abortSignal?.aborted) return;
+          hadContent = true;
+          yield chunk;
+        }
+      } catch {
+        errored = true;
+      }
+
+      if (hadContent && !errored) {
+        return;
+      }
+      // No content or error — try next provider
+    }
+
+    // All providers failed
+    yield { delta: "", usage: { inputTokens: 0, outputTokens: 0 } };
+  }
+}

package/src/adapters/llm/litellm.ts

@@ -0,0 +1,300 @@
+/**
+ * LiteLLMAdapter — OpenAI-compatible adapter for LiteLLM proxy.
+ *
+ * Uses native fetch (Node 18+). Retries 429 responses with
+ * exponential back-off + jitter (max 3 attempts). No axios.
+ * Cost extracted from usage field when available.
+ *
+ * BYOM: defaultModel is a constructor param default only.
+ * No model string is hardcoded at module scope.
+ */
+
+import type {
+  ChatRequest,
+  ChatResponse,
+  ChatUsage,
+  LLMProviderPort,
+  StreamDelta,
+} from "../../ports/llm-provider.js";
+
+export interface LiteLLMAdapterConfig {
+  baseUrl: string;
+  apiKey?: string;
+  defaultModel?: string;
+}
+
+interface OpenAIMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+interface OpenAIUsage {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens?: number;
+}
+
+interface OpenAIChoice {
+  message: { content: string | null };
+  finish_reason: string | null;
+}
+
+interface OpenAIResponse {
+  choices: OpenAIChoice[];
+  usage?: OpenAIUsage;
+  model?: string;
+}
+
+// Tokens per USD — approximate LiteLLM defaults for cost estimation.
+const INPUT_TOKENS_PER_USD = 500_000;
+const OUTPUT_TOKENS_PER_USD = 250_000;
+
+const MAX_RETRIES = 3;
+
+function jitter(baseMs: number): number {
+  // ±25% jitter
+  return baseMs * (0.75 + Math.random() * 0.5);
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function estimateInputTokens(req: ChatRequest): number {
+  // Rough approximation: 4 chars ≈ 1 token
+  const chars = req.messages.reduce((sum, m) => sum + m.content.length, 0);
+  return Math.ceil(chars / 4);
+}
+
+function mapFinishReason(
+  raw: string | null | undefined
+): ChatResponse["finishReason"] {
+  switch (raw) {
+    case "stop":
+      return "stop";
+    case "length":
+    case "max_tokens":
+      return "length";
+    case "tool_calls":
+    case "function_call":
+      return "tool";
+    default:
+      return "error";
+  }
+}
+
+export class LiteLLMAdapter implements LLMProviderPort {
+  private readonly baseUrl: string;
+  private readonly apiKey: string | undefined;
+  private readonly defaultModel: string;
+
+  constructor(config: LiteLLMAdapterConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.defaultModel = config.defaultModel ?? "gpt-3.5-turbo";
+  }
+
+  estimateCost(req: ChatRequest): { usd: number } {
+    const inputTokens = estimateInputTokens(req);
+    const maxOutputTokens = req.maxTokens ?? 512;
+    const inputCost = inputTokens / INPUT_TOKENS_PER_USD;
+    const outputCost = maxOutputTokens / OUTPUT_TOKENS_PER_USD;
+    return { usd: inputCost + outputCost };
+  }
+
+  async complete(req: ChatRequest): Promise<ChatResponse> {
+    const model = req.model ?? this.defaultModel;
+    const body = {
+      model,
+      messages: req.messages as OpenAIMessage[],
+      temperature: req.temperature,
+      max_tokens: req.maxTokens,
+      // Pass tenant metadata as user field for tracking
+      user: req.metadata?.tenantId,
+    };
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      if (req.abortSignal?.aborted) {
+        return {
+          content: "",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          model,
+          finishReason: "error",
+        };
+      }
+
+      let response: Response;
+      try {
+        response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: req.abortSignal,
+        });
+      } catch (err) {
+        // AbortError or network error
+        if (req.abortSignal?.aborted) {
+          return {
+            content: "",
+            usage: { inputTokens: 0, outputTokens: 0 },
+            model,
+            finishReason: "error",
+          };
+        }
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < MAX_RETRIES - 1) {
+          await sleep(jitter(500 * 2 ** attempt));
+        }
+        continue;
+      }
+
+      if (response.status === 429) {
+        if (attempt < MAX_RETRIES - 1) {
+          await sleep(jitter(1000 * 2 ** attempt));
+          continue;
+        }
+        // Exhausted retries — return error finishReason
+        return {
+          content: "",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          model,
+          finishReason: "error",
+        };
+      }
+
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < MAX_RETRIES - 1) {
+          await sleep(jitter(500 * 2 ** attempt));
+          continue;
+        }
+        return {
+          content: "",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          model,
+          finishReason: "error",
+        };
+      }
+
+      let json: OpenAIResponse;
+      try {
+        json = (await response.json()) as OpenAIResponse;
+      } catch {
+        return {
+          content: "",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          model,
+          finishReason: "error",
+        };
+      }
+
+      const choice = json.choices?.[0];
+      const rawUsage = json.usage;
+      const usage: ChatUsage = {
+        inputTokens: rawUsage?.prompt_tokens ?? estimateInputTokens(req),
+        outputTokens: rawUsage?.completion_tokens ?? 0,
+        costUsd: rawUsage
+          ? rawUsage.prompt_tokens / INPUT_TOKENS_PER_USD +
+            rawUsage.completion_tokens / OUTPUT_TOKENS_PER_USD
+          : undefined,
+      };
+
+      return {
+        content: choice?.message?.content ?? "",
+        usage,
+        model: json.model ?? model,
+        finishReason: mapFinishReason(choice?.finish_reason),
+      };
+    }
+
+    // Should not reach here but TypeScript requires a return
+    if (lastError) {
+      return {
+        content: "",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        model,
+        finishReason: "error",
+      };
+    }
+
+    return {
+      content: "",
+      usage: { inputTokens: 0, outputTokens: 0 },
+      model,
+      finishReason: "error",
+    };
+  }
+
+  async *stream(req: ChatRequest): AsyncIterable<StreamDelta> {
+    const model = req.model ?? this.defaultModel;
+    const body = {
+      model,
+      messages: req.messages as OpenAIMessage[],
+      temperature: req.temperature,
+      max_tokens: req.maxTokens,
+      stream: true,
+      user: req.metadata?.tenantId,
+    };
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`;
+    }
+
+    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: req.abortSignal,
+    });
+
+    if (!response.ok || !response.body) {
+      yield { delta: "", usage: { inputTokens: 0, outputTokens: 0 } };
+      return;
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    try {
+      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 data = trimmed.slice(5).trim();
+          if (data === "[DONE]") return;
+
+          try {
+            const chunk = JSON.parse(data) as {
+              choices?: Array<{ delta?: { content?: string } }>;
+            };
+            const delta = chunk.choices?.[0]?.delta?.content ?? "";
+            if (delta) yield { delta };
+          } catch {
+            // skip malformed chunk
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+}

package/src/adapters/messaging/console.ts

@@ -0,0 +1,73 @@
+/**
+ * ConsoleChannel — MessagingChannelPort adapter for local console output.
+ *
+ * Designed for tests and local development. No external API calls.
+ * Constructor requires no arguments (defaultStream = process.stdout).
+ *
+ * ANSI color codes:
+ *   info     → cyan
+ *   warn     → yellow
+ *   error    → red
+ *   critical → bright red + bold
+ *
+ * @public
+ */
+
+import type {
+  AlertLevel,
+  MessagingChannelPort,
+} from "../../ports/messaging.js";
+import { InvalidTargetError } from "../../ports/messaging.js";
+
+/** ANSI escape codes per alert level. */
+const LEVEL_ANSI: Record<AlertLevel, string> = {
+  info: "\x1b[36m", // cyan
+  warn: "\x1b[33m", // yellow
+  error: "\x1b[31m", // red
+  critical: "\x1b[1m\x1b[31m", // bold + red
+};
+
+const ANSI_RESET = "\x1b[0m";
+
+export interface ConsoleChannelConfig {
+  /**
+   * Output stream. Defaults to `process.stdout` when not provided.
+   * Inject a mock stream in tests to capture output.
+   */
+  stream?: NodeJS.WriteStream;
+}
+
+export class ConsoleChannel implements MessagingChannelPort {
+  readonly #stream: NodeJS.WriteStream;
+
+  /**
+   * @param config - Optional config. All fields optional — usable as `new ConsoleChannel()`.
+   */
+  constructor(config: ConsoleChannelConfig = {}) {
+    this.#stream = config.stream ?? process.stdout;
+  }
+
+  async sendAlert(
+    level: AlertLevel,
+    title: string,
+    body: string
+  ): Promise<void> {
+    const ansi = LEVEL_ANSI[level];
+    const levelTag = `[${level.toUpperCase()}]`;
+    this.#write(`${ansi}${levelTag} ${title}${ANSI_RESET}\n${body}\n`);
+  }
+
+  async sendMessage(target: string, text: string): Promise<void> {
+    if (!target || target.trim() === "") {
+      throw new InvalidTargetError(
+        "ConsoleChannel.sendMessage requires a non-empty target",
+        target
+      );
+    }
+    this.#write(`[MSG→${target.trim()}] ${text}\n`);
+  }
+
+  #write(line: string): void {
+    this.#stream.write(line);
+  }
+}

package/src/adapters/messaging/discord.ts

@@ -0,0 +1,125 @@
+/**
+ * DiscordChannel — MessagingChannelPort adapter for Discord Webhooks.
+ *
+ * Uses Discord embed objects with per-level colors.
+ * Webhook mode: target is ignored for sendMessage (document limitation below).
+ * Uses native fetch (Node 18+).
+ *
+ * Limitation: Discord webhooks POST to a fixed channel configured at webhook
+ * creation time. `sendMessage(target, text)` ignores `target` and always
+ * posts to that channel. If per-channel routing is needed, create one
+ * DiscordChannel instance per webhook URL.
+ *
+ * @public
+ */
+
+import type {
+  AlertLevel,
+  MessagingChannelPort,
+} from "../../ports/messaging.js";
+import { InvalidTargetError } from "../../ports/messaging.js";
+
+/** Discord embed colour (decimal) per alert level. */
+const LEVEL_COLOR: Record<AlertLevel, number> = {
+  info: 0x3498db, // blue
+  warn: 0xf39c12, // yellow
+  error: 0xe74c3c, // red
+  critical: 0xff0000, // bright red
+};
+
+/** Emoji prefix per alert level. */
+const LEVEL_EMOJI: Record<AlertLevel, string> = {
+  info: "ℹ️",
+  warn: "⚠️",
+  error: "❌",
+  critical: "🚨",
+};
+
+export interface DiscordChannelConfig {
+  /** Discord Incoming Webhook URL. Never hardcoded — pass at runtime. */
+  webhookUrl: string;
+}
+
+interface DiscordEmbed {
+  title: string;
+  description: string;
+  color: number;
+  footer: { text: string };
+  timestamp: string;
+}
+
+interface DiscordPayload {
+  content?: string;
+  embeds?: DiscordEmbed[];
+}
+
+export class DiscordChannel implements MessagingChannelPort {
+  readonly #webhookUrl: string;
+
+  constructor(config: DiscordChannelConfig) {
+    this.#webhookUrl = config.webhookUrl;
+  }
+
+  async sendAlert(
+    level: AlertLevel,
+    title: string,
+    body: string
+  ): Promise<void> {
+    const emoji = LEVEL_EMOJI[level];
+    const payload: DiscordPayload = {
+      embeds: [
+        {
+          title: `${emoji} [${level.toUpperCase()}] ${title}`,
+          description: body,
+          color: LEVEL_COLOR[level],
+          footer: { text: "vauban-agent-sdk" },
+          timestamp: new Date().toISOString(),
+        },
+      ],
+    };
+    await this.#post(payload);
+  }
+
+  /**
+   * Send a message to the webhook channel.
+   *
+   * Note: `target` is included in the message text as context but does NOT
+   * route to a different channel — Discord webhooks are bound to a single
+   * channel at creation. To send to different channels, use separate
+   * DiscordChannel instances with distinct webhook URLs.
+   */
+  async sendMessage(target: string, text: string): Promise<void> {
+    if (!target || target.trim() === "") {
+      throw new InvalidTargetError(
+        "DiscordChannel.sendMessage requires a non-empty target (used as context label)",
+        target
+      );
+    }
+    const payload: DiscordPayload = {
+      content: `[→ ${target.trim()}] ${text}`,
+    };
+    await this.#post(payload);
+  }
+
+  async #post(payload: DiscordPayload): Promise<void> {
+    const res = await fetch(this.#webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    if (res.status === 429) {
+      throw new Error("Discord rate limit hit (429); back off before retrying");
+    }
+
+    if (res.status === 204) {
+      // Discord returns 204 No Content on success
+      return;
+    }
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Discord webhook error ${res.status}: ${body}`);
+    }
+  }
+}

package/src/adapters/messaging/mcp.ts

@@ -0,0 +1,84 @@
+/**
+ * MCPChannel — MessagingChannelPort adapter for MCP tool-call dispatch.
+ *
+ * Bridges the messaging port to any MCP server that exposes a compatible tool.
+ * The adapter calls `mcpClient.callTool(toolName, args)` for both sendAlert
+ * and sendMessage, delegating delivery to the MCP server implementation.
+ *
+ * Limitations:
+ *   - Request/response only: MCP tool calls are synchronous from the caller's
+ *     perspective. There is no native push or broadcast mechanism — the MCP
+ *     server must handle delivery internally.
+ *   - Target routing for sendMessage is forwarded as `args.target`; whether
+ *     the MCP server honours it depends on the server implementation.
+ *   - Errors thrown by `callTool` propagate as-is. Rate-limit handling (429
+ *     or equivalent) is the responsibility of the MCP server or the caller.
+ *   - No acknowledgement guarantee: if callTool resolves, the message was
+ *     accepted by the MCP server but not necessarily delivered to the end
+ *     recipient.
+ *
+ * @public
+ */
+
+import type {
+  AlertLevel,
+  MessagingChannelPort,
+} from "../../ports/messaging.js";
+import { InvalidTargetError } from "../../ports/messaging.js";
+
+/**
+ * Minimal interface for an MCP client that can dispatch tool calls.
+ *
+ * Implementations may wrap `@modelcontextprotocol/sdk` Client or any
+ * compatible transport. Only `callTool` is required.
+ *
+ * @public
+ */
+export interface MCPClientLike {
+  callTool(name: string, args: unknown): Promise<unknown>;
+}
+
+export interface MCPChannelConfig {
+  /**
+   * MCP client instance used to dispatch tool calls.
+   * Must implement `callTool(name, args): Promise<unknown>`.
+   */
+  mcpClient: MCPClientLike;
+  /**
+   * Name of the MCP tool to invoke for both sendAlert and sendMessage.
+   * The tool must accept `{ level, title, body }` for alerts and
+   * `{ target, text }` for messages.
+   */
+  toolName: string;
+}
+
+export class MCPChannel implements MessagingChannelPort {
+  readonly #client: MCPClientLike;
+  readonly #toolName: string;
+
+  constructor(config: MCPChannelConfig) {
+    this.#client = config.mcpClient;
+    this.#toolName = config.toolName;
+  }
+
+  async sendAlert(
+    level: AlertLevel,
+    title: string,
+    body: string
+  ): Promise<void> {
+    await this.#client.callTool(this.#toolName, { level, title, body });
+  }
+
+  async sendMessage(target: string, text: string): Promise<void> {
+    if (!target || target.trim() === "") {
+      throw new InvalidTargetError(
+        "MCPChannel.sendMessage requires a non-empty target",
+        target
+      );
+    }
+    await this.#client.callTool(this.#toolName, {
+      target: target.trim(),
+      text,
+    });
+  }
+}