@vauban-org/agent-sdk 0.16.0

package/src/clients/pipelines.ts

@@ -0,0 +1,160 @@
+/**
+ * PipelinesClient — REST client for /api/pipelines endpoints.
+ *
+ * Wraps:
+ *   POST /api/pipelines/run            → PipelinesClient.run()
+ *   GET  /api/pipelines (via config)   → PipelinesClient.list()
+ *   GET  /api/pipelines/:id/status     → PipelinesClient.status()
+ *
+ * Authentication: Bearer token injected via getToken() on every request.
+ * Timeout: 15s for run (async, returns 202 immediately), 10s for reads.
+ *
+ * Sprint: command-center:sprint-524:quick-9
+ */
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+export interface PipelineRunInput {
+  name: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface PipelineRunResult {
+  pipelineId: string;
+  runId: string;
+  statusUrl: string;
+}
+
+export interface PipelineListEntry {
+  name: string;
+  tier: 1 | 2;
+  schedule?: string;
+}
+
+export interface PipelinesClient {
+  run(input: PipelineRunInput): Promise<PipelineRunResult>;
+  list(): Promise<{ pipelines: PipelineListEntry[] }>;
+  status(pipelineId: string): Promise<{ status: string; progress: number }>;
+}
+
+export interface PipelinesClientOptions {
+  baseUrl: string;
+  getToken: () => Promise<string>;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function buildHeaders(
+  getToken: () => Promise<string>,
+): Promise<Record<string, string>> {
+  const token = await getToken();
+  return {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${token}`,
+  };
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+export function createPipelinesClient(
+  opts: PipelinesClientOptions,
+): PipelinesClient {
+  const base = opts.baseUrl.replace(/\/$/, "");
+
+  return {
+    async run(input: PipelineRunInput): Promise<PipelineRunResult> {
+      const headers = await buildHeaders(opts.getToken);
+
+      // Build a minimal inline pipeline definition accepted by POST /api/pipelines/run.
+      // The backend validates the pipeline object via validatePipeline().
+      const res = await fetch(`${base}/api/pipelines/run`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          pipeline: {
+            name: input.name,
+            trigger: { type: "webhook" },
+            steps: [],
+            ...(input.payload ? { context: input.payload } : {}),
+          },
+        }),
+        signal: AbortSignal.timeout(15_000),
+      });
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => String(res.status));
+        throw new Error(`PipelinesClient.run failed (${res.status}): ${body}`);
+      }
+
+      const raw = (await res.json()) as {
+        runId?: string;
+        pipeline?: string;
+        status?: string;
+      };
+      const runId =
+        typeof raw.runId === "string"
+          ? raw.runId
+          : `pipe-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const pipelineId = typeof raw.pipeline === "string" ? raw.pipeline : input.name;
+      const statusUrl = `${base}/api/pipelines/${runId}/status`;
+
+      return { pipelineId, runId, statusUrl };
+    },
+
+    async list(): Promise<{ pipelines: PipelineListEntry[] }> {
+      // The CC backend does not currently expose a GET /api/pipelines/list endpoint.
+      // We return a static registry of the 10 known pipelines with their tiers.
+      // This avoids a server round-trip while keeping the client interface stable.
+      // When the backend ships a list endpoint, replace with a real fetch().
+      const known: PipelineListEntry[] = [
+        { name: "vault-guardian", tier: 1, schedule: "*/15 */4 * * *" },
+        { name: "sprint-intelligence", tier: 1, schedule: "0 9 * * 1" },
+        { name: "knowledge-compounder", tier: 1 },
+        { name: "ecosystem-health", tier: 1, schedule: "30 * * * *" },
+        { name: "daily-digest", tier: 1, schedule: "0 8 * * *" },
+        { name: "cairo-sentinel", tier: 2 },
+        { name: "competitive-intel", tier: 2, schedule: "0 18 * * *" },
+        { name: "architecture-drift", tier: 2, schedule: "0 10 * * 5" },
+        { name: "pr-review", tier: 2 },
+        { name: "incident-post-mortem", tier: 2 },
+      ];
+      return { pipelines: known };
+    },
+
+    async status(
+      pipelineId: string,
+    ): Promise<{ status: string; progress: number }> {
+      const headers = await buildHeaders(opts.getToken);
+
+      const res = await fetch(`${base}/api/pipelines/${pipelineId}/status`, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!res.ok) {
+        const body = await res.text().catch(() => String(res.status));
+        throw new Error(
+          `PipelinesClient.status failed (${res.status}): ${body}`,
+        );
+      }
+
+      const raw = (await res.json()) as {
+        status?: string;
+        stepsTotal?: number;
+        stepsCompleted?: number;
+      };
+
+      const status = typeof raw.status === "string" ? raw.status : "unknown";
+      const total =
+        typeof raw.stepsTotal === "number" && raw.stepsTotal > 0
+          ? raw.stepsTotal
+          : 1;
+      const completed =
+        typeof raw.stepsCompleted === "number" ? raw.stepsCompleted : 0;
+      const progress = Math.round((completed / total) * 100);
+
+      return { status, progress };
+    },
+  };
+}

package/src/compute/strategies/best-of-n.ts

@@ -0,0 +1,162 @@
+/**
+ * src/compute/strategies/best-of-n.ts
+ *
+ * Best-of-N (BoN) compute strategy.
+ *
+ * Samples N candidates from the generator, scores each via either a
+ * caller-supplied {@link Verifier} OR a {@link BestOfNRewardModel}, and
+ * returns the highest-scoring candidate.
+ *
+ * Caller MUST supply exactly one of `verifier` or `rewardModel`. Supplying
+ * both, or neither, throws at strategy-construction time.
+ *
+ * Tie-break: stable — the first candidate (by sampling order) wins among ties.
+ */
+
+import type { ComputeContext, Strategy, StrategyResult } from "../types.js";
+import type { Verifier } from "../verifier.js";
+
+const STRATEGY_NAME = "best-of-n";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Lightweight reward-model interface — score a candidate output in [0, 1].
+ *
+ * Distinct from {@link Verifier}: a reward model returns only a scalar score,
+ * with no rationale. Use a {@link Verifier} when audit trails / rationales
+ * are required; use a reward model when only ranking matters.
+ */
+export interface BestOfNRewardModel<TOutput> {
+  /** Score the candidate. `[0, 1]` is preferred but not enforced — higher is better. */
+  score(output: TOutput): Promise<number> | number;
+}
+
+export interface BestOfNOptions<_TInput, TOutput> {
+  /** Number of candidates to sample. `n >= 1`. */
+  n: number;
+  /** Domain-specific verifier (mutually exclusive with `rewardModel`). */
+  verifier?: Verifier<TOutput>;
+  /** Reward model (mutually exclusive with `verifier`). */
+  rewardModel?: BestOfNRewardModel<TOutput>;
+  /** Sample candidates concurrently via `Promise.all` (default `true`). */
+  parallel?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a {@link Strategy} that samples N candidates and returns the
+ * highest-scoring one.
+ *
+ * @throws RangeError when `n < 1`.
+ * @throws Error when neither or both of `verifier`/`rewardModel` are supplied.
+ */
+export function bestOfNStrategy<TInput, TOutput>(
+  opts: BestOfNOptions<TInput, TOutput>,
+): Strategy<TInput, TOutput> {
+  if (!Number.isInteger(opts.n) || opts.n < 1) {
+    throw new RangeError(`bestOfNStrategy: n must be an integer >= 1, got ${String(opts.n)}`);
+  }
+
+  const hasVerifier = opts.verifier !== undefined;
+  const hasReward = opts.rewardModel !== undefined;
+  if (hasVerifier === hasReward) {
+    throw new Error("BestOfN requires exactly one of verifier|rewardModel");
+  }
+
+  const n = opts.n;
+  const parallel = opts.parallel ?? true;
+  const verifier = opts.verifier;
+  const rewardModel = opts.rewardModel;
+
+  const scoreOne = async (candidate: TOutput): Promise<number> => {
+    if (verifier !== undefined) {
+      const r = await verifier.evaluate(candidate);
+      return r.score;
+    }
+    // rewardModel guaranteed defined by XOR check above.
+    return await (rewardModel as BestOfNRewardModel<TOutput>).score(candidate);
+  };
+
+  return {
+    name: STRATEGY_NAME,
+
+    async run(
+      input: TInput,
+      generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>,
+      ctx: ComputeContext = {},
+    ): Promise<StrategyResult<TOutput>> {
+      const start = performance.now();
+      const signal = ctx.signal;
+
+      const throwIfAborted = (): void => {
+        if (signal?.aborted) {
+          throw signal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+      };
+
+      throwIfAborted();
+
+      // ── Phase 1: sample N candidates ────────────────────────────────────
+      let candidates: TOutput[];
+      if (parallel) {
+        const tasks: Promise<TOutput>[] = [];
+        for (let i = 0; i < n; i++) {
+          tasks.push(generator(input, ctx));
+        }
+        // If any rejects, Promise.all rejects with the first rejection.
+        // We do not abort siblings (no internal AbortController by design):
+        // the caller's signal — if any — propagates via ctx.
+        candidates = await Promise.all(tasks);
+      } else {
+        candidates = [];
+        for (let i = 0; i < n; i++) {
+          throwIfAborted();
+          candidates.push(await generator(input, ctx));
+        }
+      }
+
+      throwIfAborted();
+
+      // ── Phase 2: score every candidate ─────────────────────────────────
+      const scores: number[] = parallel
+        ? await Promise.all(candidates.map((c) => Promise.resolve(scoreOne(c))))
+        : await (async () => {
+            const out: number[] = [];
+            for (const c of candidates) {
+              out.push(await scoreOne(c));
+            }
+            return out;
+          })();
+
+      // ── Phase 3: pick best (stable, first-occurrence tie-break) ────────
+      let bestIdx = 0;
+      let bestScore = scores[0] ?? Number.NEGATIVE_INFINITY;
+      for (let i = 1; i < scores.length; i++) {
+        const s = scores[i] as number;
+        if (s > bestScore) {
+          bestScore = s;
+          bestIdx = i;
+        }
+      }
+
+      const latency_ms = performance.now() - start;
+
+      return {
+        result: candidates[bestIdx] as TOutput,
+        metadata: {
+          strategy: STRATEGY_NAME,
+          candidates: candidates.length,
+          verifier_scores: scores,
+          cost: { calls: candidates.length },
+          latency_ms,
+        },
+      };
+    },
+  };
+}

package/src/compute/strategies/bon-mav.ts

@@ -0,0 +1,221 @@
+/**
+ * src/compute/strategies/bon-mav.ts
+ *
+ * BoN-MAV — Best-of-N with Multi-Agent Verification.
+ *
+ * Reference: Lifshitz et al. 2025, "Multi-Agent Verification: Scaling
+ * Test-Time Compute with Multiple Verifiers", arXiv:2502.20379.
+ *
+ * Algorithm (paper § 2.3):
+ *   1. Sample N candidate outputs from the generator.
+ *   2. For each candidate, run M aspect verifiers in parallel → score matrix [N][M].
+ *   3. Aggregate per-candidate score (paper baseline: unweighted mean of binary votes,
+ *      Eq. 1 § 2.2). We expose four modes: mean | median | min | majority-vote.
+ *   4. Return argmax candidate (ties → first occurrence).
+ *
+ * See docs/papers/bon-mav-notes.md for the paper distillation.
+ */
+
+import type { ComputeContext, Strategy, StrategyResult } from "../types.js";
+import type { Verifier } from "../verifier.js";
+import { assertVerifierResult } from "../verifier.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type MAVAggregation = "mean" | "median" | "min" | "majority-vote";
+
+export interface BonMavOptions<TOutput> {
+  /** Candidate count (>= 1). */
+  n: number;
+  /** Aspect verifiers (M >= 1). All run on every candidate. */
+  verifiers: readonly Verifier<TOutput>[];
+  /** Aggregation across verifiers. Default "mean" (paper baseline on continuous scores). */
+  aggregation?: MAVAggregation;
+  /** Generate candidates concurrently. Default true. */
+  parallel?: boolean;
+  /**
+   * Threshold for "majority-vote" aggregation: a verifier score >= threshold
+   * counts as a "yes" vote. Default 0.5. Ignored for other aggregations.
+   */
+  voteThreshold?: number;
+}
+
+/**
+ * BoN-MAV-specific metadata extension.
+ * `verifier_scores[i]` = AGGREGATED score of candidate i (length N).
+ * `mavMatrix[i][j]` = raw score from verifier j on candidate i (N × M).
+ */
+export interface BonMavMetadata {
+  strategy: string;
+  candidates: number;
+  verifier_scores: number[];
+  mavMatrix: number[][];
+  aggregation: MAVAggregation;
+  cost: { calls: number };
+  latency_ms: number;
+}
+
+export interface BonMavResult<TOutput> extends StrategyResult<TOutput> {
+  metadata: BonMavMetadata;
+}
+
+// ─── Aggregation helpers ─────────────────────────────────────────────────────
+
+function aggregate(row: readonly number[], mode: MAVAggregation, voteThreshold: number): number {
+  const m = row.length;
+  if (m === 0) return 0;
+
+  switch (mode) {
+    case "mean": {
+      let s = 0;
+      for (const x of row) s += x;
+      return s / m;
+    }
+    case "median": {
+      const sorted = [...row].sort((a, b) => a - b);
+      const mid = Math.floor(m / 2);
+      return m % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+    }
+    case "min": {
+      let lo = row[0];
+      for (let i = 1; i < m; i++) if (row[i] < lo) lo = row[i];
+      return lo;
+    }
+    case "majority-vote": {
+      let votes = 0;
+      for (const x of row) if (x >= voteThreshold) votes += 1;
+      return votes / m;
+    }
+    default: {
+      // Exhaustiveness — unreachable if MAVAggregation is honored.
+      const _exhaustive: never = mode;
+      throw new Error(`Unknown aggregation mode: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+// ─── Strategy ────────────────────────────────────────────────────────────────
+
+const STRATEGY_NAME = "bon-mav";
+
+const VALID_AGGREGATIONS: ReadonlySet<string> = new Set(["mean", "median", "min", "majority-vote"]);
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : new DOMException("Aborted", "AbortError");
+  }
+}
+
+/**
+ * Construct a BoN-MAV {@link Strategy}.
+ *
+ * Validation:
+ * - `n < 1` → RangeError
+ * - `verifiers.length < 1` → Error
+ * - unknown `aggregation` → Error
+ * - `voteThreshold` out of [0,1] → RangeError
+ */
+export function bonMavStrategy<TInput, TOutput>(
+  opts: BonMavOptions<TOutput>,
+): Strategy<TInput, TOutput> {
+  const { n, verifiers, aggregation = "mean", parallel = true, voteThreshold = 0.5 } = opts;
+
+  if (!Number.isInteger(n) || n < 1) {
+    throw new RangeError(`bonMavStrategy: n must be a positive integer, got ${n}`);
+  }
+  if (!verifiers || verifiers.length < 1) {
+    throw new Error("BoN-MAV requires at least 1 verifier");
+  }
+  if (!VALID_AGGREGATIONS.has(aggregation)) {
+    throw new Error(`bonMavStrategy: unknown aggregation "${aggregation}"`);
+  }
+  if (
+    typeof voteThreshold !== "number" ||
+    !Number.isFinite(voteThreshold) ||
+    voteThreshold < 0 ||
+    voteThreshold > 1
+  ) {
+    throw new RangeError(`bonMavStrategy: voteThreshold must be in [0,1], got ${voteThreshold}`);
+  }
+
+  const strategyLabel = `${STRATEGY_NAME}-${aggregation}`;
+
+  return {
+    name: strategyLabel,
+
+    async run(
+      input: TInput,
+      generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>,
+      ctx: ComputeContext = {},
+    ): Promise<BonMavResult<TOutput>> {
+      const start = performance.now();
+      const signal = ctx.signal;
+      throwIfAborted(signal);
+
+      // ── Step 1: sample N candidates ──
+      const childCtx: ComputeContext = { signal };
+      let candidates: TOutput[];
+      if (parallel) {
+        candidates = await Promise.all(Array.from({ length: n }, () => generator(input, childCtx)));
+      } else {
+        candidates = [];
+        for (let i = 0; i < n; i++) {
+          throwIfAborted(signal);
+          candidates.push(await generator(input, childCtx));
+        }
+      }
+      throwIfAborted(signal);
+
+      // ── Step 2: run M verifiers on each candidate (full N×M parallel) ──
+      const flat = await Promise.all(
+        candidates.flatMap((cand) =>
+          verifiers.map(async (v) => {
+            const r = await v.evaluate(cand);
+            assertVerifierResult(r);
+            return r.score;
+          }),
+        ),
+      );
+      throwIfAborted(signal);
+
+      const m = verifiers.length;
+      const mavMatrix: number[][] = [];
+      for (let i = 0; i < n; i++) {
+        mavMatrix.push(flat.slice(i * m, (i + 1) * m));
+      }
+
+      // ── Step 3: aggregate per-candidate ──
+      const aggregated: number[] = mavMatrix.map((row) =>
+        aggregate(row, aggregation, voteThreshold),
+      );
+
+      // ── Step 4: argmax (first occurrence on ties) ──
+      let bestIdx = 0;
+      let bestScore = aggregated[0];
+      for (let i = 1; i < n; i++) {
+        if (aggregated[i] > bestScore) {
+          bestScore = aggregated[i];
+          bestIdx = i;
+        }
+      }
+
+      const latency_ms = performance.now() - start;
+
+      return {
+        result: candidates[bestIdx],
+        metadata: {
+          strategy: strategyLabel,
+          candidates: n,
+          verifier_scores: aggregated,
+          mavMatrix,
+          aggregation,
+          // Paper compute accounting (§ 3): only generator calls billed.
+          cost: { calls: n },
+          latency_ms,
+        },
+      };
+    },
+  };
+}

package/src/compute/strategies/single-shot.ts

@@ -0,0 +1,45 @@
+/**
+ * src/compute/strategies/single-shot.ts
+ *
+ * Passthrough baseline strategy: calls the generator exactly once, no retries, no scoring.
+ */
+
+import type { ComputeContext, Strategy, StrategyResult } from "../types.js";
+
+const STRATEGY_NAME = "single-shot";
+
+/**
+ * Returns a {@link Strategy} that invokes the generator once and returns its result.
+ *
+ * Metadata:
+ * - `candidates`: 1
+ * - `verifier_scores`: []
+ * - `cost.calls`: 1
+ * - `latency_ms`: wall-clock duration via `performance.now()`
+ */
+export function singleShotStrategy<TInput, TOutput>(): Strategy<TInput, TOutput> {
+  return {
+    name: STRATEGY_NAME,
+
+    async run(
+      input: TInput,
+      generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>,
+      ctx: ComputeContext = {},
+    ): Promise<StrategyResult<TOutput>> {
+      const start = performance.now();
+      const result = await generator(input, ctx);
+      const latency_ms = performance.now() - start;
+
+      return {
+        result,
+        metadata: {
+          strategy: STRATEGY_NAME,
+          candidates: 1,
+          verifier_scores: [],
+          cost: { calls: 1 },
+          latency_ms,
+        },
+      };
+    },
+  };
+}

package/src/compute/types.ts

@@ -0,0 +1,36 @@
+/**
+ * src/compute/types.ts
+ *
+ * Shared types for compute strategies.
+ * Minimal surface — only what single-shot (and future strategies) need.
+ */
+
+export interface ComputeContext {
+  signal?: AbortSignal;
+}
+
+export interface StrategyResult<T> {
+  result: T;
+  metadata: {
+    strategy: string;
+    /** Number of candidates generated (1 for single-shot). */
+    candidates: number;
+    /** Verifier scores per candidate (empty for single-shot). */
+    verifier_scores: number[];
+    cost: {
+      /** Number of generator calls made. */
+      calls: number;
+    };
+    /** Wall-clock latency in milliseconds. */
+    latency_ms: number;
+  };
+}
+
+export interface Strategy<TInput, TOutput> {
+  readonly name: string;
+  run(
+    input: TInput,
+    generator: (input: TInput, ctx: ComputeContext) => Promise<TOutput>,
+    ctx?: ComputeContext,
+  ): Promise<StrategyResult<TOutput>>;
+}