@vauban-org/agent-sdk 0.16.0

package/src/skills/brain-query.ts

@@ -0,0 +1,62 @@
+/**
+ * brain_query — wrapper of BrainPort.queryKnowledge with hash propagation.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import type {
+  BrainPort,
+  BrainEntry,
+  BrainQueryFilters,
+} from "../ports/brain.js";
+import { SkillExecutionError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    query: z.string().min(1).max(512),
+    category: z.string().optional(),
+    tags: z.array(z.string()).max(16).optional(),
+    limit: z.number().int().min(1).max(100).default(10),
+    mcp_call_hash: z.string().optional(),
+  })
+  .strict();
+type BrainQueryInput = z.infer<typeof inputSchema>;
+
+export interface BrainQueryOutput {
+  entries: BrainEntry[];
+}
+
+type CtxWithBrain = SkillContext & { brain?: BrainPort };
+
+export const brainQuery: Skill<BrainQueryInput, BrainQueryOutput> = {
+  name: "brain_query",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<BrainQueryOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["brain_query"];
+      if (mock) return mock(input) as BrainQueryOutput;
+      return { entries: [] };
+    }
+    return withSkillSpan("brain_query", async () => {
+      const brain = (ctx as CtxWithBrain).brain;
+      if (!brain || !brain.queryKnowledge) {
+        throw new SkillExecutionError(
+          "brain_query",
+          "no BrainPort.queryKnowledge attached to context",
+        );
+      }
+      const filters: BrainQueryFilters = {
+        category: input.category,
+        tags: input.tags,
+        limit: input.limit,
+      };
+      if (input.mcp_call_hash) {
+        filters.mcp_call_hash = input.mcp_call_hash;
+      }
+      const entries = await brain.queryKnowledge(input.query, filters);
+      return { entries };
+    });
+  },
+};

package/src/skills/brain-store.ts

@@ -0,0 +1,69 @@
+/**
+ * brain_store — wrapper of BrainPort.archiveKnowledge with mcp_call_hash propagation.
+ *
+ * Requires the host to attach a BrainPort to the SkillContext via the
+ * extended `brain` field (added by host wiring; SDK does not depend on
+ * a concrete client). When absent or in replay, returns null id.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import type { BrainPort, BrainEntryInput } from "../ports/brain.js";
+import { SkillExecutionError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    content: z.string().min(1),
+    category: z.string().optional(),
+    tags: z.array(z.string()).max(16).optional(),
+    author: z.string().optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+    mcp_call_hash: z.string().optional(),
+  })
+  .strict();
+type BrainStoreInput = z.infer<typeof inputSchema>;
+
+export interface BrainStoreOutput {
+  id: string | null;
+  archived: boolean;
+}
+
+/** Optional brain field on context; host wires it in. */
+type CtxWithBrain = SkillContext & { brain?: BrainPort };
+
+export const brainStore: Skill<BrainStoreInput, BrainStoreOutput> = {
+  name: "brain_store",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<BrainStoreOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["brain_store"];
+      if (mock) return mock(input) as BrainStoreOutput;
+      return { id: null, archived: false };
+    }
+    return withSkillSpan("brain_store", async () => {
+      const brain = (ctx as CtxWithBrain).brain;
+      if (!brain) {
+        throw new SkillExecutionError(
+          "brain_store",
+          "no BrainPort attached to context",
+        );
+      }
+      const entry: BrainEntryInput = {
+        content: input.content,
+        category: input.category,
+        tags: input.tags,
+        author: input.author,
+        confidence: input.confidence,
+        metadata: {
+          ...(input.metadata ?? {}),
+          ...(input.mcp_call_hash ? { mcp_call_hash: input.mcp_call_hash } : {}),
+        },
+      };
+      const created = await brain.archiveKnowledge(entry);
+      return { id: created?.id ?? null, archived: created != null };
+    });
+  },
+};

package/src/skills/calendar-check.ts

@@ -0,0 +1,111 @@
+/**
+ * calendar_check — RTH / CME holiday calendar lookup.
+ *
+ * Reuses cme-holidays-2026.json packaged from quick-3 (resolved at runtime
+ * from process.env.CME_HOLIDAYS_PATH or default path under config/).
+ * Pure function — no I/O when isReplay, and idempotent at runtime since
+ * holidays are static yearly data.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    date: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, "expected YYYY-MM-DD"),
+    market: z.enum(["NYSE", "CME", "NASDAQ"]).default("CME"),
+  })
+  .strict();
+type CalendarCheckInput = z.infer<typeof inputSchema>;
+
+export interface CalendarCheckOutput {
+  date: string;
+  market: "NYSE" | "CME" | "NASDAQ";
+  /** Standard regular trading hours session (true = market open, false = closed/holiday/weekend). */
+  is_rth: boolean;
+  is_holiday: boolean;
+  is_weekend: boolean;
+  holiday_name: string | null;
+}
+
+interface HolidayRecord {
+  date: string;
+  name: string;
+  market?: string[];
+}
+
+let CACHED_HOLIDAYS: HolidayRecord[] | null = null;
+
+async function loadHolidays(): Promise<HolidayRecord[]> {
+  if (CACHED_HOLIDAYS) return CACHED_HOLIDAYS;
+  const path = process.env.CME_HOLIDAYS_PATH;
+  if (!path) {
+    // Empty list ⇒ behaves as if no holidays defined; weekend/RTH still computed.
+    CACHED_HOLIDAYS = [];
+    return CACHED_HOLIDAYS;
+  }
+  try {
+    const fs = await import("node:fs/promises");
+    const raw = await fs.readFile(path, "utf-8");
+    const parsed = JSON.parse(raw) as
+      | HolidayRecord[]
+      | { holidays?: HolidayRecord[] };
+    CACHED_HOLIDAYS = Array.isArray(parsed)
+      ? parsed
+      : (parsed.holidays ?? []);
+    return CACHED_HOLIDAYS;
+  } catch (err) {
+    throw new SkillExecutionError("calendar_check", "could not load holidays", {
+      cause: err,
+    });
+  }
+}
+
+/** Test helper. */
+export function _resetCalendarCache(): void {
+  CACHED_HOLIDAYS = null;
+}
+
+export const calendarCheck: Skill<CalendarCheckInput, CalendarCheckOutput> = {
+  name: "calendar_check",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<CalendarCheckOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["calendar_check"];
+      if (mock) return mock(input) as CalendarCheckOutput;
+      return {
+        date: input.date,
+        market: input.market,
+        is_rth: false,
+        is_holiday: false,
+        is_weekend: false,
+        holiday_name: null,
+      };
+    }
+    return withSkillSpan("calendar_check", async () => {
+      const holidays = await loadHolidays();
+      const dt = new Date(`${input.date}T12:00:00Z`);
+      const dow = dt.getUTCDay(); // 0=Sun, 6=Sat
+      const isWeekend = dow === 0 || dow === 6;
+      const match = holidays.find(
+        (h) =>
+          h.date === input.date &&
+          (h.market === undefined || h.market.includes(input.market)),
+      );
+      const isHoliday = match != null;
+      return {
+        date: input.date,
+        market: input.market,
+        is_rth: !isWeekend && !isHoliday,
+        is_holiday: isHoliday,
+        is_weekend: isWeekend,
+        holiday_name: match?.name ?? null,
+      };
+    });
+  },
+};

package/src/skills/cboe-vix-spot.ts

@@ -0,0 +1,89 @@
+/**
+ * cboe_vix_spot — CBOE delayed VIX quote with 15min cache.
+ *
+ * V5 piège 4: NOT Yahoo Finance. CBOE delayed quote is the canonical source.
+ * Cache stub uses an in-process Map; host can override via SkillContext.cache.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z.object({}).strict();
+type CboeVixSpotInput = z.infer<typeof inputSchema>;
+
+export interface CboeVixSpotOutput {
+  symbol: "VIX";
+  last: number;
+  delayed_minutes: number;
+  fetched_at: string;
+  cached: boolean;
+}
+
+interface CacheEntry {
+  expires_at: number;
+  value: CboeVixSpotOutput;
+}
+const PROCESS_CACHE = new Map<string, CacheEntry>();
+const CACHE_KEY = "vix-spot";
+const CACHE_TTL_MS = 15 * 60 * 1000;
+
+export const cboeVixSpot: Skill<CboeVixSpotInput, CboeVixSpotOutput> = {
+  name: "cboe_vix_spot",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<CboeVixSpotOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["cboe_vix_spot"];
+      if (mock) return mock(input) as CboeVixSpotOutput;
+      return {
+        symbol: "VIX",
+        last: 0,
+        delayed_minutes: 15,
+        fetched_at: new Date(0).toISOString(),
+        cached: false,
+      };
+    }
+    const now = Date.now();
+    const hit = PROCESS_CACHE.get(CACHE_KEY);
+    if (hit && hit.expires_at > now) {
+      return { ...hit.value, cached: true };
+    }
+    return withSkillSpan("cboe_vix_spot", async () => {
+      // CBOE delayed-quote endpoint (public, no API key).
+      const url =
+        "https://cdn.cboe.com/api/global/delayed_quotes/quotes/VIX.json";
+      const res = await fetch(url, {
+        headers: { Accept: "application/json" },
+      });
+      if (!res.ok) {
+        throw new SkillExecutionError("cboe_vix_spot", `${res.status}`, {
+          status: res.status,
+        });
+      }
+      const data = (await res.json()) as {
+        data?: { last?: number | string; current_price?: number | string };
+      };
+      const lastRaw = data.data?.last ?? data.data?.current_price ?? 0;
+      const last = typeof lastRaw === "string" ? Number(lastRaw) : lastRaw;
+      const value: CboeVixSpotOutput = {
+        symbol: "VIX",
+        last,
+        delayed_minutes: 15,
+        fetched_at: new Date(now).toISOString(),
+        cached: false,
+      };
+      PROCESS_CACHE.set(CACHE_KEY, {
+        value,
+        expires_at: now + CACHE_TTL_MS,
+      });
+      return value;
+    });
+  },
+};
+
+/** Test helper: clear in-process VIX cache. */
+export function _clearCboeVixCache(): void {
+  PROCESS_CACHE.clear();
+}

package/src/skills/errors.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill-specific error classes.
+ *
+ * Each external service (Brave/Tavily, Alpaca, Telegram, Slack, SMTP/Resend,
+ * CBOE, Starknet) throws a `<Skill>NotConfiguredError` when required env keys
+ * are missing — distinguishes "config gap" from "live API failure".
+ *
+ * @public
+ */
+
+export class SkillNotConfiguredError extends Error {
+  readonly skillName: string;
+  readonly missingEnv: readonly string[];
+  constructor(skillName: string, missingEnv: readonly string[]) {
+    super(
+      `Skill '${skillName}' not configured: missing env ${missingEnv.join(", ")}`,
+    );
+    this.name = "SkillNotConfiguredError";
+    this.skillName = skillName;
+    this.missingEnv = missingEnv;
+  }
+}
+
+export class SkillExecutionError extends Error {
+  readonly skillName: string;
+  readonly status?: number;
+  readonly cause?: unknown;
+  constructor(
+    skillName: string,
+    message: string,
+    opts?: { status?: number; cause?: unknown },
+  ) {
+    super(`Skill '${skillName}' failed: ${message}`);
+    this.name = "SkillExecutionError";
+    this.skillName = skillName;
+    this.status = opts?.status;
+    this.cause = opts?.cause;
+  }
+}
+
+export class SqlReadOnlyViolation extends Error {
+  readonly query: string;
+  constructor(query: string) {
+    super("SQL skill rejected non-read query (cc:read scope)");
+    this.name = "SqlReadOnlyViolation";
+    this.query = query;
+  }
+}
+
+export class HttpFetchAllowlistError extends Error {
+  readonly url: string;
+  readonly host: string;
+  constructor(url: string, host: string) {
+    super(`http_fetch: host '${host}' not in HTTP_FETCH_ALLOWLIST`);
+    this.name = "HttpFetchAllowlistError";
+    this.url = url;
+    this.host = host;
+  }
+}

package/src/skills/hitl-request.ts

@@ -0,0 +1,68 @@
+/**
+ * hitl_request — programmatic HITL trigger.
+ *
+ * INSERTs a row into hitl_approvals (status='pending') and returns its id.
+ * The agent then awaits resolution via the hitl-gate from quick-2 (separate
+ * concern; this skill is fire-and-return-id).
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    agent_run_id: z.string().uuid(),
+    reason: z.string().min(1).max(4_000),
+    risk_level: z.enum(["low", "medium", "high", "critical"]).default("medium"),
+    payload: z.record(z.string(), z.unknown()).optional(),
+    timeout_seconds: z.number().int().min(1).max(86_400).default(900),
+  })
+  .strict();
+type HitlRequestInput = z.infer<typeof inputSchema>;
+
+export interface HitlRequestOutput {
+  id: string;
+  status: "pending" | "replay";
+  expires_at: string;
+}
+
+export const hitlRequest: Skill<HitlRequestInput, HitlRequestOutput> = {
+  name: "hitl_request",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<HitlRequestOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["hitl_request"];
+      if (mock) return mock(input) as HitlRequestOutput;
+      return {
+        id: "00000000-0000-0000-0000-000000000000",
+        status: "replay",
+        expires_at: new Date(0).toISOString(),
+      };
+    }
+    return withSkillSpan("hitl_request", async () => {
+      const expiresAt = new Date(
+        Date.now() + input.timeout_seconds * 1000,
+      ).toISOString();
+      const { rows } = await ctx.db.query<{ id: string }>(
+        `INSERT INTO hitl_approvals
+          (agent_run_id, reason, risk_level, payload, status, expires_at)
+         VALUES ($1, $2, $3, $4::jsonb, 'pending', $5)
+         RETURNING id`,
+        [
+          input.agent_run_id,
+          input.reason,
+          input.risk_level,
+          JSON.stringify(input.payload ?? {}),
+          expiresAt,
+        ],
+      );
+      const id = rows[0]?.id;
+      if (!id) {
+        throw new Error("hitl_request: INSERT returned no id");
+      }
+      return { id, status: "pending", expires_at: expiresAt };
+    });
+  },
+};

package/src/skills/http-fetch.ts

@@ -0,0 +1,92 @@
+/**
+ * http_fetch — GET only, allow-listed domains via env HTTP_FETCH_ALLOWLIST
+ * (comma-sep list of bare hostnames or `*.example.com` patterns).
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { HttpFetchAllowlistError, SkillExecutionError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    url: z.string().url(),
+    headers: z.record(z.string(), z.string()).optional(),
+    timeout_ms: z.number().int().min(100).max(30_000).default(15_000),
+  })
+  .strict();
+type HttpFetchInput = z.infer<typeof inputSchema>;
+
+export interface HttpFetchOutput {
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+  truncated: boolean;
+}
+
+const MAX_RESPONSE_BYTES = 512 * 1024;
+
+function parseAllowlist(): string[] {
+  const raw = process.env.HTTP_FETCH_ALLOWLIST ?? "";
+  return raw
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter((s) => s.length > 0);
+}
+
+export function isHostAllowed(host: string, allowlist: string[]): boolean {
+  const lower = host.toLowerCase();
+  return allowlist.some((pattern) => {
+    if (pattern.startsWith("*.")) {
+      const suffix = pattern.slice(1); // ".example.com"
+      return lower.endsWith(suffix) && lower !== suffix.slice(1);
+    }
+    return lower === pattern;
+  });
+}
+
+export const httpFetch: Skill<HttpFetchInput, HttpFetchOutput> = {
+  name: "http_fetch",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<HttpFetchOutput> {
+    const parsed = new URL(input.url);
+    const allowlist = parseAllowlist();
+    if (allowlist.length === 0) {
+      throw new HttpFetchAllowlistError(input.url, parsed.hostname);
+    }
+    if (!isHostAllowed(parsed.hostname, allowlist)) {
+      throw new HttpFetchAllowlistError(input.url, parsed.hostname);
+    }
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["http_fetch"];
+      if (mock) return mock(input) as HttpFetchOutput;
+      return { status: 0, headers: {}, body: "", truncated: false };
+    }
+    return withSkillSpan("http_fetch", async () => {
+      const ac = new AbortController();
+      const timer = setTimeout(() => ac.abort(), input.timeout_ms);
+      try {
+        const res = await fetch(input.url, {
+          method: "GET",
+          headers: input.headers,
+          signal: ac.signal,
+        });
+        const text = await res.text();
+        const truncated = text.length > MAX_RESPONSE_BYTES;
+        const body = truncated ? text.slice(0, MAX_RESPONSE_BYTES) : text;
+        const headers: Record<string, string> = {};
+        res.headers.forEach((v, k) => {
+          headers[k] = v;
+        });
+        return { status: res.status, headers, body, truncated };
+      } catch (err) {
+        throw new SkillExecutionError("http_fetch", "fetch error", {
+          cause: err,
+        });
+      } finally {
+        clearTimeout(timer);
+      }
+    });
+  },
+};

package/src/skills/index.ts

@@ -0,0 +1,71 @@
+/**
+ * Skill Catalog — 13 builtin OODA skills + record_outcome helper.
+ *
+ * Each skill is a pure function with a strict Zod input schema, typed output,
+ * and `isReplay` enforcement (V8-2 critical for sprint-530 replay engine).
+ * OTEL instrumentation is wired automatically when env
+ * `OTEL_EXPORTER_OTLP_ENDPOINT` is set.
+ *
+ * Differentiator vs Hermes 118 skills: each call emits a run_step with
+ * `leaf_hash_poseidon` so audits can prove "agent X called skill Y with
+ * input Z at time T".
+ *
+ * @public
+ */
+
+export {
+  SkillNotConfiguredError,
+  SkillExecutionError,
+  SqlReadOnlyViolation,
+  HttpFetchAllowlistError,
+} from "./errors.js";
+
+export { webSearch } from "./web-search.js";
+export type { WebSearchOutput, WebSearchResult } from "./web-search.js";
+
+export { alpacaQuote } from "./alpaca-quote.js";
+export type { AlpacaQuoteOutput } from "./alpaca-quote.js";
+
+export { brainStore } from "./brain-store.js";
+export type { BrainStoreOutput } from "./brain-store.js";
+
+export { brainQuery } from "./brain-query.js";
+export type { BrainQueryOutput } from "./brain-query.js";
+
+export { telegramNotify } from "./telegram-notify.js";
+export type { TelegramNotifyOutput } from "./telegram-notify.js";
+
+export { slackNotify } from "./slack-notify.js";
+export type { SlackNotifyOutput } from "./slack-notify.js";
+
+export { sendEmail } from "./send-email.js";
+export type { SendEmailOutput } from "./send-email.js";
+
+export { runSqlQuery, isReadOnlySql } from "./run-sql-query.js";
+export type { RunSqlQueryOutput } from "./run-sql-query.js";
+
+export { cboeVixSpot, _clearCboeVixCache } from "./cboe-vix-spot.js";
+export type { CboeVixSpotOutput } from "./cboe-vix-spot.js";
+
+export { starknetBalance } from "./starknet-balance.js";
+export type { StarknetBalanceOutput } from "./starknet-balance.js";
+
+export { calendarCheck, _resetCalendarCache } from "./calendar-check.js";
+export type { CalendarCheckOutput } from "./calendar-check.js";
+
+export { hitlRequest } from "./hitl-request.js";
+export type { HitlRequestOutput } from "./hitl-request.js";
+
+export { httpFetch, isHostAllowed } from "./http-fetch.js";
+export type { HttpFetchOutput } from "./http-fetch.js";
+
+export { recordOutcomeSkill, _resetOutcomesIndex } from "./record-outcome.js";
+export type { RecordOutcomeOutput } from "./record-outcome.js";
+
+// Skill Ledger types + resolver (SDK v0.8.0 — sprint-530:quick-4)
+export { resolveSkillsForAgent } from "./skill-ledger.js";
+export type {
+  SkillLedgerEntry,
+  SkillLifecycleState,
+  ResolveSkillsOptions,
+} from "./skill-ledger.js";