@vauban-org/agent-sdk 0.16.0

package/src/runs/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Runs module types — @vauban-org/agent-sdk v0.5.3 (sprint-523 Bloc 3).
+ *
+ * Mirrors:
+ *   - src/routes/run-stream.ts  (RunStepStreamEventName, RunStepStreamEvent)
+ *   - src/routes/agent-health.ts (AgentHealth, Anomaly, CircuitBreakerSnapshot)
+ *
+ * Intentionally kept free of server-side dependencies.
+ */
+
+import type { RunStep } from "../proof/types.js";
+
+export type { RunStep };
+
+export type RunStreamEventName =
+  | "step_existing"
+  | "step_new"
+  | "run_complete"
+  | "ping"
+  | "error";
+
+export interface RunStreamEvent {
+  name: RunStreamEventName;
+  id?: string;
+  data:
+    | RunStep
+    | { status: string; duration_ms?: number }
+    | { error: string }
+    | undefined;
+}
+
+export interface AgentHealth {
+  agent_id: string;
+  window: "24h" | "7d" | "30d";
+  uptime_pct: number;
+  error_rate: number;
+  p50_latency_ms: number;
+  p99_latency_ms: number;
+  run_count: number;
+  last_run_at: string | null;
+  last_status: string | null;
+}
+
+export interface Anomaly {
+  agent_id: string;
+  cost_dimension: string;
+  run_id: string | null;
+  observed: number;
+  baseline_mean: number;
+  baseline_stddev: number;
+  z_score: number;
+  severity: "low" | "medium" | "high";
+  detected_at: string;
+}
+
+export interface CircuitBreakerSnapshot {
+  provider: string;
+  state: "closed" | "open" | "half-open";
+  failure_count: number;
+  last_failure: string | null;
+  last_success: string | null;
+  reset_after_ms: number | null;
+}

package/src/safety/immune.ts

@@ -0,0 +1,145 @@
+/**
+ * Immune detection — cosine similarity-based threat detection.
+ *
+ * Sprint-564: C3 — MAAG immune system (simplified: no voyage-4/pgvector in core).
+ *
+ * Cosine similarity engine for detecting known attack patterns.
+ * StressLedger is STORED ISOLATED — NEVER via BrainPort (P4 security).
+ * voyage-4 + pgvector integration deferred to external infra (Brain API).
+ *
+ * Golden fixtures: known attacker corpus with expected cosine thresholds.
+ */
+
+export interface ImmuneMemoryEntry {
+  /** Embedding vector of the detected pattern. */
+  embedding: number[];
+  /** Human-readable label. */
+  label: string;
+  /** Proof hash for L3 anchoring (Vauban Proof Stack). */
+  proofHash?: string;
+  /** When this entry was recorded. */
+  timestamp: number;
+}
+
+export interface ImmuneMatch {
+  entry: ImmuneMemoryEntry;
+  similarity: number;
+  threshold: number;
+}
+
+/**
+ * Cosine similarity between two vectors. Returns 0-1.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) return 0;
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i]! * b[i]!;
+    normA += a[i]! * a[i]!;
+    normB += b[i]! * b[i]!;
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denominator === 0) return 0;
+  return dotProduct / denominator;
+}
+
+/**
+ * StressLedger — ISOLATED store for immune memory entries.
+ * NEVER stored via BrainPort (P4 security: attack patterns must not
+ * be queryable or modifiable through the knowledge graph).
+ */
+export class StressLedger {
+  private entries: ImmuneMemoryEntry[] = [];
+
+  /** Record an immune memory entry. Returns the entry with proof hash. */
+  record(embedding: number[], label: string): ImmuneMemoryEntry {
+    const entry: ImmuneMemoryEntry = {
+      embedding,
+      label,
+      timestamp: Date.now(),
+    };
+    this.entries.push(entry);
+    return entry;
+  }
+
+  /** Find all entries above a cosine similarity threshold. */
+  search(embedding: number[], threshold = 0.92): ImmuneMatch[] {
+    const matches: ImmuneMatch[] = [];
+    for (const entry of this.entries) {
+      const similarity = cosineSimilarity(embedding, entry.embedding);
+      if (similarity >= threshold) {
+        matches.push({ entry, similarity, threshold });
+      }
+    }
+    return matches.sort((a, b) => b.similarity - a.similarity);
+  }
+
+  /** Number of stored entries. */
+  get size(): number {
+    return this.entries.length;
+  }
+
+  /** Export all entries (for snapshot testing). */
+  export(): ImmuneMemoryEntry[] {
+    return [...this.entries];
+  }
+
+  /** Clear all entries. */
+  clear(): void {
+    this.entries = [];
+  }
+}
+
+// ─── Golden fixtures — known attacker corpus ─────────────────────────────────
+
+export const GOLDEN_ATTACK_EMBEDDINGS: ReadonlyArray<{
+  label: string;
+  embedding: number[];
+}> = [
+  {
+    label: "prompt_injection_ignore",
+    embedding: [0.8, 0.6, 0.1, 0.2, 0.9, 0.1, 0.05, 0.3],
+  },
+  {
+    label: "data_exfiltration_attempt",
+    embedding: [0.1, 0.9, 0.8, 0.7, 0.1, 0.2, 0.9, 0.1],
+  },
+  {
+    label: "role_escalation",
+    embedding: [0.7, 0.1, 0.9, 0.1, 0.8, 0.6, 0.1, 0.2],
+  },
+];
+
+/** Run golden fixture validation. Returns false if any fixture fails detection. */
+export function validateGoldenFixtures(ledger: StressLedger): {
+  passed: boolean;
+  results: Array<{ label: string; matched: boolean; similarity: number }>;
+} {
+  const results: Array<{ label: string; matched: boolean; similarity: number }> = [];
+
+  // Record golden fixtures
+  for (const fixture of GOLDEN_ATTACK_EMBEDDINGS) {
+    ledger.record(fixture.embedding, fixture.label);
+  }
+
+  // Test each fixture against the ledger
+  for (const fixture of GOLDEN_ATTACK_EMBEDDINGS) {
+    const matches = ledger.search(fixture.embedding, 0.92);
+    const selfMatch = matches.find((m) => m.entry.label === fixture.label);
+    results.push({
+      label: fixture.label,
+      matched: !!selfMatch,
+      similarity: selfMatch?.similarity ?? 0,
+    });
+  }
+
+  return {
+    passed: results.every((r) => r.matched),
+    results,
+  };
+}

package/src/safety/index.ts

@@ -0,0 +1,6 @@
+export {
+  sanitizeExternalInput,
+  keepSafeOnly,
+  DEFAULT_INSTRUCTION_PATTERNS,
+} from "./sanitize.js";
+export type { SanitizeConfig, SanitizedItem } from "./sanitize.js";

package/src/safety/sanitize.ts

@@ -0,0 +1,183 @@
+/**
+ * sanitize — Guards the LLM context against the Lethal Trifecta (Simon Willison).
+ * MUST be called before ANY externally-scraped content (Reddit post, tweet,
+ * Discord msg, web page, competitor blog) is injected into an LLM prompt or
+ * tool result.
+ *
+ * Defense layers:
+ *   Layer 1 — content length cap: 500 chars max per item (hard truncation
+ *             with "…" suffix). Protects context budget + limits injection surface.
+ *   Layer 2 — instruction marker regex: detects the most common jailbreak
+ *             patterns. If match → SKIP the item entirely (NOT sanitize; log
+ *             + discard). False positives are acceptable; missed injections are not.
+ *   Layer 3 (future) — embedding-based adversarial classifier.
+ *
+ * IMPORTANT: E2B sandbox protects execution; it does NOT protect LLM context.
+ * This sanitizer is the ONLY guard before content reaches the LLM prompt.
+ */
+
+export interface SanitizeConfig {
+  /** Maximum characters per item (Unicode code points, not bytes). Default: 500. */
+  maxContentChars?: number;
+  /** Regex list; a match on any pattern causes the item to be skipped. */
+  instructionMarkerPatterns?: RegExp[];
+  /** If true, log skipped items via console.warn with a structured payload. Default: true. */
+  logSkips?: boolean;
+}
+
+export interface SanitizedItem<T> {
+  /** True if the item survived sanitization (possibly truncated); false if discarded. */
+  kept: boolean;
+  /** Original item (with content possibly truncated in the `.content` field). */
+  item: T;
+  /** Reason the item was dropped (undefined if kept). */
+  reason?: string;
+}
+
+/**
+ * Default instruction marker patterns. These target the most common LLM
+ * jailbreak vectors observed in 2024-2026:
+ *   - Direct instruction overrides ("ignore previous instructions")
+ *   - Role impersonation ("SYSTEM:", "ASSISTANT:")
+ *   - Tool-call smuggling via fake XML/markdown tags
+ *   - ChatML control tokens ("<|system|>")
+ *   - Anthropic-style Human:/Assistant: markers smuggled via \n\n escapes
+ *   - DAN / jailbreak prompt injections
+ *
+ * Precision is deliberately tuned toward false-positives-acceptable. A
+ * false negative here means a prompt injection succeeds — catastrophic.
+ * A false positive means a benign Reddit post is dropped — recoverable.
+ */
+export const DEFAULT_INSTRUCTION_PATTERNS: RegExp[] = [
+  // Direct instruction override (requires both IGNORE + INSTRUCTIONS/PROMPTS)
+  /\b(IGNORE\s+(PREVIOUS|ALL|PRIOR)\s+(INSTRUCTIONS?|PROMPTS?))\b/i,
+  // Override + role verb (SYSTEM/ASSISTANT/INSTRUCTION)
+  /\bOVERRIDE\b.*\b(SYSTEM|ASSISTANT|INSTRUCTION)/i,
+  // Role marker injection at start-of-line or after punctuation
+  /\b(SYSTEM|ASSISTANT)\s*:/i,
+  // XML-style tool_call smuggling (open or close tag)
+  /<\/?\s*tool_call\s*>/i,
+  // <instructions> fake tag
+  /<\/?\s*instructions?\s*>/i,
+  // Explicit jailbreak terminology
+  /\bJAILBREAK\b/i,
+  // DAN prompt variants (DAN + mode/prompt)
+  /\bDAN\b.*\b(mode|prompt)/i,
+  // ChatML control tokens (<|user|>, <|system|>, <|im_start|>, …)
+  /<\|[a-zA-Z_]+\|>/,
+  // Anthropic-style marker injection via explicit \n\n (or doubly-escaped
+  // \\n\\n when smuggled inside a JSON string). Covers both serialization
+  // layers — attackers may inject at either.
+  /(?:\\\\|\\)n(?:\\\\|\\)n\s*(?:Human|Assistant)\s*:/,
+];
+
+const DEFAULT_MAX_CONTENT_CHARS = 500;
+
+interface SkipLogPayload {
+  event: "sanitize.skip";
+  reason: string;
+  pattern?: string;
+  // Preview trimmed further for log size; never logs the full suspect content.
+  preview: string;
+}
+
+function logSkip(payload: SkipLogPayload): void {
+  // Structured warn: downstream observers (pino, OTel) can scrape this.
+  // We intentionally avoid dynamic imports of pino here — the sanitizer
+  // must be importable from any context (worker, edge, test).
+  console.warn(JSON.stringify(payload));
+}
+
+/**
+ * Truncate a string to `maxChars` Unicode code points, appending "…" when
+ * truncation occurs. Uses `Array.from` to split on code points so
+ * surrogate pairs (emoji, CJK extended) are never cut mid-pair.
+ */
+function truncateByCodePoints(content: string, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  const codePoints = Array.from(content);
+  if (codePoints.length <= maxChars) return content;
+  return `${codePoints.slice(0, maxChars).join("")}…`;
+}
+
+/**
+ * First pattern that matches the content (or null). Returned for logging
+ * so ops can tune regex sensitivity.
+ */
+function findMatchingPattern(
+  content: string,
+  patterns: RegExp[],
+): RegExp | null {
+  for (const pattern of patterns) {
+    if (pattern.test(content)) return pattern;
+  }
+  return null;
+}
+
+/**
+ * Sanitize a batch of externally-scraped items before LLM ingestion.
+ *
+ * Contract:
+ *   - Throws TypeError if an item's `.content` field is not a string.
+ *   - Never mutates input items; returns new objects with truncated content.
+ *   - Returns one SanitizedItem per input (1:1 mapping, order preserved).
+ *
+ * @param items  Array of objects with a `.content: string` field.
+ * @param opts   Optional config override.
+ */
+export function sanitizeExternalInput<T extends { content: string }>(
+  items: T[],
+  opts?: SanitizeConfig,
+): SanitizedItem<T>[] {
+  const maxChars = opts?.maxContentChars ?? DEFAULT_MAX_CONTENT_CHARS;
+  const patterns =
+    opts?.instructionMarkerPatterns ?? DEFAULT_INSTRUCTION_PATTERNS;
+  const shouldLog = opts?.logSkips ?? true;
+
+  return items.map((item) => {
+    if (typeof item.content !== "string") {
+      // Fail loud: a non-string content field is a contract violation by the
+      // caller. Silently coercing would hide a bug.
+      throw new TypeError(
+        `sanitizeExternalInput: item.content must be a string, got ${typeof item.content}`,
+      );
+    }
+
+    // Layer 2 first — if an injection marker is found, we DROP the item
+    // rather than truncate-and-hope. A truncated jailbreak is still a
+    // jailbreak.
+    const hit = findMatchingPattern(item.content, patterns);
+    if (hit !== null) {
+      const reason = `instruction_marker_match:${hit.source}`;
+      if (shouldLog) {
+        logSkip({
+          event: "sanitize.skip",
+          reason,
+          pattern: hit.source,
+          preview: item.content.slice(0, 80),
+        });
+      }
+      return { kept: false, item, reason };
+    }
+
+    // Layer 1 — truncate by code points (not bytes) to avoid mangling
+    // UTF-8 multi-byte sequences.
+    const truncated = truncateByCodePoints(item.content, maxChars);
+    const sanitizedItem: T = { ...item, content: truncated };
+    return { kept: true, item: sanitizedItem };
+  });
+}
+
+/**
+ * Convenience: run `sanitizeExternalInput` and return only the kept items,
+ * already content-truncated. Shape-preserving — the returned array contains
+ * the same T type as the input, with content possibly shortened.
+ */
+export function keepSafeOnly<T extends { content: string }>(
+  items: T[],
+  opts?: SanitizeConfig,
+): T[] {
+  return sanitizeExternalInput(items, opts)
+    .filter((r) => r.kept)
+    .map((r) => r.item);
+}

package/src/sdk-permission-mapping.ts

@@ -0,0 +1,123 @@
+/**
+ * sdk-permission-mapping — pure projections from `cc:*` scope + Biscuit
+ * tool list onto the SDK's runtime permission envelope.
+ *
+ * Two surfaces:
+ *  - `scopeToSdkPermissions(scope)` mirrors the JWT-only path used in
+ *    `mapScopesToSdkPermissions` but takes a SINGLE scope value (handier
+ *    for code paths that already know the resolved scope).
+ *  - `capabilityToSdkPermissions(scope, tools)` returns the INTERSECTION
+ *    of the static scope projection and the agent's dynamic Biscuit tool
+ *    allowlist. Tools that don't grant MCP capability remove `mcp:*`
+ *    permissions; an empty tool list strips MCP entirely regardless of
+ *    scope.
+ *
+ * Both functions are PURE (no IO, no globals). The empty-tools case is
+ * called out explicitly so a misconfigured agent token cannot quietly
+ * inherit the scope's full surface.
+ */
+
+export type CcScope = "cc:read" | "cc:execute" | "cc:admin";
+
+export type FileIoMode = "off" | "read-only" | "sandboxed-tmp";
+export type BashMode = "off" | "restricted";
+
+/**
+ * Permission envelope produced by this module. Distinct from the
+ * `SdkPermissions` shape in `permissions/sdk-permissions.ts`: that one is
+ * tightly coupled to the SDK loop, this one is a stable shape for hosts
+ * computing intersections (no readonly arrays — caller may freeze).
+ */
+export interface SdkPermissions {
+  bash: BashMode;
+  fileIo: FileIoMode;
+  mcp: string[];
+}
+
+const READ_PERMS: SdkPermissions = {
+  bash: "off",
+  fileIo: "read-only",
+  mcp: ["brain:read", "citadel:read"],
+};
+
+const EXECUTE_PERMS: SdkPermissions = {
+  bash: "restricted",
+  fileIo: "sandboxed-tmp",
+  mcp: ["brain:write", "citadel:write"],
+};
+
+const ADMIN_PERMS: SdkPermissions = {
+  bash: "restricted",
+  fileIo: "sandboxed-tmp",
+  mcp: ["brain:write", "citadel:write", "brain:admin", "citadel:admin"],
+};
+
+/** Project a single `cc:*` scope onto SdkPermissions. Pure. */
+export function scopeToSdkPermissions(scope: CcScope): SdkPermissions {
+  switch (scope) {
+    case "cc:read":
+      return clone(READ_PERMS);
+    case "cc:execute":
+      return clone(EXECUTE_PERMS);
+    case "cc:admin":
+      return clone(ADMIN_PERMS);
+  }
+}
+
+/**
+ * Map a Biscuit tool name to an MCP sub-scope. The mapping is conservative:
+ * unknown tools grant NO MCP scope. Hosts may extend this map by
+ * passing tools that match a known prefix (e.g. `brain:*`, `citadel:*`).
+ */
+function toolToMcpScope(tool: string): string | null {
+  if (tool === "brainQuery" || tool === "queryKnowledge") return "brain:read";
+  if (tool === "brainArchive" || tool === "archiveKnowledge")
+    return "brain:write";
+  if (tool === "citadelRead") return "citadel:read";
+  if (tool === "citadelWrite" || tool === "createTask") return "citadel:write";
+  // Pre-namespaced (e.g. "brain:read") → identity if the prefix is known.
+  if (
+    tool.startsWith("brain:") ||
+    tool.startsWith("citadel:") ||
+    tool.startsWith("starknet:")
+  ) {
+    return tool;
+  }
+  return null;
+}
+
+/**
+ * Compute the INTERSECTION of `scopeToSdkPermissions(scope)` and the
+ * agent's tool allowlist. Tools that don't unlock MCP scopes do not
+ * grant MCP. An empty tool list strips MCP entirely.
+ */
+export function capabilityToSdkPermissions(
+  scope: CcScope,
+  tools: readonly string[],
+): SdkPermissions {
+  const base = scopeToSdkPermissions(scope);
+
+  // Empty tools → no MCP, regardless of scope.
+  if (tools.length === 0) {
+    return { ...base, mcp: [] };
+  }
+
+  // Map each tool to an MCP sub-scope; intersect with the scope's grant.
+  const requested = new Set<string>();
+  for (const t of tools) {
+    const sub = toolToMcpScope(t);
+    if (sub) requested.add(sub);
+  }
+  const granted = new Set(base.mcp);
+  const intersection = [...requested].filter((s) => granted.has(s)).sort();
+
+  return {
+    bash: base.bash,
+    fileIo: base.fileIo,
+    mcp: intersection,
+  };
+}
+
+function clone(p: SdkPermissions): SdkPermissions {
+  return { bash: p.bash, fileIo: p.fileIo, mcp: [...p.mcp] };
+}

package/src/skills/_otel.ts

@@ -0,0 +1,31 @@
+/**
+ * Optional OTEL helper for skills.
+ *
+ * If env OTEL_EXPORTER_OTLP_ENDPOINT is set, wrap fn in a span; else no-op.
+ * Internal — not part of the public Skill Catalog API.
+ *
+ * @internal
+ */
+import { trace } from "@opentelemetry/api";
+
+export async function withSkillSpan<T>(
+  skillName: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  if (!process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+    return fn();
+  }
+  const tracer = trace.getTracer("@vauban-org/agent-sdk:skills");
+  return tracer.startActiveSpan(`skill.${skillName}`, async (span) => {
+    try {
+      const result = await fn();
+      span.setAttribute("skill.name", skillName);
+      span.end();
+      return result;
+    } catch (err) {
+      span.recordException(err as Error);
+      span.end();
+      throw err;
+    }
+  });
+}

package/src/skills/alpaca-quote.ts

@@ -0,0 +1,82 @@
+/**
+ * alpaca_quote — Alpaca paper/live quote.
+ *
+ * cc:read scope. Live mode requires ALPACA_API_KEY / ALPACA_API_SECRET.
+ *
+ * @public
+ */
+import { z } from "zod";
+import type { Skill, SkillContext } from "../orchestration/ooda/skills.js";
+import { SkillExecutionError, SkillNotConfiguredError } from "./errors.js";
+import { withSkillSpan } from "./_otel.js";
+
+const inputSchema = z
+  .object({
+    symbol: z
+      .string()
+      .min(1)
+      .max(16)
+      .regex(/^[A-Z0-9.\-]+$/),
+    mode: z.enum(["paper", "live"]).default("paper"),
+  })
+  .strict();
+type AlpacaQuoteInput = z.infer<typeof inputSchema>;
+
+export interface AlpacaQuoteOutput {
+  symbol: string;
+  bid: number;
+  ask: number;
+  timestamp: string;
+  mode: "paper" | "live" | "replay";
+}
+
+export const alpacaQuote: Skill<AlpacaQuoteInput, AlpacaQuoteOutput> = {
+  name: "alpaca_quote",
+  inputSchema,
+  async execute(input, ctx: SkillContext): Promise<AlpacaQuoteOutput> {
+    if (ctx.isReplay) {
+      const mock = ctx.dryRunMocks["alpaca_quote"];
+      if (mock) return mock(input) as AlpacaQuoteOutput;
+      return {
+        symbol: input.symbol,
+        bid: 0,
+        ask: 0,
+        timestamp: new Date(0).toISOString(),
+        mode: "replay",
+      };
+    }
+    return withSkillSpan("alpaca_quote", async () => {
+      const apiKey = process.env.ALPACA_API_KEY;
+      const apiSecret = process.env.ALPACA_API_SECRET;
+      if (!apiKey || !apiSecret) {
+        throw new SkillNotConfiguredError("alpaca_quote", [
+          "ALPACA_API_KEY",
+          "ALPACA_API_SECRET",
+        ]);
+      }
+      const dataHost = "https://data.alpaca.markets";
+      const url = `${dataHost}/v2/stocks/${encodeURIComponent(input.symbol)}/quotes/latest`;
+      const res = await fetch(url, {
+        headers: {
+          "APCA-API-KEY-ID": apiKey,
+          "APCA-API-SECRET-KEY": apiSecret,
+        },
+      });
+      if (!res.ok) {
+        throw new SkillExecutionError("alpaca_quote", `${res.status}`, {
+          status: res.status,
+        });
+      }
+      const data = (await res.json()) as {
+        quote?: { bp?: number; ap?: number; t?: string };
+      };
+      return {
+        symbol: input.symbol,
+        bid: data.quote?.bp ?? 0,
+        ask: data.quote?.ap ?? 0,
+        timestamp: data.quote?.t ?? new Date().toISOString(),
+        mode: input.mode,
+      };
+    });
+  },
+};

package/src/skills/base-skills.ts

@@ -0,0 +1,38 @@
+/**
+ * Base Skills — universal skills available to all agent consumers.
+ *
+ * Every skill registry built via `buildSkills()` includes these by default.
+ * Domain-specific extras are layered on top per consumer configuration.
+ *
+ * Skills intentionally NOT base (must be explicitly granted per agent):
+ * - http-fetch: gateway to arbitrary external APIs
+ * - send-email: user-facing communication channel
+ * - telegram-notify: ops channel (write access)
+ * - run-sql-query: raw data access
+ * - prometheus-query: infra read access
+ *
+ * @public @since 0.18.0
+ */
+
+import type { Skill } from "../orchestration/ooda/skills.js";
+
+/**
+ * Names of skills included in every base registry.
+ * Exposed so consumers can assert or enumerate defaults.
+ */
+export const BASE_SKILL_NAMES = [
+  "brain-query",
+  "brain-store",
+  "slack-notify",
+  "llm-complete",
+] as const satisfies readonly string[];
+
+export type BaseSkillName = (typeof BASE_SKILL_NAMES)[number];
+
+/**
+ * Descriptor for a domain skill: a name + the Skill implementation.
+ */
+export interface DomainSkillEntry {
+  readonly name: string;
+  readonly skill: Skill;
+}