@vauban-org/agent-sdk 0.16.0

package/src/adapters/messaging/slack.ts

@@ -0,0 +1,109 @@
+/**
+ * SlackChannel — MessagingChannelPort adapter for Slack Incoming Webhooks.
+ *
+ * Uses Block Kit for alerts (color-coded attachments).
+ * Webhook mode only — no bot token / chat.postMessage for now.
+ * Uses native fetch (Node 18+).
+ *
+ * @public
+ */
+
+import type {
+  AlertLevel,
+  MessagingChannelPort,
+} from "../../ports/messaging.js";
+import { InvalidTargetError } from "../../ports/messaging.js";
+
+/** Slack attachment color per alert level. */
+const LEVEL_COLOR: Record<AlertLevel, string> = {
+  info: "good",
+  warn: "warning",
+  error: "danger",
+  critical: "danger",
+};
+
+/** Emoji prefix per alert level. */
+const LEVEL_EMOJI: Record<AlertLevel, string> = {
+  info: "ℹ️",
+  warn: "⚠️",
+  error: "❌",
+  critical: "🚨",
+};
+
+export interface SlackChannelConfig {
+  /** Slack Incoming Webhook URL. Never hardcoded — pass at runtime. */
+  webhookUrl: string;
+}
+
+interface SlackPayload {
+  text?: string;
+  attachments?: SlackAttachment[];
+}
+
+interface SlackAttachment {
+  color: string;
+  title: string;
+  text: string;
+  footer: string;
+  ts: number;
+}
+
+export class SlackChannel implements MessagingChannelPort {
+  readonly #webhookUrl: string;
+
+  constructor(config: SlackChannelConfig) {
+    this.#webhookUrl = config.webhookUrl;
+  }
+
+  async sendAlert(
+    level: AlertLevel,
+    title: string,
+    body: string
+  ): Promise<void> {
+    const emoji = LEVEL_EMOJI[level];
+    const color = LEVEL_COLOR[level];
+    const payload: SlackPayload = {
+      attachments: [
+        {
+          color,
+          title: `${emoji} [${level.toUpperCase()}] ${title}`,
+          text: body,
+          footer: "vauban-agent-sdk",
+          ts: Math.floor(Date.now() / 1000),
+        },
+      ],
+    };
+    await this.#post(payload);
+  }
+
+  async sendMessage(target: string, text: string): Promise<void> {
+    if (!target || target.trim() === "") {
+      throw new InvalidTargetError(
+        "SlackChannel.sendMessage requires a non-empty target",
+        target
+      );
+    }
+    // Webhook mode: target is prepended as context (no channel routing)
+    const payload: SlackPayload = {
+      text: `[→ ${target.trim()}] ${text}`,
+    };
+    await this.#post(payload);
+  }
+
+  async #post(payload: SlackPayload): 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("Slack rate limit hit (429); back off before retrying");
+    }
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new Error(`Slack webhook error ${res.status}: ${body}`);
+    }
+  }
+}

package/src/adapters/messaging/telegram.ts

@@ -0,0 +1,134 @@
+/**
+ * TelegramChannel — MessagingChannelPort adapter for Telegram Bot API.
+ *
+ * Uses native fetch (Node 18+). MarkdownV2 escaping applied automatically.
+ * No axios or other HTTP packages.
+ *
+ * @public
+ */
+
+import type {
+  AlertLevel,
+  MessagingChannelPort,
+} from "../../ports/messaging.js";
+import { InvalidTargetError } from "../../ports/messaging.js";
+
+/** Emoji prefix per alert level. */
+const LEVEL_EMOJI: Record<AlertLevel, string> = {
+  info: "ℹ️",
+  warn: "⚠️",
+  error: "❌",
+  critical: "🚨",
+};
+
+/**
+ * Escape text for Telegram MarkdownV2.
+ * https://core.telegram.org/bots/api#markdownv2-style
+ */
+function escapeMdV2(text: string): string {
+  // Characters that must be escaped in MarkdownV2
+  return text.replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, (ch) => `\\${ch}`);
+}
+
+export interface TelegramChannelConfig {
+  /** Telegram Bot API token (from @BotFather). Never hardcoded — pass at runtime. */
+  botToken: string;
+  /** Default chat_id or @channel_username for sendAlert. */
+  defaultChatId?: string;
+}
+
+interface TelegramApiResponse {
+  ok: boolean;
+  description?: string;
+  error_code?: number;
+}
+
+/** Rate-limit error code from Telegram API. */
+const TELEGRAM_RATE_LIMIT_CODE = 429;
+
+/**
+ * Thrown when Telegram returns a 429 Too Many Requests.
+ *
+ * @public
+ */
+export class TelegramRateLimitError extends Error {
+  constructor(public readonly retryAfterSeconds?: number) {
+    super(
+      `Telegram rate limit hit${
+        retryAfterSeconds != null ? `; retry after ${retryAfterSeconds}s` : ""
+      }`
+    );
+    this.name = "TelegramRateLimitError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class TelegramChannel implements MessagingChannelPort {
+  readonly #botToken: string;
+  readonly #defaultChatId?: string;
+
+  constructor(config: TelegramChannelConfig) {
+    this.#botToken = config.botToken;
+    this.#defaultChatId = config.defaultChatId;
+  }
+
+  async sendAlert(
+    level: AlertLevel,
+    title: string,
+    body: string
+  ): Promise<void> {
+    const chatId = this.#defaultChatId;
+    if (!chatId) {
+      throw new InvalidTargetError(
+        "TelegramChannel.sendAlert requires defaultChatId in constructor config",
+        ""
+      );
+    }
+    const emoji = LEVEL_EMOJI[level];
+    const levelUpper = level.toUpperCase();
+    const text =
+      `${emoji} *\\[${escapeMdV2(levelUpper)}\\] ${escapeMdV2(title)}*\n` +
+      `${escapeMdV2(body)}`;
+    await this.#post(chatId, text, "MarkdownV2");
+  }
+
+  async sendMessage(target: string, text: string): Promise<void> {
+    if (!target || target.trim() === "") {
+      throw new InvalidTargetError(
+        "TelegramChannel.sendMessage requires a non-empty target (chat_id or @channel)",
+        target
+      );
+    }
+    await this.#post(target.trim(), text);
+  }
+
+  async #post(
+    chatId: string,
+    text: string,
+    parseMode?: "MarkdownV2" | "HTML"
+  ): Promise<void> {
+    const url = `https://api.telegram.org/bot${this.#botToken}/sendMessage`;
+    const body: Record<string, string> = { chat_id: chatId, text };
+    if (parseMode) body["parse_mode"] = parseMode;
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+
+    if (res.status === TELEGRAM_RATE_LIMIT_CODE) {
+      const data = (await res.json().catch(() => ({}))) as {
+        parameters?: { retry_after?: number };
+      };
+      throw new TelegramRateLimitError(data.parameters?.retry_after);
+    }
+
+    if (!res.ok) {
+      const data = (await res.json().catch(() => ({}))) as TelegramApiResponse;
+      throw new Error(
+        `Telegram API error ${res.status}: ${data.description ?? "unknown"}`
+      );
+    }
+  }
+}

package/src/adapters/registry/memory.ts

@@ -0,0 +1,84 @@
+/**
+ * MemoryAgentRegistry — in-process adapter for AgentRegistryPort.
+ *
+ * Zero dependencies. Suitable for unit tests, single-process deployments,
+ * and as a local cache in front of PostgresAgentRegistry.
+ *
+ * Thread safety: not applicable (Node.js single-threaded event loop).
+ * Persistence: none — state is lost on process restart.
+ */
+
+import type {
+  AgentDescriptor,
+  AgentRegistryPort,
+} from "../../ports/agent-registry.js";
+
+export class MemoryAgentRegistry implements AgentRegistryPort {
+  private readonly store = new Map<string, AgentDescriptor>();
+
+  /**
+   * Register (upsert) an agent descriptor.
+   * Overwrites any existing descriptor with the same `id`.
+   */
+  async register(descriptor: AgentDescriptor): Promise<void> {
+    this.store.set(descriptor.id, { ...descriptor });
+  }
+
+  /**
+   * List agents, optionally narrowed by a partial descriptor filter.
+   *
+   * Only scalar top-level fields are compared (`product`, `trigger`,
+   * `tenantId`). Arrays (`capabilities`) are not compared here — use
+   * `resolve()` for capability-based lookup.
+   */
+  async list(filter?: Partial<AgentDescriptor>): Promise<AgentDescriptor[]> {
+    const all = Array.from(this.store.values());
+    if (!filter) return all.map((d) => ({ ...d }));
+
+    return all
+      .filter((d) => {
+        if (filter.id !== undefined && d.id !== filter.id) return false;
+        if (filter.product !== undefined && d.product !== filter.product)
+          return false;
+        if (filter.trigger !== undefined && d.trigger !== filter.trigger)
+          return false;
+        if (filter.tenantId !== undefined && d.tenantId !== filter.tenantId)
+          return false;
+        return true;
+      })
+      .map((d) => ({ ...d }));
+  }
+
+  /**
+   * Resolve agents that declare the given capability.
+   *
+   * When `opts.tenantId` is provided, only agents whose `tenantId` matches
+   * OR whose `tenantId` is undefined (global agents) are returned.
+   */
+  async resolve(
+    capability: string,
+    opts?: { tenantId?: string }
+  ): Promise<AgentDescriptor[]> {
+    const results: AgentDescriptor[] = [];
+
+    for (const d of this.store.values()) {
+      if (!d.capabilities.includes(capability)) continue;
+
+      if (opts?.tenantId !== undefined) {
+        // Include only the exact tenant + global agents
+        if (d.tenantId !== undefined && d.tenantId !== opts.tenantId) continue;
+      }
+
+      results.push({ ...d });
+    }
+
+    return results;
+  }
+
+  /**
+   * Remove an agent by id. No-op if the id is not registered.
+   */
+  async unregister(id: string): Promise<void> {
+    this.store.delete(id);
+  }
+}

package/src/adapters/registry/postgres.ts

@@ -0,0 +1,166 @@
+/**
+ * PostgresAgentRegistry — persistent adapter for AgentRegistryPort.
+ *
+ * Requires the `agent_registry` table (migration 039_agent_registry_port.sql).
+ * Uses RLS for tenant isolation — call `resolve()` with `tenantId` to scope
+ * queries via `set_config('app.tenant_id', ...)`.
+ *
+ * Depends on `DbPort` (compatible with `pg.Pool` / `pg.Client`).
+ */
+
+import type { DbPort } from "../../ports/db.js";
+import type {
+  AgentDescriptor,
+  AgentRegistryPort,
+} from "../../ports/agent-registry.js";
+
+// ─── Row shape returned by Postgres ──────────────────────────────────────────
+
+interface AgentRegistryRow {
+  id: string;
+  product: string;
+  capabilities: string[];
+  input_schema: object;
+  trigger: "event" | "cron" | "hitl" | "webhook";
+  llm_requirements: { minContextWindow?: number; toolUse?: boolean } | null;
+  tenant_id: string | null;
+}
+
+function rowToDescriptor(row: AgentRegistryRow): AgentDescriptor {
+  const d: AgentDescriptor = {
+    id: row.id,
+    product: row.product,
+    capabilities: row.capabilities,
+    inputSchema: row.input_schema,
+    trigger: row.trigger,
+  };
+  if (row.llm_requirements !== null) {
+    d.llmRequirements = row.llm_requirements;
+  }
+  if (row.tenant_id !== null) {
+    d.tenantId = row.tenant_id;
+  }
+  return d;
+}
+
+// ─── Adapter ─────────────────────────────────────────────────────────────────
+
+export class PostgresAgentRegistry implements AgentRegistryPort {
+  constructor(private readonly db: DbPort) {}
+
+  /**
+   * Register (upsert) an agent descriptor using INSERT … ON CONFLICT DO UPDATE.
+   * Safe to call on every process start (auto-register pattern).
+   */
+  async register(descriptor: AgentDescriptor): Promise<void> {
+    await this.db.query(
+      `INSERT INTO agent_registry
+         (id, product, capabilities, input_schema, trigger, llm_requirements, tenant_id)
+       VALUES ($1, $2, $3, $4, $5, $6, $7)
+       ON CONFLICT (id) DO UPDATE SET
+         product          = EXCLUDED.product,
+         capabilities     = EXCLUDED.capabilities,
+         input_schema     = EXCLUDED.input_schema,
+         trigger          = EXCLUDED.trigger,
+         llm_requirements = EXCLUDED.llm_requirements,
+         tenant_id        = EXCLUDED.tenant_id,
+         updated_at       = NOW()`,
+      [
+        descriptor.id,
+        descriptor.product,
+        descriptor.capabilities,
+        JSON.stringify(descriptor.inputSchema),
+        descriptor.trigger,
+        descriptor.llmRequirements !== undefined
+          ? JSON.stringify(descriptor.llmRequirements)
+          : null,
+        descriptor.tenantId ?? null,
+      ]
+    );
+  }
+
+  /**
+   * List agents, optionally filtered by scalar descriptor fields.
+   */
+  async list(filter?: Partial<AgentDescriptor>): Promise<AgentDescriptor[]> {
+    const conditions: string[] = [];
+    const params: unknown[] = [];
+
+    if (filter?.id !== undefined) {
+      params.push(filter.id);
+      conditions.push(`id = $${params.length}`);
+    }
+    if (filter?.product !== undefined) {
+      params.push(filter.product);
+      conditions.push(`product = $${params.length}`);
+    }
+    if (filter?.trigger !== undefined) {
+      params.push(filter.trigger);
+      conditions.push(`trigger = $${params.length}`);
+    }
+    if (filter?.tenantId !== undefined) {
+      params.push(filter.tenantId);
+      conditions.push(`tenant_id = $${params.length}`);
+    }
+
+    const where =
+      conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+
+    const result = await this.db.query<AgentRegistryRow>(
+      `SELECT id, product, capabilities, input_schema, trigger,
+              llm_requirements, tenant_id
+       FROM agent_registry
+       ${where}
+       ORDER BY id`,
+      params
+    );
+
+    return result.rows.map(rowToDescriptor);
+  }
+
+  /**
+   * Resolve agents that declare the given capability.
+   *
+   * When `opts.tenantId` is provided, `set_config` injects the tenant id so
+   * that Postgres RLS policy `tenant_isolation` applies. The query also
+   * returns global agents (tenant_id IS NULL) alongside tenant-scoped ones.
+   */
+  async resolve(
+    capability: string,
+    opts?: { tenantId?: string }
+  ): Promise<AgentDescriptor[]> {
+    if (opts?.tenantId !== undefined) {
+      // Set tenant context for RLS; true = local to transaction
+      await this.db.query(`SELECT set_config('app.tenant_id', $1, true)`, [
+        opts.tenantId,
+      ]);
+    }
+
+    const params: unknown[] = [capability];
+    let tenantClause = "";
+
+    if (opts?.tenantId !== undefined) {
+      params.push(opts.tenantId);
+      tenantClause = `AND (tenant_id IS NULL OR tenant_id = $${params.length})`;
+    }
+
+    const result = await this.db.query<AgentRegistryRow>(
+      `SELECT id, product, capabilities, input_schema, trigger,
+              llm_requirements, tenant_id
+       FROM agent_registry
+       WHERE capabilities @> ARRAY[$1::text]
+       ${tenantClause}
+       ORDER BY id`,
+      params
+    );
+
+    return result.rows.map(rowToDescriptor);
+  }
+
+  /**
+   * Remove an agent by id. No-op if the id does not exist.
+   */
+  async unregister(id: string): Promise<void> {
+    await this.db.query(`DELETE FROM agent_registry WHERE id = $1`, [id]);
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,2 @@
+// Agent-specific types barrel (SDK v0.7.1 — sprint-526 Bloc 5b)
+export * from "./trading.js";

package/src/agents/trading.ts

@@ -0,0 +1,114 @@
+/**
+ * Agent-specific trading types — @vauban-org/agent-sdk v0.7.1 (sprint-526 Bloc 5b)
+ *
+ * Pure types + one pure helper. No I/O, no side effects.
+ *
+ * Types mirror the `trade_detail` DB schema (sprint-526:quick-1) so the SDK
+ * surface stays in sync with persistence without a direct DB dependency.
+ *
+ * @public
+ */
+
+/**
+ * A single trade record, mirroring the `trade_detail` table.
+ * All monetary values are in integer cents to avoid float64 rounding.
+ */
+export interface Trade {
+  id: string;
+  outcome_id: string;
+  agent_run_id: string | null;
+  symbol: string;
+  side: "BUY" | "SELL";
+  quantity: number;
+  entry_price_cents: number;
+  exit_price_cents: number | null;
+  pnl_cents: number | null;
+  slippage_bps: number | null;
+  alpaca_order_id: string;
+  trading_mode: "paper" | "live";
+  entry_at: string;
+  exit_at: string | null;
+  exit_reason: "stop" | "target" | "timeout" | "manual" | null;
+}
+
+/**
+ * Observable snapshot of a RiskGuard circuit-breaker instance.
+ * Mirrors the in-memory state exposed by the OODA RiskGuard.
+ */
+export interface RiskGuardState {
+  name: string;
+  state: "closed" | "open" | "half-open";
+  failure_count: number;
+  last_failure: string | null;
+  reset_after: string | null;
+}
+
+/**
+ * A single orientation-memory entry persisted to Brain.
+ * The `metadata.kind` discriminator enables efficient FTS filtering.
+ */
+export interface OrientationMemory {
+  entry_id: string;
+  content: string;
+  metadata: {
+    kind: "orientation-memory";
+    symbol: string;
+    regime: string;
+    observed_at: string;
+  };
+}
+
+/**
+ * Runtime-configurable thresholds for the trading-nq agent.
+ * Loaded via `AgentConfigLoader` so changes apply without restart.
+ */
+export interface TradingNQConfig {
+  thresholds: {
+    conviction_min: number;
+    kelly_cap: number;
+    kelly_bootstrap_fraction: number;
+    bootstrap_trade_threshold: number;
+    hitl_timeout_ms: number;
+    stop_loss_atr_multiple: number;
+    target_atr_multiple: number;
+    trade_timeout_minutes: number;
+  };
+}
+
+/**
+ * Compute a Kelly criterion sizing fraction with a bootstrap fallback.
+ *
+ * V5 anti-pattern #2 (piège 2): never apply full Kelly before sufficient
+ * historical data. When `historicalTradeCount < bootstrap_trade_threshold`,
+ * returns a conservative fixed fraction instead of the Kelly estimate.
+ *
+ * Variance is floored at `1e-9` to guard against divide-by-zero.
+ * Fraction is clamped to `[0, kelly_cap]` — never negative, never unbounded.
+ *
+ * @param historicalTradeCount - Completed trades available for calibration.
+ * @param expectedReturn       - Expected return per trade (e.g. mean PnL).
+ * @param variance             - Variance of returns (must be ≥ 0).
+ * @param config               - Cap + bootstrap parameters.
+ * @returns Sizing fraction and the mode used for traceability.
+ *
+ * @public
+ */
+export function computeKellyFraction(
+  historicalTradeCount: number,
+  expectedReturn: number,
+  variance: number,
+  config: {
+    kelly_cap: number;
+    kelly_bootstrap_fraction: number;
+    bootstrap_trade_threshold: number;
+  },
+): { fraction: number; mode: "bootstrap" | "kelly" } {
+  if (historicalTradeCount < config.bootstrap_trade_threshold) {
+    return { fraction: config.kelly_bootstrap_fraction, mode: "bootstrap" };
+  }
+  const kelly = expectedReturn / Math.max(variance, 1e-9);
+  return {
+    fraction: Math.min(Math.max(kelly, 0), config.kelly_cap),
+    mode: "kelly",
+  };
+}

package/src/auth/errors.ts

@@ -0,0 +1,66 @@
+/**
+ * Event auth errors — typed failures for cross-product event verification.
+ *
+ * ADR-ECO-017: verifyEvent throws typed errors for each failure mode.
+ * Consumers MUST catch and handle these explicitly (no silent ignore).
+ *
+ * @module auth/errors
+ * @public
+ */
+
+/** Thrown when the event's HMAC signature does not match the recomputed value. */
+export class InvalidSignatureError extends Error {
+  constructor(message = "Event signature is invalid") {
+    super(message);
+    this.name = "InvalidSignatureError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when the event timestamp is outside the acceptable clock skew window.
+ * Default window: 5 minutes (±300 000 ms).
+ */
+export class ClockSkewError extends Error {
+  readonly skewMs: number;
+  constructor(skewMs: number) {
+    super(
+      `Event timestamp skew (${skewMs}ms) exceeds the allowed window. Possible replay or clock drift.`
+    );
+    this.name = "ClockSkewError";
+    this.skewMs = skewMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when the nonce (idempotencyKey) has already been seen within the TTL window.
+ * Indicates a replay attack or duplicate delivery.
+ */
+export class ReplayDetectedError extends Error {
+  readonly idempotencyKey: string;
+  constructor(idempotencyKey: string) {
+    super(
+      `Replay detected: idempotencyKey "${idempotencyKey}" has already been processed within the nonce TTL window.`
+    );
+    this.name = "ReplayDetectedError";
+    this.idempotencyKey = idempotencyKey;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when the event's source field is not in the allowed enum.
+ * Allowed sources: forge | vauban | vauban-finance | brain | citadel | glacis | cc | tenant
+ */
+export class UnknownSourceError extends Error {
+  readonly source: string;
+  constructor(source: string) {
+    super(
+      `Unknown event source: "${source}". Must be one of: forge, vauban, vauban-finance, brain, citadel, glacis, cc, tenant.`
+    );
+    this.name = "UnknownSourceError";
+    this.source = source;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}